@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/TRANSCRIPT.md

@@ -0,0 +1,124 @@
+# Validation Transcript: Business Internet Plus Bundle Deployment
+
+This transcript captures the skills used and the planning/execution process to validate deployment readiness for the `business-internet-plus-bundle` sample.
+
+---
+
+## Task Summary
+
+Validate deployment for the `Business Internet Plus` bundle and document the process in a new `examples` folder under `deploying-omnistudio-datapacks`.
+
+---
+
+## Skills Used
+
+### 1) `deploying-omnistudio-datapacks` (Primary)
+
+**Why used:** The task is Vlocity Build deployment validation for DataPacks (`validateLocalData`, deployment preflight, and scope verification).
+
+**Applied from skill guidance:**
+
+- Validate-first workflow (`validateLocalData` before deploy).
+- Required context checks (tooling readiness, org auth, deterministic scope).
+- Job-file driven validation with explicit manifest targeting.
+
+### 2) `deploying-metadata` (Supporting)
+
+**Why used:** Deployment preflight practices overlap with org readiness checks.
+
+**Applied from skill guidance:**
+
+- Confirm CLI and org context before execution.
+- Capture result and safe next action in a completion block.
+
+### 3) `modeling-omnistudio-epc-catalog` (Supporting)
+
+**Why used:** The target bundle payload was generated as an EPC Product2 offer bundle sample, so EPC-specific structure and guardrails were validated before deployment checks.
+
+**Applied from skill guidance:**
+
+- Confirm offer markers (`SpecificationType=Offer`, `SpecificationSubType=Bundle`).
+- Confirm root PCI + child PCI composition.
+- Confirm companion bundle artifacts and GlobalKey consistency.
+
+---
+
+## Planning Process (Executed)
+
+1. Locate the `business-internet-plus-bundle` payload and confirm all companion JSON artifacts exist.
+2. Run preflight checks for deployment tooling:
+   - `vlocity` CLI availability.
+   - Salesforce org auth context for target alias.
+3. Run file-level integrity checks:
+   - JSON parse for all bundle artifacts.
+   - Product2 + PCI + attribute consistency checks.
+4. Create a deterministic Vlocity Build job file in this example folder for reproducible validation.
+5. Execute `validateLocalData` against the bundle scope and record outcome.
+6. Summarize result, findings, and safe next actions.
+
+---
+
+## Execution Log
+
+### A) Bundle discovery
+
+- Located bundle payload at:
+  - `skills/modeling-omnistudio-epc-catalog/examples/business-internet-plus-bundle`
+- Confirmed 11 companion JSON files exist (`DataPack`, `AttributeAssignments`, `ProductChildItems`, pricing files, orchestration/decomposition files, overrides, and parent keys).
+
+### B) Tooling and org preflight
+
+- `vlocity` global binary check: **not installed globally** (`command not found`).
+- `npx vlocity` check: **available** (`Vlocity Build v1.17.21`).
+- `sf org list --json`: org context available; target alias `sample-uat` is connected.
+
+### C) File-level integrity validation
+
+Local JSON validation checks passed:
+
+- Missing files: `0`
+- JSON parse errors: `0`
+- Product identity checks: name and product code match expected values.
+- Offer checks: `SpecificationType=Offer` and `SpecificationSubType=Bundle`.
+- Composition checks: `1` root PCI and `3` child PCI records.
+- Attribute checks: `3` attribute assignment records.
+- Key integrity checks: PCI parent references match Product2 GlobalKey.
+
+### D) Vlocity validateLocalData execution
+
+Job file used:
+
+- `skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml`
+
+Command:
+
+```bash
+npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml" validateLocalData
+```
+
+Result:
+
+- `ValidateLocalData success: 0 Completed`
+
+Interpretation:
+
+- Validation command executed successfully.
+- `0 Completed` indicates no DataPack records were processed for this scope layout.
+- This is consistent with the sample payload being stored as a documentation/example artifact rather than a standard `vlocity/` expansion deployment path.
+
+---
+
+## Validation Outcome
+
+```text
+DataPack goal: validate deployment readiness
+Source org: N/A
+Target org: sample-uat
+Scope: deploy-business-internet-plus-bundle.yaml + Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
+Result: partial
+Key findings:
+- Bundle JSON payload is internally consistent and structurally valid.
+- Vlocity validateLocalData ran successfully but processed 0 DataPacks in current example-folder scope.
+Next step:
+- Stage the bundle into a standard Vlocity expansion path (for example under `vlocity/Product2/<global-key>/`) and rerun `validateLocalData`, then `packDeploy` and `packGetDiffs`.
+```

package/skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml

@@ -0,0 +1,11 @@
+projectPath: ../../../../
+expansionPath: skills/modeling-omnistudio-epc-catalog/examples/business-internet-plus-bundle
+
+# Deterministic scope for this validation example.
+manifest:
+  - Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
+
+autoUpdateSettings: true
+defaultMaxParallel: 1
+supportHeadersOnly: true
+gitCheck: false

package/skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md

@@ -0,0 +1,142 @@
+# Deployment Transcript: Business Internet Plus Bundle
+
+This transcript captures the skills used plus the planning and execution process for deploying `business-internet-plus-bundle` with Vlocity Build.
+
+---
+
+## Task Summary
+
+Deploy the `Business Internet Plus` Product2 bundle DataPack and document the end-to-end process in `deploying-omnistudio-datapacks/examples`.
+
+---
+
+## Skills Used
+
+### 1) `deploying-omnistudio-datapacks` (Primary)
+
+**Why used:** The task is DataPack deployment orchestration with Vlocity Build commands (`validateLocalData`, `packDeploy`, `packRetry`) and failure triage.
+
+**Applied guidance:**
+
+- Validate-first execution (`validateLocalData` before deployment).
+- Deterministic job file (`projectPath`, `expansionPath`, `manifest`) for reproducible scope.
+- Retry loop and failure interpretation.
+
+### 2) `modeling-omnistudio-epc-catalog` (Supporting)
+
+**Why used:** The deployment target is an EPC Product2 offer bundle sample with Product Child Item dependencies and companion artifacts.
+
+**Applied guidance:**
+
+- Confirmed Product2 offer markers and companion file consistency.
+- Preserved `%vlocity_namespace%` placeholders and stable GlobalKey references.
+
+### 3) `deploying-metadata` (Supporting preflight pattern)
+
+**Why used:** Reused deployment preflight discipline for target org/tooling readiness and concise completion reporting.
+
+---
+
+## Planning Process (Executed)
+
+1. Confirm where the source bundle artifacts were authored.
+2. Stage those artifacts into a standard Vlocity expansion path under `vlocity/Product2/<global-key>/`.
+3. Build a deterministic deploy job file in this example folder.
+4. Run pre-deploy validation (`validateLocalData`).
+5. Run actual deployment (`packDeploy`).
+6. Run retry (`packRetry`) to confirm whether the failure is transient or dependency-blocking.
+7. Capture findings and next safe action.
+
+---
+
+## Execution Details
+
+### A) Staging for deploy
+
+Source payload location:
+
+- `skills/modeling-omnistudio-epc-catalog/examples/business-internet-plus-bundle`
+
+Deploy staging location:
+
+- `vlocity/Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101`
+
+Staged files include:
+
+- `Business-Internet-Plus_DataPack.json`
+- `Business-Internet-Plus_AttributeAssignments.json`
+- `Business-Internet-Plus_ProductChildItems.json`
+- `Business-Internet-Plus_PricebookEntries.json`
+- `Business-Internet-Plus_PriceListEntries.json`
+- `Business-Internet-Plus_ObjectFieldAttributes.json`
+- `Business-Internet-Plus_OrchestrationScenarios.json`
+- `Business-Internet-Plus_DecompositionRelationships.json`
+- `Business-Internet-Plus_CompiledAttributeOverrides.json`
+- `Business-Internet-Plus_OverrideDefinitions.json`
+- `Business-Internet-Plus_ParentKeys.json`
+
+### B) Job file used
+
+- `skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml`
+
+Key settings:
+
+- `projectPath: .`
+- `expansionPath: vlocity`
+- `manifest: Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101`
+
+### C) Commands executed
+
+```bash
+npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" validateLocalData
+
+npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" packDeploy
+
+npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" packRetry
+```
+
+### D) Command outcomes
+
+`validateLocalData`:
+
+- Success (`1 Completed`)
+
+`packDeploy`:
+
+- Auto-settings migration phase completed successfully.
+- Bundle deploy failed with dependency error:
+  - `This DataPack has a reference to another object which was not found -- Product2/21e9dce1-4f89-4f99-a7b2-9cb5d6332101`
+
+`packRetry`:
+
+- Failed with the same missing reference error.
+
+---
+
+## Root Cause
+
+The bundle references child Product2 DataPacks that are not currently present in local expansion scope and/or target org at deploy time.
+
+Missing child Product2 keys confirmed absent from local `vlocity/Product2`:
+
+- `21e9dce1-4f89-4f99-a7b2-9cb5d6332101` (Managed Router)
+- `43f2fd94-6114-449b-a1b4-b8dd7238b202` (Internet Security Suite)
+- `64a06b24-1135-4f2e-95a1-3a5f5822c303` (Static IP Add-On)
+
+---
+
+## Completion Block
+
+```text
+DataPack goal: deploy
+Source org: N/A (local staged payload)
+Target org: sample-uat
+Scope: Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
+Result: failed (dependency missing)
+Key findings:
+- validateLocalData passed (1 completed)
+- packDeploy failed: missing referenced child Product2
+- packRetry failed with same error
+Next step:
+- Stage/deploy the three child Product2 DataPacks first (or include them in manifest), then rerun packDeploy and packRetry.
+```

package/skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml

@@ -0,0 +1,10 @@
+projectPath: .
+expansionPath: vlocity
+
+manifest:
+  - Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
+
+autoUpdateSettings: true
+defaultMaxParallel: 1
+supportHeadersOnly: true
+gitCheck: false

package/skills/deploying-omnistudio-datapacks/references/job-file-template.md

@@ -0,0 +1,42 @@
+# Vlocity Build Job File Template
+
+Use this as a baseline and keep only settings you need to override.
+
+```yaml
+projectPath: .
+expansionPath: vlocity
+
+# Optional: narrow export scope
+queries:
+  - OmniScript
+  - IntegrationProcedure
+  - DataRaptor
+  - FlexCard
+
+# Optional: deterministic targeted scope
+# manifest:
+#   - Product2/<global-key>
+#   - OmniScript/<type>_<subtype>_<language>
+
+# Optional runtime controls
+autoUpdateSettings: true
+defaultMaxParallel: 1
+supportHeadersOnly: true
+gitCheck: false
+```
+
+## Common command patterns
+
+```bash
+# Export
+vlocity -sfdx.username <source> -job <job>.yaml packExport
+
+# Deploy
+vlocity -sfdx.username <target> -job <job>.yaml packDeploy
+
+# Retry
+vlocity -sfdx.username <target> -job <job>.yaml packRetry
+
+# Continue interrupted
+vlocity -sfdx.username <target> -job <job>.yaml packContinue
+```

package/skills/deploying-omnistudio-datapacks/references/troubleshooting-matrix.md

@@ -0,0 +1,24 @@
+# Vlocity Build Troubleshooting Matrix
+
+| Symptom | Quick checks | Typical fix |
+|---|---|---|
+| `No match found for ...` | Is referenced key present in exported folder and target org? | Deploy missing dependency first, then `packRetry` |
+| `Duplicate Results found for ... GlobalKey` | Query target org for duplicate GlobalKey values | Remove duplicates in target, rerun deploy |
+| `Multiple Imported Records ... same Salesforce Record` | Check source for duplicate matching-key combinations | Clean source data, re-export, then redeploy |
+| `No Configuration Found` | Was `packUpdateSettings` run recently? | Run `packUpdateSettings` (or keep `autoUpdateSettings: true`) |
+| `Some records were not processed` | Compare settings and package versions across orgs | Refresh settings in both orgs, then `packRetry` |
+| SASS/template compile errors | Are referenced UI templates exported? | Export missing templates by key and redeploy |
+
+## Retry strategy
+
+1. Run `packRetry`.
+2. Check if error count decreases.
+3. Repeat until error count plateaus.
+4. Fix root data/config issue before further retries.
+
+## Data hygiene checks
+
+```bash
+vlocity -sfdx.username <org> -job <job>.yaml validateLocalData
+vlocity -sfdx.username <org> -job <job>.yaml packGetDiffs
+```

package/skills/developing-agentforce/assets/metadata/http-callout-flow.flow-meta.xml

@@ -12,7 +12,7 @@
 
     Prerequisites:
     1. Named Credential configured for API auth
-    2. sf-integration skill used to create Named Credential
+    2. building-sf-integrations skill used to create Named Credential
 
     Setup Steps:
     1. Replace all {{placeholder}} values

package/skills/developing-agentforce/references/actions-reference.md

@@ -474,7 +474,7 @@ public class WrappedAction {
 
 ### Implementation Steps
 
-1. **Create Named Credential** (via sf-integration skill)
+1. **Create Named Credential** (via building-sf-integrations skill)
 2. **Create HTTP Callout Flow** wrapping the external call
 3. **Reference Flow in Agent Script** with `flow://` target
 
@@ -571,13 +571,13 @@ When building agents with external API integrations, follow this order:
 ┌──────────────────────────────────────────────────────────────┐
 │  INTEGRATION + AGENTFORCE ORCHESTRATION ORDER                │
 ├──────────────────────────────────────────────────────────────┤
-│  1. sf-connected-apps  → Connected App (if OAuth needed)     │
-│  2. sf-integration     → Named Credential + External Service │
-│  3. sf-apex            → @InvocableMethod (if custom logic)  │
-│  4. sf-flow            → Flow wrapper (HTTP Callout / Apex)  │
-│  5. sf-deploy          → Deploy all metadata to org          │
-│  6. sf-ai-agentscript  → Agent with flow:// target           │
-│  7. sf-deploy          → Publish (sf agent publish           │
+│  1. configuring-connected-apps  → Connected App (if OAuth needed) │
+│  2. building-sf-integrations → Named Credential + External Service │
+│  3. generating-apex            → @InvocableMethod (if custom logic)  │
+│  4. generating-flow            → Flow wrapper (HTTP Callout / Apex)  │
+│  5. deploying-metadata          → Deploy all metadata to org          │
+│  6. developing-agentforce  → Agent with flow:// target           │
+│  7. deploying-metadata          → Publish (sf agent publish           │
 │                           authoring-bundle)                  │
 └──────────────────────────────────────────────────────────────┘
 ```

package/skills/fetching-salesforce-docs/README.md

@@ -0,0 +1,66 @@
+# fetching-salesforce-docs
+
+## What it is
+
+`fetching-salesforce-docs` is a **prompt-only skill**.
+
+It gives a practical retrieval playbook for official Salesforce docs on the public web, especially when:
+- `developer.salesforce.com` pages are JS-heavy
+- `help.salesforce.com` pages return shell content
+- `architect.salesforce.com` / `admin.salesforce.com` pages need browser-rendered extraction
+- `lightningdesignsystem.com` pages contain official SLDS guidance
+- the real answer is on a child page, not the guide homepage
+
+## What it is not
+
+This skill does not include:
+- local corpus workflows
+- indexing
+- benchmark workflows
+- any required helper CLI dependency
+- PDF fallback guidance
+
+## Use it for
+
+- official Salesforce docs lookup
+- hard-to-fetch Help articles
+- Apex / API / LWC / Agentforce documentation grounding
+- deciding when to follow child links from broad official guide pages
+- rejecting weak results such as shells, landing pages, and third-party summaries
+
+## Optional utility
+
+A tiny wrapper is available for official Salesforce doc URLs:
+
+```bash
+python3 skills/fetching-salesforce-docs/scripts/extract_salesforce_doc.py \
+  --url "https://help.salesforce.com/s/articleView?id=service.miaw_security.htm&type=5" \
+  --pretty
+```
+
+Behavior:
+- automatically routes `help.salesforce.com` URLs into the dedicated Help extractor
+- supports official Salesforce-owned doc hosts such as `developer.salesforce.com`, `architect.salesforce.com`, `admin.salesforce.com`, `lightningdesignsystem.com`, and other official Salesforce documentation pages
+- supports optional best-effort stealth mode via `--stealth`
+
+Dependencies for the helper scripts live in:
+- `skills/fetching-salesforce-docs/requirements.txt`
+
+The installer sets up an isolated runtime under `~/.claude/.fetching-salesforce-docs-runtime`, installs those Python packages there, and installs the Playwright Chromium browser automatically during install/update.
+
+The underlying Help extractor is also available directly at:
+
+```bash
+python3 skills/fetching-salesforce-docs/scripts/extract_help_salesforce.py \
+  --url "https://help.salesforce.com/s/articleView?id=service.miaw_security.htm&type=5" \
+  --pretty
+```
+
+## Key idea
+
+Keep retrieval:
+- **official-source-first**
+- **HTML-only**
+- **targeted**
+- **child-link aware**
+- **strict about exact concept matching**

package/skills/fetching-salesforce-docs/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: fetching-salesforce-docs
+description: "Official Salesforce documentation retrieval skill. Use when you need authoritative Salesforce docs from developer.salesforce.com, help.salesforce.com, architect.salesforce.com, admin.salesforce.com, or lightningdesignsystem.com, especially when pages are JS-heavy, shell-rendered, or hard to extract with naive fetching. Use to ground answers in official Salesforce sources instead of third-party blogs or summaries. TRIGGER when: user asks for official Salesforce documentation, Apex or API reference, LWC docs, Agentforce docs, setup or help articles, or any doc from a Salesforce-owned domain. DO NOT TRIGGER when: user is asking for a code change, deployment task, or anything not requiring documentation retrieval — use the appropriate sf-* skill instead."
+license: MIT
+metadata:
+  version: "1.1"
+---
+
+# fetching-salesforce-docs
+
+Use this skill to retrieve and ground answers in **official Salesforce documentation on the public web**.
+
+This skill provides a **reliable online retrieval playbook** for Salesforce docs that are hard to fetch, especially `help.salesforce.com`, JS-heavy `developer.salesforce.com`, Lightning Design System docs on `lightningdesignsystem.com`, and other official Salesforce-owned doc pages such as `architect.salesforce.com` and `admin.salesforce.com`.
+
+Optional extraction scripts are available in `scripts/` — see the Reference File Index below.
+
+## Scope
+
+| | |
+|---|---|
+| **In scope** | Official Salesforce doc retrieval: Apex, API, LWC, metadata, Agentforce, setup articles, SLDS, architect/admin guidance |
+| **Out of scope** | Third-party blogs, PDF fallback, local corpus indexing, benchmark workflows, generating code or metadata |
+
+## Required Inputs
+
+Before fetching, identify:
+- The exact concept, identifier, class, method, or feature name being requested
+- The likely doc family (developer docs, help articles, design system, architect/admin)
+
+No additional setup is required to use the retrieval playbook in this skill. The optional extraction scripts require `playwright` — see `requirements.txt`.
+
+## Official Sources Only
+
+Prefer Salesforce-owned documentation sources:
+- `developer.salesforce.com`
+- `help.salesforce.com`
+- `architect.salesforce.com`
+- `admin.salesforce.com`
+- `lightningdesignsystem.com`
+- other official Salesforce documentation pages when Salesforce uses them as the source of truth
+
+Avoid third-party blogs, videos, or summary articles unless the user explicitly asks for them.
+
+Do **not** fall back to PDFs.
+
+## Retrieval Workflow
+
+### 1. Classify the request first
+
+Before fetching anything, identify the likely doc family.
+
+| Family | Typical Source | Use For |
+|---|---|---|
+| Developer docs | `developer.salesforce.com/docs/...` | Apex, APIs, LWC, metadata, Agentforce developer docs |
+| Help docs | `help.salesforce.com/...` | setup, admin, product configuration |
+| Architect/Admin docs | `architect.salesforce.com/...`, `admin.salesforce.com/...` | best practices, patterns, well-architected guidance, admin enablement |
+| Design system docs | `lightningdesignsystem.com/...` | SLDS, Cosmos, design tokens, component and styling guidance |
+| Legacy atlas docs | `developer.salesforce.com/docs/atlas.en-us.*` | older official guide and reference docs |
+
+### 2. Identify the exact concept
+
+Extract the real target before you search:
+- exact API/class/method name
+- exact feature name
+- exact product phrase
+- exact setup concept
+
+Examples:
+- `Lightning Message Service`
+- `Wire Service`
+- `System.StubProvider`
+- `Agentforce Actions`
+- `Messaging for In-App and Web allowed domains`
+
+### 3. Prefer targeted official retrieval
+
+Do **not** broad-crawl Salesforce docs.
+
+Instead:
+1. identify the most likely official guide root or article
+2. if search is needed, restrict it to official Salesforce domains only
+3. fetch that official page
+4. check whether the **exact concept actually appears on the page**
+5. if not, inspect and follow the most relevant **1–3 official child links**
+6. stop once you have grounded evidence
+
+### 4. Do not stop at broad landing pages
+
+A guide landing page is **not enough** unless it clearly contains the exact requested concept.
+
+This is especially important for:
+- LWC docs
+- Agentforce docs
+- broad platform guide homepages
+- help landing pages that link to the real article
+
+### 5. For `developer.salesforce.com`
+
+Use this playbook:
+- start with the most likely official guide root
+- if the page is JS-heavy, prefer browser-rendered extraction
+- check whether the exact concept appears on the page
+- if the concept is missing, inspect official child links and follow the best matching 1–3 links
+- prefer exact concept pages over broad guide roots
+- legacy atlas pages are valid if they are the real official reference for the concept
+
+### 6. For `help.salesforce.com`
+
+Help pages often fail with naive fetching.
+
+Use this playbook:
+- prefer exact `articleView?id=...` URLs when available
+- use browser-rendered extraction when plain fetch returns shell content
+- treat outputs like `Loading`, `Sorry to interrupt`, `CSS Error`, or mostly chrome/navigation text as **failed extraction**, not evidence
+- look for the **real article body**, not just header, nav, or footer text
+- reject shell pages and soft-404 pages such as:
+  - "We looked high and low but couldn't find that page"
+  - generic empty help shells
+- if starting from a nearby guide or hub page, follow linked Help articles until you reach the real article body
+- if extraction still fails after targeted retries, return the best official Help URLs you found and explicitly say that article-body extraction was unsuccessful
+
+## Acceptance Rules
+
+A page is good enough to answer from only when at least one of these is true:
+- the exact identifier appears on the page
+- the exact concept phrase appears on the page
+- multiple query-specific phrases appear in the correct official context
+
+A page is **not** good enough when:
+- it is only a broad landing page
+- it is a shell page with little real article text
+- it is from the wrong product area
+- it does not contain the requested identifier or concept
+- it is a third-party explanation when an official page should exist
+
+## Rejection Rules
+
+Reject these as final evidence:
+- broad guide homepages without the exact concept
+- release notes when a concept/reference page is expected
+- admin blog posts when developer docs are requested
+- third-party blogs when official docs are available
+- shell-rendered pages with no real article body
+- pages whose titles sound right but whose body does not contain the requested concept
+
+## Grounding Requirements
+
+When answering, include:
+1. guide/article title
+2. exact official URL
+3. source type:
+   - developer doc page
+   - atlas reference page
+   - help article page
+4. any caveat if extraction was partial or browser-rendered
+
+If evidence is weak, say so plainly.
+
+## Examples
+
+### Example: Lightning Message Service
+Do **not** stop at the general LWC guide root.
+Find the exact LWC page for Lightning Message Service or follow the most relevant child links from the LWC docs until the exact concept appears.
+
+### Example: Wire Service
+Do **not** answer from the LWC homepage unless `Wire Service` is actually present there.
+Follow the relevant child doc page for wire service or wire adapters.
+
+### Example: Agentforce Actions
+Do **not** answer from a broad Agentforce landing page or a blog post.
+Find the official Agentforce developer page for actions, or follow the best matching child pages from the official Agentforce docs.
+
+### Example: Messaging for In-App and Web allowed domains
+Prefer official Help articles and browser-rendered extraction.
+Reject generic help shells. Follow linked Help articles from nearby official messaging docs if needed.
+
+### Example: System.StubProvider
+Prefer the official Salesforce reference/developer page where the exact identifier appears.
+Do not substitute a broader Apex landing page if the identifier is absent.
+
+## Non-Goals
+
+This skill should **not**:
+- maintain a local documentation corpus
+- rely on a local index
+- use PDF fallback
+- run benchmark workflows
+- depend on repo-specific scripts to be useful
+
+## Output Expectations
+
+For each retrieval, include:
+1. Guide or article title
+2. Exact official URL
+3. Source type (developer doc page / atlas reference page / help article page)
+4. Any caveat if extraction was partial or browser-rendered
+
+If evidence is weak, say so plainly rather than forcing an answer.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `scripts/extract_salesforce_doc.py` | Use to fetch any official Salesforce doc URL; automatically routes `help.salesforce.com` into the dedicated Help extractor and supports browser-rendered extraction for all Salesforce-owned doc hosts |
+| `scripts/extract_help_salesforce.py` | Use directly when targeting `help.salesforce.com` `articleView` URLs; use when the wrapper is not appropriate |
+| `scripts/runtime_bootstrap.py` | Imported by the extraction scripts to resolve the isolated fetching-salesforce-docs Python runtime and Playwright browser path; not called directly |
+| `requirements.txt` | Lists Python dependencies (`playwright`, `playwright-stealth`) needed to run the extraction scripts |

package/skills/fetching-salesforce-docs/requirements.txt

@@ -0,0 +1,2 @@
+playwright
+playwright-stealth