docs: fix stale Bun references and add systemic doc drift checks (#1024)

## Summary

Fix the Bun→Node migration documentation drift with systemic
improvements that prevent this class of error from recurring.

**Supersedes #1022** — that PR found real issues but missed several
stale references and lacked systemic prevention.

## Changes

### 1. Fix `generate-docs-sections.ts` root cause

- Replace `extractBunVersion()` with `extractPnpmVersion()` derived from
`packageManager` field
- **Make both version extractors throw on mismatch** instead of silently
falling back — this is the core systemic fix that prevents the generator
from ever silently producing wrong output again
- Update all prerequisite generators to reference Node.js + pnpm
- Remove "or Bun" from library-usage prerequisite

### 2. Expand generated marker coverage

Convert hand-written toolchain-dependent prose into generated sections
so it can't drift:

- `DEVELOPMENT.md` prerequisites → `GENERATED:START/END dev-prereq`
markers
- `DEVELOPMENT.md` build section → `GENERATED:START/END build-toolchain`
markers
- `contributing.md` build section → `GENERATED:START/END build-commands`
markers

Also fix remaining stale refs in: `library-usage.md`,
`plugins/README.md`, `check-no-deps.ts`

### 3. Add generic `check:stale-refs` toolchain consistency check

New `script/check-stale-references.ts` that **derives stale patterns
from `package.json`** — not hardcoded to Bun:

- Reads `packageManager` field to determine the current PM (`pnpm`)
- Flags all other PMs' dev commands (`bun run`, `yarn remove`, etc.) in
dev-facing docs
- **If the project ever migrates from pnpm to something else**, changing
`packageManager` automatically makes the check flag every `pnpm run` /
`pnpm add` reference
- Added to CI lint job

### 4. Enhance `check:fragments` with subcommand coverage validation

The existing check only verified fragment files exist — not that they
document all subcommands. New Check 5:

- Verifies each fragment mentions all subcommands in the route (via
heading or code reference)
- Handles default commands (`sentry local` = `sentry local serve`)
- Strips fenced code blocks to avoid false heading matches from bash
comments
- Warns by default, `--strict` flag for hard errors

### 5. Fill subcommand coverage gaps

- `dashboard.md`: add `revisions`, `restore` examples
- `cli.md`: add `defaults`, `import` examples  
- `issue.md`: add `events` subcommand and `@latest`/`@most_frequent`
selectors

## Verification

All checks pass:
- `check:fragments` — all subcommands covered
- `check:stale-refs` — no stale PM references (23 files scanned)
- `check:docs-sections` — all generated sections up to date
- `check:deps` — error message fixed
- `typecheck` — clean
- `test:unit` — 314 files, 7227 tests pass

Author: BYK

.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

.lore.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
 

DEVELOPMENT.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

README.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/contributing.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/content/docs/library-usage.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/cli.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
+
+# With explicit org
+sentry dashboard restore my-org 12345 --revision 1
+```
+
+:::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/dashboard.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

docs/src/fragments/commands/issue.md

@@ -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",