feat(docs): auto-generate driftable doc sections (supersedes #851)

.github/workflows/ci.yml

@@ -148,7 +148,7 @@ jobs:
       - name: Check docs sections
         id: check-sections
         run: |
-          if git diff --quiet DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md; then
+          if git diff --quiet README.md DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md docs/src/content/docs/getting-started.mdx; then
             echo "Docs sections are up to date"
           else
             echo "stale=true" >> "$GITHUB_OUTPUT"
@@ -159,7 +159,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add plugins/sentry-cli/skills/sentry-cli/ DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md
+          git add plugins/sentry-cli/skills/sentry-cli/ README.md DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md docs/src/content/docs/getting-started.mdx
           git diff --cached --quiet || (git commit -m "chore: regenerate docs" && git push)
       - name: Fail for fork PRs with stale generated files
         if: (steps.check-skill.outputs.stale == 'true' || steps.check-sections.outputs.stale == 'true') && steps.token.outcome != 'success'

DEVELOPMENT.md

@@ -69,15 +69,20 @@ When creating your Sentry OAuth application:
 
 ## Environment Variables
 
-| Variable                | Description                                                      | Default              |
-| ----------------------- | ---------------------------------------------------------------- | -------------------- |
-| `SENTRY_CLIENT_ID`      | Sentry OAuth app client ID                                       | (required for build) |
-| `SENTRY_HOST`           | Sentry instance URL (for self-hosted, takes precedence)          | `https://sentry.io`  |
-| `SENTRY_URL`            | Alias for `SENTRY_HOST`                                          | `https://sentry.io`  |
-| `SENTRY_AUTH_TOKEN`     | API token for non-interactive use (lower priority than stored OAuth by default) | —     |
-| `SENTRY_FORCE_ENV_TOKEN`| Force env token to take priority over stored OAuth token         | —                    |
-| `SENTRY_CLI_NO_TELEMETRY`| Disable CLI telemetry (error tracking)                          | —                    |
-| `SENTRY_LOG_LEVEL`      | Diagnostic log level (`error`, `warn`, `log`, `info`, `debug`, `trace`) | `info`        |
+The table below lists the most common development variables. For the complete reference, see the generated [Configuration](https://cli.sentry.dev/configuration/) page.
+
+<!-- GENERATED:START dev-env-vars -->
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SENTRY_AUTH_TOKEN` | API token for non-interactive use (lower priority than stored OAuth by default) | — |
+| `SENTRY_FORCE_ENV_TOKEN` | Force env token to take priority over stored OAuth token | — |
+| `SENTRY_HOST` | Sentry instance URL (for self-hosted, takes precedence) | `https://sentry.io` |
+| `SENTRY_URL` | Alias for `SENTRY_HOST` | `https://sentry.io` |
+| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID | (required for build) |
+| `SENTRY_CONFIG_DIR` | Override credentials/cache directory | `~/.sentry/` |
+| `SENTRY_LOG_LEVEL` | Diagnostic log level (`error`, `warn`, `log`, `info`, `debug`, `trace`) | `info` |
+| `SENTRY_CLI_NO_TELEMETRY` | Disable CLI telemetry (error tracking) | — |
+<!-- GENERATED:END dev-env-vars -->
 
 ## Building
 

README.md

@@ -76,7 +76,9 @@ Credentials are stored in `~/.sentry/` with restricted permissions (mode 600).
 
 ## Library Usage
 
-Use Sentry CLI programmatically in Node.js (≥22) or Bun without spawning a subprocess:
+<!-- GENERATED:START library-prereq -->
+Use Sentry CLI programmatically in Node.js (≥22.12) or Bun without spawning a subprocess:
+<!-- GENERATED:END library-prereq -->
 
 ```typescript
 import createSentrySDK from "sentry";
@@ -115,7 +117,9 @@ Errors are thrown as `SentryError` with `.exitCode` and `.stderr`.
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) v1.0+
+<!-- GENERATED:START dev-prereq -->
+- [Bun](https://bun.sh) v1.3+
+<!-- GENERATED:END dev-prereq -->
 
 ### Setup
 
@@ -137,13 +141,17 @@ bun run --env-file=.env.local src/bin.ts --help
 
 ### Scripts
 
+<!-- GENERATED:START dev-scripts -->
 ```bash
-bun run build        # Build for current platform
-bun run typecheck    # Type checking
-bun run lint         # Check for issues
-bun run lint:fix     # Auto-fix issues
-bun test             # Run tests
+bun run build         # Build for current platform
+bun run typecheck     # Type checking
+bun run lint          # Check for issues
+bun run lint:fix      # Auto-fix issues
+bun run test:unit     # Run unit tests
+bun run test:e2e      # Run end-to-end tests
+bun run generate:docs # Regenerate command docs and skills
 ```
+<!-- GENERATED:END dev-scripts -->
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 

docs/src/content/docs/contributing.md

@@ -9,7 +9,9 @@ We welcome contributions to the Sentry CLI! This guide will help you get started
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) runtime (v1.0 or later)
+<!-- GENERATED:START dev-prereq -->
+- [Bun](https://bun.sh) runtime (v1.3 or later)
+<!-- GENERATED:END dev-prereq -->
 - Git
 
 ### Getting Started

docs/src/content/docs/getting-started.mdx

@@ -36,6 +36,16 @@ The `--version` flag takes precedence over `SENTRY_VERSION` if both are set.
 The chosen channel is persisted so that `sentry cli upgrade` automatically
 tracks the same channel on future updates.
 
+#### Supported Platforms
+
+{/* GENERATED:START platform-support */}
+| OS | Architectures | Notes |
+|----|---------------|-------|
+| **macOS** | x64, arm64 (Apple Silicon) |  |
+| **Linux** | x64, arm64 | glibc and musl (Alpine) |
+| **Windows** | x64 | Via Git Bash, MSYS2, or WSL |
+{/* GENERATED:END platform-support */}
+
 ### Homebrew
 
 ```bash

docs/src/content/docs/self-hosted.md

@@ -67,12 +67,16 @@ If you pass a self-hosted Sentry URL as a command argument (e.g., an issue or ev
 
 ## Relevant Environment Variables
 
+<!-- GENERATED:START self-hosted-env-vars -->
 | Variable | Description |
 |----------|-------------|
 | `SENTRY_HOST` | Base URL of your Sentry instance (takes precedence over `SENTRY_URL`) |
 | `SENTRY_URL` | Alias for `SENTRY_HOST` |
 | `SENTRY_CLIENT_ID` | Client ID of your public OAuth application |
+| `SENTRY_CUSTOM_HEADERS` | Custom HTTP headers for proxy/IAP (semicolon-separated `Name: Value` pairs) |
+| `SENTRY_FORCE_ENV_TOKEN` | Force env token over stored OAuth token |
 | `SENTRY_ORG` | Default organization slug |
 | `SENTRY_PROJECT` | Default project slug (supports `org/project` format) |
+<!-- GENERATED:END self-hosted-env-vars -->
 
 See [Configuration](./configuration/) for the full environment variable reference.

docs/src/fragments/commands/event.md

@@ -2,6 +2,34 @@
 
 ## Examples
 
+### Listing Events
+
+```bash
+# List events for an issue (using short ID)
+sentry event list PROJ-ABC
+
+# List events for an issue (using numeric ID)
+sentry event list 123456789
+
+# Filter by search query
+sentry event list PROJ-ABC --query "browser:Chrome"
+
+# Include full event bodies (stacktraces)
+sentry event list PROJ-ABC --full
+
+# Limit results and time range
+sentry event list PROJ-ABC --limit 50 --period 24h
+
+# Paginate through results
+sentry event list PROJ-ABC -c next
+sentry event list PROJ-ABC -c prev
+
+# Output as JSON
+sentry event list PROJ-ABC --json
+```
+
+### Viewing Events
+
 ```bash
 sentry event view abc123def456abc123def456abc12345
 ```

docs/src/fragments/commands/release.md

@@ -31,6 +31,15 @@ sentry release deploy 1.0.0 staging "Deploy #42"
 # Propose a version from git HEAD
 sentry release create $(sentry release propose-version)
 
+# List deploys for a release
+sentry release deploys 1.0.0
+sentry release deploys my-org/1.0.0
+
+# Delete a release
+sentry release delete my-org/1.0.0
+sentry release delete my-org/1.0.0 --yes        # Skip confirmation
+sentry release delete my-org/1.0.0 --dry-run    # Preview without deleting
+
 # Output as JSON
 sentry release list --json
 sentry release view 1.0.0 --json

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

@@ -20,6 +20,15 @@ View details of a specific event
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
+**Examples:**
+
+```bash
+sentry event view abc123def456abc123def456abc12345
+
+# Open in browser
+sentry event view abc123def456abc123def456abc12345 -w
+```
+
 ### `sentry event list <issue>`
 
 List events for an issue
@@ -55,10 +64,27 @@ List events for an issue
 **Examples:**
 
 ```bash
-sentry event view abc123def456abc123def456abc12345
+# List events for an issue (using short ID)
+sentry event list PROJ-ABC
 
-# Open in browser
-sentry event view abc123def456abc123def456abc12345 -w
+# List events for an issue (using numeric ID)
+sentry event list 123456789
+
+# Filter by search query
+sentry event list PROJ-ABC --query "browser:Chrome"
+
+# Include full event bodies (stacktraces)
+sentry event list PROJ-ABC --full
+
+# Limit results and time range
+sentry event list PROJ-ABC --limit 50 --period 24h
+
+# Paginate through results
+sentry event list PROJ-ABC -c next
+sentry event list PROJ-ABC -c prev
+
+# Output as JSON
+sentry event list PROJ-ABC --json
 ```
 
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

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

@@ -121,6 +121,15 @@ sentry release deploy 1.0.0 staging "Deploy #42"
 # Propose a version from git HEAD
 sentry release create $(sentry release propose-version)
 
+# List deploys for a release
+sentry release deploys 1.0.0
+sentry release deploys my-org/1.0.0
+
+# Delete a release
+sentry release delete my-org/1.0.0
+sentry release delete my-org/1.0.0 --yes        # Skip confirmation
+sentry release delete my-org/1.0.0 --dry-run    # Preview without deleting
+
 # Output as JSON
 sentry release list --json
 sentry release view 1.0.0 --json