docs: documentation audit — fix gaps between implementation and docs

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

@@ -7,7 +7,9 @@ AI coding agents like Claude Code — and any agent that reads skills from `~/.a
 
 ## Automatic Installation
 
-When you install the CLI (via `curl`, Homebrew, or a package manager), `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary.
+When you install the CLI via `curl` or Homebrew, `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary.
+
+If you installed via a package manager (`npm`, `pnpm`, `bun`), run `sentry cli setup` manually after installation to install agent skills.
 
 To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
 

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

@@ -112,10 +112,17 @@ sentry auth logout
 
 ## Self-Hosted Sentry
 
-Using a self-hosted Sentry instance? Set `SENTRY_URL` to point at it:
+Using a self-hosted Sentry instance? Use the `--url` flag on login to register your instance:
 
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth login
+sentry auth login --url https://sentry.example.com
+```
+
+You can also set `SENTRY_HOST` (or `SENTRY_URL`) as an environment variable:
+
+```bash
+export SENTRY_HOST=https://sentry.example.com
+sentry auth login
 ```
 
 See the [Self-Hosted](../self-hosted/) guide for full setup details.

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

@@ -119,12 +119,14 @@ const help = await sdk.run("help", "issue");
 ## Authentication
 
 The `token` option provides an auth token for the current invocation. When
-omitted, it falls back to environment variables and stored credentials:
+omitted, it falls back to stored credentials and environment variables:
 
 1. `token` option (highest priority)
-2. `SENTRY_AUTH_TOKEN` environment variable
-3. `SENTRY_TOKEN` environment variable
-4. Stored OAuth token from `sentry auth login`
+2. Stored OAuth token from `sentry auth login` (if not expired)
+3. `SENTRY_AUTH_TOKEN` environment variable
+4. `SENTRY_TOKEN` environment variable
+
+Set `SENTRY_FORCE_ENV_TOKEN=1` to make environment variable tokens take priority over stored OAuth.
 
 ```typescript
 // Explicit token

docs/src/fragments/commands/auth.md

@@ -20,16 +20,39 @@ sentry auth login
 sentry auth login --token YOUR_SENTRY_API_TOKEN
 ```
 
+### Read-only login
+
+```bash
+# Request only read scopes (project:read, org:read, event:read, etc.)
+sentry auth login --read-only
+```
+
+### Custom scopes
+
+```bash
+# Request specific OAuth scopes (comma-separated or repeated)
+sentry auth login --scope project:read --scope org:read
+sentry auth login --scope project:read,org:read,event:read
+```
+
 ### Self-hosted Sentry
 
+Use `--url` to register your instance as a trusted host (recommended):
+
+```bash
+sentry auth login --url https://sentry.example.com
+```
+
+Or set the host via environment variable:
+
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth login
+SENTRY_HOST=https://sentry.example.com sentry auth login
 ```
 
 For token-based auth with self-hosted:
 
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
+sentry auth login --url https://sentry.example.com --token YOUR_TOKEN
 ```
 
 See [Self-Hosted Sentry](../self-hosted/) for details.

docs/src/fragments/commands/proguard.md

@@ -2,6 +2,27 @@
 
 ## Examples
 
+### Upload mapping files
+
+```bash
+# Upload a ProGuard/R8 mapping file
+sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt
+
+# Upload multiple mapping files at once
+sentry proguard upload mapping1.txt mapping2.txt
+
+# Preview without uploading (dry run)
+sentry proguard upload mapping.txt --no-upload
+
+# Force a specific UUID instead of computing from content
+sentry proguard upload mapping.txt --uuid 12345678-1234-1234-1234-123456789abc
+
+# Require at least one mapping file (exit non-zero if none found)
+sentry proguard upload ./mappings/ --require-one
+```
+
+### Compute UUID
+
 ```bash
 # Compute the UUID for a ProGuard/R8 mapping file
 sentry proguard uuid ./app/build/outputs/mapping/release/mapping.txt
@@ -17,3 +38,6 @@ sentry proguard uuid mapping.txt --json
   Sentry uses to associate a mapping with obfuscated Android stack traces.
 - This matches the UUID computed by the legacy `sentry-cli proguard uuid`
   command byte-for-byte.
+- `sentry proguard upload` uses the DIF chunk-upload protocol. Each mapping
+  file is bundled as `proguard/<uuid>.txt`. Org/project are resolved via
+  standard auto-detection (DSN, env vars, config defaults).

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

@@ -30,9 +30,18 @@ sentry auth login
 
 sentry auth login --token YOUR_SENTRY_API_TOKEN
 
-SENTRY_URL=https://sentry.example.com sentry auth login
+# Request only read scopes (project:read, org:read, event:read, etc.)
+sentry auth login --read-only
 
-SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
+# Request specific OAuth scopes (comma-separated or repeated)
+sentry auth login --scope project:read --scope org:read
+sentry auth login --scope project:read,org:read,event:read
+
+sentry auth login --url https://sentry.example.com
+
+SENTRY_HOST=https://sentry.example.com sentry auth login
+
+sentry auth login --url https://sentry.example.com --token YOUR_TOKEN
 ```
 
 ### `sentry auth logout`

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

@@ -20,6 +20,25 @@ Upload ProGuard/R8 mapping files to Sentry
 - `--no-upload - Compute and print UUIDs without uploading (dry-run)`
 - `--require-one - Require at least one mapping file (error if none provided)`
 
+**Examples:**
+
+```bash
+# Upload a ProGuard/R8 mapping file
+sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt
+
+# Upload multiple mapping files at once
+sentry proguard upload mapping1.txt mapping2.txt
+
+# Preview without uploading (dry run)
+sentry proguard upload mapping.txt --no-upload
+
+# Force a specific UUID instead of computing from content
+sentry proguard upload mapping.txt --uuid 12345678-1234-1234-1234-123456789abc
+
+# Require at least one mapping file (exit non-zero if none found)
+sentry proguard upload ./mappings/ --require-one
+```
+
 ### `sentry proguard uuid <path>`
 
 Compute the UUID for a ProGuard mapping file