docs: fix documentation gaps and auto-sync REFERENCE_FILES

Fix genuine documentation gaps not covered by auto-generation (#569):
- Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md
- Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md
- Add project:admin scope to DEVELOPMENT.md and self-hosted.md
- Expand README commands table from 6 to 14 entries
- Fix credential storage path (config.db -> cli.db) in auth docs
- Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary)
- Add missing examples for auth logout/refresh/token, project
  create/delete, cli setup
- Align curl install flags (-fsS) between README and docs site

Close automation gap from #569: make generate-skill.ts auto-update
the REFERENCE_FILES array in agent-skills.ts so new command groups
are automatically included in runtime skill installation. Extend
check-skill.ts to detect drift in agent-skills.ts and update CI
auto-commit to include the file.

Author: BYK

.github/workflows/ci.yml

@@ -125,7 +125,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/ docs/public/.well-known/skills/index.json docs/src/content/docs/commands/
+          git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json docs/src/content/docs/commands/ src/lib/agent-skills.ts
           git commit -m "chore: regenerate skill files and command docs"
           git push
       - name: Fail for fork PRs with stale generated files

DEVELOPMENT.md

@@ -59,7 +59,7 @@ When creating your Sentry OAuth application:
 
 - **Redirect URI**: Not required for device flow
 - **Scopes**: The CLI requests these scopes:
-  - `project:read`, `project:write`
+  - `project:read`, `project:write`, `project:admin`
   - `org:read`
   - `event:read`, `event:write`
   - `member:read`

README.md

@@ -19,7 +19,7 @@
 ### Install Script (Recommended)
 
 ```bash
-curl -fsSL https://cli.sentry.dev/install | bash
+curl https://cli.sentry.dev/install -fsS | bash
 ```
 
 ### Homebrew
@@ -72,10 +72,18 @@ sentry issue plan PROJ-ABC
 |---------|-------------|
 | `sentry auth` | Login, logout, check authentication status |
 | `sentry org` | List and view organizations |
-| `sentry project` | List and view projects |
+| `sentry project` | List, view, create, and delete projects |
 | `sentry issue` | List, view, explain, and plan issues |
 | `sentry event` | View event details |
+| `sentry trace` | List and view distributed traces |
+| `sentry span` | List and view spans |
+| `sentry log` | List and view logs (with streaming) |
+| `sentry dashboard` | List, view, and create dashboards with widgets |
+| `sentry sourcemap` | Inject debug IDs and upload sourcemaps |
+| `sentry init` | Initialize Sentry in your project |
+| `sentry schema` | Browse the Sentry API schema |
 | `sentry api` | Make direct API requests |
+| `sentry cli` | Upgrade, setup, fix, and send feedback |
 
 For detailed documentation, visit [cli.sentry.dev](https://cli.sentry.dev).
 

docs/src/content/docs/commands/auth.md

@@ -96,6 +96,24 @@ SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 
 See [Self-Hosted Sentry](../self-hosted/) for details.
 
+### Logout
+
+```bash
+sentry auth logout
+```
+
+### Refresh token
+
+```bash
+sentry auth refresh
+```
+
+### Print stored token
+
+```bash
+sentry auth token
+```
+
 ### Check auth status
 
 ```bash
@@ -118,14 +136,14 @@ sentry auth whoami
 
 ## Credential Storage
 
-Auth tokens are stored in a SQLite database at `~/.sentry/config.db` with restricted file permissions.
+Auth tokens are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions.
 
 ## Environment Variable Precedence
 
 The CLI checks for auth tokens in the following order, using the first one found:
 
-1. `SENTRY_AUTH_TOKEN` environment variable (legacy)
-2. `SENTRY_TOKEN` environment variable
-3. The stored token in the SQLite database
+1. `SENTRY_AUTH_TOKEN` environment variable
+2. `SENTRY_TOKEN` environment variable (legacy alias)
+3. The stored OAuth token in the SQLite database
 
 When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.

docs/src/content/docs/commands/cli.md

@@ -144,3 +144,16 @@ Feedback is sent via Sentry's telemetry system. If telemetry is disabled (`SENTR
 ```bash
 sentry cli fix
 ```
+
+### Configure shell integration
+
+```bash
+# Run full setup (PATH, completions, agent skills)
+sentry cli setup
+
+# Skip agent skill installation
+sentry cli setup --no-agent-skills
+
+# Skip PATH and completion modifications
+sentry cli setup --no-modify-path --no-completions
+```

docs/src/content/docs/commands/project.md

@@ -117,3 +117,26 @@ DSN: https://abc123@sentry.io/123456
 # Open project in browser
 sentry project view my-org/frontend -w
 ```
+
+### Create a project
+
+```bash
+# Create a new project
+sentry project create my-new-app javascript-nextjs
+
+# Create under a specific org and team
+sentry project create my-org/my-new-app python --team backend-team
+
+# Preview without creating
+sentry project create my-new-app node --dry-run
+```
+
+### Delete a project
+
+```bash
+# Delete a project (will prompt for confirmation)
+sentry project delete my-org/old-project
+
+# Delete without confirmation
+sentry project delete my-org/old-project --yes
+```

docs/src/content/docs/configuration.md

@@ -7,6 +7,20 @@ The Sentry CLI can be configured through environment variables and a local datab
 
 ## Environment Variables
 
+### `SENTRY_AUTH_TOKEN`
+
+Authentication token for the Sentry API. This is the primary way to authenticate in CI/CD pipelines and scripts where interactive login is not possible.
+
+```bash
+export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
+```
+
+You can create auth tokens in your [Sentry account settings](https://sentry.io/settings/account/api/auth-tokens/). When set, this takes precedence over any stored OAuth token from `sentry auth login`.
+
+### `SENTRY_TOKEN`
+
+Legacy alias for `SENTRY_AUTH_TOKEN`. If both are set, `SENTRY_AUTH_TOKEN` takes precedence.
+
 ### `SENTRY_HOST`
 
 Base URL of your Sentry instance. **Only needed for [self-hosted Sentry](./self-hosted/).** SaaS users (sentry.io) should not set this.
@@ -125,6 +139,22 @@ Disable the automatic update check that runs periodically in the background.
 export SENTRY_CLI_NO_UPDATE_CHECK=1
 ```
 
+### `SENTRY_INSTALL_DIR`
+
+Override the directory where the CLI binary is installed. Used by the install script and `sentry cli upgrade` to control the binary location.
+
+```bash
+export SENTRY_INSTALL_DIR=/usr/local/bin
+```
+
+### `SENTRY_NO_CACHE`
+
+Disable API response caching. When set, the CLI will not cache API responses and will always make fresh requests.
+
+```bash
+export SENTRY_NO_CACHE=1
+```
+
 ## Global Options
 
 These flags are accepted by every command. They are not shown in individual command `--help` output, but are always available.

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

@@ -44,7 +44,7 @@ export SENTRY_CLIENT_ID=your-client-id
 If your instance is on an older version or you prefer not to create an OAuth application, you can use an API token instead:
 
 1. Go to **Settings → Developer Settings → Personal Tokens** in your Sentry instance (or visit `https://sentry.example.com/settings/account/api/auth-tokens/new-token/`)
-2. Create a new token with the following scopes: `project:read`, `project:write`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read`
+2. Create a new token with the following scopes: `project:read`, `project:write`, `project:admin`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read`
 3. Pass it to the CLI:
 
 ```bash

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

@@ -36,13 +36,25 @@ SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 
 Log out of Sentry
 
+**Examples:**
+
+```bash
+sentry auth logout
+```
+
 ### `sentry auth refresh`
 
 Refresh your authentication token
 
 **Flags:**
 - `--force - Force refresh even if token is still valid`
 
+**Examples:**
+
+```bash
+sentry auth refresh
+```
+
 ### `sentry auth status`
 
 View authentication status
@@ -67,6 +79,12 @@ sentry auth whoami
 
 Print the stored authentication token
 
+**Examples:**
+
+```bash
+sentry auth token
+```
+
 ### `sentry auth whoami`
 
 Show the currently authenticated user

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

@@ -19,6 +19,19 @@ Create a new project
 - `-t, --team <value> - Team to create the project under`
 - `-n, --dry-run - Validate inputs and show what would be created without creating it`
 
+**Examples:**
+
+```bash
+# Create a new project
+sentry project create my-new-app javascript-nextjs
+
+# Create under a specific org and team
+sentry project create my-org/my-new-app python --team backend-team
+
+# Preview without creating
+sentry project create my-new-app node --dry-run
+```
+
 ### `sentry project delete <org/project>`
 
 Delete a project
@@ -28,6 +41,16 @@ Delete a project
 - `-f, --force - Force deletion without confirmation`
 - `-n, --dry-run - Validate and show what would be deleted without deleting`
 
+**Examples:**
+
+```bash
+# Delete a project (will prompt for confirmation)
+sentry project delete my-org/old-project
+
+# Delete without confirmation
+sentry project delete my-org/old-project --yes
+```
+
 ### `sentry project list <org/project>`
 
 List projects