@salesforce/afv-skills 1.23.0 → 1.25.0

package/skills/dx-org-manage/references/creating-snapshot.md

@@ -0,0 +1,103 @@
+# Creating Snapshots
+
+Creates a point-in-time snapshot of a scratch org using `sf org create snapshot`. Snapshots preserve scratch org state and configuration for reuse in scratch org definition files.
+
+---
+
+## Required Inputs
+
+Infer from the user's request:
+
+- **Source org**: Scratch org ID (starts with 00D) or username/alias to snapshot
+- **Snapshot name**: Unique name for the snapshot (required)
+- **Dev Hub**: Dev Hub org alias/username (uses default if not specified)
+- **Description** (optional): Document snapshot contents, version control reference
+
+---
+
+## Workflow
+
+1. **Gather inputs** — get source org, snapshot name, and optional description
+2. **Build command** — construct `sf org create snapshot` with appropriate flags
+3. **Execute via Bash tool** — run command with `--json` flag
+4. **Return result** — report snapshot ID and status
+
+### Command Patterns
+
+| User intent | Execute via Bash tool |
+|-------------|---------|
+| Create snapshot with name only | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --json` |
+| Create snapshot with description | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --description "<desc>" --json` |
+| Specify Dev Hub explicitly | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --target-dev-hub <devHubAlias> --json` |
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always use `--json` flag | Provides structured output for reliable parsing and error handling |
+| Snapshot names must be unique in the Dev Hub | Duplicate names cause creation to fail |
+| Source org must be a scratch org | Snapshots only work with scratch orgs, not sandboxes or production orgs |
+| Dev Hub must have snapshot feature enabled | "NOT_FOUND" error means Dev Hub doesn't support snapshots |
+| Source org accepts ID or username/alias | Command auto-resolves aliases to org IDs; org IDs start with 00D |
+| Include description for tracking | Best practice: reference version control tag or commit ID in description |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|------------|
+| "NOT_FOUND" error when creating snapshot | Dev Hub doesn't have snapshot feature enabled — contact admin to enable in Dev Hub settings |
+| "No org found for <alias>" error | Source org alias doesn't exist or isn't authenticated — verify with `sf org list` |
+| Snapshot name already exists | Use a different unique name — snapshot names must be unique per Dev Hub |
+| "An error while created the org snapshot" | Generic error — check that source org is a scratch org and still active |
+| Long-running snapshot creation | Use `sf org get snapshot --snapshot <name>` to check status — snapshot creation is asynchronous |
+
+---
+
+## Output Expectations
+
+The command returns JSON output with the created snapshot details.
+
+See `examples/snapshots/success_output.json` and `examples/snapshots/error_output.json` for complete response structures.
+
+Example success response:
+```json
+{
+  "result": {
+    "SnapshotId": "0Ym...",
+    "SnapshotName": "MySnapshot",
+    "Status": "Active",
+    "SourceOrg": "00D..."
+  }
+}
+```
+
+---
+
+## Using Snapshots
+
+After creating a snapshot, use it to create scratch orgs by:
+
+1. **In scratch org definition file:**
+   ```json
+   {
+     "snapshot": "MySnapshot"
+   }
+   ```
+
+2. **Or via command flag:**
+   ```bash
+   sf org create scratch --snapshot MySnapshot --target-dev-hub <alias> --alias <name> --json
+   ```
+
+See `snapshot_usage.md` for detailed examples.
+
+---
+
+## Additional Resources
+
+- See `cli_flags.md` for detailed explanation of all available flags
+- See `snapshot_usage.md` for how to use snapshots in scratch org creation

package/skills/dx-org-manage/references/definition_file_options.md

@@ -0,0 +1,224 @@
+# Scratch Org Definition File Options
+
+Complete reference for scratch org definition file configuration. Use this when users need to configure org features, settings, or advanced options beyond basic org creation.
+
+## File Structure
+
+```json
+{
+  "orgName": "My Company",
+  "edition": "Developer",
+  "features": ["<feature>", "<feature>"],
+  "settings": {
+    "<SettingType>": {
+      "<settingName>": <value>
+    }
+  },
+  "adminEmail": "admin@example.com",
+  "description": "Scratch org for feature X development",
+  "hasSampleData": false,
+  "snapshot": "SnapshotName",
+  "sourceOrg": "00D1234567890ABC",
+  "username": "custom.username@example.com"
+}
+```
+
+## Core Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `orgName` | string | Yes | Name of the company (user-visible) |
+| `edition` | string | Yes* | Developer, Enterprise, Group, Professional, or Partner variants |
+| `adminEmail` | string | No | Email for the admin user |
+| `description` | string | No | Description shown in Dev Hub |
+| `hasSampleData` | boolean | No | Include standard sample data (default: false) |
+| `username` | string | No | Custom username for admin (must be globally unique) |
+
+\* Not required if using `snapshot` or `sourceOrg`.
+
+**CLI Flag Overrides:** When using a definition file with `--definition-file`, you can override any of these fields with CLI flags:
+- `--edition` overrides `edition`
+- `--name` overrides `orgName`
+- `--username` overrides `username`
+- `--description` overrides `description`
+- `--admin-email` overrides `adminEmail`
+- `--release` overrides `release`
+- `--snapshot` overrides `snapshot`
+- `--source-org` overrides `sourceOrg`
+
+CLI flags take precedence over definition file values.
+
+## Features Array
+
+Enable org features by adding to `features` array. Common features:
+
+```json
+"features": [
+  "Communities",
+  "ServiceCloud",
+  "Sites",
+  "MultiCurrency",
+  "PersonAccounts",
+  "Walkthroughs",
+  "AdvancedPersonAccountSecurity"
+]
+```
+
+**Finding available features:**
+- Run: `sf org list metadata-types --target-org <dev-hub>`
+- Look for `FeatureParameterValueSet` type
+- Or check: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm
+
+## Settings Object
+
+Configure org settings by type. Format:
+
+```json
+"settings": {
+  "lightningExperienceSettings": {
+    "enableS1DesktopEnabled": true
+  },
+  "mobileSettings": {
+    "enableS1EncryptedStoragePref2": false
+  },
+  "securitySettings": {
+    "passwordPolicies": {
+      "minimumPasswordLength": 10
+    }
+  }
+}
+```
+
+**Common settings:**
+
+### Language Settings
+```json
+"languageSettings": {
+  "enableTranslationWorkbench": true
+}
+```
+
+### Chatter Settings
+```json
+"chatterSettings": {
+  "enableChatter": true
+}
+```
+
+### Path Settings
+```json
+"pathAssistantSettings": {
+  "pathAssistantEnabled": true
+}
+```
+
+## Alternative Creation Sources
+
+### Snapshot
+```json
+{
+  "snapshot": "BaselineSnapshot"
+}
+```
+
+Creates org from a snapshot. The `edition` field is optional when using snapshots.
+
+### Source Org (Org Shape)
+```json
+{
+  "sourceOrg": "00D1234567890ABC"
+}
+```
+
+Creates org from an org shape. The `edition` field is optional when using org shapes.
+
+**Note:** `snapshot` and `sourceOrg` are mutually exclusive.
+
+## Release Overrides
+
+Control which Salesforce release the scratch org uses:
+
+```json
+{
+  "release": "preview"
+}
+```
+
+Options: `preview` (next release), `previous` (previous release). Only use during Salesforce release transition periods.
+
+## Duration Control
+
+While not part of the definition file, you can override duration with the CLI flag:
+```bash
+--duration-days 15
+```
+
+Maximum: 30 days. Default: 7 days.
+
+## Packaging Options
+
+```json
+{
+  "ancestorId": "04t...",
+  "ancestorVersion": "1.0",
+  "namespace": "myns"
+}
+```
+
+Used for second-generation package (2GP) development.
+
+**CLI Packaging Flags:**
+- `--no-ancestors` - Exclude 2GP ancestors from the scratch org
+- `--no-namespace` - Create scratch org without namespace, even if Dev Hub has one
+
+## Example: Full Configuration
+
+```json
+{
+  "orgName": "Acme Corp Dev Org",
+  "edition": "Developer",
+  "description": "Feature X development scratch org",
+  "adminEmail": "dev-team@acme.com",
+  "hasSampleData": false,
+  "features": [
+    "Communities",
+    "ServiceCloud",
+    "MultiCurrency"
+  ],
+  "settings": {
+    "lightningExperienceSettings": {
+      "enableS1DesktopEnabled": true
+    },
+    "securitySettings": {
+      "passwordPolicies": {
+        "minimumPasswordLength": 10,
+        "minimumPasswordLifetime": false,
+        "obscure": false
+      }
+    },
+    "languageSettings": {
+      "enableTranslationWorkbench": true
+    }
+  }
+}
+```
+
+## Connected App Authentication
+
+For enhanced security, use a Connected App for authentication:
+
+```bash
+sf org create scratch --definition-file config.json --client-id <consumer-key>
+```
+
+When `--client-id` is provided, CLI prompts for the client secret. The scratch org will use the Connected App for authentication instead of default JWT.
+
+## Common Pitfalls
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Features not available | Feature name spelled wrong or not available in edition | Check feature name spelling and edition compatibility |
+| Settings ignored | Invalid setting name or structure | Verify setting exists in Metadata API docs |
+| JSON parse error | Invalid JSON syntax | Validate JSON with linter |
+| Conflicting options | Both `snapshot` and `sourceOrg` specified | Use only one alternative creation source |
+| CLI flag ignored | Trying to override a field that doesn't support override | Only certain fields can be overridden (see CLI Flag Overrides section) |

package/skills/dx-org-manage/references/edition_types.md

@@ -0,0 +1,78 @@
+# Scratch Org Edition Types
+
+Reference for choosing the right Salesforce edition for scratch org creation.
+
+## Available Editions
+
+| Edition | When to use | License limits | Features |
+|---------|-------------|----------------|----------|
+| `developer` | Default choice for most development | 2 user licenses | Most features available, best for general development |
+| `enterprise` | Enterprise-specific features needed | 5 user licenses | All enterprise features, territory management, advanced approvals |
+| `group` | Testing Professional edition behavior | 5 user licenses | Professional edition features |
+| `professional` | Professional edition-specific testing | 5 user licenses | Professional edition feature set |
+
+## Partner Editions
+
+Only available if the Dev Hub is a Partner Business Org:
+
+| Edition | When to use |
+|---------|-------------|
+| `partner developer` | Partner app development |
+| `partner enterprise` | Partner enterprise app testing |
+| `partner group` | Partner professional edition testing |
+| `partner professional` | Partner professional edition apps |
+
+## Edition Comparison
+
+### Developer Edition (Recommended Default)
+- **Best for**: General development, most common use case
+- **Features**: Apex, Visualforce, Lightning, Process Builder, Flow, most platform features
+- **Limitations**: 2 user licenses (sufficient for most dev work)
+- **Use when**: User doesn't specify or needs general Salesforce development environment
+
+### Enterprise Edition
+- **Best for**: Enterprise-specific features, larger team testing
+- **Additional features**: Territory Management 2.0, Advanced Approval Processes
+- **Use when**: Testing enterprise-only features or need more than 2 users
+
+### Group/Professional Edition
+- **Best for**: Testing behavior specific to Professional edition
+- **Use when**: Building apps for Professional edition customers or testing edition-specific constraints
+
+## Choosing an Edition
+
+Follow this decision tree:
+
+```text
+1. Does user specify edition? → Use specified edition
+2. Does user need Partner edition? → Check if Dev Hub is Partner Business Org
+3. Does user need Enterprise features? → Use enterprise
+4. Default → Use developer
+```
+
+## CLI Usage
+
+**With flag:**
+```bash
+sf org create scratch --edition developer --alias my-org
+```
+
+**With definition file:**
+```json
+{
+  "edition": "Developer"
+}
+```
+
+**Important notes:**
+- Edition value is case-insensitive in CLI flags but case-sensitive in definition files (capital first letter)
+- Partner editions use space format: `partner developer`, `partner enterprise`, etc. (no hyphen)
+- CLI flag `--edition` overrides definition file `edition` if both are specified
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `edition value must be one of` | Invalid edition name | Use: developer, enterprise, group, professional, or partner editions (e.g., "partner developer") |
+| Partner edition not available | Dev Hub is not a Partner Business Org | Use non-partner edition or switch to Partner Dev Hub |
+| Features not available in edition | Requested features not available in chosen edition | Use Enterprise edition or remove unavailable features |

package/skills/dx-org-manage/references/opening-org.md

@@ -0,0 +1,160 @@
+# Opening Orgs
+
+Opens a Salesforce org or specific metadata artifact in a browser using `sf org open`. Handles all variants: default org, alias or username, browser selection, incognito mode, path navigation, metadata file → Builder, and URL-only output.
+
+---
+
+## Required Inputs
+
+Infer from the user's request:
+
+- **Target org**: Use default org unless a specific alias/username is mentioned
+- **What to open**: Path, file, or org home
+- **Browser**: Only include if explicitly requested (chrome, firefox, edge)
+- **Incognito**: Only if user says "private" or "incognito"
+- **URL only**: If user says "URL", "link", or "don't open browser"
+
+Do not ask for clarification - infer and execute immediately.
+
+---
+
+## Workflow
+
+1. **Match user request** to command in table below
+2. **Execute via Bash tool**: `sf org open` with appropriate flags
+3. **Return result**
+
+If error occurs:
+- "no target org" → advise: `sf config set target-org <alias>`
+- auth error → advise: `sf org login web --alias <alias>`
+
+### Command Decision Table
+
+| User intent | Execute via Bash tool |
+|-------------|---------|
+| Open default org | `sf org open` |
+| Open specific org | `sf org open --target-org <alias>` |
+| Open in specific browser | `sf org open --browser chrome` (or firefox, edge) |
+| Private/incognito mode | `sf org open --private` |
+| Navigate to path | `sf org open --path '<path>'` |
+| Get URL only | `sf org open --url-only` |
+| Path + URL only | `sf org open --path '<path>' --url-only` |
+| Open local file | `sf org open --source-file <file-path>` |
+| File + URL only | `sf org open --source-file <file-path> --url-only` |
+
+**Note:** Flags `--private`, `--url-only`, `--browser` are mutually exclusive.
+
+---
+
+## Common Paths
+
+### Setup Pages
+```bash
+# Setup home
+sf org open --path '/lightning/setup/SetupOneHome/home'
+
+# Object Manager
+sf org open --path '/lightning/setup/ObjectManager/home'
+
+# Users
+sf org open --path '/lightning/setup/ManageUsers/home'
+
+# Permission Sets
+sf org open --path '/lightning/setup/PermSets/home'
+
+# Flows
+sf org open --path '/lightning/setup/Flows/home'
+
+# Custom Metadata Types
+sf org open --path '/lightning/setup/CustomMetadata/home'
+```
+
+### App Pages
+```bash
+# App Launcher
+sf org open --path '/lightning/setup/NavigationMenus/home'
+
+# Reports
+sf org open --path '/lightning/o/Report/home'
+
+# Dashboards
+sf org open --path '/lightning/o/Dashboard/home'
+```
+
+---
+
+## Opening Metadata Files
+
+### Supported Metadata Types
+
+`--source-file` works with these metadata types:
+- **FlexiPage** (Lightning pages) → Lightning App Builder
+- **Flow** → Flow Builder
+- **ApexPage** (Visualforce) → Visualforce Page Editor
+- **ApexClass** → Apex Class detail page
+- **CustomObject** → Object Manager
+
+### Important Constraints
+
+| Constraint | Behavior |
+|-----------|----------|
+| Metadata must be deployed in the org | CLI queries org for record ID; undeployed metadata causes error or fallback |
+| FlexiPage fallback | Silently falls back to `/lightning/setup/FlexiPageList/home` if not found |
+| Flow error | Throws `FlowIdNotFound` if Flow not deployed |
+| ApexClass error | Throws `ApexClassIdNotFound` if class not deployed |
+| CustomObject error | Throws `CustomObjectIdNotFound` if object not deployed |
+
+### Example Commands
+
+```bash
+# Open Lightning page in App Builder
+sf org open --source-file force-app/main/default/flexipages/Account_Record_Page.flexipage-meta.xml
+
+# Open Flow in Flow Builder
+sf org open --source-file force-app/main/default/flows/MyFlow.flow-meta.xml
+
+# Open Apex class
+sf org open --source-file force-app/main/default/classes/MyController.cls
+```
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| `--path` and `--source-file` are mutually exclusive | Both control navigation destination; choose one |
+| `--source-file` supported types: FlexiPage, Flow, ApexPage, ApexClass, CustomObject | CLI queries the org for the record ID; unsupported types or undeployed metadata fall back silently (FlexiPage) or throw a named error (Flow/ApexClass/CustomObject) |
+| Do not hardcode `force-app/main/default/` for `--source-file` | Project package paths vary; use the path the user provides or read `sfdx-project.json` |
+| Must use Bash tool, not MCP tools | MCP tools like `list_all_orgs` cannot open orgs in browser |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|------------|
+| No target org found | Set default: `sf config set target-org <alias>` or specify `--target-org <alias>` |
+| Auth error | Re-authenticate: `sf org login web --alias <alias>` |
+| `--source-file` opens wrong page or throws `FlowIdNotFound` / `ApexClassIdNotFound` / `CustomObjectIdNotFound` | Metadata is not deployed in the org. Run `sf project deploy start --source-file <path> --target-org <alias>` first. FlexiPage silently falls back to org home; Flow/ApexClass/CustomObject throw an error. |
+| Metadata file opens wrong Builder | Verify the file extension matches the metadata type (e.g. `.flow-meta.xml` for Flow Builder) |
+| URL-only flag but user expects browser to open | `--url-only` prints the URL without launching — remove the flag to open the browser |
+| Path not found / 404 | Verify the path is correct; some paths require specific permissions or licenses |
+
+---
+
+## Output Expectations
+
+### Default behavior
+- Opens the specified org/path in the system's default browser
+- No console output on success
+
+### With `--url-only`
+Returns the login URL without opening browser:
+```text
+https://...-dev-ed.develop.my.salesforce.com/secur/frontdoor.jsp?sid=...
+```
+
+### With `--source-file`
+- Opens the metadata in its appropriate Builder/Editor
+- Example: FlexiPage → Lightning App Builder, Flow → Flow Builder

package/skills/dx-org-manage/references/snapshot_usage.md

@@ -0,0 +1,74 @@
+# Using Snapshots in Scratch Org Definition Files
+
+After creating a snapshot, reference it in scratch org definition files to create new scratch orgs from the saved state.
+
+## Scratch Org Definition File Format
+
+Use the `snapshot` field instead of `edition` in your `project-scratch-def.json`:
+
+```json
+{
+  "orgName": "My Company",
+  "snapshot": "MySnapshot",
+  "features": ["EnableSetPasswordInApi"],
+  "settings": {
+    "lightningExperienceSettings": {
+      "enableS1DesktopEnabled": true
+    }
+  }
+}
+```
+
+## Key Differences from Edition-Based Definitions
+
+| Field | Edition-based | Snapshot-based |
+|-------|--------------|----------------|
+| Primary field | `"edition": "Developer"` | `"snapshot": "MySnapshot"` |
+| Contents | Empty org with edition defaults | Pre-configured org state from snapshot |
+
+## Creating a Scratch Org from Snapshot
+
+```bash
+sf org create scratch --definition-file config/project-scratch-def.json --alias from-snapshot
+```
+
+The scratch org will be created with all the metadata, data, and configuration from the snapshot.
+
+## Common Use Cases
+
+### 1. Package Development
+
+```json
+{
+  "orgName": "Package Dev Org",
+  "snapshot": "Dependencies_v1.2.0",
+  "description": "Org with all dependencies installed"
+}
+```
+
+### 2. Testing Baseline
+
+```json
+{
+  "orgName": "Test Baseline",
+  "snapshot": "TestData_Populated",
+  "description": "Org with sample data for testing"
+}
+```
+
+### 3. CI/CD Pipeline
+
+```json
+{
+  "orgName": "CI Scratch Org",
+  "snapshot": "Nightly_Build_Baseline",
+  "description": "Latest nightly build dependencies"
+}
+```
+
+## Workflow Summary
+
+1. **Create snapshot**: `sf org create snapshot --source-org <scratch> --name MySnapshot`
+2. **Check status**: `sf org get snapshot --snapshot MySnapshot`
+3. **Reference in definition file**: `"snapshot": "MySnapshot"`
+4. **Create new scratch org**: `sf org create scratch --definition-file config/project-scratch-def.json`