@salesforce/plugin-agent 1.39.0 → 1.39.1

package/README.md

@@ -130,7 +130,7 @@ EXAMPLES
     $ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
 ```
 
-_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/activate.ts)_
 
 ## `sf agent create`
 
@@ -197,7 +197,7 @@ EXAMPLES
     $ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
 ```
 
-_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/create.ts)_
 
 ## `sf agent deactivate`
 
@@ -238,7 +238,7 @@ EXAMPLES
     $ sf agent deactivate --api-name Resort_Manager --target-org my-org
 ```
 
-_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/deactivate.ts)_
 
 ## `sf agent generate agent-spec`
 
@@ -345,7 +345,7 @@ EXAMPLES
     $ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
 ```
 
-_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/generate/agent-spec.ts)_
+_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/generate/agent-spec.ts)_
 
 ## `sf agent generate authoring-bundle`
 
@@ -422,7 +422,7 @@ EXAMPLES
       other-package-dir/main/default --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/generate/authoring-bundle.ts)_
+_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/generate/authoring-bundle.ts)_
 
 ## `sf agent generate template`
 
@@ -484,7 +484,7 @@ EXAMPLES
       my-package --source-org my-scratch-org
 ```
 
-_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/generate/template.ts)_
 
 ## `sf agent generate test-spec`
 
@@ -549,7 +549,7 @@ EXAMPLES
       force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
 ```
 
-_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/generate/test-spec.ts)_
+_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/generate/test-spec.ts)_
 
 ## `sf agent preview`
 
@@ -622,7 +622,7 @@ EXAMPLES
     $ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
 ```
 
-_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -694,7 +694,7 @@ EXAMPLES
     $ sf agent preview end --all --target-org <target_org>
 ```
 
-_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -752,7 +752,7 @@ EXAMPLES
     $ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/preview/send.ts)_
 
 ## `sf agent preview sessions`
 
@@ -785,7 +785,7 @@ EXAMPLES
     $ sf agent preview sessions
 ```
 
-_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -850,7 +850,7 @@ EXAMPLES
     $ sf agent preview start --api-name My_Published_Agent
 ```
 
-_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -910,7 +910,7 @@ EXAMPLES
     $ sf agent publish authoring-bundle --api-name MyAuthoringbundle --concise
 ```
 
-_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/publish/authoring-bundle.ts)_
+_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -965,7 +965,7 @@ EXAMPLES
     $ sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview
 ```
 
-_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -1000,7 +1000,7 @@ EXAMPLES
     $ sf agent test list --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -1076,7 +1076,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1160,7 +1160,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1244,7 +1244,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/run.ts)_
 
 ## `sf agent test run-eval`
 
@@ -1317,11 +1317,11 @@ EXAMPLES
   $ echo '{"tests":[...]}' | sf agent test run-eval --spec --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/run-eval.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/test/run-eval.ts)_
+_See code: [src/commands/agent/test/run-eval.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/test/run-eval.ts)_
 
 ## `sf agent trace delete`
 
-Delete agent preview trace files.
+Delete trace files from an agent preview session.
 
 ```
 USAGE
@@ -1329,28 +1329,34 @@ USAGE
     [--no-prompt]
 
 FLAGS
-  -a, --agent=<value>       Only delete traces for this agent name (substring match). Matches against the name used when
-                            starting the session, whether that's an authoring bundle or a published agent API name.
+  -a, --agent=<value>       API name of the agent used to filter the list of trace files you want to delete. Matches
+                            against the API name used when starting the session, either an authoring bundle or a
+                            published agent API name.
       --no-prompt           Skip the confirmation prompt and delete immediately.
-      --older-than=<value>  Only delete traces older than this duration. Accepts a number followed by a unit: m/minutes,
-                            h/hours, d/days, w/weeks (e.g. 7d, 24h, 2w).
-      --session-id=<value>  Only delete traces from this session ID.
+      --older-than=<value>  Duration used to filter the list of trace files; only files older than the duration are
+                            deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples:
+                            7d, 24h, 2w.
+      --session-id=<value>  Session ID used to filter the list of trace files you want to delete. Use the "agent preview
+                            sessions" CLI command to list all known agent preview sessions along with their session IDs.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
   --json               Format output as json.
 
 DESCRIPTION
-  Delete agent preview trace files.
+  Delete trace files from an agent preview session.
 
-  Deletes trace files recorded during agent preview sessions. By default, shows a preview of what will be deleted and
-  prompts for confirmation. Use --no-prompt to skip confirmation.
+  When you run an agent preview conversation (either interactive or programmatic), trace files are automatically
+  recorded and saved in your local DX project. Use this command to delete some or all of the trace files.
 
-  Without filters, deletes all traces for all agents and sessions. Use flags to narrow the scope: filter by agent name
-  (--agent), by session (--session-id), or by age (--older-than).
+  By default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip
+  confirmation.
+
+  Without filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope:
+  filter by agent API name (--agent), by session (--session-id), or by age (--older-than).
 
 EXAMPLES
-  Delete all traces for all agents and sessions (with confirmation prompt):
+  Delete all traces for all agents and sessions; prompt for confirmation:
 
     $ sf agent trace delete
 
@@ -1366,29 +1372,31 @@ EXAMPLES
 
     $ sf agent trace delete --older-than 7d
 
-  Delete traces older than 24 hours for a specific agent, no prompt:
+  Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:
 
     $ sf agent trace delete --agent My_Agent --older-than 24h --no-prompt
 
-  Delete all traces without confirmation:
+  Delete all traces for all agents and sessions; don't prompt for confirmation:
 
     $ sf agent trace delete --no-prompt
 ```
 
-_See code: [src/commands/agent/trace/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/trace/delete.ts)_
+_See code: [src/commands/agent/trace/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/trace/delete.ts)_
 
 ## `sf agent trace list`
 
-List the trace files that were recorded during all agent preview sessions.
+List the available trace files that were recorded during all agent preview sessions.
 
 ```
 USAGE
   $ sf agent trace list [--json] [--flags-dir <value>] [--session-id <value>] [-a <value>] [--since <value>]
 
 FLAGS
-  -a, --agent=<value>       Only show traces for this agent name (substring match). Matches against the name used when
-                            starting the session, whether that's an authoring bundle or a published agent API name.
-      --session-id=<value>  Session ID used to filter the list of trace files.
+  -a, --agent=<value>       API name of the agent used to filter the list of available trace files. Matches against the
+                            API name used when starting the session, either an authoring bundle or a published agent API
+                            name.
+      --session-id=<value>  Session ID used to filter the list of trace files. Use the "agent preview sessions" CLI
+                            command to list all known agent preview sessions along with their session IDs.
       --since=<value>       Date used to filter the list of trace files; only those recorded on or after the date are
                             listed.
 
@@ -1397,33 +1405,34 @@ GLOBAL FLAGS
   --json               Format output as json.
 
 DESCRIPTION
-  List the trace files that were recorded during all agent preview sessions.
+  List the available trace files that were recorded during all agent preview sessions.
 
-  Lists trace files recorded during agent preview sessions. By default, lists all traces for all agents and all of their
-  sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date
+  When you run an agent preview conversation (either interactive or programmatic), trace files are automatically
+  recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of
+  their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date
   (--since).
 
   Each row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column
   shows the authoring bundle or API name used when starting the session.
 
 EXAMPLES
-  List all traces for all agents and sessions:
+  List all trace files for all agents and sessions:
 
     $ sf agent trace list
 
-  List all traces for a specific agent:
+  List all trace files for a specific agent:
 
     $ sf agent trace list --agent My_Agent
 
-  List traces for a specific session:
+  List trace files for a specific session:
 
     $ sf agent trace list --session-id <SESSION_ID>
 
-  List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
+  List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
 
     $ sf agent trace list --since 2026-04-20
 
-  List traces recorded on or after a specific UTC time:
+  List trace files recorded on or after a specific UTC time:
 
     $ sf agent trace list --since 2026-04-20T14:00:00Z
 
@@ -1442,11 +1451,11 @@ FLAG DESCRIPTIONS
     (2026-04-20T14:00:00.000Z). The "Recorded At" values shown in the table output are valid inputs.
 ```
 
-_See code: [src/commands/agent/trace/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/trace/list.ts)_
+_See code: [src/commands/agent/trace/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/trace/list.ts)_
 
 ## `sf agent trace read`
 
-Read and analyze trace files from an agent preview session.
+Read trace files from an agent preview session.
 
 ```
 USAGE
@@ -1454,43 +1463,58 @@ USAGE
     actions|grounding|routing|errors] [-t <value>]
 
 FLAGS
-  -d, --dimension=<option>  Dimension to drill into when using --format detail. One of: actions, grounding, routing,
-                            errors. Required when --format is detail.
+  -d, --dimension=<option>  Dimension to drill into when using "--format detail"; used to filter and organize the trace
+                            data to answer a specific type of question.
                             <options: actions|grounding|routing|errors>
-  -f, --format=<option>     [default: summary] Output format: summary (default), detail, or raw. Use detail with
-                            --dimension to drill into a specific aspect of the trace.
+  -f, --format=<option>     [default: summary] Output format of the trace data; specifies the level of detail you want
+                            in the trace files.
                             <options: summary|detail|raw>
-  -s, --session-id=<value>  (required) Session ID to read traces for.
-  -t, --turn=<value>        Scope output to this conversation turn number.
+  -s, --session-id=<value>  (required) Session ID to read traces for. Use the "agent preview sessions" CLI command to
+                            list all known agent preview sessions along with their session IDs
+  -t, --turn=<value>        Turn number for which you want trace data. A turn is a single utterance or response in a
+                            conversation, starting with 1.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
   --json               Format output as json.
 
 DESCRIPTION
-  Read and analyze trace files from an agent preview session.
-
-  Reads trace files recorded during an agent preview session and outputs them in one of three formats.
-
-  **--format summary** (default): A per-turn narrative showing topic routing, actions executed, and the agent's
-  response. Use this to quickly understand what happened in a session.
-
-  **--format detail**: Diagnostic drill-down into a specific dimension (--dimension required). Filters output to only
-  the trace steps relevant to that dimension, minimizing noise.
-
-  **--format raw**: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to
-  perform custom analysis.
-
-  Available dimensions for --format detail: actions, grounding, routing, errors.
-
-  Use --turn N to scope output to a single conversation turn.
+  Read trace files from an agent preview session.
+
+  When you run an agent preview conversation (either interactive or programmatic), trace files are automatically
+  recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data.
+  Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe,
+  monitor, investigate, and troubleshoot agent events and behavior.
+
+  Use the --format flag to specify one of these formats of the outputted trace data:
+
+  - summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this
+  to quickly understand what happened in a preview session.
+  - detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that
+  dimension, minimizing noise.
+  - raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom
+  analysis.
+
+  If you specify "--format detail", you must also specify a dimension with the --dimension flag. Dimensions are a way to
+  slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence
+  of everything that happened, each dimension filters and organizes the trace data to answer a specific type of
+  question. These are the available dimensions and the information they provide:
+
+  - actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this
+  dimension to understand what the agent actually did when answering an utterance in the preview session.
+  - grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent "thought" about the problem
+  - the AI reasoning that determined which actions to take.
+  - routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and
+  why the agent switched between different subagents or contexts during the conversation.
+  - errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all
+  steps.
 
 EXAMPLES
-  Show a session summary (all turns):
+  Show a session trace summary for all turns in the session with the specified ID:
 
     $ sf agent trace read --session-id <SESSION_ID>
 
-  Show summary for a single turn:
+  Show a trace summary for the second turn (utterance or response) of the conversation:
 
     $ sf agent trace read --session-id <SESSION_ID> --turn 2
 
@@ -1498,7 +1522,7 @@ EXAMPLES
 
     $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension actions
 
-  Drill into routing decisions for a specific turn:
+  Drill into routing decisions for the first turn of the conversation:
 
     $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension routing --turn 1
 
@@ -1515,7 +1539,7 @@ EXAMPLES
     $ sf agent trace read --session-id <SESSION_ID> --json
 ```
 
-_See code: [src/commands/agent/trace/read.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/trace/read.ts)_
+_See code: [src/commands/agent/trace/read.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/trace/read.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1562,6 +1586,6 @@ EXAMPLES
     $ sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.0/src/commands/agent/validate/authoring-bundle.ts)_
+_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.39.1/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

package/messages/agent.trace.delete.md

@@ -1,24 +1,26 @@
 # summary
 
-Delete agent preview trace files.
+Delete trace files from an agent preview session.
 
 # description
 
-Deletes trace files recorded during agent preview sessions. By default, shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.
+When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.
 
-Without filters, deletes all traces for all agents and sessions. Use flags to narrow the scope: filter by agent name (--agent), by session (--session-id), or by age (--older-than).
+By default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.
+
+Without filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).
 
 # flags.agent.summary
 
-Only delete traces for this agent name (substring match). Matches against the name used when starting the session, whether that's an authoring bundle or a published agent API name.
+API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.
 
 # flags.session-id.summary
 
-Only delete traces from this session ID.
+Session ID used to filter the list of trace files you want to delete. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs.
 
 # flags.older-than.summary
 
-Only delete traces older than this duration. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks (e.g. 7d, 24h, 2w).
+Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.
 
 # flags.no-prompt.summary
 
@@ -26,11 +28,11 @@ Skip the confirmation prompt and delete immediately.
 
 # error.invalidOlderThan
 
-Invalid --older-than value: '%s'. Use a number followed by a unit: m/minutes, h/hours, d/days, w/weeks (e.g. 7d, 24h, 30m, 2w).
+Invalid --older-than value: '%s'. Use a number followed by a unit: m/minutes, h/hours, d/days, w/weeks, Examples: 7d, 24h, 30m, 2w.
 
 # prompt.confirm
 
-Delete %s trace file(s)? This cannot be undone.
+Delete %s trace file(s)? This can't be undone.
 
 # output.noneFound
 
@@ -62,7 +64,7 @@ Plan ID
 
 # examples
 
-- Delete all traces for all agents and sessions (with confirmation prompt):
+- Delete all traces for all agents and sessions; prompt for confirmation:
 
   <%= config.bin %> <%= command.id %>
 
@@ -78,10 +80,10 @@ Plan ID
 
   <%= config.bin %> <%= command.id %> --older-than 7d
 
-- Delete traces older than 24 hours for a specific agent, no prompt:
+- Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:
 
   <%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt
 
-- Delete all traces without confirmation:
+- Delete all traces for all agents and sessions; don't prompt for confirmation:
 
   <%= config.bin %> <%= command.id %> --no-prompt

package/messages/agent.trace.list.md

@@ -1,20 +1,20 @@
 # summary
 
-List the trace files that were recorded during all agent preview sessions.
+List the available trace files that were recorded during all agent preview sessions.
 
 # description
 
-Lists trace files recorded during agent preview sessions. By default, lists all traces for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).
+When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).
 
 Each row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.
 
 # flags.agent.summary
 
-Only show traces for this agent name (substring match). Matches against the name used when starting the session, whether that's an authoring bundle or a published agent API name.
+API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.
 
 # flags.session-id.summary
 
-Session ID used to filter the list of trace files.
+Session ID used to filter the list of trace files. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs.
 
 # flags.since.summary
 
@@ -58,23 +58,23 @@ Path
 
 # examples
 
-- List all traces for all agents and sessions:
+- List all trace files for all agents and sessions:
 
   <%= config.bin %> <%= command.id %>
 
-- List all traces for a specific agent:
+- List all trace files for a specific agent:
 
   <%= config.bin %> <%= command.id %> --agent My_Agent
 
-- List traces for a specific session:
+- List trace files for a specific session:
 
   <%= config.bin %> <%= command.id %> --session-id <SESSION_ID>
 
-- List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
+- List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
 
   <%= config.bin %> <%= command.id %> --since 2026-04-20
 
-- List traces recorded on or after a specific UTC time:
+- List trace files recorded on or after a specific UTC time:
 
   <%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z