@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/building-omnistudio-flexcard/references/best-practices.md

@@ -0,0 +1,291 @@
+<!-- Parent: building-omnistudio-flexcard/SKILL.md -->
+
+# FlexCard Best Practices
+
+## Layout Design Patterns
+
+### Single Card
+
+Use for displaying summary information about a single record. Group related fields into logical sections.
+
+```
+┌──────────────────────────────────┐
+│  Header: Record Name             │
+├──────────────────────────────────┤
+│  Section 1: Key Details          │
+│  ┌────────────┬─────────────┐    │
+│  │ Field A    │ Field B     │    │
+│  │ Field C    │ Field D     │    │
+│  └────────────┴─────────────┘    │
+├──────────────────────────────────┤
+│  Section 2: Status               │
+│  ┌──────────────────────────┐    │
+│  │ Status Badge  │ Date     │    │
+│  └──────────────────────────┘    │
+├──────────────────────────────────┤
+│  [Action Button 1] [Action 2]   │
+└──────────────────────────────────┘
+```
+
+**Guidelines:**
+- Limit to 8-10 fields per card to avoid information overload
+- Place the most important fields in the top section
+- Use consistent field alignment (label-left or label-top)
+- Group related fields in the same row when they share context
+
+### Card List
+
+Use for displaying a collection of related records. Each card in the list renders from one item in the data source array.
+
+```
+┌──────────────────────────────────┐
+│  Card 1: Record A                │
+│  Field 1 | Field 2 | [Action]   │
+├──────────────────────────────────┤
+│  Card 2: Record B                │
+│  Field 1 | Field 2 | [Action]   │
+├──────────────────────────────────┤
+│  Card 3: Record C                │
+│  Field 1 | Field 2 | [Action]   │
+└──────────────────────────────────┘
+  Showing 1-3 of 15  [Next →]
+```
+
+**Guidelines:**
+- Keep each list card compact (3-5 fields maximum)
+- Include a clear identifier field (Name, Title, or ID) in each card
+- Add pagination when the data source can return more than 10 records
+- Use consistent card height to maintain visual rhythm
+- Provide a "View All" link when the list is truncated
+
+### Tabbed Card
+
+Use when a single record has multiple contexts worth displaying. Each tab represents a different state with its own data source or field set.
+
+```
+┌──────────────────────────────────┐
+│  [Tab 1: Overview] [Tab 2: History] [Tab 3: Related] │
+├──────────────────────────────────┤
+│  Tab 1 Content                   │
+│  ┌──────────────────────────┐    │
+│  │ Fields for this context  │    │
+│  └──────────────────────────┘    │
+└──────────────────────────────────┘
+```
+
+**Guidelines:**
+- Limit to 3-5 tabs to avoid horizontal overflow
+- Use concise tab labels (1-2 words)
+- Load non-active tab data lazily (on tab selection)
+- Mark the default active tab based on the most common use case
+
+### Flyout Card
+
+Use for progressive disclosure: show a summary, then expand for details on demand.
+
+```
+┌──────────────────────────────────┐
+│  Summary: Key Fields  [▼ More]   │
+└──────────────────────────────────┘
+       ↓ (on click)
+┌──────────────────────────────────┐
+│  Summary: Key Fields  [▲ Less]   │
+├──────────────────────────────────┤
+│  Detail Section                  │
+│  Additional fields, history,     │
+│  related records, etc.           │
+└──────────────────────────────────┘
+```
+
+**Guidelines:**
+- Keep the summary to 2-3 fields that answer "what is this?"
+- Load flyout content on demand, not on initial card render
+- Provide a clear visual indicator for the expand/collapse action
+- Maintain the flyout state if the user scrolls away and returns
+
+---
+
+## Data Source Optimization
+
+### Minimize IP Calls
+
+- Use a single IP that returns all required data rather than multiple IPs for individual fields
+- If the card has multiple data sources, ensure they do not query overlapping data
+- Cache IP responses where the data does not change frequently (use IP caching options)
+
+### Input Parameter Efficiency
+
+- Pass only the parameters the IP needs; do not forward the entire page context
+- Use `{recordId}` as the primary context parameter for record-level cards
+- Avoid passing large objects as input parameters; pass IDs and let the IP query
+
+### Response Structure
+
+- Design IP responses to match the FlexCard's field mapping structure directly
+- Avoid deep nesting in IP responses when the FlexCard only needs top-level fields
+- Use `resultListPath` to point directly to the array node in list-type cards
+
+### Error Handling in Data Sources
+
+- Configure a fallback state for when the IP returns an error
+- Set reasonable timeout values for data source calls
+- Log data source errors for debugging without exposing raw error messages to end users
+
+---
+
+## Action Configuration
+
+### OmniScript Launch Actions
+
+| Consideration | Guidance |
+|---------------|----------|
+| **Parameter mapping** | Map card data fields to OmniScript input fields explicitly |
+| **Pre-population** | Pass enough context for the OmniScript to pre-fill known values |
+| **Return handling** | Refresh the FlexCard data source after the OmniScript completes |
+| **Error states** | Handle the case where the OmniScript fails or is cancelled |
+
+### Navigation Actions
+
+| Consideration | Guidance |
+|---------------|----------|
+| **Record navigation** | Use `{recordId}` merge fields, not hardcoded IDs |
+| **URL navigation** | Use relative URLs for internal Salesforce navigation |
+| **External URLs** | Open in a new tab; warn users if leaving Salesforce |
+| **Conditional navigation** | Disable navigation buttons when the target is invalid |
+
+### Action Button Placement
+
+- Place primary actions at the bottom of the card or in the card header
+- Limit to 2-3 actions per card; use a "More Actions" overflow menu for additional actions
+- Use descriptive button labels ("Submit Claim", not "Submit" or "Go")
+- Visually distinguish primary actions (filled button) from secondary actions (outline button)
+
+---
+
+## SLDS Compliance for Styling
+
+### Required Practices
+
+- Use SLDS design tokens for all colors, spacing, font sizes, and border radii
+- Use `slds-card` or `slds-tile` patterns for card containers
+- Use `slds-grid` and `slds-col` for multi-column layouts within cards
+- Apply `slds-text-heading_small` and related text utilities for consistent typography
+
+### Color Usage
+
+```
+Correct:  Use SLDS token  →  var(--slds-g-color-brand-base-50)
+Wrong:    Hardcoded hex    →  #0176d3
+Wrong:    Hardcoded rgb    →  rgb(1, 118, 211)
+```
+
+- Status indicators: use `slds-badge` with appropriate color variants
+- Background colors: use `slds-box` with `slds-theme_shade` or `slds-theme_default`
+- Text colors: rely on inherited SLDS text colors; override only when necessary
+
+### Spacing
+
+- Use SLDS spacing utilities: `slds-m-top_small`, `slds-p-around_medium`, etc.
+- Maintain consistent spacing between card sections (use `slds-m-bottom_medium`)
+- Do not use pixel values directly; map to the SLDS spacing scale
+
+### Dark Mode Compatibility
+
+- All colors must come from SLDS CSS custom properties (`--slds-g-color-*`)
+- Test card rendering in both light and dark modes
+- Avoid background images that only work on light backgrounds
+- Use `currentColor` for icon fills so they adapt to the text color
+
+---
+
+## Accessibility Requirements
+
+### Interactive Elements
+
+- Every button must have an `aria-label` or visible text label
+- Links must have descriptive text (not "Click here" or "Learn more" without context)
+- Icon-only buttons require `aria-label` describing the action
+
+### Keyboard Navigation
+
+- All action buttons must be focusable via Tab key
+- Buttons must activate on Enter and Space key presses
+- Tab order must follow the visual reading order (top-to-bottom, left-to-right)
+- Flyout expand/collapse must be keyboard accessible
+
+### Screen Reader Support
+
+- Use semantic heading elements for card titles and section headers
+- Data fields should have associated labels readable by screen readers
+- Status indicators must convey meaning through text, not color alone
+- Dynamic content updates should use `aria-live` regions
+
+### Color Contrast
+
+- Text on card backgrounds must meet WCAG 2.1 AA contrast ratio (4.5:1)
+- Interactive element boundaries must have 3:1 contrast against their background
+- Do not use color as the sole method of conveying information (add icons or text)
+
+---
+
+## Performance with Large Data Sets
+
+### Data Volume Guidelines
+
+| Record Count | Recommended Approach |
+|-------------|---------------------|
+| 1-5 | Load all records in a single card list |
+| 6-25 | Load with pagination (show 5-10 per page) |
+| 26-100 | Server-side pagination via IP; load one page at a time |
+| 100+ | Reconsider the UX; use search/filter instead of browsing |
+
+### Rendering Performance
+
+- Limit child card nesting to 2 levels maximum
+- Avoid rendering more than 25 cards simultaneously in a card list
+- Use conditional visibility to hide sections rather than rendering and hiding with CSS
+- Lazy-load tab content and flyout details on user interaction
+
+### Data Source Performance
+
+- Set appropriate IP cache durations for data that does not change frequently
+- Avoid chaining multiple IPs when a single IP can return all needed data
+- Use `resultListPath` to avoid client-side data transformation
+- Monitor IP execution times; optimize IPs that take longer than 2 seconds
+
+---
+
+## Child Card Composition
+
+### When to Use Child Cards
+
+- The parent card displays summary data and the child card shows related detail
+- Multiple cards share a common layout pattern that should be defined once
+- Different sections of a card require independent data sources
+
+### Composition Guidelines
+
+- Pass data from parent to child via input parameters, not global variables
+- Keep child cards self-contained: they should work independently for testing
+- Limit nesting to 2 levels (parent → child → grandchild maximum)
+- Document the parent-child data flow in the FlexCard's description
+
+### Data Flow Pattern
+
+```
+Parent FlexCard
+  ├── Data Source: IP_GetAccountSummary
+  │     └── Passes {AccountId} to child
+  └── Child FlexCard: AccountContacts
+        └── Data Source: IP_GetContacts
+              └── Input: {AccountId} from parent
+```
+
+### Avoiding Composition Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|-------------|---------|----------|
+| Deep nesting (3+ levels) | Performance degradation, hard to debug | Flatten the structure; combine data in the IP |
+| Shared mutable state | Child cards modifying parent data | Use one-way data flow (parent → child only) |
+| Duplicate data sources | Same IP called by parent and child | Consolidate into parent data source; pass results down |
+| Tightly coupled children | Child card cannot function without parent | Design children to accept input parameters and work standalone |

package/skills/building-omnistudio-flexcard/references/data-binding-guide.md

@@ -0,0 +1,311 @@
+<!-- Parent: building-omnistudio-flexcard/SKILL.md -->
+
+# FlexCard Data Binding Guide
+
+## Integration Procedure Data Source Configuration
+
+### Basic IP Binding
+
+The most common FlexCard data source is an Integration Procedure. The data source configuration specifies which IP to call, what input to send, and where to find the results in the IP response.
+
+```json
+{
+  "dataSource": {
+    "type": "IntegrationProcedures",
+    "value": {
+      "ipMethod": "Type_SubType",
+      "inputMap": {
+        "recordId": "{recordId}"
+      },
+      "resultListPath": ""
+    }
+  }
+}
+```
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `type` | Data source type identifier | `"IntegrationProcedures"` (plural, capital P) |
+| `ipMethod` | IP Type and SubType joined by underscore | `"Account_GetSummary"` |
+| `inputMap` | Key-value pairs sent as IP input | `{ "recordId": "{recordId}" }` |
+| `resultListPath` | JSON path to the array node for list-type cards | `"records"` or `""` for root |
+
+### IP Method Naming Convention
+
+The `ipMethod` value combines the IP's Type and SubType fields:
+
+```
+IP Type:    "Account"
+IP SubType: "GetSummary"
+ipMethod:   "Account_GetSummary"
+```
+
+Ensure the IP is active and the Type/SubType match exactly (case-sensitive).
+
+### Input Map Parameters
+
+Input parameters pass context from the FlexCard's hosting environment into the IP:
+
+```json
+{
+  "inputMap": {
+    "recordId": "{recordId}",
+    "accountId": "{Account.Id}",
+    "status": "Active",
+    "limit": 10
+  }
+}
+```
+
+| Syntax | Resolves To |
+|--------|------------|
+| `{recordId}` | The current record's ID from the hosting Lightning page |
+| `{Account.Id}` | A field from a parent FlexCard's data source |
+| `"Active"` | A static/literal value |
+| `{param.customKey}` | A URL parameter or custom context variable |
+
+---
+
+## Field Mapping Syntax
+
+### Basic Field Mapping
+
+Map IP response fields to FlexCard display elements using curly-brace merge syntax:
+
+```
+IP Response JSON:                    FlexCard Merge Field:
+─────────────────                    ─────────────────────
+{ "Name": "Acme Corp" }        →    {Name}
+{ "Status": "Active" }         →    {Status}
+{ "Amount": 50000 }            →    {Amount}
+```
+
+### Nested Field Mapping
+
+Access nested objects in the IP response using dot notation:
+
+```
+IP Response JSON:                         FlexCard Merge Field:
+─────────────────                         ─────────────────────
+{                                    →    {Account.Name}
+  "Account": {                       →    {Account.Industry}
+    "Name": "Acme Corp",            →    {Account.Owner.Name}
+    "Industry": "Technology",
+    "Owner": {
+      "Name": "Jane Smith"
+    }
+  }
+}
+```
+
+### Array Field Mapping
+
+For card list layouts, set `resultListPath` to the array node. Each card in the list renders one item from the array:
+
+```json
+{
+  "dataSource": {
+    "value": {
+      "ipMethod": "Contact_GetRelated",
+      "resultListPath": "contacts"
+    }
+  }
+}
+```
+
+```
+IP Response:                              Each Card Renders:
+────────────                              ──────────────────
+{                                         Card 1: {Name} → "Alice"
+  "contacts": [                                   {Email} → "alice@acme.com"
+    { "Name": "Alice", "Email": "..." },
+    { "Name": "Bob",   "Email": "..." }, Card 2: {Name} → "Bob"
+    { "Name": "Carol", "Email": "..." }          {Email} → "bob@acme.com"
+  ]
+}                                         Card 3: {Name} → "Carol"
+                                                  {Email} → "carol@acme.com"
+```
+
+### Formatted Field Display
+
+Apply formatting to merge fields for display:
+
+| Format Need | Approach |
+|-------------|----------|
+| Currency | Format in the IP response (e.g., return `"$50,000.00"`) or use OmniStudio formatting |
+| Date | Return ISO date from IP; apply date formatting in the FlexCard field configuration |
+| Boolean | Use conditional rendering to show icons or text instead of true/false |
+| Percentage | Return as a number; format display in the FlexCard field |
+
+---
+
+## Conditional Rendering Based on Data
+
+### Field-Level Visibility
+
+Show or hide individual fields based on a data value:
+
+```
+Condition:  {Status} == "Active"
+Action:     Show the "Renewal Date" field
+
+Condition:  {Amount} > 100000
+Action:     Show the "High Value" badge
+
+Condition:  {Email} != null
+Action:     Show the email field (hide when null)
+```
+
+### State-Level Visibility
+
+FlexCards support multiple states. Each state can have visibility conditions:
+
+| State | Visibility Condition | Use Case |
+|-------|---------------------|----------|
+| Default | Always visible | Primary card content |
+| Empty | Data source returns 0 records | "No records found" message |
+| Error | Data source returns error | Error notification |
+| Conditional | Field matches specific value | Status-specific card layout |
+
+### Conditional Rendering Operators
+
+| Operator | Syntax | Example |
+|----------|--------|---------|
+| Equals | `==` | `{Status} == "Active"` |
+| Not equals | `!=` | `{Status} != "Closed"` |
+| Greater than | `>` | `{Amount} > 10000` |
+| Less than | `<` | `{DaysOpen} < 30` |
+| Contains | `CONTAINS` | `{Name} CONTAINS "Corp"` |
+| Is null | `== null` | `{Email} == null` |
+| Is not null | `!= null` | `{Phone} != null` |
+
+### Conditional Styling
+
+Apply different styles based on data values:
+
+```
+If {Status} == "Active"    → Green badge (slds-badge slds-theme_success)
+If {Status} == "Expired"   → Red badge (slds-badge slds-theme_error)
+If {Status} == "Pending"   → Yellow badge (slds-badge slds-theme_warning)
+```
+
+Use SLDS theme classes rather than inline color styles to maintain dark mode compatibility.
+
+---
+
+## Multi-Data-Source Cards
+
+### When to Use Multiple Data Sources
+
+- The card displays data from unrelated objects that cannot be fetched in a single IP
+- Different sections of the card have different refresh requirements
+- A child card needs its own independent data source
+
+### Configuration Pattern
+
+```
+FlexCard: AccountOverview
+├── Data Source 1: "Account_GetSummary"
+│     Input: { "recordId": "{recordId}" }
+│     Fields: {ds1.Name}, {ds1.Industry}, {ds1.Status}
+│
+├── Data Source 2: "Case_GetOpenCount"
+│     Input: { "accountId": "{recordId}" }
+│     Fields: {ds2.openCaseCount}, {ds2.lastCaseDate}
+│
+└── Data Source 3: "Opportunity_GetPipeline"
+      Input: { "accountId": "{recordId}" }
+      Fields: {ds3.totalPipeline}, {ds3.nextCloseDate}
+```
+
+### Data Source Naming
+
+When a card has multiple data sources, reference fields using the data source name prefix:
+
+```
+Single data source:     {Name}
+Multiple data sources:  {ds1.Name}  or  {accountSummary.Name}
+```
+
+### Load Order and Dependencies
+
+- Data sources load in parallel by default
+- If Data Source 2 depends on a value from Data Source 1, configure the dependency order
+- Use conditional rendering to hide sections until their data source has loaded
+- Display a loading indicator while data sources are in progress
+
+### Coordinating Multiple Sources
+
+| Pattern | Description | Use Case |
+|---------|-------------|----------|
+| **Parallel load** | All sources fetch simultaneously | Independent data sets |
+| **Sequential load** | Source B waits for Source A | Source B needs a value from Source A's response |
+| **Conditional load** | Source B only loads if Source A meets a condition | Avoid unnecessary API calls |
+
+---
+
+## Error Handling for Failed Data Sources
+
+### Common Failure Modes
+
+| Failure | Cause | User Impact |
+|---------|-------|------------|
+| IP not found | IP name misspelled or IP not deployed | Card shows no data; console error |
+| IP inactive | IP exists but is not activated | Card shows no data |
+| IP timeout | IP takes too long to execute | Card shows loading indefinitely |
+| IP error response | IP logic throws an exception | Card may show partial data or error state |
+| Auth failure | User lacks permission to run the IP | Card shows no data; access error |
+| Network error | Connectivity issue between client and server | Card shows no data |
+
+### Error State Design
+
+Configure an explicit error state rather than letting the card fail silently:
+
+```
+┌──────────────────────────────────┐
+│  ⚠ Unable to load account data   │
+│                                  │
+│  The data source returned an     │
+│  error. Try refreshing the page. │
+│                                  │
+│  [Refresh]  [Contact Support]    │
+└──────────────────────────────────┘
+```
+
+**Error State Guidelines:**
+- Use plain language, not technical error codes
+- Provide an actionable next step (refresh, retry, contact admin)
+- Log the technical error details for debugging (not displayed to end users)
+- Do not show a blank card with no explanation
+
+### Fallback Strategies
+
+| Strategy | Implementation | When to Use |
+|----------|---------------|-------------|
+| **Cached data** | Show previously loaded data with a "stale" indicator | Data changes infrequently |
+| **Partial render** | Show fields that loaded; hide failed sections | Multi-source card where only one source fails |
+| **Empty state** | Show "No data available" with context | Single-source card where the source fails |
+| **Retry** | Provide a manual retry button | Transient errors (network, timeout) |
+
+### Debugging Data Source Issues
+
+1. **Check IP activation**: Query `SELECT Name, IsActive FROM OmniProcess WHERE Name = 'Type_SubType'`
+2. **Verify IP input**: Use the OmniStudio Preview tool to test the IP with the same input parameters
+3. **Check field paths**: Ensure merge field paths (`{field.subfield}`) match the actual IP response structure
+4. **Review permissions**: Confirm the running user has access to the IP and the underlying objects
+5. **Inspect browser console**: FlexCard data source errors appear in the browser developer console
+6. **Test with static data**: Temporarily configure the FlexCard with a static JSON data source to isolate whether the issue is the IP or the card
+
+### Data Source Validation Checklist
+
+Before deploying a FlexCard, verify each data source:
+
+- [ ] IP exists in the target org
+- [ ] IP is activated
+- [ ] IP Type and SubType match the `ipMethod` value exactly (case-sensitive)
+- [ ] Input parameters use correct merge field syntax
+- [ ] `resultListPath` points to the correct array node (for list cards)
+- [ ] All merge fields in the card map to actual fields in the IP response
+- [ ] Error state is configured for graceful failure
+- [ ] Empty state is configured for zero-record responses
+- [ ] Data source has been tested with real data in a sandbox

package/skills/building-omnistudio-flexcard/references/scoring-rubric.md

@@ -0,0 +1,66 @@
+# FlexCard Scoring Rubric: Breakdown Detail
+
+Detailed point-by-point scoring criteria for the 130-point FlexCard validation. Read during Phase 3 when running the full scoring rubric.
+
+## Design & Layout (25 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| Layout type matches use case | 5 | Single, list, tabbed, or flyout chosen appropriately |
+| Field grouping is logical | 5 | Related fields are visually grouped together |
+| Responsive behavior | 5 | Card adapts to different viewport widths |
+| Consistent spacing | 5 | Margins and padding follow SLDS (Salesforce Lightning Design System) spacing scale |
+| Visual hierarchy | 5 | Primary information is prominent, secondary is de-emphasized |
+
+## Data Binding (20 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| IP references are valid | 5 | All referenced IPs exist and are active |
+| Merge field syntax correct | 5 | `{datasource.field}` paths resolve to actual IP response fields |
+| Input parameters mapped | 5 | Record context passed correctly to IP inputs |
+| Multi-source coordination | 5 | Multiple data sources load in correct order without conflicts |
+
+## Actions & Navigation (20 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| Action buttons functional | 5 | All buttons trigger their configured actions |
+| OmniScript params mapped | 5 | Context data flows correctly into launched OmniScripts |
+| Navigation targets valid | 5 | Record and URL navigation resolves correctly |
+| Labels are descriptive | 5 | Action labels clearly communicate what the action does |
+
+## Styling (20 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| SLDS tokens used | 5 | Colors, fonts, spacing via design tokens |
+| Consistent typography | 5 | Text sizes follow SLDS type scale |
+| Card pattern compliance | 5 | Uses standard SLDS card or tile patterns |
+| Dark mode compatible | 5 | No hardcoded colors; works with SLDS dark theme |
+
+## Accessibility (15 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| ARIA labels on interactive elements | 5 | Buttons, links, and inputs have accessible names |
+| Keyboard navigable | 5 | All actions reachable via Tab, activated via Enter/Space |
+| Color contrast sufficient | 5 | Meets WCAG 2.1 AA contrast ratio (4.5:1 for text) |
+
+## Testing (15 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| Populated data verified | 3 | Card renders correctly with full data |
+| Empty state verified | 3 | Empty-state message displays properly |
+| Error state verified | 3 | Graceful handling of IP errors |
+| Multi-record verified | 3 | Card list renders correct items |
+| Mobile viewport verified | 3 | Layout adapts to small screens |
+
+## Performance (15 points)
+
+| Criterion | Points | Description |
+|-----------|--------|-------------|
+| Data source calls minimized | 5 | No redundant or duplicate IP invocations |
+| Child card nesting limited | 5 | Maximum 2 levels of nested child cards |
+| Lazy loading for hidden states | 5 | Non-visible tabs/flyouts load on demand |

package/skills/building-omnistudio-flexcard/scripts/flexcard-commands.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# FlexCard CLI Commands
+# Replace <org> with your org alias and <Name> with the FlexCard API name.
+
+# Query active FlexCards in the org
+sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true LIMIT 200" -o <org>
+
+# Retrieve a specific FlexCard by name
+sf project retrieve start -m OmniUiCard:<Name> -o <org>
+
+# Deploy a FlexCard to the target org
+sf project deploy start -m OmniUiCard:<Name> -o <org>
+
+# Retrieve all FlexCards
+sf project retrieve start -m OmniUiCard -o <org>
+
+# Deploy all OmniStudio metadata (FlexCards + dependencies)
+sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>
+
+# Check deploy status (use job ID from deploy output)
+sf project deploy report --job-id <jobId> -o <org>
+
+# In namespaced orgs (managed package), prefix the metadata type:
+# sf project deploy start -m omnistudio__OmniUiCard:<Name> -o <org>