@salesforce/afv-skills 1.23.0 → 1.25.0

package/skills/{getting-datacloud-schema → data360-schema-get}/references/README.md

@@ -1,4 +1,4 @@
-# getting-datacloud-schema Skill
+# data360-schema-get Skill
 
 ## Overview
 
@@ -7,25 +7,25 @@ A skill that retrieves Data Lake Object (DLO) and Data Model Object (DMO) schema
 ## Usage
 
 **List all DLOs:**
-```
+```text
 "Show me all DLOs in afvibe org"
 "List Data Lake Objects in myorg"
 ```
 
 **Get specific DLO schema:**
-```
+```text
 "Get the schema for Employee__dll in afvibe"
 "What fields does the Employee__dll DLO have in myorg?"
 ```
 
 **List all DMOs:**
-```
+```text
 "Show me all DMOs in afvibe org"
 "List Data Model Objects in myorg"
 ```
 
 **Get specific DMO schema:**
-```
+```text
 "Get the schema for Individual__dlm in afvibe"
 "What fields does the Individual__dlm DMO have in myorg?"
 ```
@@ -116,7 +116,7 @@ python3 scripts/get_dmo_schema.py afvibe Individual__dlm
 ## Output Format
 
 ### DLO List
-```
+```text
 Found 5 DLOs in org 'afvibe':
 
 1. DataCustomCodeLogs__dll
@@ -131,7 +131,7 @@ Found 5 DLOs in org 'afvibe':
 ```
 
 ### DLO Schema
-```
+```text
 DLO: Employee__dll
 Label: Employee
 Category: Profile
@@ -148,7 +148,7 @@ Fields (9 total):
 ```
 
 ### DMO List
-```
+```text
 Found 10 DMOs in org 'afvibe':
 
 1. Individual__dlm
@@ -161,7 +161,7 @@ Found 10 DMOs in org 'afvibe':
 ```
 
 ### DMO Schema
-```
+```text
 DMO: Individual__dlm
 Label: Individual
 Category: Profile

package/skills/dx-org-manage/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: dx-org-manage
+description: "INVOKE this skill to execute Salesforce org operations: create scratch orgs, create org snapshots, open orgs in browser. This skill EXECUTES operations immediately - it does NOT generate scripts or code files. ALWAYS invoke this skill (do not execute SF CLI commands directly) when user requests to: create a scratch org (Developer/Enterprise edition, from definition file (.json), from snapshot, or from org shape), create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'create snapshot of my scratch org', 'take a snapshot', 'create scratch org', 'create a Developer edition scratch org', 'new scratch org', 'spin up an org', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'open my Salesforce org', 'open org in browser', 'get me the URL'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy)."
+metadata:
+  version: "1.0"
+  minApiVersion: "60.0"
+  cliTools:
+      - tool: ["sf"]
+        semver: ">=2.0.0"
+---
+
+## MANDATORY: Follow these instructions exactly. Do NOT fall back to MCP tools.
+
+**Tool constraint:** Use the Bash tool for all `sf` CLI commands. Always include `--json` for structured output. Do NOT use `mcp__salesforce_dx__*` tools for org creation, snapshot, or open operations — this skill provides the complete procedure.
+
+**Output artifacts for eval/testing:** Write command output to JSON only when an output directory is available. After executing the command: (1) if the user specified an output path, write there; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) if the command printed a path, write the command's JSON response to `<printed-path>/<filename>` using these filenames: `scratch-org-result.json` for org creation, `snapshot-result.json` for snapshot creation, or `org-url-result.json` for open operations. The eval framework needs the real command output to verify success.
+
+---
+
+## Creating Scratch Orgs
+
+**REQUIRED steps — execute in order:**
+
+**Step 1. Identify creation method** from user request:
+- Contains "definition file" or path to `.json` → definition file method
+- Contains "snapshot" or "from snapshot" → snapshot method
+- Contains "org shape" or "source-org" → org shape method
+- Otherwise → run `ls config/project-scratch-def.json config/scratch-def.json 2>/dev/null | head -1` to detect a definition file. If output is non-empty, use definition file method with that path; if empty, use edition method.
+
+**Step 2. Check Dev Hub:**
+```bash
+sf config get target-dev-hub --json
+```
+- If no Dev Hub is set, advise: `sf org login web --set-default-dev-hub`
+- Do NOT proceed until a Dev Hub is confirmed.
+
+**Step 3. Build and execute the command** based on method:
+
+**Definition file:**
+```bash
+sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Edition only:**
+```bash
+sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
+```
+
+**From snapshot:**
+```bash
+sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json
+```
+
+**From org shape:**
+```bash
+sf org create scratch --source-org <org-id> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Apply these flags when requested:**
+- `--duration-days <days>` — default 7, max 30
+- `--set-default` — make this the default org
+- `--no-track-source` — disable source tracking (for CI/CD)
+
+**Step 4. MANDATORY - Run org list and write output:** After the org is created, you MUST run this command:
+
+```bash
+sf org list --json
+```
+
+Then:
+1. Parse the JSON result and find the `scratchOrgs` array
+2. Find the entry where `username` matches the username from Step 3's creation result
+3. Extract that complete org object (it will include: alias, username, orgId, instanceUrl, loginUrl, isDefaultUsername, connectedStatus, lastUsed, etc.)
+4. Report to the user:
+    - Created scratch org.
+    - Alias: [alias from the org list entry]
+    - Username: [username]
+    - Org ID: [orgId]
+
+5. If an output directory is available (per the output artifacts rule above), write ONLY that extracted org object (NOT the full creation result) to `<output-dir>/scratch-org-result.json`
+
+Example: If `sf org list --json` returns `{"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}]}}`, write just the inner org object `{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}` to the file.
+
+Do NOT write the creation command's output. Do NOT suggest verification steps to the user.
+
+**Error handling:**
+- "Snapshot not found" → suggest `sf org list snapshot --target-dev-hub <alias>`
+- "No default Dev Hub" → advise `sf org login web --set-default-dev-hub`
+
+**When you need more detail:**
+- For available features, settings, and definition file structure → load `references/definition_file_options.md`
+- For edition selection guidance and comparison → load `references/edition_types.md`
+- For snapshot workflow and post-creation usage → load `references/snapshot_usage.md`
+- For complete scratch org creation workflow → load `references/creating-scratch-org.md`
+
+---
+
+## Creating Snapshots
+
+**REQUIRED steps — execute in order:**
+
+**Step 1. Get inputs:**
+- Source org: scratch org ID or alias (from user)
+- Snapshot name: unique name (from user)
+- Description: optional (from user)
+
+**Step 2. Determine Dev Hub:**
+- If user specifies a Dev Hub (alias or username) → use that value
+- Otherwise, check for default:
+```bash
+sf config get target-dev-hub --json
+```
+- If no default Dev Hub is set, advise: `sf org login web --set-default-dev-hub`
+
+**Step 3. Execute:**
+```bash
+sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json
+```
+
+With description:
+```bash
+sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json
+```
+
+**Step 4. Report result:** Returns JSON with SnapshotId and Status. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/snapshot-result.json`.
+
+**Error handling:**
+- "NOT_FOUND" → Dev Hub doesn't have snapshot feature enabled
+- "Snapshot name already exists" → use a different unique name
+
+**When you need more detail:**
+- For complete snapshot creation workflow and flag reference → load `references/creating-snapshot.md`
+- For CLI flag reference → load `references/cli_flags.md`
+
+---
+
+## Opening Orgs
+
+**REQUIRED steps — execute in order:**
+
+**Step 1. Match user request to command:**
+
+| User wants | Command |
+|-----------|---------|
+| Open default org | `sf org open --json` |
+| Open specific org | `sf org open --target-org <alias> --json` |
+| Specific browser | `sf org open --browser chrome --json` |
+| Incognito mode | `sf org open --private --json` |
+| Navigate to path | `sf org open --path '<path>' --json` |
+| URL only (don't open) | `sf org open --url-only --json` |
+| Open metadata file | `sf org open --source-file <file-path> --json` |
+
+**Step 2. Execute the matching command using the Bash tool.**
+
+**Step 3. Report result:** Returns URL or opens browser. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/org-url-result.json`.
+
+**Error handling:**
+- "no target org" → advise `sf config set target-org <alias>`
+- "auth error" → advise `sf org login web --alias <alias>`
+
+**When you need more detail:**
+- For complete opening org workflow and all available flags → load `references/opening-org.md`
+
+---
+
+## Reference File Index
+
+Load these reference files for detailed guidance:
+
+| File | When to read |
+|------|-------------|
+| `references/definition_file_options.md` | User needs to configure org features, settings, or advanced definition file options beyond basic org creation |
+| `references/edition_types.md` | User asks which edition to choose or needs to understand edition differences |
+| `references/snapshot_usage.md` | User wants to use snapshots in definition files or needs post-snapshot workflow guidance |
+| `references/creating-scratch-org.md` | Troubleshooting scratch org creation failures or need complete workflow with all options |
+| `references/cli_flags.md` | User needs complete snapshot CLI flag reference |
+| `references/creating-snapshot.md` | Troubleshooting snapshot creation failures or need detailed snapshot workflow |
+| `references/opening-org.md` | User needs to navigate to specific setup paths, open metadata files, or use advanced open flags |
+
+## Example Files
+
+Example command outputs for testing and troubleshooting:
+
+| File | Purpose |
+|------|---------|
+| `examples/scratch-orgs/success_definition_file.json` | Successful scratch org creation using `--definition-file` |
+| `examples/scratch-orgs/success_edition.json` | Successful scratch org creation using `--edition developer` |
+| `examples/scratch-orgs/success_snapshot.json` | Successful scratch org creation using `--snapshot` |
+| `examples/scratch-orgs/error_no_devhub.json` | Error when Dev Hub not authenticated |
+| `examples/scratch-orgs/error_timeout.json` | Timeout error during org creation (exit code 69) |
+| `examples/snapshots/success_output.json` | Successful snapshot creation |
+| `examples/snapshots/error_output.json` | Common snapshot error scenarios |

package/skills/dx-org-manage/examples/README.md

@@ -0,0 +1,45 @@
+# Examples Directory
+
+This directory contains example outputs for the three workflows supported by the `dx-org-manage` skill.
+
+## Structure
+
+```text
+examples/
+├── README.md                          # This file
+├── scratch-orgs/                      # Scratch org creation examples
+│   ├── success_definition_file.json
+│   ├── success_edition.json
+│   ├── error_no_devhub.json
+│   └── error_timeout.json
+└── snapshots/                         # Snapshot creation examples
+    ├── success_output.json
+    └── error_output.json
+```
+
+## scratch-orgs/
+
+Examples of `sf org create scratch` command outputs for all four creation methods.
+
+- **success_definition_file.json** - Successful creation using `--definition-file`
+- **success_edition.json** - Successful creation using `--edition developer`
+- **success_snapshot.json** - Successful creation using `--snapshot`
+- **error_no_devhub.json** - Error when Dev Hub not authenticated
+- **error_timeout.json** - Timeout error (exit code 69)
+
+## snapshots/
+
+Examples of `sf org create snapshot` command outputs.
+
+- **success_output.json** - Successful snapshot creation
+- **error_output.json** - Common error scenarios (NOT_FOUND, duplicate name, etc.)
+
+## Usage
+
+These examples help illustrate:
+1. Expected JSON/text response formats
+2. Common error patterns
+3. How to parse success indicators (`username`, `orgId`, etc.)
+4. Async operation handling (snapshot creation, timeout scenarios)
+
+Reference these when building eval datasets or troubleshooting command outputs.

package/skills/dx-org-manage/examples/scratch-orgs/error_no_devhub.json

@@ -0,0 +1,9 @@
+{
+  "status": 1,
+  "name": "NoDefaultEnvFound",
+  "message": "No default Dev Hub org found. Set a default Dev Hub org using 'sf config set target-dev-hub <username|alias>'.",
+  "exitCode": 1,
+  "context": "ScratchOrgCreateCommand",
+  "stack": "NoDefaultEnvFound: No default Dev Hub org found...",
+  "warnings": []
+}

package/skills/dx-org-manage/examples/scratch-orgs/error_timeout.json

@@ -0,0 +1,13 @@
+{
+  "status": 69,
+  "name": "ScratchOrgCreateTimeoutError",
+  "message": "The scratch org did not complete within your wait time (2 minutes).",
+  "exitCode": 69,
+  "context": "ScratchOrgCreateCommand",
+  "data": {
+    "requestId": "2SR5g000000BlYjGAK",
+    "resumeCommand": "sf org resume scratch --job-id 2SR5g000000BlYjGAK --json"
+  },
+  "stack": "ScratchOrgCreateTimeoutError: The scratch org did not complete...",
+  "warnings": []
+}

package/skills/dx-org-manage/examples/scratch-orgs/success_definition_file.json

@@ -0,0 +1,28 @@
+{
+  "status": 0,
+  "result": {
+    "username": "test-abcd1234@example.com",
+    "orgId": "00D5g000008xYZ1EAM",
+    "scratchOrgInfo": {
+      "Id": "2SR5g000000BlYjGAK",
+      "Edition": "Developer",
+      "Status": "Active",
+      "SignupUsername": "test-abcd1234@example.com",
+      "AdminEmail": "admin@example.com",
+      "Namespace": null,
+      "OrgName": "My Company",
+      "ConnectedAppConsumerKey": "3MVG9...",
+      "ScratchOrg": "00D5g000008xYZ1EAM",
+      "CreatedDate": "2026-06-12T15:10:00.000+0000",
+      "ExpirationDate": "2026-06-19"
+    },
+    "authFields": {
+      "accessToken": "00D5g...",
+      "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
+      "username": "test-abcd1234@example.com",
+      "orgId": "00D5g000008xYZ1EAM",
+      "loginUrl": "https://test.salesforce.com"
+    },
+    "warnings": []
+  }
+}

package/skills/dx-org-manage/examples/scratch-orgs/success_edition.json

@@ -0,0 +1,26 @@
+{
+  "status": 0,
+  "result": {
+    "username": "test-xyz5678@example.com",
+    "orgId": "00D5g000009aBC2EAM",
+    "scratchOrgInfo": {
+      "Id": "2SR5g000000CdEfGHI",
+      "Edition": "Developer",
+      "Status": "Active",
+      "SignupUsername": "test-xyz5678@example.com",
+      "AdminEmail": "dev@example.com",
+      "Namespace": null,
+      "OrgName": "Company",
+      "ScratchOrg": "00D5g000009aBC2EAM",
+      "CreatedDate": "2026-06-12T15:15:00.000+0000",
+      "ExpirationDate": "2026-06-19"
+    },
+    "authFields": {
+      "accessToken": "00D5g...",
+      "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
+      "username": "test-xyz5678@example.com",
+      "orgId": "00D5g000009aBC2EAM"
+    },
+    "warnings": []
+  }
+}

package/skills/dx-org-manage/examples/scratch-orgs/success_snapshot.json

@@ -0,0 +1,27 @@
+{
+  "status": 0,
+  "result": {
+    "username": "test-snap9012@example.com",
+    "orgId": "00D5g00000aDEF3EAM",
+    "scratchOrgInfo": {
+      "Id": "2SR5g000000EfGhIJK",
+      "Edition": "Developer",
+      "Status": "Active",
+      "SignupUsername": "test-snap9012@example.com",
+      "AdminEmail": "dev@example.com",
+      "Namespace": null,
+      "OrgName": "Company",
+      "ScratchOrg": "00D5g00000aDEF3EAM",
+      "SnapshotName": "MySnapshot",
+      "CreatedDate": "2026-06-12T15:20:00.000+0000",
+      "ExpirationDate": "2026-06-19"
+    },
+    "authFields": {
+      "accessToken": "00D5g...",
+      "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
+      "username": "test-snap9012@example.com",
+      "orgId": "00D5g00000aDEF3EAM"
+    },
+    "warnings": []
+  }
+}

package/skills/dx-org-manage/examples/snapshots/error_output.json

@@ -0,0 +1,9 @@
+{
+  "status": 1,
+  "name": "NOT_FOUND",
+  "message": "Org snapshots are not enabled in this org. Contact Salesforce to enable org snapshots.",
+  "exitCode": 1,
+  "commandName": "SnapshotCreate",
+  "stack": "NOT_FOUND: Org snapshots are not enabled in this org...",
+  "warnings": []
+}

package/skills/dx-org-manage/examples/snapshots/success_output.json

@@ -0,0 +1,15 @@
+{
+  "status": 0,
+  "result": {
+    "Id": "0Oo5g00000001ABCAA",
+    "Status": "Pending",
+    "SourceOrg": "00D5g00000001XyEAI",
+    "SnapshotName": "MySnapshot",
+    "Description": "Baseline configuration with Package v1.2.0",
+    "Content": "metadatadata",
+    "CreatedDate": "2026-06-04T20:00:00.000+0000",
+    "CreatedBy": "0055g00000001UserEAA",
+    "LastModifiedDate": "2026-06-04T20:00:00.000+0000",
+    "LastModifiedBy": "0055g00000001UserEAA"
+  }
+}

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

@@ -0,0 +1,67 @@
+# CLI Flags Reference
+
+Complete reference for `sf org create snapshot` command flags.
+
+## Required Flags
+
+| Flag | Alias | Description | Example |
+|------|-------|-------------|---------|
+| `--source-org` | `-o` | ID or authenticated username/alias of scratch org to snapshot | `--source-org my-scratch` |
+| `--name` | `-n` | Unique name for the snapshot | `--name MySnapshot` |
+| `--target-dev-hub` | `-v` | Dev Hub org username or alias (required unless default is set) | `--target-dev-hub DevHub` |
+
+## Optional Flags
+
+| Flag | Alias | Description | Example |
+|------|-------|-------------|---------|
+| `--description` | `-d` | Description of snapshot contents | `--description "Package v1.2.0"` |
+| `--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
+
+### Basic Snapshot Creation
+
+```bash
+sf org create snapshot --source-org my-scratch --name MySnapshot --json
+```
+
+### With Description
+
+```bash
+sf org create snapshot \
+  --source-org my-scratch \
+  --name MySnapshot \
+  --description "Baseline with Package v1.2.0" \
+  --json
+```
+
+### Using Org ID Instead of Alias
+
+```bash
+sf org create snapshot \
+  --source-org 00D5g00000001XyEAI \
+  --name MySnapshot \
+  --json
+```
+
+### Specify Dev Hub Explicitly
+
+```bash
+sf org create snapshot \
+  --source-org my-scratch \
+  --name MySnapshot \
+  --target-dev-hub MyDevHub \
+  --json
+```
+
+## Important Notes
+
+- **Source org auto-resolution**: Accepts org ID (starts with 00D) or username/alias — aliases are automatically resolved to org IDs
+- **Description best practice**: Include version control reference (git tag, commit SHA) to track snapshot contents
+- **Asynchronous creation**: Snapshot creation happens asynchronously — use `sf org get snapshot` to check status

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

@@ -0,0 +1,164 @@
+# Creating Scratch Orgs
+
+Detailed workflow for creating Salesforce scratch orgs using `sf org create scratch`. Supports four creation methods: definition file, edition flag, snapshot, and org shape.
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Dev Hub org**: Username or alias of authenticated Dev Hub (or use default from `target-dev-hub` config)
+- **Creation method**: Which approach to use (see Workflow step 1)
+- **Alias**: Optional but recommended for easy reference
+
+Optional but commonly used:
+- **Duration**: Days before org expires (default: 7, max: 30)
+- **Set as default**: Whether to make this the default org
+- **Source tracking**: Whether to enable (default: yes, disable for CI/CD performance)
+
+---
+
+## Workflow
+
+### 1. Identify creation method
+
+Determine which approach based on user request:
+
+| Method | When to use | Required flags |
+|--------|-------------|----------------|
+| Definition file | User provides config file or needs org features/settings | `--definition-file <path>` |
+| Edition only | Quick simple org, no special config needed | `--edition <edition>` |
+| Snapshot | Clone from existing snapshot | `--snapshot <name>` |
+| Org shape | Mimic another org's structure | `--source-org <id>` |
+
+**Mutually exclusive**: `--edition`, `--snapshot`, and `--source-org` cannot be combined.
+
+### 2. Verify Dev Hub authentication
+
+Check if Dev Hub is authenticated:
+- If `--target-dev-hub` not provided, check `sf config get target-dev-hub`
+- If no Dev Hub configured, prompt user to authenticate: `sf org login web --set-default-dev-hub`
+
+### 3. Build the command
+
+Construct based on creation method:
+
+**Definition file approach:**
+```bash
+sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Edition-only approach:**
+```bash
+sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
+```
+
+**Snapshot approach:**
+```bash
+sf org create scratch --snapshot <name> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Org shape approach:**
+```bash
+sf org create scratch --source-org <id> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Common optional flags:**
+- `--duration-days <days>` — Set expiration (default 7, max 30)
+- `--set-default` — Make this the default org
+- `--no-track-source` — Disable source tracking for CI/CD performance
+- `--wait <minutes>` — Wait for completion (default 5 minutes, min 2)
+- `--async` — Return immediately, don't wait for completion
+
+**⚠️ CRITICAL: This is a BLOCKING command**
+- The command **WAITS** until the scratch org is fully created (or times out)
+- When the command returns success, the org is **READY TO USE** — do NOT poll with `sf org list` waiting for it to become ready
+- The JSON response with `username` and `orgId` means creation is **COMPLETE**
+- Only use `--async` if you want to check status later with `sf org resume scratch`
+- **Note**: SKILL.md Step 4 requires running `sf org list --json` once after creation for artifact collection (not for polling status)
+
+**Before executing, verify:**
+- [ ] `--json` flag is present in the command
+- [ ] At least ONE of `--edition`, `--snapshot`, `--source-org`, or `--definition-file` is specified (flags can override definition file values)
+- [ ] `--snapshot` and `--source-org` are not combined (mutually exclusive)
+- [ ] `--target-dev-hub` is resolved (either in command or from config)
+
+### 4. Handle async creation
+
+If `--async` or `--wait` timeout occurs:
+- CLI displays: "The scratch org did not complete within your wait time."
+- CLI automatically shows the resume command with Request ID
+- Timeout exits with code 69
+- User can resume with the displayed command: `sf org resume scratch --job-id <request-id> --json`
+
+### 5. Report result
+
+When the command returns, check JSON response. If it contains `username` and `orgId`, the org is **COMPLETE and READY**. Do NOT run additional commands to verify completion.
+
+Successful creation returns:
+```json
+{
+   "username": "test-...@example.com",
+   "orgId": "00D...",
+   "scratchOrgInfo": {
+      "Id": "2SR...",
+      "ScratchOrg": "00D...",
+      "SignupUsername": "test-...@example.com"
+   }
+}
+```
+
+This JSON response means: org is created, authenticated, and ready for `sf org open`, `sf project deploy`, or any other commands.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always include `--json` flag | Returns structured output for parsing success/failure |
+| **Command blocks until completion — do NOT poll for status** | The command waits until the org is created (or times out). When it returns with `username` and `orgId` in JSON, the org is ready. Do NOT poll repeatedly with `sf org list` waiting for it to become ready — the command already waited for you. Only exception: if using `--async` flag or command timed out (exit code 69), then use `sf org resume scratch` to check status. **Note**: SKILL.md Step 4 requires a single `sf org list --json` call after creation for artifact collection (not polling) |
+| Dev Hub must be authenticated | Scratch org creation requires Dev Hub access |
+| `--edition`, `--snapshot`, `--source-org` are mutually exclusive | Only one creation source allowed per command |
+| Definition file overrides can use flags | Flags like `--edition`, `--name`, `--username`, `--release`, `--admin-email` override definition file values |
+| Snapshot requires same Dev Hub | Snapshot must be created in the same Dev Hub you're using |
+| Duration max is 30 days | Platform limit for scratch org expiration |
+| Source tracking enabled by default | Disable with `--no-track-source` only for CI/CD or performance needs |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|------------|
+| `No default Dev Hub org found` | Authenticate Dev Hub with `sf org login web --set-default-dev-hub` or specify `--target-dev-hub` |
+| `NamedOrgNotFoundError` on Dev Hub | Dev Hub org is not authenticated — run `sf org login web` |
+| `edition value must be one of` | Invalid edition specified — use developer, enterprise, group, professional, or partner variants |
+| `Snapshot not found` | Snapshot doesn't exist in this Dev Hub — run `sf org list snapshot` to see available |
+| `sourceOrg value must be 15 or 18 characters` | Org shape ID format incorrect — use output from `sf org list shape` |
+| `The org could not be created` | Generic creation failure — check Dev Hub limits, licensing, or try again |
+| Timeout during creation (exit code 69) | Command timed out waiting for org. CLI displays the resume command with Request ID. User can run the displayed command or increase `--wait` time (min 2 minutes) for next attempt |
+| `Definition file not found` | Path to definition file is incorrect — verify file exists |
+| Partner editions unavailable | Partner editions only work if Dev Hub is a Partner Business Org |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- **Created scratch org**: Authenticated and ready to use
+- **JSON response**: Contains `username`, `orgId`, `scratchOrgInfo` with Request ID
+- **Local auth info**: Stored in `.sf/` directory for future CLI commands
+
+If `--async` used or timeout occurs:
+- **Request ID**: Returned in `scratchOrgInfo.Id` (format: `2SR...`)
+- **Resume command**: `sf org resume scratch --job-id <request-id> --json`
+- **Timeout exit code**: 69
+
+---
+
+## Additional Resources
+
+- See `definition_file_options.md` for org features, settings, and configuration templates
+- See `edition_types.md` for available edition types and when to use each