@salesforce/afv-skills 1.6.9 → 1.7.1

package/skills/{agentforce-development → developing-agentforce}/references/agent-script-core-language.md

@@ -192,8 +192,8 @@ The expression inside `{! ... }` is evaluated by the runtime during deterministi
 - `@topic.<name>` — reference a topic by name
 - `@variables.<name>` — reference a variable (use in logic)
 - `{!@variables.<name>}` — reference a variable in prompt text (template injection)
-- `@outputs.<name>` — reference an action output (only in post-action context)
-- `@inputs.<name>` — reference an action input (in action definition)
+- `@outputs.<name>` — action output (only in `set`/`if` immediately after the action — unavailable elsewhere)
+- `@inputs.<name>` — action input (only in `with` during invocation — NOT in `set` or post-execution)
 - `@utils.<function>` — reference a utility (escalate, transition to, setVariables)
 
 **Do NOT use `<>` as inequality operator.** Use `!=` instead.
@@ -243,6 +243,26 @@ config:
     - `default_agent_user`
     - MessagingSession linked variables (`EndUserId`, `RoutableId`, `ContactId`, `EndUserLanguage`)
     - Escalation topic with `@utils.escalate`
+    - `connection messaging:` block
+
+  **Common mistake — service-agent constructs on employee agent:**
+
+  ```agentscript
+  # WRONG — employee agent with service-agent constructs
+  config:
+      agent_type: "AgentforceEmployeeAgent"
+      default_agent_user: "agent@org.ext"    # PROHIBITED — causes "Internal Error"
+  variables:
+      EndUserId: linked string               # SERVICE ONLY — no messaging session
+          source: @MessagingSession.MessagingEndUserId
+  connection messaging:                       # SERVICE ONLY — no messaging channel
+      escalation_message: "Transferring..."
+
+  # RIGHT — clean employee agent config
+  config:
+      agent_type: "AgentforceEmployeeAgent"
+      # No default_agent_user, no MessagingSession vars, no connection block
+  ```
 
 **Conditionally required fields:**
 - `default_agent_user` — **required for `AgentforceServiceAgent`, prohibited for `AgentforceEmployeeAgent`**. This is the Salesforce username of the Einstein Agent User that runs agent actions on behalf of the customer. The user must exist in the target org, be active, and have the Einstein Agent license assigned.
@@ -528,6 +548,23 @@ run @actions.process_order
 
 After an action completes, you can check outputs and transition.
 
+**Scope lifecycle — `@inputs` and `@outputs` are ephemeral:**
+- `@inputs`: only in `with` directives during invocation. NOT in `set`/`if` after execution.
+- `@outputs`: only in `set`/`if` immediately after invocation. NOT in instructions or later actions.
+- To reuse an input value post-execution, capture it in `@variables` BEFORE the action call.
+
+```agentscript
+# WRONG — silent failure, @inputs out of scope in set
+run @actions.get_station_status
+    with station_name = ...
+    set @variables.station = @inputs.station_name   # FAILS SILENTLY
+
+# RIGHT — use @outputs (if action echoes value) or capture input beforehand
+run @actions.get_station_status
+    with station_name = ...
+    set @variables.station = @outputs.station_name
+```
+
 **How pipe sections become the LLM prompt**:
 
 All logic is resolved first; only matching `|` pipe lines are included in the prompt:
@@ -852,7 +889,7 @@ reasoning:
 
 Transition discards the current topic's prompt and starts fresh with the target topic.
 
-**`@utils.escalate`** — route to a human agent:
+**`@utils.escalate`** — route to a human agent (**service agents only** — requires a `connection messaging:` block, which is only valid for `AgentforceServiceAgent`; do not use in employee agents):
 
 ```agentscript
 reasoning:

package/skills/{agentforce-development → developing-agentforce}/references/agent-user-setup.md

@@ -18,7 +18,7 @@ PID_DigitalAgent (typically included with Agentforce licenses)
 | **`default_agent_user` in config** | Required | Omit entirely |
 | **Respects Sharing Rules** | No (consistent permissions) | Yes (user's data access) |
 
-**How to check agent type**: Look at the `agent_type` field in the `config:` block of your `.agent` file, or query: `sf data query --query "SELECT DeveloperName, Type FROM BotDefinition WHERE DeveloperName = 'AgentName'" -o TARGET_ORG --json`
+**How to check agent type**: Look at the `agent_type` field in the `config:` block of your `.agent` file, or query: `sf data query --json --query "SELECT DeveloperName, Type FROM BotDefinition WHERE DeveloperName = 'AgentName'" -o TARGET_ORG`
 
 ---
 
@@ -28,18 +28,19 @@ For CLI-first workflow (tested: ~8 minutes total):
 
 ```bash
 # Step 1: Query existing Einstein Agent Users (30 seconds)
-sf data query \
+sf data query --json \
   --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 2: Create Einstein Agent User (2 minutes)
-# Get Profile ID
-PROFILE_ID=$(sf data query \
+# Get Profile ID (read result.records[0].Id from JSON response)
+sf data query --json \
   --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" \
-  -o TARGET_ORG --json | jq -r '.result.records[0].Id')
+  -o TARGET_ORG
 
 # For Production/Sandbox (non-scratch org):
-sf data create record --sobject User --values \
+# Use the ProfileId from the query above
+sf data create record --json --sobject User --values \
   "Username=<agent_name>_user@<orgId>.ext \
    LastName=<AgentName> \
    Email=admin@example.com \
@@ -47,55 +48,55 @@ sf data create record --sobject User --values \
    TimeZoneSidKey=America/Los_Angeles \
    LocaleSidKey=en_US \
    EmailEncodingKey=UTF-8 \
-   ProfileId=${PROFILE_ID} \
+   ProfileId=<PROFILE_ID> \
    LanguageLocaleKey=en_US" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # For Scratch Orgs (use user definition file):
 # sf org create user --definition-file config/einstein-agent-user.json -o TARGET_ORG
 
 # Step 3: Assign System Permission Set (1 minute)
-sf org assign permset \
+sf org assign permset --json \
   --name AgentforceServiceAgentUser \
   --on-behalf-of <agent_name>_user@<orgId>.ext \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 4: Deploy Custom Permission Set (3 minutes)
 # (Create the .permissionset-meta.xml file first - see Section 3.2 template)
-sf project deploy start \
+sf project deploy start --json \
   --metadata PermissionSet:<AgentName>_Access \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Assign custom PS
-sf org assign permset \
+sf org assign permset --json \
   --name <AgentName>_Access \
   --on-behalf-of <agent_name>_user@<orgId>.ext \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 5: Verify All Permissions (1 minute)
-sf data query \
+sf data query --json \
   --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '<agent_name>_user@<orgId>.ext' ORDER BY PermissionSet.Name" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Expected: AgentforceServiceAgentUser + <AgentName>_Access
 
 # Step 6: Deploy Agent Bundle (unpublished metadata)
-sf project deploy start \
+sf project deploy start --json \
   --source-dir force-app/main/default/aiAuthoringBundles/<AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
 # Step 7: Test BEFORE Publishing (recommended)
-sf agent preview start \
+sf agent preview start --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 # Test all topics and actions to verify permissions
 
 # Step 8: Publish & Activate (only after testing passes)
-sf agent publish authoring-bundle \
+sf agent publish authoring-bundle --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 
-sf agent activate \
+sf agent activate --json \
   --api-name <AgentName> \
   -o TARGET_ORG
 ```
@@ -118,19 +119,20 @@ Service agents need a dedicated service account with consistent permissions.
 
 **Get Org ID first** (needed for username format):
 ```bash
-sf org display -o TARGET_ORG --json | jq -r '.result.id'
+sf org display --json -o TARGET_ORG
+# Read result.id from the JSON response
 ```
 
 **Query existing Einstein Agent Users** (skip creation if one exists):
 ```bash
-sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true" -o TARGET_ORG
 ```
 
 **Create the user** (if none exists):
 
 1. Get the Einstein Agent User profile ID:
    ```bash
-   sf data query --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" -o TARGET_ORG --json
+   sf data query --json --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" -o TARGET_ORG
    ```
 
 2. Create a user definition file (`config/einstein-agent-user.json`):
@@ -153,7 +155,7 @@ sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Nam
 
    **Option A: Scratch Org (Definition File)**
    ```bash
-   sf org create user \
+   sf org create user --json \
      --definition-file config/einstein-agent-user.json \
      -o TARGET_ORG
    ```
@@ -161,21 +163,22 @@ sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Profile.Nam
    **Option B: Production/Sandbox (Direct Record Creation)**
    ```bash
    # Get Profile ID first
-   PROFILE_ID=$(sf data query \
+   # Get Profile ID (read result.records[0].Id from JSON response)
+   sf data query --json \
      --query "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'" \
-     -o TARGET_ORG --json | jq -r '.result.records[0].Id')
+     -o TARGET_ORG
 
-   # Create user directly
-   sf data create record --sobject User --values \
-     "Username='{agent_name}_agent@{orgId}.ext' LastName='{AgentName} Agent' Email='placeholder@example.com' Alias='agntuser' ProfileId='${PROFILE_ID}' TimeZoneSidKey='America/Los_Angeles' LocaleSidKey='en_US' EmailEncodingKey='UTF-8' LanguageLocaleKey='en_US'" \
-     -o TARGET_ORG --json
+   # Create user directly (use ProfileId from query above)
+   sf data create record --json --sobject User --values \
+     "Username='{agent_name}_agent@{orgId}.ext' LastName='{AgentName} Agent' Email='placeholder@example.com' Alias='agntuser' ProfileId='<PROFILE_ID>' TimeZoneSidKey='America/Los_Angeles' LocaleSidKey='en_US' EmailEncodingKey='UTF-8' LanguageLocaleKey='en_US'" \
+     -o TARGET_ORG
    ```
 
    **Note**: `sf org create user` only works in scratch orgs. For production/sandbox, use `sf data create record`. Attempting `sf org create user` in a non-scratch org fails with an authorization error.
 
 4. Verify creation:
    ```bash
-   sf data query --query "SELECT Id, Username, IsActive FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+   sf data query --json --query "SELECT Id, Username, IsActive FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
    ```
 
 **Username format**: `{agent_name}_agent@{orgId}.ext` (production) or `{agent_name}.{suffix}@{orgfarm}.salesforce.com` (dev/scratch). Always query the target org to confirm the exact format.
@@ -192,12 +195,12 @@ Via Setup UI:
 
 Via CLI:
 ```bash
-sf org assign permset --name AgentforceServiceAgentUser --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG --json
+sf org assign permset --json --name AgentforceServiceAgentUser --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG
 ```
 
 Verify assignment:
 ```bash
-sf data query --query "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG
 ```
 
 ---
@@ -230,7 +233,7 @@ Key rule: Include EVERY Apex class referenced via `apex://` in your agent script
 
 Deploy the permission set:
 ```bash
-sf project deploy start --source-dir force-app/main/default/permissionsets/{AgentName}_Access.permissionset-meta.xml -o TARGET_ORG --json
+sf project deploy start --json --source-dir force-app/main/default/permissionsets/{AgentName}_Access.permissionset-meta.xml -o TARGET_ORG
 ```
 
 ---
@@ -239,12 +242,12 @@ sf project deploy start --source-dir force-app/main/default/permissionsets/{Agen
 
 Via CLI:
 ```bash
-sf org assign permset --name {AgentName}_Access --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG --json
+sf org assign permset --json --name {AgentName}_Access --on-behalf-of "{agent_name}_agent@{orgId}.ext" -o TARGET_ORG
 ```
 
 Verify both permission sets are assigned:
 ```bash
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 ```
 
 Expected output includes both:
@@ -273,9 +276,9 @@ config:
 #### 6.1: Deploy Agent Bundle (Unpublished)
 
 ```bash
-sf project deploy start \
+sf project deploy start --json \
   --source-dir force-app/main/default/aiAuthoringBundles/<AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 This deploys the agent as **unpublished metadata** — you can edit freely without version management.
@@ -283,9 +286,9 @@ This deploys the agent as **unpublished metadata** — you can edit freely witho
 #### 6.2: Test with Preview (Before Publishing)
 
 ```bash
-sf agent preview start \
+sf agent preview start --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 What to test:
@@ -312,9 +315,9 @@ See [preview-test-loop.md](preview-test-loop.md) for the complete smoke test wor
 Only publish after all tests pass.
 
 ```bash
-sf agent publish authoring-bundle \
+sf agent publish authoring-bundle --json \
   --api-name <AgentName> \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 **Publishing does NOT activate.** The new BotVersion is created as `Inactive`. You must explicitly activate.
@@ -322,19 +325,19 @@ sf agent publish authoring-bundle \
 #### 6.4: Activate Agent
 
 ```bash
-sf agent activate \
+sf agent activate --json \
   --api-name <AgentName> \
   -o TARGET_ORG
 ```
 
-`sf agent activate` does NOT support `--json`. It prints a plain-text confirmation.
+Note: `sf agent activate` may not support `--json` in all CLI versions. It prints a plain-text confirmation.
 
 #### 6.5: Verify Activation
 
 ```bash
-sf data query \
+sf data query --json \
   --query "SELECT Id, DeveloperName, Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<AgentName>' ORDER BY CreatedDate DESC LIMIT 1" \
-  -o TARGET_ORG --json
+  -o TARGET_ORG
 ```
 
 Expected: `Status = 'Active'`
@@ -366,7 +369,7 @@ Same XML template as Step 3 above. Include `<classAccesses>` for all Apex classe
 Assign the custom PS to employees (not to a service account):
 
 ```bash
-sf org assign permset --name {AgentName}_Access --on-behalf-of "employee@company.com" -o TARGET_ORG --json
+sf org assign permset --json --name {AgentName}_Access --on-behalf-of "employee@company.com" -o TARGET_ORG
 ```
 
 Or use Permission Set Groups for role-based access.
@@ -384,7 +387,7 @@ config:
 ### Step 4: Publish
 
 ```bash
-sf agent publish authoring-bundle --api-name Employee_Agent -o TARGET_ORG --json
+sf agent publish authoring-bundle --json --api-name Employee_Agent -o TARGET_ORG
 ```
 
 ---
@@ -409,22 +412,22 @@ Run this combined query to verify all setup steps for a Service Agent:
 
 ```bash
 # 1. Einstein Agent User exists and is active
-sf data query --query "SELECT Id, Username, IsActive, Profile.Name FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT Id, Username, IsActive, Profile.Name FROM User WHERE Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 
 # 2. System PS assigned
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = 'AgentforceServiceAgentUser'" -o TARGET_ORG
 
 # 3. Custom PS assigned
-sf data query --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = '{AgentName}_Access'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext' AND PermissionSet.Name = '{AgentName}_Access'" -o TARGET_ORG
 
 # 4. All permission sets for user (combined view)
-sf data query --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG --json
+sf data query --json --query "SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment WHERE Assignee.Username = '{agent_name}_agent@{orgId}.ext'" -o TARGET_ORG
 
 # 5. Agent config has default_agent_user
 # Check your .agent file's config: block
 
 # 6. Agent publishes successfully
-sf agent publish authoring-bundle --api-name AgentName -o TARGET_ORG --json
+sf agent publish authoring-bundle --json --api-name AgentName -o TARGET_ORG
 ```
 
 Checklist:

package/skills/{agentforce-development → developing-agentforce}/references/agent-validation-and-debugging.md

@@ -20,7 +20,7 @@ The `sf agent validate` command checks Agent Script files for syntax errors, str
 After modifying any `.agent` file, always run this command:
 
 ```bash
-sf agent validate authoring-bundle --api-name <AGENT_NAME> --json
+sf agent validate authoring-bundle --json --api-name <AGENT_NAME>
 ```
 
 Replace `<AGENT_NAME>` with the directory name under `aiAuthoringBundles/` (without the `.agent` extension). Always include `--json` so the output is machine-readable.
@@ -28,7 +28,7 @@ Replace `<AGENT_NAME>` with the directory name under `aiAuthoringBundles/` (with
 Example:
 
 ```bash
-sf agent validate authoring-bundle --api-name Local_Info_Agent --json
+sf agent validate authoring-bundle --json --api-name Local_Info_Agent
 ```
 
 ### Interpreting Output
@@ -183,21 +183,21 @@ ALWAYS use `--json` when calling from a script or AI assistant (not interactive
 #### Step 1: Start a Session
 
 ```bash
-sf agent preview start --authoring-bundle <BUNDLE_NAME> --json
+sf agent preview start --json --authoring-bundle <BUNDLE_NAME> --use-live-actions
 ```
 
-This command returns a session ID. Capture it immediately — you need it for every subsequent command.
+This command returns a session ID. Capture it immediately — you need it for every subsequent command. Use `--use-live-actions` to execute real backing logic (recommended). Omit it only when backing logic doesn't exist yet and you want simulated preview.
 
 Example:
 
 ```bash
-sf agent preview start --authoring-bundle Local_Info_Agent --json
+sf agent preview start --json --authoring-bundle Local_Info_Agent --use-live-actions
 ```
 
 #### Step 2: Send Utterances
 
 ```bash
-sf agent preview send --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> -u "<MESSAGE>" --json
+sf agent preview send --json --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> -u "<MESSAGE>"
 ```
 
 Include the same `--authoring-bundle` name and the session ID from Step 1. You can send multiple utterances in the same session — do not end and restart between turns.
@@ -205,13 +205,13 @@ Include the same `--authoring-bundle` name and the session ID from Step 1. You c
 Example:
 
 ```bash
-sf agent preview send --authoring-bundle Local_Info_Agent --session-id abc123def456 -u "What's the weather?" --json
+sf agent preview send --json --authoring-bundle Local_Info_Agent --session-id abc123def456 -u "What's the weather?"
 ```
 
 #### Step 3: End a Session (Optional)
 
 ```bash
-sf agent preview end --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID> --json
+sf agent preview end --json --authoring-bundle <BUNDLE_NAME> --session-id <SESSION_ID>
 ```
 
 This command returns the path to session trace files. Call it when the conversation is complete. Do not end prematurely — if the user may ask follow-up questions, keep the session open.
@@ -229,7 +229,7 @@ Simulated preview mode speeds up inner-loop development but cannot validate real
 **Live Preview Mode.** Real backing code executes and returns real outputs. Pass `--use-live-actions`:
 
 ```bash
-sf agent preview start --authoring-bundle <BUNDLE_NAME> --use-live-actions --json
+sf agent preview start --json --authoring-bundle <BUNDLE_NAME> --use-live-actions
 ```
 
 Use live preview mode when:
@@ -240,6 +240,8 @@ Live preview mode is required for reliable grounding testing. The grounding chec
 
 CRITICAL: `--use-live-actions` is ONLY valid with `--authoring-bundle`. Published agents (`--api-name`) always execute real actions — do NOT pass `--use-live-actions` with `--api-name`.
 
+CRITICAL: `--use-live-actions` is a flag on `preview start` ONLY. Do NOT pass it to `preview send` or `preview end` — those commands do not accept it and will error.
+
 ### Agent Identification
 
 Use exactly one of these mutually exclusive flags:
@@ -264,7 +266,7 @@ The CLI automatically uses the project's default target org. Always omit `--targ
 sf agent preview --authoring-bundle My_Bundle
 
 # CORRECT — programmatic API
-sf agent preview start --authoring-bundle My_Bundle --json
+sf agent preview start --json --authoring-bundle My_Bundle
 ```
 
 The bare `sf agent preview` command is an interactive REPL for humans. Automation cannot provide terminal input (ESC), so it hangs. Use `start`/`send`/`end` with `--json`.
@@ -273,10 +275,10 @@ The bare `sf agent preview` command is an interactive REPL for humans. Automatio
 
 ```bash
 # WRONG — mutually exclusive flags
-sf agent preview start --authoring-bundle My_Bundle --api-name My_Agent --json
+sf agent preview start --json --authoring-bundle My_Bundle --api-name My_Agent
 
 # CORRECT — choose one
-sf agent preview start --authoring-bundle My_Bundle --json
+sf agent preview start --json --authoring-bundle My_Bundle
 ```
 
 These flags are mutually exclusive. Use the one matching your agent type.
@@ -299,11 +301,11 @@ Use `agent preview` commands with `--api-name` to preview published agents.
 
 ```bash
 # WRONG — no session exists
-sf agent preview send --authoring-bundle My_Bundle -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle -u "Hello"
 
 # CORRECT — start first, capture session ID
-sf agent preview start --authoring-bundle My_Bundle --json
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview start --json --authoring-bundle My_Bundle
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 Each session has a unique ID. You must start before sending.
@@ -312,10 +314,10 @@ Each session has a unique ID. You must start before sending.
 
 ```bash
 # WRONG — missing --authoring-bundle
-sf agent preview send --session-id <ID> -u "Hello" --json
+sf agent preview send --json --session-id <ID> -u "Hello"
 
 # CORRECT
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 Every command after `start` must include the same `--authoring-bundle` or `--api-name` flag.
@@ -324,10 +326,10 @@ Every command after `start` must include the same `--authoring-bundle` or `--api
 
 ```bash
 # WRONG — concurrent sessions collide
-sf agent preview send --authoring-bundle My_Bundle -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle -u "Hello"
 
 # CORRECT — always include session ID
-sf agent preview send --authoring-bundle My_Bundle --session-id <ID> -u "Hello" --json
+sf agent preview send --json --authoring-bundle My_Bundle --session-id <ID> -u "Hello"
 ```
 
 If multiple agents have concurrent sessions against the same agent, omitting the session ID causes them to interfere. Always pass the session ID from `start`.
@@ -699,7 +701,7 @@ Use this systematic 8-step approach when diagnosing any agent behavior issue.
 
 6. **Fix** — Update Agent Script instructions, variable logic, or action definitions based on what you found.
 
-7. **Validate** — Run `sf agent validate authoring-bundle --api-name <AGENT_NAME> --json` to ensure the fix doesn't introduce syntax errors.
+7. **Validate** — Run `sf agent validate authoring-bundle --json --api-name <AGENT_NAME>` to ensure the fix doesn't introduce syntax errors.
 
 8. **Re-Test** — Run a new preview session with the same input and compare traces. Verify the fix resolved the issue.