@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/dx-app-analytics-use/SKILL.md

@@ -1,135 +0,0 @@
----
-name: dx-app-analytics-use
-description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use querying-soql), or Data Cloud query/search (use retrieving-datacloud)."
-metadata:
-  version: "1.0"
-  minApiVersion: "56.0"
----
-
-# App Analytics
-
-## When This Skill Owns the Task
-
-Use `dx-app-analytics-use` when the work involves:
-- Creating `AppAnalyticsQueryRequest` records via the REST/sObject API
-- Configuring `AppAnalyticsSettings` via the Metadata API (simulation mode, opt-out)
-- Understanding the query lifecycle: New → Pending → Complete → Expired → Failed
-- Choosing between dataType values: PackageUsageSummary, PackageUsageLog, SubscriberSnapshot
-- File format and compression options for analytics downloads
-- Time-range filtering with startTime, endTime, availableSince
-- Troubleshooting failed or expired analytics queries
-
-Delegate elsewhere when the user is:
-- Running standard CRM SOQL queries → querying-soql
-- Working with Data Cloud SQL or DMOs → retrieving-datacloud
-- Building reports/dashboards on standard objects → reporting skills
-- Deploying or retrieving generic metadata XML → deploying-metadata / retrieving-metadata
-
----
-
-## Available Types
-
-### AppAnalyticsQueryRequest (REST/sObject API)
-
-An asynchronous query request that ISV partners use to retrieve usage analytics data for their managed packages from the ISV Intelligence Data Lake. Records are created via `POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest` and polled via `GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id>`. The system processes the query and provides a presigned download URL upon completion.
-
-**Fields (14 properties):**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| DataType | string (filterable) | Type of analytics data. Values: `PackageUsageSummary`, `PackageUsageLog`, `SubscriberSnapshot` |
-| RequestState | string (filterable) | Processing status. Values: `New`, `Pending`, `Complete`, `Expired`, `Failed`, `NoData`, `Delivered` |
-| StartTime | string | Start of time range for requested data |
-| EndTime | string | End of time range. Should be set on an hour boundary |
-| AvailableSince | string | Limits query to data indexed after this time (inclusive). Use for incremental retrieval |
-| PackageIds | string | Comma-delimited list of managed package IDs (033-prefix) |
-| OrganizationIds | string | Comma-delimited list of subscriber org IDs to filter results |
-| DownloadUrl | string | Presigned URL for downloading results. Populated when RequestState is Complete |
-| DownloadSize | long | Size in bytes of the result data file |
-| DownloadExpirationTime | string | Time at which the download URL expires |
-| FileType | string (filterable) | Output format. Values: `csv`, `parquet` |
-| FileCompression | string (filterable) | Compression. Values: `none`, `gzip`, `snappy` |
-| QuerySubmittedTime | string | Time the query was submitted to the Data Lake |
-| ErrorMessage | string | Diagnostic message for failed queries |
-
-### AppAnalyticsSettings (Metadata API)
-
-Configuration settings for ISV App Analytics that control simulation mode and opt-out behavior. Deployed via the Metadata API (`sf project deploy`) or Tooling API.
-
-**Fields (2 properties):**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| enableSimulationMode | boolean (filterable) | When true, allows querying sample usage logs for integration testing without real subscriber data |
-| enableAppAnalyticsOptOut | boolean (filterable) | When true, opts this subscriber org out of AppExchange App Analytics data collection |
-
----
-
-## Request Lifecycle
-
-```text
-New → Pending → Complete → (download within expiration window)
-                         → Expired (download URL no longer valid)
-                         → Delivered (download confirmed received)
-         → Failed (check errorMessage)
-         → NoData (no matching records for the criteria)
-```
-
----
-
-## Common Patterns
-
-### Query Package Usage Summary (last 7 days)
-
-Create a record via the REST API:
-
-```bash
-POST /services/data/v60.0/sobjects/AppAnalyticsQueryRequest
-Content-Type: application/json
-
-{
-  "DataType": "PackageUsageSummary",
-  "StartTime": "<7-days-ago>T00:00:00Z",
-  "EndTime": "<today-on-hour-boundary>T00:00:00Z",
-  "PackageIds": "033XXXXXXXXXXXX",
-  "FileType": "csv",
-  "FileCompression": "gzip"
-}
-```
-
-Poll the record via GET until `RequestState` reaches `Complete`, then download from `DownloadUrl`.
-
-### Incremental Data Retrieval
-
-Set `AvailableSince` to the timestamp of your last successful query completion to avoid re-downloading data you already have.
-
-### Enable Simulation Mode for Testing
-
-Deploy `AppAnalyticsSettings` via Metadata API with `enableSimulationMode: true` to query sample data without real subscribers.
-
----
-
-## High-Signal Gotchas
-
-- AppAnalyticsQueryRequest is an **sObject** — create and poll records via the REST Data API (`/sobjects/AppAnalyticsQueryRequest`), NOT via Metadata API XML deployment.
-- AppAnalyticsQueryRequest does NOT have Apex triggers and does NOT flow through custom objects or Flows.
-- Download URLs expire — always check `DownloadExpirationTime` before attempting download.
-- `EndTime` should be set on an hour boundary for consistent results.
-- `AvailableSince` is inclusive — data indexed at exactly that timestamp will be included.
-- `PackageIds` uses 033-prefix IDs, not 04t (package version) IDs.
-- Data is processed asynchronously by the ISV Intelligence Data Lake infrastructure. There is no synchronous query option.
-- `FileType: parquet` with `FileCompression: snappy` gives optimal performance for large datasets.
-
----
-
-## Output Format
-
-```text
-Analytics task: <query / configure / troubleshoot>
-Data type: <PackageUsageSummary / PackageUsageLog / SubscriberSnapshot>
-Package IDs: <033-prefixed IDs>
-Time range: <startTime> to <endTime>
-File format: <csv|parquet> / <none|gzip|snappy>
-Request state: <current state>
-Next step: <poll for completion / download / investigate failure>
-```

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

@@ -1,66 +0,0 @@
-# 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

@@ -1,208 +0,0 @@
----
-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."
-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

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