docs: weekly documentation audit — add sentry docs/status coverage, install flags, plugin syntax

apps/cli-docs/src/content/docs/agent-guidance.md

@@ -9,6 +9,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 
 - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed.
 - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation.
+- **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally.
 - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
 - **Use `sentry issue view <id>` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
@@ -135,6 +136,26 @@ sentry local -f ai
 # Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false })
 ```
 
+### Query Sentry Documentation
+
+```bash
+# Ask a documentation question
+sentry docs "How do I configure tracing in Next.js?"
+
+# Search the documentation index
+sentry docs list "source maps"
+```
+
+### Check Sentry Service Status
+
+```bash
+# Show current status of Sentry services
+sentry status
+
+# Machine-readable status
+sentry status --json
+```
+
 ### Explore the API Schema
 
 ```bash
@@ -273,6 +294,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.
+- **Fetching Sentry docs externally**: Use `sentry docs "your question"` to query Sentry's documentation from the CLI — this returns concise answers with source links, without needing to fetch or parse documentation pages.
 - **Release version mismatch**: The `org/version` positional is `<org-slug>/<version>`, where `org/` is the org, not part of the version. `sentry release create sentry/1.0.0` creates version `1.0.0` in org `sentry`. If your `Sentry.init()` uses `release: "1.0.0"`, this is correct. Don't double-prefix like `sentry/myapp/1.0.0`.
 - **Running `set-commits --auto` without a git checkout**: `--auto` needs a local git repo to discover the origin remote URL and HEAD commit. In CI, ensure `actions/checkout` with `fetch-depth: 0` runs before `set-commits --auto`.
 - **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` and `sentry issue view --json` already include `shortId`, `title`, `count`, `userCount`, `priority`, `level`, `status`, `permalink`, and other fields at the top level. When using `--fields` to select specific fields like `count` or `userCount`, the CLI automatically ensures these fields are present in the API response. Use `--fields` to select specific fields and `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose.

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

@@ -53,6 +53,7 @@ With this skill, agents can:
 - **AI analysis** - Get root cause analysis and fix plans via Seer AI
 - **Browse projects** - List projects and organizations you have access to
 - **Explore the API** - Browse API endpoints with `sentry schema` and make arbitrary requests with `sentry api`
+- **Query documentation** - Ask questions about Sentry setup and configuration with `sentry docs`
 - **Make API calls** - Execute arbitrary Sentry API requests
 - **Authenticate** - Help you set up CLI authentication
 
@@ -64,8 +65,10 @@ When you ask your agent about Sentry errors or want to investigate an issue, the
 - "What's the stack trace for ISSUE-123?" → `sentry issue view ISSUE-123`
 - "List all projects in my organization" → `sentry project list my-org`
 - "What API endpoints exist for releases?" → `sentry schema releases`
+- "How do I set up source maps for Next.js?" → `sentry docs "source maps Next.js"`
+- "What is Sentry's status right now?" → `sentry status`
 
-The CLI has dedicated commands for most Sentry tasks, so agents should prefer `sentry` commands over constructing raw API calls. The `sentry schema` command provides built-in API exploration, and `sentry api` handles authenticated requests for anything not covered by a dedicated command.
+The CLI has dedicated commands for most Sentry tasks, so agents should prefer `sentry` commands over constructing raw API calls. The `sentry docs` command queries Sentry's documentation directly from the terminal, the `sentry schema` command provides built-in API exploration, and `sentry api` handles authenticated requests for anything not covered by a dedicated command.
 
 The skill uses your existing CLI authentication, so you'll need to run `sentry auth login` first if you haven't already.
 

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

@@ -34,6 +34,27 @@ 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.
 
+### Installer Flags
+
+The install script accepts additional flags to customize behavior:
+
+```bash
+# Skip shell config modifications (~/.zshrc, ~/.bashrc, etc.)
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-modify-path
+
+# Skip shell completion installation
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-completions
+
+# Skip AI agent skill installation
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-agent-skills
+```
+
+You can also set `SENTRY_INSTALL_DIR` to override the binary installation directory:
+
+```bash
+SENTRY_INSTALL_DIR=~/.local/bin curl https://cli.sentry.dev/install -fsS | bash
+```
+
 ### Supported Platforms
 
 {/* GENERATED:START platform-support */}

apps/cli-docs/src/fragments/commands/auth.md

@@ -69,6 +69,12 @@ sentry auth logout
 
 ```bash
 sentry auth refresh
+
+# Refresh with read-only scopes
+sentry auth refresh --read-only
+
+# Refresh with specific scopes
+sentry auth refresh --scope project:read --scope org:read
 ```
 
 ### Print stored token

packages/cli/plugins/README.md

@@ -4,35 +4,28 @@ Agent skills for using the Sentry CLI, following the [Agent Skills](https://gith
 
 ## Installation
 
-### Claude Code (from GitHub)
+### Automatic (recommended)
 
-```bash
-# Add the marketplace
-claude plugin marketplace add getsentry/cli
+When you install the CLI via the install script, Homebrew, or a package manager,
+`sentry cli setup` automatically installs skills into detected agent directories
+(`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`.
 
-# Install the plugin
-claude plugin install sentry/cli
-```
+### dotagents
 
-### Claude Code (from local clone)
+[dotagents](https://github.com/getsentry/dotagents) installs the skill from
+the well-known source:
 
 ```bash
-# Add the marketplace from local clone
-claude plugin marketplace add /path/to/sentry/cli
-
-# Install the plugin
-claude plugin install sentry/cli
+npx @sentry/dotagents add https://cli.sentry.dev sentry-cli
 ```
 
-After installation, restart Claude Code. The skills will be automatically invoked when relevant to your task.
-
 ### Cursor
 
 Skills are automatically available in `.cursor/skills/` for Cursor users.
 
 ### Other Agents
 
-Copy the `plugins/sentry-cli/skills/` directory to your agent's skills location, or reference the SKILL.md files directly according to your agent's documentation.
+Copy the `plugins/sentry-cli/skills/` directory to your agent's skills location, or reference the SKILL.md files directly according to your agent's documentation. Any agent that reads skills from `~/.agents` will pick up automatically installed skills.
 
 ## Available Skills
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -21,6 +21,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 
 - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed.
 - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation.
+- **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally.
 - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
 - **Use `sentry issue view <id>` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
@@ -147,6 +148,26 @@ sentry local -f ai
 # Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false })
 ```
 
+#### Query Sentry Documentation
+
+```bash
+# Ask a documentation question
+sentry docs "How do I configure tracing in Next.js?"
+
+# Search the documentation index
+sentry docs list "source maps"
+```
+
+#### Check Sentry Service Status
+
+```bash
+# Show current status of Sentry services
+sentry status
+
+# Machine-readable status
+sentry status --json
+```
+
 #### Explore the API Schema
 
 ```bash
@@ -285,6 +306,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.
+- **Fetching Sentry docs externally**: Use `sentry docs "your question"` to query Sentry's documentation from the CLI — this returns concise answers with source links, without needing to fetch or parse documentation pages.
 - **Release version mismatch**: The `org/version` positional is `<org-slug>/<version>`, where `org/` is the org, not part of the version. `sentry release create sentry/1.0.0` creates version `1.0.0` in org `sentry`. If your `Sentry.init()` uses `release: "1.0.0"`, this is correct. Don't double-prefix like `sentry/myapp/1.0.0`.
 - **Running `set-commits --auto` without a git checkout**: `--auto` needs a local git repo to discover the origin remote URL and HEAD commit. In CI, ensure `actions/checkout` with `fetch-depth: 0` runs before `set-commits --auto`.
 - **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` and `sentry issue view --json` already include `shortId`, `title`, `count`, `userCount`, `priority`, `level`, `status`, `permalink`, and other fields at the top level. When using `--fields` to select specific fields like `count` or `userCount`, the CLI automatically ensures these fields are present in the API response. Use `--fields` to select specific fields and `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose.

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

@@ -64,6 +64,12 @@ Refresh your OAuth access token
 
 ```bash
 sentry auth refresh
+
+# Refresh with read-only scopes
+sentry auth refresh --read-only
+
+# Refresh with specific scopes
+sentry auth refresh --scope project:read --scope org:read
 ```
 
 ### `sentry auth status`