fix(cli): Generate accurate command references

Keep positional syntax and examples in command metadata for help, docs, and skills. Validate agent-conversation targets before API access.

Co-Authored-By: OpenAI GPT-6 Sol <noreply@openai.com>

Author: BYK

apps/cli-docs/src/fragments/commands/agent-conversation.md

@@ -1,36 +0,0 @@
-
-
-
-## Examples
-
-### List conversations
-
-```bash
-# List recent agent conversations
-sentry agent-conversation list
-
-# Explicit organization
-sentry agent-conversation list my-org
-
-# Show more, last 24 hours
-sentry agent-conversation list --limit 50 --period 24h
-
-# Filter conversations
-sentry agent-conversation list -q "has:errors"
-
-# Paginate through results
-sentry agent-conversation list my-org -c next
-```
-
-### View a conversation transcript
-
-```bash
-# View full transcript (org auto-detected)
-sentry agent-conversation view conv-123
-
-# Explicit org (slash-separated)
-sentry agent-conversation view my-org/conv-123
-
-# JSON output
-sentry agent-conversation view my-org/conv-123 --json
-```

packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -389,7 +389,7 @@ Authenticate with Sentry
 Work with Sentry organizations
 
 - `sentry org list` — List organizations
-- `sentry org view <org>` — View details of an organization
+- `sentry org view [<org>]` — View details of an organization
 
 → Full flags and examples: `references/org.md`
 
@@ -399,16 +399,16 @@ Work with Sentry projects
 
 - `sentry project create [<org>/]<name>:<platform>...` — Create one or more projects
 - `sentry project delete <org/project>` — Delete a project
-- `sentry project list <org/project>` — List projects
-- `sentry project view <org/project>` — View details of a project
+- `sentry project list [<org/project>]` — List projects
+- `sentry project view [<org/project>]` — View details of a project
 
 → Full flags and examples: `references/project.md`
 
 ### Issue
 
 Manage Sentry issues
 
-- `sentry issue list <org/project>` — List issues in a project
+- `sentry issue list [<org/project>]` — List issues in a project
 - `sentry issue events <issue>` — List events for a specific issue
 - `sentry issue explain <issue...>` — Analyze one or more issues using Seer AI
 - `sentry issue plan <issue>` — Generate a solution plan using Seer AI
@@ -444,12 +444,12 @@ Make an authenticated API request
 
 Manage Sentry alert rules
 
-- `sentry alert issues list <org/project>` — List issue alert rules
+- `sentry alert issues list [<org/project>]` — List issue alert rules
 - `sentry alert issues view <org/project/rule-id-or-name>` — View an issue alert rule
-- `sentry alert issues create <target>` — Create an issue alert rule
+- `sentry alert issues create [<target>]` — Create an issue alert rule
 - `sentry alert issues delete <org/project/rule-id-or-name>` — Delete an issue alert rule
 - `sentry alert issues edit <org/project/rule-id-or-name>` — Edit an issue alert rule
-- `sentry alert metrics list <target>` — List metric alert rules
+- `sentry alert metrics list [<target>]` — List metric alert rules
 - `sentry alert metrics view <org/rule-id-or-name>` — View a metric alert rule
 - `sentry alert metrics create <target>` — Create a metric alert rule
 - `sentry alert metrics delete <org/rule-id-or-name>` — Delete a metric alert rule
@@ -470,14 +470,14 @@ Manage mobile build artifacts
 
 CLI-related commands
 
-- `sentry cli completion <shell>` — Print the shell completion script
+- `sentry cli completion [<shell>]` — Print the shell completion script
 - `sentry cli defaults <key value...>` — View and manage default settings
 - `sentry cli feedback <message...>` — Send feedback about the CLI
 - `sentry cli fix` — Diagnose and repair CLI database issues
 - `sentry cli import` — Import settings from legacy .sentryclirc files
 - `sentry cli setup` — Configure shell integration
 - `sentry cli uninstall` — Uninstall Sentry CLI
-- `sentry cli upgrade <version>` — Update the Sentry CLI to the latest version
+- `sentry cli upgrade [<version>]` — Update the Sentry CLI to the latest version
 
 → Full flags and examples: `references/cli.md`
 
@@ -493,8 +493,8 @@ Manage code mappings for stack trace linking
 
 List and view agent conversations
 
-- `sentry agent-conversation list <org>` — List recent agent conversations
-- `sentry agent-conversation view <org/conversation-id>` — View an agent conversation transcript
+- `sentry agent-conversation list [<org>]` — List recent agent conversations
+- `sentry agent-conversation view [<org>/]<conversation-id>` — View an agent conversation transcript
 
 → Full flags and examples: `references/agent-conversation.md`
 
@@ -547,7 +547,7 @@ Search and query current Sentry documentation
 
 Find Sentry DSNs
 
-- `sentry dsn list <org/project>` — List DSNs
+- `sentry dsn list [<org/project>]` — List DSNs
 
 → Full flags and examples: `references/dsn.md`
 
@@ -581,7 +581,7 @@ Upload React Native sourcemaps from build steps
 
 Search and inspect Session Replays
 
-- `sentry replay list <org/project>` — List recent Session Replays
+- `sentry replay list [<org/project>]` — List recent Session Replays
 - `sentry replay view <replay-id-or-url...>` — View a Session Replay
 - `sentry replay download <replay-id-or-url...>` — Download a Session Replay as rrweb JSON
 
@@ -591,14 +591,14 @@ Search and inspect Session Replays
 
 Work with Sentry releases
 
-- `sentry release list <org/project>` — List releases with adoption and health metrics
+- `sentry release list [<org/project>]` — List releases with adoption and health metrics
 - `sentry release view <org/version>` — View release details with health metrics
 - `sentry release create <org/version>` — Create a release
 - `sentry release finalize <org/version>` — Finalize a release
 - `sentry release delete <org/version>` — Delete a release
 - `sentry release archive <org/version>` — Archive a release
 - `sentry release restore <org/version>` — Restore an archived release
-- `sentry release deploy <org/version> <environment> <name>` — Create a deploy for a release
+- `sentry release deploy <org/version> <environment> [<name>]` — Create a deploy for a release
 - `sentry release deploys <org/version>` — List deploys for a release
 - `sentry release set-commits <org/version>` — Set commits for a release
 - `sentry release propose-version` — Propose a release version
@@ -609,31 +609,31 @@ Work with Sentry releases
 
 Work with Sentry repositories
 
-- `sentry repo list <org/project>` — List repositories
+- `sentry repo list [<org/project>]` — List repositories
 
 → Full flags and examples: `references/repo.md`
 
 ### Team
 
 Work with Sentry teams
 
-- `sentry team list <org/project>` — List teams
+- `sentry team list [<org/project>]` — List teams
 
 → Full flags and examples: `references/team.md`
 
 ### Explore
 
 Query aggregate event data (Explore)
 
-- `sentry explore <target>` — Query aggregate event data (Explore)
+- `sentry explore [<target>]` — Query aggregate event data (Explore)
 
 → Full flags and examples: `references/explore.md`
 
 ### Feedback
 
 Manage User Feedback
 
-- `sentry feedback list <org/project>` — List and search User Feedback
+- `sentry feedback list [<org/project>]` — List and search User Feedback
 - `sentry feedback view <feedback>` — View a User Feedback item
 - `sentry feedback resolve <feedback>` — Mark User Feedback as resolved
 - `sentry feedback unresolve <feedback>` — Return User Feedback to the inbox
@@ -655,7 +655,7 @@ View Sentry logs
 Work with Sentry cron monitors
 
 - `sentry monitor run <monitor-slug command...>` — Wrap a command with cron monitor check-ins
-- `sentry monitor list <org/project>` — List cron monitors
+- `sentry monitor list [<org/project>]` — List cron monitors
 
 → Full flags and examples: `references/monitor.md`
 
@@ -700,7 +700,7 @@ Check Sentry service status
 
 View distributed traces
 
-- `sentry trace list <org/project>` — List recent traces in a project
+- `sentry trace list [<org/project>]` — List recent traces in a project
 - `sentry trace view <org/project/trace-id...>` — View details of a specific trace
 - `sentry trace logs <org/project/trace-id...>` — View logs associated with a trace
 
@@ -710,16 +710,16 @@ View distributed traces
 
 Manage product trials
 
-- `sentry trial list <org>` — List product trials
-- `sentry trial start <name> <org>` — Start a product trial
+- `sentry trial list [<org>]` — List product trials
+- `sentry trial start <name> [<org>]` — Start a product trial
 
 → Full flags and examples: `references/trial.md`
 
 ### Init
 
 Initialize Sentry in your project (experimental)
 
-- `sentry init <target> <directory>` — Initialize Sentry in your project (experimental)
+- `sentry init [<target>] [<directory>]` — Initialize Sentry in your project (experimental)
 
 → Full flags and examples: `references/init.md`
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md

@@ -11,7 +11,7 @@ requires:
 
 List and view agent conversations
 
-### `sentry agent-conversation list <org>`
+### `sentry agent-conversation list [<org>]`
 
 List recent agent conversations
 
@@ -64,7 +64,7 @@ sentry agent-conversation list -q "has:errors"
 sentry agent-conversation list my-org -c next
 ```
 
-### `sentry agent-conversation view <org/conversation-id>`
+### `sentry agent-conversation view [<org>/]<conversation-id>`
 
 View an agent conversation transcript
 
@@ -74,10 +74,10 @@ View an agent conversation transcript
 **Examples:**
 
 ```bash
-# View full transcript (org auto-detected)
+# View full transcript (organization auto-detected)
 sentry agent-conversation view conv-123
 
-# Explicit org (slash-separated)
+# Explicit organization
 sentry agent-conversation view my-org/conv-123
 
 # JSON output

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md

@@ -11,7 +11,7 @@ requires:
 
 Manage Sentry alert rules
 
-### `sentry alert issues list <org/project>`
+### `sentry alert issues list [<org/project>]`
 
 List issue alert rules
 
@@ -49,7 +49,7 @@ sentry alert issues view my-org/my-project/12345
 sentry alert issues view my-org/my-project/"Error Spike"
 ```
 
-### `sentry alert issues create <target>`
+### `sentry alert issues create [<target>]`
 
 Create an issue alert rule
 
@@ -112,7 +112,7 @@ Edit an issue alert rule
 sentry alert issues edit my-org/my-project/12345 --name "Prod Error Spike" --status disabled
 ```
 
-### `sentry alert metrics list <target>`
+### `sentry alert metrics list [<target>]`
 
 List metric alert rules
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -11,7 +11,7 @@ requires:
 
 CLI-related commands
 
-### `sentry cli completion <shell>`
+### `sentry cli completion [<shell>]`
 
 Print the shell completion script
 
@@ -172,7 +172,7 @@ sentry cli uninstall --yes --keep-config
 sentry cli uninstall
 ```
 
-### `sentry cli upgrade <version>`
+### `sentry cli upgrade [<version>]`
 
 Update the Sentry CLI to the latest version
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/dsn.md

@@ -11,7 +11,7 @@ requires:
 
 Find Sentry DSNs
 
-### `sentry dsn list <org/project>`
+### `sentry dsn list [<org/project>]`
 
 List DSNs
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/explore.md

@@ -11,7 +11,7 @@ requires:
 
 Query aggregate event data (Explore)
 
-### `sentry explore <target>`
+### `sentry explore [<target>]`
 
 Query aggregate event data (Explore)
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/feedback.md

@@ -11,7 +11,7 @@ requires:
 
 Manage User Feedback
 
-### `sentry feedback list <org/project>`
+### `sentry feedback list [<org/project>]`
 
 List and search User Feedback
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/init.md

@@ -11,7 +11,7 @@ requires:
 
 Initialize Sentry in your project (experimental)
 
-### `sentry init <target> <directory>`
+### `sentry init [<target>] [<directory>]`
 
 Initialize Sentry in your project (experimental)
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/issue.md

@@ -11,7 +11,7 @@ requires:
 
 Manage Sentry issues
 
-### `sentry issue list <org/project>`
+### `sentry issue list [<org/project>]`
 
 List issues in a project