docs: fix stale Bun references and add systemic doc drift checks

.github/workflows/ci.yml

@@ -197,6 +197,7 @@ jobs:
       - run: pnpm run check:deps
       - run: pnpm run check:errors
       - run: pnpm run check:patches
+      - run: pnpm run check:stale-refs
 
   test-unit:
     name: Unit Tests

DEVELOPMENT.md

@@ -2,7 +2,10 @@
 
 ## Prerequisites
 
-- [Bun](https://bun.sh/) installed
+<!-- GENERATED:START dev-prereq -->
+- [Node.js](https://nodejs.org/) v22.15+ installed
+- [pnpm](https://pnpm.io/) v10.11+ installed
+<!-- GENERATED:END dev-prereq -->
 - A Sentry OAuth application (create one at https://sentry.io/settings/account/api/applications/)
 
 ## Setup
@@ -88,11 +91,13 @@ The table below lists the most common development variables. For the complete re
 
 ## Building
 
-Building the native binary still requires Bun:
+<!-- GENERATED:START build-toolchain -->
+Build the native binary (uses esbuild for bundling and fossilize for Node SEA packaging):
 
 ```bash
 pnpm run build
 ```
+<!-- GENERATED:END build-toolchain -->
 
 ## Architecture
 

README.md

@@ -77,7 +77,7 @@ Credentials are stored in `~/.sentry/` with restricted permissions (mode 600).
 ## Library Usage
 
 <!-- GENERATED:START library-prereq -->
-Use Sentry CLI programmatically in Node.js (≥22.15) or Bun without spawning a subprocess:
+Use Sentry CLI programmatically in Node.js (≥22.15) without spawning a subprocess:
 <!-- GENERATED:END library-prereq -->
 
 ```typescript
@@ -118,7 +118,7 @@ Errors are thrown as `SentryError` with `.exitCode` and `.stderr`.
 ### Prerequisites
 
 <!-- GENERATED:START dev-prereq -->
-- [Bun](https://bun.sh) v1.3+
+- [Node.js](https://nodejs.org) v22.15+ and [pnpm](https://pnpm.io) v10.11+
 <!-- GENERATED:END dev-prereq -->
 
 ### Setup

docs/src/content/docs/contributing.md

@@ -10,7 +10,8 @@ We welcome contributions to the Sentry CLI! This guide will help you get started
 ### Prerequisites
 
 <!-- GENERATED:START dev-prereq -->
-- [Bun](https://bun.sh) runtime (v1.3 or later)
+- [Node.js](https://nodejs.org) (v22.15 or later)
+- [pnpm](https://pnpm.io) (v10.11 or later)
 <!-- GENERATED:END dev-prereq -->
 - Git
 
@@ -84,8 +85,9 @@ cli/
 
 ## Building
 
+<!-- GENERATED:START build-commands -->
 ```bash
-# Build for current platform (requires Bun for native binary compilation)
+# Build for current platform (uses esbuild + fossilize for Node SEA packaging)
 pnpm run build
 
 # Build for all platforms
@@ -94,6 +96,7 @@ pnpm run build:all
 # Create npm bundle
 pnpm run bundle
 ```
+<!-- GENERATED:END build-commands -->
 
 ## Testing
 

docs/src/content/docs/library-usage.md

@@ -1,6 +1,6 @@
 ---
 title: Library Usage
-description: Use the Sentry CLI programmatically in Node.js or Bun
+description: Use the Sentry CLI programmatically in Node.js
 ---
 
 The Sentry CLI can be used as a JavaScript/TypeScript library, running commands
@@ -216,7 +216,6 @@ Calls should be sequential (awaited one at a time).
 ## Requirements
 
 - **Node.js >= 22** (required for `node:sqlite`)
-- Or **Bun** (any recent version)
 
 ## Streaming Commands
 

docs/src/fragments/commands/cli.md

@@ -61,6 +61,52 @@ The CLI detects how it was installed and uses the appropriate upgrade method:
 
 Nightly builds are only available as standalone binaries (via the curl install method). Switching to nightly from a package manager install will automatically migrate to a standalone binary.
 
+### View and manage defaults
+
+```bash
+# Show all current defaults
+sentry cli defaults
+
+# Set default organization
+sentry cli defaults org my-org
+
+# Set default project
+sentry cli defaults project my-project
+
+# Set default Sentry URL (self-hosted)
+sentry cli defaults url https://sentry.example.com
+
+# Disable telemetry
+sentry cli defaults telemetry off
+
+# Clear a single default
+sentry cli defaults org --clear
+
+# Clear all defaults
+sentry cli defaults --clear
+```
+
+### Import legacy settings
+
+Import settings from `.sentryclirc` files used by the legacy `sentry-cli`:
+
+```bash
+# Auto-detect and import .sentryclirc
+sentry cli import
+
+# Preview what would be imported
+sentry cli import --dry-run
+
+# Skip confirmation prompt
+sentry cli import --yes
+
+# Explicitly trust a self-hosted URL
+sentry cli import --url https://sentry.example.com
+
+# Skip API validation of the imported token
+sentry cli import --skip-validation
+```
+
 ### Send feedback
 
 ```bash

docs/src/fragments/commands/dashboard.md

@@ -108,6 +108,36 @@ sentry dashboard widget delete 'My Dashboard' --title 'Error Count'
 sentry dashboard widget delete 12345 --index 2
 ```
 
+### View revision history
+
+```bash
+# List revisions by dashboard title
+sentry dashboard revisions 'Frontend Performance'
+
+# List revisions by dashboard ID
+sentry dashboard revisions 12345
+
+# With explicit org
+sentry dashboard revisions my-org 12345
+```
+
+### Restore a previous revision
+
+```bash
+# Restore by dashboard title and revision number
+sentry dashboard restore 'Frontend Performance' --revision 3
+
+# Restore by dashboard ID
+sentry dashboard restore 12345 --revision 1
+
+# Preview without applying
+sentry dashboard restore 12345 --revision 1 --dry-run
+```
+
+:::tip
+Use `sentry dashboard revisions` to find the revision number before restoring.
+:::
+
 ## Query Shorthand
 
 The `--query` flag supports shorthand for aggregate functions:

docs/src/fragments/commands/issue.md

@@ -53,6 +53,40 @@ Sentry search uses **implicit AND** — space-separated terms are all required.
 Full syntax reference: [Sentry Search Docs](https://docs.sentry.io/concepts/search/)
 :::
 
+### Magic selectors
+
+Use `@latest` and `@most_frequent` to target issues without knowing their ID:
+
+```bash
+# View the most recent issue
+sentry issue view @latest
+
+# Explain the most frequently occurring issue
+sentry issue explain @most_frequent
+
+# Generate a fix plan for the latest issue
+sentry issue plan @latest
+```
+
+### List events for an issue
+
+```bash
+# List recent events for an issue
+sentry issue events FRONT-ABC
+
+# Filter events by search query
+sentry issue events FRONT-ABC --query "browser:Chrome"
+
+# Show full event details
+sentry issue events FRONT-ABC --full
+
+# Limit results and filter by time period
+sentry issue events FRONT-ABC --limit 50 --period 24h
+
+# Paginate through results
+sentry issue events FRONT-ABC -c next
+```
+
 ### View an issue
 
 ```bash

package.json

@@ -120,7 +120,8 @@
     "check:deps": "pnpm tsx script/check-no-deps.ts",
     "check:errors": "pnpm tsx script/check-error-patterns.ts",
     "check:patches": "pnpm tsx script/check-patches.ts",
-    "check:docs-sections": "pnpm tsx script/generate-docs-sections.ts --check"
+    "check:docs-sections": "pnpm tsx script/generate-docs-sections.ts --check",
+    "check:stale-refs": "pnpm tsx script/check-stale-references.ts"
   },
   "type": "module",
   "types": "./dist/index.d.cts",

plugins/README.md

@@ -81,7 +81,7 @@ The SKILL.md file is **auto-generated** from the CLI's command definitions. Do n
 To regenerate after modifying commands:
 
 ```bash
-bun run generate:docs
+pnpm run generate:docs
 ```
 
 CI will auto-commit updated skill files when they are stale.

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

@@ -20,6 +20,31 @@ View and manage default settings
 - `-y, --yes - Skip confirmation prompt`
 - `-f, --force - Force the operation without confirmation`
 
+**Examples:**
+
+```bash
+# Show all current defaults
+sentry cli defaults
+
+# Set default organization
+sentry cli defaults org my-org
+
+# Set default project
+sentry cli defaults project my-project
+
+# Set default Sentry URL (self-hosted)
+sentry cli defaults url https://sentry.example.com
+
+# Disable telemetry
+sentry cli defaults telemetry off
+
+# Clear a single default
+sentry cli defaults org --clear
+
+# Clear all defaults
+sentry cli defaults --clear
+```
+
 ### `sentry cli feedback <message...>`
 
 Send feedback about the CLI
@@ -57,6 +82,25 @@ Import settings from legacy .sentryclirc files
 - `--url <value> - Explicitly trust this URL (bypasses same-file trust check)`
 - `--skip-validation - Skip token validation against the Sentry API`
 
+**Examples:**
+
+```bash
+# Auto-detect and import .sentryclirc
+sentry cli import
+
+# Preview what would be imported
+sentry cli import --dry-run
+
+# Skip confirmation prompt
+sentry cli import --yes
+
+# Explicitly trust a self-hosted URL
+sentry cli import --url https://sentry.example.com
+
+# Skip API validation of the imported token
+sentry cli import --skip-validation
+```
+
 ### `sentry cli setup`
 
 Configure shell integration

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

@@ -175,11 +175,37 @@ List dashboard revisions
 - `-n, --limit <value> - Maximum number of revisions to list - (default: "25")`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**Examples:**
+
+```bash
+# List revisions by dashboard title
+sentry dashboard revisions 'Frontend Performance'
+
+# List revisions by dashboard ID
+sentry dashboard revisions 12345
+
+# With explicit org
+sentry dashboard revisions my-org 12345
+```
+
 ### `sentry dashboard restore <org/dashboard...>`
 
 Restore a dashboard revision
 
 **Flags:**
 - `-r, --revision <value> - Revision ID to restore`
 
+**Examples:**
+
+```bash
+# Restore by dashboard title and revision number
+sentry dashboard restore 'Frontend Performance' --revision 3
+
+# Restore by dashboard ID
+sentry dashboard restore 12345 --revision 1
+
+# Preview without applying
+sentry dashboard restore 12345 --revision 1 --dry-run
+```
+
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

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

@@ -111,6 +111,25 @@ List events for a specific issue
 | `crashFile` | string \| null | Crash file URL |
 | `metadata` | object \| null | Event metadata |
 
+**Examples:**
+
+```bash
+# List recent events for an issue
+sentry issue events FRONT-ABC
+
+# Filter events by search query
+sentry issue events FRONT-ABC --query "browser:Chrome"
+
+# Show full event details
+sentry issue events FRONT-ABC --full
+
+# Limit results and filter by time period
+sentry issue events FRONT-ABC --limit 50 --period 24h
+
+# Paginate through results
+sentry issue events FRONT-ABC -c next
+```
+
 ### `sentry issue explain <issue>`
 
 Analyze an issue's root cause using Seer AI
@@ -122,6 +141,15 @@ Analyze an issue's root cause using Seer AI
 **Examples:**
 
 ```bash
+# View the most recent issue
+sentry issue view @latest
+
+# Explain the most frequently occurring issue
+sentry issue explain @most_frequent
+
+# Generate a fix plan for the latest issue
+sentry issue plan @latest
+
 # Analyze root cause (may take a few minutes for new issues)
 sentry issue explain 123456789