docs(issue): add command reference for explain and plan

docs/src/content/docs/commands/issue.md

@@ -95,3 +95,99 @@ Latest event:
 ```bash
 sentry issue view FRONT-ABC -w
 ```
+
+### `sentry issue explain`
+
+Analyze an issue's root cause using Seer AI.
+
+```bash
+sentry issue explain <issue-id>
+```
+
+This command analyzes the issue and provides:
+- Identified root causes
+- Reproduction steps
+- Relevant code locations
+
+The analysis may take a few minutes for new issues.
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<issue-id>` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--org <org-slug>` | Organization slug (required for short IDs if not auto-detected) |
+| `--project <project-slug>` | Project slug (required for short suffixes if not auto-detected) |
+| `--force` | Force new analysis even if one already exists |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# By numeric issue ID
+sentry issue explain 123456789
+
+# By short ID
+sentry issue explain MYPROJECT-ABC --org my-org
+
+# By short suffix (requires project context)
+sentry issue explain G --org my-org --project my-project
+
+# Force a fresh analysis
+sentry issue explain 123456789 --force
+```
+
+**Requirements:**
+
+- Seer AI enabled for your organization
+- GitHub integration configured with repository access
+- Code mappings set up to link stack frames to source files
+
+### `sentry issue plan`
+
+Generate a solution plan for a Sentry issue using Seer AI.
+
+```bash
+sentry issue plan <issue-id>
+```
+
+This command requires that `sentry issue explain` has been run first to identify the root cause. It generates a solution plan with specific implementation steps to fix the issue.
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<issue-id>` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--org <org-slug>` | Organization slug (required for short IDs if not auto-detected) |
+| `--project <project-slug>` | Project slug (required for short suffixes if not auto-detected) |
+| `--cause <n>` | Root cause ID to plan (required if multiple causes were identified) |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# After running explain, create a plan
+sentry issue plan 123456789
+
+# Specify which root cause to plan for (if multiple were found)
+sentry issue plan 123456789 --cause 0
+
+# By short ID
+sentry issue plan MYPROJECT-ABC --org my-org --cause 1
+```
+
+**Requirements:**
+
+- Root cause analysis must be completed first (`sentry issue explain`)
+- GitHub integration configured for your organization
+- Code mappings set up for your project

docs/src/content/docs/features.md

@@ -0,0 +1,219 @@
+---
+title: Features
+description: Advanced features of the Sentry CLI
+---
+
+The Sentry CLI includes several features designed to streamline your workflow, especially in complex project setups.
+
+## DSN Auto-Detection
+
+The CLI automatically detects your Sentry project from your codebase, eliminating the need to specify `--org` and `--project` flags for every command.
+
+### How It Works
+
+DSN detection follows this priority order (highest first):
+
+1. **Source code** - Explicit DSN in `Sentry.init()` calls
+2. **Environment files** - `.env.local`, `.env`, etc.
+3. **Environment variable** - `SENTRY_DSN`
+
+When a DSN is found, the CLI resolves it to your organization and project, then caches the result for fast subsequent lookups.
+
+### Supported Languages
+
+The CLI can detect DSNs from source code in these languages:
+
+| Language | File Extensions | Detection Pattern |
+|----------|-----------------|-------------------|
+| JavaScript/TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | `Sentry.init({ dsn: "..." })` |
+| Python | `.py` | `sentry_sdk.init(dsn="...")` |
+| Go | `.go` | `sentry.Init(sentry.ClientOptions{Dsn: "..."})` |
+| Java | `.java` | `Sentry.init(options -> options.setDsn("..."))` |
+| Ruby | `.rb` | `Sentry.init { |config| config.dsn = "..." }` |
+| PHP | `.php` | `\Sentry\init(['dsn' => '...'])` |
+
+### Caching
+
+To avoid scanning your codebase on every command, the CLI caches:
+
+- **DSN location** - Which file contains the DSN
+- **Resolved project** - The org/project slugs from the API
+
+The cache is validated on each run by checking if the source file still contains the same DSN. If the DSN changes or the file is deleted, a full scan is triggered.
+
+### Usage
+
+Once your project has a DSN configured, commands automatically use it:
+
+```bash
+# Instead of:
+sentry issue list --org my-org --project my-project
+
+# Just run:
+sentry issue list
+```
+
+The CLI will show which project was detected:
+
+```
+Detected project: my-app (from .env)
+
+ID          SHORT ID    TITLE                           COUNT
+123456789   MYAPP-ABC   TypeError: Cannot read prop...  142
+```
+
+## Monorepo Support & Alias System
+
+In monorepos with multiple Sentry projects, the CLI generates short aliases for each project, making it easy to work with issues across projects.
+
+### How Aliases Work
+
+When you run `sentry issue list`, the CLI:
+
+1. Scans for DSNs in monorepo directories (`packages/`, `apps/`, etc.)
+2. Generates unique short aliases for each project
+3. Caches the aliases for use with other commands
+
+Aliases are the shortest unique prefix of each project slug. For example:
+
+| Project Slug | Alias |
+|--------------|-------|
+| `frontend` | `f` |
+| `functions` | `fu` |
+| `backend` | `b` |
+
+For projects with a common prefix (like `spotlight-electron`, `spotlight-website`), the prefix is stripped first:
+
+| Project Slug | Alias |
+|--------------|-------|
+| `spotlight-electron` | `e` |
+| `spotlight-website` | `w` |
+| `spotlight-backend` | `b` |
+
+### Using Alias-Suffix Format
+
+After running `issue list`, you can reference issues using the `alias-suffix` format:
+
+```bash
+# List issues - note the ALIAS column
+sentry issue list
+```
+
+```
+ALIAS  SHORT ID             TITLE                           COUNT
+e      SPOTLIGHT-ELEC-4Y    TypeError: Cannot read prop...  142
+w      SPOTLIGHT-WEB-ABC    Failed to fetch user data       89
+b      SPOTLIGHT-BACK-XYZ   Connection timeout              34
+```
+
+```bash
+# View issue using alias-suffix
+sentry issue view e-4Y
+
+# Explain using alias-suffix
+sentry issue explain w-ABC
+
+# Works with any issue command
+sentry issue plan b-XYZ
+```
+
+### Cross-Organization Support
+
+If you work with multiple organizations that have projects with the same slug, the CLI uses org-prefixed aliases:
+
+```
+ALIAS    SHORT ID        TITLE
+o1:api   ORG1-API-123    Error in API handler
+o2:api   ORG2-API-456    Database connection failed
+```
+
+## Issue ID Formats
+
+The CLI accepts several formats for identifying issues:
+
+### Numeric ID
+
+The internal Sentry issue ID:
+
+```bash
+sentry issue view 123456789
+sentry issue explain 987654321
+```
+
+### Full Short ID
+
+The project-prefixed short ID shown in Sentry UI:
+
+```bash
+sentry issue view MYPROJECT-ABC
+sentry issue explain FRONTEND-XYZ
+```
+
+### Short Suffix
+
+Just the suffix portion when `--project` context is provided:
+
+```bash
+sentry issue view ABC --org my-org --project myproject
+```
+
+### Alias-Suffix
+
+The short alias plus suffix, available after running `issue list`:
+
+```bash
+# First, list issues to populate the alias cache
+sentry issue list
+
+# Then use alias-suffix format
+sentry issue view e-4Y
+sentry issue explain w-ABC
+sentry issue plan b-XYZ
+```
+
+This format is especially useful in monorepos where you're working across multiple projects.
+
+## AI-Powered Analysis with Seer
+
+The CLI integrates with Sentry's Seer AI to provide root cause analysis and fix plans directly in your terminal.
+
+### Root Cause Analysis
+
+Use `sentry issue explain` to understand why an issue is happening:
+
+```bash
+sentry issue explain MYPROJECT-ABC
+```
+
+Seer analyzes:
+- Stack traces and error messages
+- Related events and patterns
+- Your codebase (via GitHub integration)
+
+And provides:
+- Detailed root cause explanation
+- Reproduction steps
+- Relevant code locations
+
+### Fix Plans
+
+After understanding the root cause, use `sentry issue plan` to get actionable fix steps:
+
+```bash
+sentry issue plan MYPROJECT-ABC
+```
+
+The plan includes:
+- Specific files to modify
+- Code changes to make
+- Implementation guidance
+
+### Requirements
+
+For Seer integration to work, you need:
+
+1. **Seer enabled** for your organization
+2. **GitHub integration** configured with repository access
+3. **Code mappings** set up to link stack frames to source files
+
+See [Sentry's Seer documentation](https://docs.sentry.io/product/issues/issue-details/ai-suggested-solution/) for setup instructions.

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

@@ -210,6 +210,24 @@ Analyze an issue's root cause using Seer AI
 - `--json - Output as JSON`
 - `--force - Force new analysis even if one exists`
 
+**Examples:**
+
+```bash
+sentry issue explain <issue-id>
+
+# By numeric issue ID
+sentry issue explain 123456789
+
+# By short ID
+sentry issue explain MYPROJECT-ABC --org my-org
+
+# By short suffix (requires project context)
+sentry issue explain G --org my-org --project my-project
+
+# Force a fresh analysis
+sentry issue explain 123456789 --force
+```
+
 #### `sentry issue plan <arg0>`
 
 Generate a solution plan using Seer AI
@@ -220,6 +238,21 @@ Generate a solution plan using Seer AI
 - `--cause <value> - Root cause ID to plan (required if multiple causes exist)`
 - `--json - Output as JSON`
 
+**Examples:**
+
+```bash
+sentry issue plan <issue-id>
+
+# After running explain, create a plan
+sentry issue plan 123456789
+
+# Specify which root cause to plan for (if multiple were found)
+sentry issue plan 123456789 --cause 0
+
+# By short ID
+sentry issue plan MYPROJECT-ABC --org my-org --cause 1
+```
+
 #### `sentry issue view <arg0>`
 
 View details of a specific issue