@salesforce/afv-skills 1.24.0 → 1.26.0

package/skills/dx-org-permission-set-assign/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: dx-org-permission-set-assign
+description: "ALWAYS USE THIS SKILL to assign permission sets to org users. Assign one or more permission sets to org users using the sf org assign permset command. TRIGGER when the user asks to assign, grant, give, add, or apply permission sets to users, admins, specific orgs, or specific users. Supports granting permissions, giving access, and adding permission sets to default admin or specific users via --on-behalf-of. DO NOT TRIGGER for listing permission sets or checking user permissions."
+compatibility: Salesforce CLI (sf) v2+
+metadata:
+  version: "1.0"
+---
+
+# dx-org-permission-set-assign
+
+Assigns one or more permission sets to org users using `sf org assign permset`. Handles all variants: default admin user, specific org targets, multiple permission sets, and assignment to specific users.
+
+---
+
+## ⚠️ Tool Restrictions
+
+**Use ONLY the Bash tool** to execute `sf org assign permset`. Do NOT use MCP tools like `assign_permission_set` — ignore them completely.
+
+---
+
+## Scope
+
+- **In scope**: Assigning permission sets to users via `sf org assign permset`
+- **Out of scope**: Creating permission sets (use `platform-permission-set-generate`), listing permission sets, checking user permissions
+
+---
+
+## Required Inputs
+
+Infer from the user's request:
+
+- **Permission set name(s)**: Extract from user message (can be multiple)
+- **Target org**: Use default unless specific alias/username mentioned
+- **Target user(s)**: Default is org's default admin user; use `--on-behalf-of` if specific users mentioned
+
+---
+
+## Workflow
+
+1. Match user request to command in table below
+2. Execute via Bash tool: `sf org assign permset` with appropriate flags and `--json` flag
+3. Return result
+
+If error occurs, check the `failures` array in JSON output for details.
+
+### Command Decision Table
+
+| User intent | Execute via Bash tool |
+|-------------|---------|
+| Assign one permission set to default admin | `sf org assign permset --name <PermSetName> --json` |
+| Assign multiple permission sets to default admin | `sf org assign permset --name <PermSet1> --name <PermSet2> --json` |
+| Assign to specific org | `sf org assign permset --name <PermSetName> --target-org <alias> --json` |
+| Assign to specific user(s) | `sf org assign permset --name <PermSetName> --on-behalf-of <username1> --on-behalf-of <username2> --json` |
+| Assign multiple sets to specific users | `sf org assign permset --name <PermSet1> --name <PermSet2> --on-behalf-of <username1> --on-behalf-of <username2> --json` |
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always use `--json` flag | Provides structured output for reliable parsing and error handling |
+| Permission set names are case-sensitive | Use exact API names as they appear in the org |
+| Multiple `--name` flags can be combined in one command | More efficient than separate commands per permission set |
+| Multiple `--on-behalf-of` flags assign to multiple users | Batch assignment in single command; processed sequentially to avoid auth file collisions |
+| Use CLI username aliases, not Salesforce User.Alias field | The `--target-org` and `--on-behalf-of` flags expect CLI aliases set via `sf alias set`, not the User object's Alias field |
+| Duplicate assignments are idempotent | Re-assigning an already-assigned permission set succeeds silently |
+| Partial success is possible | Command can return both successes and failures in one run; non-zero exit code if any failures |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Permission set name with spaces | Enclose in double quotes: `--name "Permission Set Name"` |
+| "PermissionSet not found" error | Verify permission set exists in target org; check for typos in name |
+| Assignment succeeds but user doesn't see permissions | Check `<hasActivationRequired>` in permission set metadata — may need manual activation in Setup |
+| "User not found" error | Username/alias doesn't exist in target org — verify with `sf org display user --target-org <alias>` |
+| Partial success (some users succeed, others fail) | Check JSON output — command returns both `successes` and `failures` arrays; exit code will be non-zero if any failures occurred |
+
+---
+
+## Output Expectations
+
+The command returns JSON output with status code and result details.
+
+See `examples/success_output.json` and `examples/error_output.json` for response structures.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `examples/success_output.json` | To understand successful assignment response structure |
+| `examples/error_output.json` | To handle common error scenarios |
+| `references/cli_flags.md` | For detailed explanation of all available flags |

package/skills/dx-org-permission-set-assign/examples/error_output.json

@@ -0,0 +1,19 @@
+{
+  "status": 1,
+  "result": {
+    "successes": [],
+    "failures": [
+      {
+        "name": "user1@my.org",
+        "message": "No PermissionSet named DreamHoue found",
+        "details": [
+          {
+            "message": "No PermissionSet named DreamHoue found",
+            "errorCode": "INVALID_CROSS_REFERENCE_KEY",
+            "fields": []
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/dx-org-permission-set-assign/examples/success_output.json

@@ -0,0 +1,16 @@
+{
+  "status": 0,
+  "result": {
+    "successes": [
+      {
+        "name": "admin@example.com",
+        "value": "PermSet1"
+      },
+      {
+        "name": "admin@example.com",
+        "value": "PermSet2"
+      }
+    ],
+    "failures": []
+  }
+}

package/skills/dx-org-permission-set-assign/references/cli_flags.md

@@ -0,0 +1,68 @@
+# CLI Flags Reference
+
+Complete reference for `sf org assign permset` command flags.
+
+## Required Flags
+
+| Flag | Alias | Description | Example |
+|------|-------|-------------|---------|
+| `--name` | `-n` | Permission set to assign (can be repeated) | `--name MyPermSet` |
+| `--target-org` | `-o` | Username or alias of the target org (required unless default is set) | `--target-org my-scratch` |
+
+## Optional Flags
+
+| Flag | Alias | Description | Example |
+|------|-------|-------------|---------|
+| `--on-behalf-of` | `-b` | Username or alias to assign the permission set to (can be repeated) | `--on-behalf-of user1@my.org` |
+| `--api-version` | | Override the API version used for API requests | `--api-version 66.0` |
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Format output as JSON (ALWAYS use this) |
+
+## Usage Patterns
+
+### Single Permission Set to Default Admin
+
+```bash
+sf org assign permset --name MyPermSet --json
+```
+
+### Multiple Permission Sets to Default Admin
+
+```bash
+sf org assign permset --name PermSet1 --name PermSet2 --json
+```
+
+### Assign to Specific Org
+
+```bash
+sf org assign permset --name MyPermSet --target-org my-scratch --json
+```
+
+### Assign to Specific Users
+
+```bash
+sf org assign permset --name MyPermSet --on-behalf-of user1@my.org --on-behalf-of user2@my.org --json
+```
+
+### Combined: Multiple Sets, Multiple Users, Specific Org
+
+```bash
+sf org assign permset \
+  --name PermSet1 \
+  --name PermSet2 \
+  --on-behalf-of user1@my.org \
+  --on-behalf-of user2@my.org \
+  --target-org my-scratch \
+  --json
+```
+
+## Important Notes
+
+- **Multiple Values**: Use multiple `--name` or `--on-behalf-of` flags rather than comma-separated values
+- **Spaces in Names**: Enclose permission set names with spaces in double quotes: `--name "Permission Set Name"`
+- **Default Behavior**: Without `--on-behalf-of`, assigns to the org's default admin user
+- **Processing**: Multiple users are processed sequentially to avoid auth file collisions

package/skills/experience-cms-brand-apply/SKILL.md

@@ -30,7 +30,7 @@ Universal skill for searching, extracting, and applying CMS brand guidelines to
 
 ## Before You Start
 
-**CRITICAL: You must retrieve brand instructions BEFORE generating or modifying any brand.**
+**CRITICAL: You must retrieve brand instructions BEFORE applying any brand.**
 
 When a user requests branded content:
 

package/skills/experience-ui-bundle-app-coordinate/SKILL.md

@@ -3,7 +3,7 @@ name: experience-ui-bundle-app-coordinate
 description: "MUST activate when the user wants to build, create, or generate a React application, React app, web application, single-page application (SPA), or frontend application — even if no project files exist yet. MUST also activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. Do NOT use for Lightning Experience apps with custom objects (use platform-lightning-app-coordinate). Do NOT use for single-concern edits to an existing page (use experience-ui-bundle-frontend-generate)."
 metadata:
   version: "1.0"
-  related-skills: experience-ui-bundle-metadata-generate, experience-ui-bundle-features-generate, experience-ui-bundle-salesforce-data-access, experience-ui-bundle-frontend-generate, experience-ui-bundle-agentforce-client-generate, experience-ui-bundle-file-upload-generate, experience-ui-bundle-deploy, experience-ui-bundle-site-generate, experience-ui-bundle-custom-app-generate
+  relatedSkills: experience-ui-bundle-metadata-generate, experience-ui-bundle-features-generate, experience-ui-bundle-salesforce-data-access, experience-ui-bundle-frontend-generate, experience-ui-bundle-agentforce-client-generate, experience-ui-bundle-file-upload-generate, experience-ui-bundle-deploy, experience-ui-bundle-site-generate, experience-ui-bundle-custom-app-generate
 ---
 
 # Building a UI Bundle App
@@ -42,7 +42,7 @@ Build a complete, deployable Salesforce React UI bundle application from a natur
 
 ### Phase 1: Scaffolding (Foundation)
 
-```
+```text
 UI Bundle scaffold (sf template generate ui-bundle)
     v
 Install dependencies (npm install)
@@ -56,7 +56,7 @@ Creates the UI bundle directory structure, meta XML, and optional routing/header
 
 ### Phase 2: Features (Optional)
 
-```
+```text
 Search project code (src/) for existing implementations
     v
 Install dependencies (npm install)
@@ -72,21 +72,25 @@ Installs pre-built, tested feature packages. Skip if the app requires no pre-bui
 
 ### Phase 3: Data Access (Backend Wiring)
 
-```
-Acquire schema (npm run graphql:schema)
+```text
+Ground every entity/field against the org (per experience-ui-bundle-salesforce-data-access)
     v
-Look up entity schema (graphql-search.sh, max 2 runs)
+Generate queries/mutations FROM the verified names (never from guessed fields)
     v
-Generate queries/mutations (use verified field names, @optional on all record fields)
+Generate types (npm run graphql:codegen) and wire into components
     v
 Validate and test (npx eslint, ask user before testing mutations)
 ```
 
-Sets up the data layer using `@salesforce/sdk-data`. GraphQL is preferred for record operations; REST for Connect, Apex, or UI API endpoints.
+Sets up the data layer using the **`@salesforce/platform-sdk`** Data SDK (`createDataSDK().graphql`).
+GraphQL is preferred for record operations; REST for Connect, Apex, or UI API endpoints. **The
+`experience-ui-bundle-salesforce-data-access` skill owns the grounding + authoring workflow — load it and follow
+it; do not substitute a local-schema grep or guessed field names.** Grounding happens against the
+**live org**, so it does not require a local `schema.graphql` to be present.
 
 ### Phase 4: UI (Frontend)
 
-```
+```text
 Layout, navigation, header, and footer (appLayout.tsx)
     v
 Pages (routed views)
@@ -98,7 +102,7 @@ Builds the React UI. References the data layer from Phase 3 and the features fro
 
 ### Phase 5: Integrations (Optional)
 
-```
+```text
 Agentforce chat widget (if requested)
 File upload API (if requested)
 ```
@@ -107,7 +111,7 @@ These are independent and can be executed in parallel if both are needed.
 
 ### Phase 6: Deployment
 
-```
+```text
 Org authentication
     v
 Pre-deploy UI bundle build (npm install + npm run build)
@@ -132,7 +136,7 @@ Choose **one** of the following based on the app's audience:
 
 #### Phase 7a: Experience Site (External)
 
-```
+```text
 Resolve site properties (siteName, appDevName, etc.)
     v
 Generate site metadata (Network, CustomSite, DigitalExperience)
@@ -144,7 +148,7 @@ Creates the Digital Experience site that hosts the UI bundle. Use when the user
 
 #### Phase 7b: Custom Application (Internal)
 
-```
+```text
 Resolve app properties (appName, appNamespace, appLabel)
     v
 Generate CustomApplication metadata (applications/*.app-meta.xml)
@@ -172,9 +176,16 @@ Creates a Custom Application entry in the Lightning App Launcher. Use when the a
 6. Determine if an Experience Site is needed
 7. Identify external domains for CSP registration
 
+> **The plan MUST contain an explicit grounding step before any query authoring.** Do not list
+> guessed object/field names as settled facts and defer verification to codegen. The data-access
+> portion of the plan must read: "verify these entities/fields against the org (via
+> `experience-ui-bundle-salesforce-data-access`), then author queries from the verified names." A plan that
+> authors queries first and codegens later is the failure mode that produces guessed fields and
+> hand-stubbed types — do not emit it.
+
 **Output: Build Plan**
 
-```
+```text
 UI Bundle App Build Plan: [App Name]
 
 SCAFFOLDING:
@@ -187,8 +198,9 @@ FEATURES:
 
 DATA ACCESS:
 - Objects: [Salesforce objects to query/mutate]
-- Queries: [list of GraphQL queries needed]
-- REST endpoints: [Apex REST or Connect API calls, if any]
+- Grounding: [verify each object + its fields against the org via experience-ui-bundle-salesforce-data-access BEFORE authoring — list the objects/fields to confirm, not assumed-correct names]
+- Queries: [GraphQL queries to author FROM the verified names]
+- REST endpoints: [only where GraphQL/uiapi genuinely cannot cover it — not as a fallback for fields that were hard to verify]
 
 UI:
 - Layout: [description of app shell/navigation]
@@ -245,7 +257,7 @@ Execute each phase sequentially. Complete all steps within a phase before moving
 
 **Phase 3 -- Data Access** (skip if no Salesforce data needed)
 - 1. Load skill: Invoke `experience-ui-bundle-salesforce-data-access`
-- 2. Execute: Fetch schema, look up entities, generate queries/mutations, wire into components
+- 2. Execute: **Ground entities/fields against the org first** (per the skill), then author queries/mutations **from the verified names**, run codegen, wire into components. Never guess fields or hand-edit generated types.
 - 3. Verify: Run `npx eslint` on files with GraphQL queries
 - 4. Checkpoint: Data layer ready -- proceed to Phase 4
 
@@ -283,7 +295,7 @@ Execute each phase sequentially. Complete all steps within a phase before moving
 
 After all phases complete, present a build summary:
 
-```
+```text
 UI Bundle App Build Complete: [App Name]
 
 PHASES COMPLETED:
@@ -314,7 +326,7 @@ Before presenting the build as complete, verify:
 - [ ] **Lint passes**: `npx eslint src/` reports 0 errors
 - [ ] **No boilerplate**: All placeholder text, default titles, and template content has been replaced
 - [ ] **Navigation works**: `appLayout.tsx` has real nav items matching created pages
-- [ ] **Data layer wired**: Components use `@salesforce/sdk-data` (if data access phase was executed)
+- [ ] **Data layer wired**: Components use the `@salesforce/platform-sdk` Data SDK (`createDataSDK().graphql`), with all entities/fields grounded against the org — not guessed (if data access phase was executed)
 - [ ] **CSP registered**: All external domains have CSP Trusted Site metadata (if applicable)
 
 ---

package/skills/experience-ui-bundle-file-upload-generate/SKILL.md

@@ -34,7 +34,7 @@ npm install @salesforce/ui-bundle-template-feature-react-file-upload
 Dependencies are automatically installed:
 
 - `@salesforce/ui-bundle` (API client)
-- `@salesforce/sdk-data` (data SDK)
+- `@salesforce/platform-sdk` (data SDK; the old `@salesforce/sdk-data` name is dead — see the `experience-ui-bundle-salesforce-data-access` skill)
 
 ## 2. Understand the three upload patterns
 

package/skills/experience-ui-bundle-frontend-generate/implementation/header-footer.md

@@ -100,7 +100,7 @@ export default function AppLayout() {
 
 `AppLayout` is the single shell rendered at the root route. Every page is a child rendered via `<Outlet />`. Placing the header and footer here ensures they appear on every page without touching individual pages or the route registry.
 
-```
+```text
 AppLayout (appLayout.tsx)
 ├── AppHeader          ← renders on every page
 ├── NavigationMenu     ← keep if already present