@salesforce/afv-skills 1.7.5 → 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/deploying-ui-bundle/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: deploying-ui-bundle
 description: "MUST activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the task involves deploying, pushing to an org, or post-deploy setup. Use this skill when deploying a UI bundle app to a Salesforce org. Covers the full deployment sequence: org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Activate when files like *.uibundle-meta.xml or sfdx-project.json exist and the user mentions deploying, pushing, org setup, or post-deploy tasks."
+metadata:
+  version: "1.0"
 ---
 
 # Deploying a UI Bundle

package/skills/developing-agentforce/SKILL.md

@@ -4,7 +4,7 @@ description: "Build, modify, debug, and deploy agents with Agentforce Agent Scri
 license: Apache-2.0
 compatibility: "Requires Agentforce license, API v66.0+, Einstein Agent User"
 metadata:
-  version: "0.5.1"
+  version: "1.0"
   last_updated: "2026-04-08"
 ---
 

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