@ryanstark24/sfgraph-skills 1.1.0

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

@@ -0,0 +1,72 @@
+---
+name: sf-dead-code-audit
+description: Identify unused Apex / LWC / Flow / fields with confidence buckets and freshness signals.
+triggers:
+  - "dead code"
+  - "unused apex"
+  - "unused fields"
+  - "what can I delete"
+  - "cleanup audit"
+tools_used:
+  - dead_code_audit
+  - freshness_report
+  - trace_upstream
+  - staleness_check
+---
+
+# sf-dead-code-audit
+
+Use when the user wants to inventory metadata that appears unreferenced. Output must be bucketed by confidence — deletion in Salesforce is reversible only via backup, so we communicate uncertainty.
+
+## 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.).
+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).
+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).
+   - **suspicious-uncertain** — looks dead but the graph has known blind spots (dynamic SOQL string-interpolated field name, reflection-style `Type.forName`, external system reference).
+5. Render the Mermaid bar-chart / treemap returned by the tool grouped by category.
+6. For confident-dead items, propose a destructive-changes.xml snippet but do not save it. The user owns the delete decision.
+
+## Visualization
+
+Render a **`flowchart TD`** treemap-style grouping. Top-level nodes are metadata categories (ApexClass, LWC, Flow, Field); under each, sub-nodes are the three confidence buckets, sized loosely by item count. Avoid drawing the dead items themselves — the table carries that detail.
+
+```
+flowchart TD
+  Root --> Apex
+  Apex --> A_conf[confident-dead: 12]:::conf
+  Apex --> A_likely[likely-dead: 8]:::likely
+  Apex --> A_uncert[uncertain: 4]:::uncert
+  classDef conf fill:#fcc
+  classDef likely fill:#ffe6cc
+  classDef uncert fill:#ffd
+```
+
+When the org has >100 dead candidates, drop the diagram and rely on the per-bucket tables — the chart becomes noise.
+
+## Staleness check
+
+Before calling `dead_code_audit`, invoke `staleness_check` for the target org. Stale ingests make dead-code analysis dangerously wrong (a recently-added caller would be invisible). 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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Scope** — what was scanned (org id, category filter).
+- **Bucket: confident-dead** — table of name / type / last-touched / evidence.
+- **Bucket: likely-dead** — same shape.
+- **Bucket: suspicious-uncertain** — same shape with the specific blind spot called out.
+- **Mermaid summary chart** — embedded.
+- **Proposed destructive-changes.xml** (confident bucket only, fenced block, not written to disk).
+
+## Don't
+
+- Do not collapse buckets. Confidence is the product here.
+- Do not delete or stage anything. Output only.
+- Do not include managed-package items as deletable.
+- Do not skip the `trace_upstream` confirmation step for any item the user actually plans to remove.

package/skills/sf-deployment-manifest/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sf-deployment-manifest
+description: Generate a package.xml deployment manifest covering a change set and its required dependencies.
+triggers:
+  - "deployment manifest"
+  - "package.xml"
+  - "what do I need to deploy"
+  - "build manifest"
+  - "deploy plan"
+tools_used:
+  - deployment_manifest_gen
+  - cross_org_diff
+  - staleness_check
+---
+
+# sf-deployment-manifest
+
+Use when the user wants a `package.xml` that captures a set of changes plus everything they transitively depend on for a successful deploy.
+
+## Playbook
+
+1. Establish the source and target orgs. The tool's contract today is a strict cross-org diff: it inputs `from_org` (source) and `to_org` (target) and emits the metadata that exists in `from_org` but is missing or different in `to_org` (plus a `destructiveChanges.xml` for things present only in `to_org`).
+2. Optionally call `cross_org_diff` first to preview the set difference before generating the manifest XML.
+3. Call `deployment_manifest_gen` with `from_org` + `to_org` (+ optional `category` filter). The tool does NOT currently walk `DEPENDS_ON` edges — it returns the set difference as `package.xml` / `destructiveChanges.xml`. Dependency-closure walking is planned future work; for now the user is responsible for any additional parent metadata not surfaced by the diff.
+4. Inspect the result for ambiguous dependencies (managed-package types, namespace mismatches) and surface them as warnings.
+5. Emit the `package.xml` inside a fenced code block. Also emit `destructiveChanges.xml` if the diff includes removals.
+6. If extra dependencies are needed beyond the raw diff, ask the user to extend the set manually — do not silently fabricate dependency edges the graph doesn't have.
+
+## Visualization
+
+Render a **`flowchart LR`** dependency closure graph. The user's explicit change set is one subgraph; auto-pulled dependencies are another. Edge labels carry the dependency reason (`parent-of`, `layout-for`, `required-permission`).
+
+```
+flowchart LR
+  subgraph Requested
+    F[Field:Account.Tier__c]
+  end
+  subgraph Closure
+    O[CustomObject:Account]
+    L[Layout:Account-Layout]
+  end
+  F -->|parent-of| O
+  F -->|layout-for| L
+```
+
+If the closure expands past 60 nodes, summarise per metadata type and only render the diagram for the top 20 — beyond that the graph becomes unreadable.
+
+## Staleness check
+
+Before calling `deployment_manifest_gen`, invoke `staleness_check` for the source org. A stale graph means missing dependencies in the manifest, which fail at deploy time. 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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Source set** — what was requested.
+- **Closure additions** — what was pulled in by dependency traversal, grouped by metadata type.
+- **Warnings** — managed-package / namespace / ambiguous-dependency notes.
+- **package.xml** — fenced code block.
+- **destructiveChanges.xml** — fenced code block (only if applicable).
+- **Mermaid dependency graph** — embedded.
+
+## Don't
+
+- **Never deploy.** This skill emits XML; the user runs `sf project deploy start`.
+- Do not silently include managed-package types as deployable — flag them.
+- Do not omit API version; default to the source org's API version unless the user overrides.
+- Do not write the XML to disk on the user's behalf. They paste it where they want it.

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

@@ -0,0 +1,66 @@
+---
+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.
+triggers:
+  - "explain this method"
+  - "what does <ClassName.method> do"
+  - "walk me through <qname>"
+  - "annotate the conditionals"
+tools_used:
+  - explain_code
+  - trace_upstream
+  - trace_downstream
+  - staleness_check
+---
+
+# sf-explain-code
+
+Use this skill when the user wants a plain-English explanation of a specific code unit (an Apex method, an LWC handler, a trigger body). It reads the stored source via the graph's snippet store, generates an annotated explanation, and caches that explanation back so the next caller gets it for free.
+
+## 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.
+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:
+   - **One-paragraph summary**: what the method does at a high level.
+   - **Annotated source block**: re-emit the source with terse `// → ...` comments after each conditional branch and each loop. Keep comments to one line.
+   - **Side effects**: list any SOQL/DML found in the body, with target objects/fields. The reader needs to know what hits the database.
+   - **Reaches** (optional): if the method clearly delegates to other code, call `trace_downstream(qname=X, depth=2)` and summarise what it touches.
+5. **Cache the explanation back** via `explain_code(qname=X, annotation=<summary + annotated block>)`. This makes the next read of the same qname instant.
+
+## Visualization
+
+When the method has **more than two branches** (counting `if`, `else if`, `switch when`, and early `return` guards), render a `flowchart TD` of the conditional structure. Skip the diagram for straight-line code — it adds noise.
+
+```
+flowchart TD
+  S[start] --> C1{isClosed?}
+  C1 -- yes --> R1[return early]
+  C1 -- no --> C2{amount > 0?}
+  C2 -- yes --> A[apply tax]
+  C2 -- no --> E[throw]
+```
+
+## Staleness check
+
+Before reading the snippet, call `staleness_check` for the org. If the ingest is stale:
+
+> Your ingest is N days old. The source you're explaining may not match production. Run `sfgraph ingest --org <alias>` to refresh.
+
+Continue the playbook either way; just flag the risk.
+
+## Response shape
+
+- **TL;DR** — one sentence: "what this method does".
+- **Annotated source** — fenced code block tagged with the source format.
+- **Side effects** — SOQL/DML/callouts.
+- **Mermaid** — only when conditional structure justifies it.
+- **Cached** — confirm the explanation was cached back, with the qname.
+
+## 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.

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

@@ -0,0 +1,67 @@
+---
+name: sf-flow-impact
+description: Find every Flow / Process Builder / workflow that reads or writes a given field or object.
+triggers:
+  - "which flows use"
+  - "flow impact"
+  - "what flows touch"
+  - "flow references"
+  - "automation on this field"
+tools_used:
+  - analyze_field
+  - trace_upstream
+  - staleness_check
+---
+
+# sf-flow-impact
+
+Use when the user asks which automation references a specific field or object — typically before a field rename, type change, or deletion.
+
+## Playbook
+
+1. Resolve the target. Call `analyze_field` for a single field; for an SObject, list its fields first and ask the user to narrow if the scope is large.
+2. Filter the readers/writers from `analyze_field` to Flow-family node types: `Flow`, `ProcessBuilder`, `WorkflowRule`, `OmniProcess`.
+3. Call `trace_upstream` on each Flow to surface what triggers it (record-triggered context, Apex `Invocable`, platform event, button).
+4. Bucket results into **reads**, **writes**, **both**. Note whether each Flow is `Active`, `Draft`, or `Obsolete`.
+5. Render the Mermaid field-to-flow diagram returned by the tool. If more than 20 flows reference the field, group by entry trigger type.
+6. Call out compatibility risk: type changes break decision criteria; deletions break assignments.
+
+## Visualization
+
+Render a **`flowchart LR`** field-to-flow diagram. The target field is the central node; each Flow is a leaf node. Edge style encodes read (`-->`) vs write (`==>`); colour encodes Flow status (Active / Draft / Obsolete).
+
+```
+flowchart LR
+  F[(Account.Tier__c)]
+  F --> Fl1[Flow:Account_OnUpdate]:::active
+  F ==> Fl2[Flow:Account_BeforeInsert]:::active
+  F --> Fl3[Flow:Account_Legacy]:::obsolete
+  classDef active fill:#cfc
+  classDef obsolete fill:#eee,stroke-dasharray:3 3
+```
+
+If more than 20 flows reference the field, group leaves by entry-trigger type and render at the group level rather than per-flow.
+
+## Staleness check
+
+Before calling `analyze_field`, invoke `staleness_check` for the target org. Newly-created or recently-modified Flows are invisible in a stale graph, which makes this skill produce false negatives. 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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Target** — `SObject.Field` or `SObject`.
+- **Reads** — table of Flow name / status / entry trigger.
+- **Writes** — same shape.
+- **Both** — same shape.
+- **Mermaid field-to-flow diagram** — embedded.
+- **Compatibility risks** — bullets for type-change / delete / rename impacts.
+
+## Don't
+
+- Do not include Apex callers here; that belongs to `sf-cross-layer-trace`.
+- Do not modify or activate / deactivate any Flow.
+- Do not skip Draft / Obsolete flows by default — call them out separately instead.
+- Do not assume `analyze_field` covers Apex-generated dynamic field references; flag the limitation.

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

@@ -0,0 +1,64 @@
+---
+name: sf-governor-risk-fix
+description: Detect governor-limit risks (SOQL/DML in loops, unbounded queries) and produce a remediation checklist.
+triggers:
+  - "governor limit"
+  - "SOQL in loop"
+  - "DML in loop"
+  - "CPU time"
+  - "heap"
+  - "bulkification"
+tools_used:
+  - governor_risk_check
+  - staleness_check
+---
+
+# sf-governor-risk-fix
+
+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.
+
+## 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.
+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.
+
+```
+flowchart TD
+  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
+```
+
+If the scan returns >50 findings, render only the top-10-by-fan-in row and link to the full table — a wall of cells doesn't help triage.
+
+## Staleness check
+
+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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Summary counts** — total findings by severity (high / medium / low) and by rule.
+- **Findings grouped by rule** — each finding: location, fan-in, recommended pattern.
+- **Mermaid heat-map** — embedded.
+- **Remediation checklist** — copy-pasteable Markdown checkboxes.
+
+## Don't
+
+- **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 silently exclude managed-package code; mention it was filtered out if so.

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

@@ -0,0 +1,64 @@
+---
+name: sf-impact-from-diff
+description: Compute downstream blast radius and test-coverage gaps for a git diff before merge.
+triggers:
+  - "what does this PR break"
+  - "impact of this diff"
+  - "before I merge"
+  - "blast radius"
+  - "what does this change affect"
+tools_used:
+  - impact_from_git_diff
+  - test_gap_intelligence_from_git_diff
+  - staleness_check
+---
+
+# 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.
+
+## 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.
+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.
+
+## 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`).
+
+```
+flowchart LR
+  C[ApexClass:AccountSvc]:::changed --> D1[ApexClass:AccountCtl]
+  C --> D2[Flow:Account_OnUpdate]
+  D1 --> T1[LWC:accountList]
+  classDef changed fill:#fcc,stroke:#900
+```
+
+When the impact set exceeds 40 nodes, summarise per category and offer the user a follow-up scoped to a single changed file before drawing the diagram.
+
+## Staleness check
+
+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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **TL;DR** — one sentence: N files changed, M dependents touched, K gaps.
+- **Impact by tier** — direct / first-degree / transitive bullets with node names + types.
+- **Test gaps** — bulleted list of `ClassName.methodName` not covered, with the impacted node that surfaced them.
+- **Mermaid graph** — embedded from tool output.
+- **Suggested follow-ups** — point at `sf-governor-risk-fix` or `sf-cross-layer-trace` if the change touches Apex or spans layers.
+
+## Don't
+
+- Do not "approve" or "reject" the diff. You report; the human decides.
+- Do not auto-write tests or modify code. This skill is read-only.
+- Do not silently truncate the dependent list — always say when results were capped.
+- Do not run on a clean working tree without telling the user there is nothing to analyse.

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

@@ -0,0 +1,71 @@
+---
+name: sf-metadata-refresh
+description: Check sfgraph ingest staleness, surface dead/stale metadata in the org, and tell the user exactly how to refresh.
+triggers:
+  - "refresh the graph"
+  - "is my data fresh"
+  - "how do I update"
+  - "sync the org"
+  - "re-ingest"
+tools_used:
+  - staleness_check
+  - freshness_report
+  - start_ingest_job
+  - get_ingest_job
+---
+
+# sf-metadata-refresh
+
+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.
+
+## 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
+   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:
+   - For their default org: `sfgraph ingest`
+   - For a named alias: `sfgraph ingest --org <alias>`
+   - For **multiple orgs** in one run: `sfgraph ingest --orgs prod,uat,qa` (sequential) or add `--parallel` to fan them out concurrently.
+   - For **every authenticated org**: `sfgraph ingest --all` (add `--parallel` to refresh them all at once).
+   - For a **clean rebuild from scratch** (when the graph has drifted or parser logic changed): `sfgraph ingest --rebuild --org <alias>` (existing graph moves to `backups/`; pair with `--no-backup` to delete instead).
+   - On **production orgs without Source Tracking**, add `--detect-deletions` so qnames that disappeared upstream get removed during the full sync.
+   - If the user just changed `sf` CLI state (logged into a new org, renamed an alias, or ran `sf config set target-org=…`), tell them to run **`sfgraph refresh-orgs`** before any sfgraph workflow — that re-snapshots `~/.sf/` into `<dataDir>/orgs-snapshot.json` so the MCP child (running in a sandbox that can't read `~/.sf/` directly) sees the new aliases / default-org. This command does NOT touch the graph or MCP config; it only refreshes the alias snapshot.
+4. `get_ingest_job` only returns historical CLI runs the MCP process happened to observe in-memory; it has no relationship to `start_ingest_job` anymore. Use it only if the user asks about a prior run.
+5. Call `freshness_report` to surface dead/stale metadata in the org itself (not the graph) — Apex classes/Flows/LWCs/objects that haven't been touched in months. This explains _what content might be old_ even after the graph is refreshed.
+6. Bucket the `freshness_report` output into hot / current / stale / dead and call out the worst offenders.
+
+## Visualization
+
+**No diagram.** This skill is about timestamps and commands, not topology. Render a tight markdown checklist instead:
+
+```
+- Last ingest: 2024-05-01T08:12:33Z
+- Age: 13 days  (STALE)
+- Recommended action: refresh now
+- Command: `sfgraph ingest --org prod`
+- Then re-run the analysis you started.
+```
+
+Pair it with the bucketed freshness table from `freshness_report` for the org-side picture.
+
+## Staleness check
+
+`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
+
+- **Graph staleness** — checklist above.
+- **Refresh command** — fenced one-liner the user can copy.
+- **Org-side freshness** — bucketed table from `freshness_report` (hot / current / stale / dead with counts and top items).
+- **Suggested next skill** — `sf-dead-code-audit` if the dead bucket is large.
+
+## Don't
+
+- Do not run the ingest yourself via the shell. The user must execute `sfgraph ingest`; `start_ingest_job` returns the command, not a running job.
+- Do not conflate graph staleness (ingest timestamp) with org-side freshness (metadata last-modified) — they're independent signals.
+- Do not draw a Mermaid diagram for this skill. Timestamps + commands beat shapes.
+- Do not silently skip `freshness_report` even when the graph is fresh — org-side rot is still useful signal.

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

@@ -0,0 +1,71 @@
+---
+name: sf-omnistudio-migration-audit
+description: Inventory Vlocity-CMT vs OmniStudio-on-Core assets and verify CANONICAL_OF mirror counts.
+triggers:
+  - "omnistudio migration"
+  - "vlocity to omnistudio"
+  - "CMT migration"
+  - "omnistudio audit"
+  - "migrate from vlocity"
+tools_used:
+  - cross_org_diff
+  - staleness_check
+---
+
+# sf-omnistudio-migration-audit
+
+Use when the user is mid-migration from Vlocity CMT (managed package) to OmniStudio on Core and wants to verify parity by category.
+
+## 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`.
+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.
+   - **partial** — twin exists but `CANONICAL_OF` missing or one-side has additional logic nodes.
+   - **not started** — CMT asset has no Core twin.
+6. Render a Mermaid bar chart per category: CMT / Core / Canonical / Unmirrored.
+
+## Visualization
+
+Render a **`flowchart LR`** parity diagram. Left subgraph is Vlocity-CMT; right is OmniStudio-on-Core; `CANONICAL_OF` edges connect mirrored pairs. Unmirrored nodes hang off either side with a dashed border.
+
+```
+flowchart LR
+  subgraph CMT
+    D1[vlocity_cmt__DataRaptor:Foo]
+  end
+  subgraph Core
+    D2[OmniDataTransform:Foo]
+  end
+  D1 -. CANONICAL_OF .-> D2
+  D3[vlocity_cmt__OmniScript:Bar]:::unmirrored
+  classDef unmirrored stroke-dasharray:4 4,fill:#fdd
+```
+
+For orgs with >50 CMT assets, swap the diagram for a per-category counts table — the parity story is the counts, not the topology.
+
+## Staleness check
+
+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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Scope** — one org or two orgs compared.
+- **Per-category table** — DataRaptor / IntegrationProcedure / OmniScript / VlocityCard rows with the five counts above.
+- **Buckets** — fully migrated / partial / not started, each as a bulleted list of asset names.
+- **Mermaid bar chart** — embedded.
+- **Recommended next step** — typically a focused `sf-cross-layer-trace` on the highest-risk unmirrored asset.
+
+## Don't
+
+- Do not include non-OmniStudio Vlocity assets (e.g. `vlocity_cmt__Pricebook2`) in migration counts.
+- Do not auto-create `CANONICAL_OF` edges. This is a read-only audit.
+- Do not assume name match implies semantic equivalence; require the `CANONICAL_OF` edge before counting as migrated.
+- Do not modify or deploy any OmniStudio metadata.

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

@@ -0,0 +1,66 @@
+---
+name: sf-schema-overview
+description: Build an ERD-style overview of one or more SObjects and how they relate across Apex, Flow, and LWC layers.
+triggers:
+  - "show the schema"
+  - "object model"
+  - "data model"
+  - "how are these objects related"
+  - "ERD"
+  - "field map for"
+tools_used:
+  - analyze_field
+  - trace_upstream
+  - trace_downstream
+  - staleness_check
+---
+
+# sf-schema-overview
+
+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.
+
+## 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.
+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.
+
+## Visualization
+
+Render an **`erDiagram`**. One entity per object; relationship cardinality from Lookup (`||--o{`) vs MasterDetail (`||--|{`). Fall back to a **`flowchart LR`** if the client renderer doesn't support `erDiagram`.
+
+```
+erDiagram
+  Account ||--o{ Contact : "has"
+  Account ||--o{ Opportunity : "has"
+  Opportunity }o--|| Pricebook2 : "uses"
+```
+
+When the schema has >20 entities, prune to the focal object's two-hop neighbourhood — a sprawling ERD is unreadable. State that you pruned, and offer to expand on request.
+
+## Staleness check
+
+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.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Focal objects** — the object(s) the diagram is centred on.
+- **Entities** — one bullet per object with its key fields (highest-arity fields first).
+- **Relationships** — table: source object / target object / type (Lookup/MasterDetail) / required.
+- **Cross-layer consumers** — bullets per object naming the Apex classes, Flows, and LWCs that touch it.
+- **Mermaid ERD** — embedded.
+- **Suggested next skill** — typically `sf-cross-layer-trace` for any field the user asks about in detail.
+
+## Don't
+
+- Do not include every field on every object — pick highest-arity or user-named ones. ERDs that list 200 fields are useless.
+- Do not infer relationships from name match; only use edges from `trace_downstream`/`trace_upstream`.
+- Do not modify the schema. This is pure read.
+- Do not skip the cross-layer consumer summary — the value of this skill over a raw ERD is the layer context.