docs: documentation audit — fix version claims, license, agent coverage, and auth examples

[cursor]

Documentation Audit Report (2026-08-03)

Weekly automated audit that reads the full codebase and cross-references it against documentation to find gaps.

---

Changes Made

File	Fix
getting-started.mdx	Corrected Node.js requirement from "22.15+" to "20+" (matches engines.node >= 20.0 in package.json; 22.15+ gives native node:sqlite, 20–22.14 uses WASM fallback)
getting-started.mdx	Updated version pin example from 0.19.0 to 0.40.0
install script	Updated version examples from 0.19.0 to 0.40.0
env-registry.ts	Updated SENTRY_VERSION example from 0.19.0 to 0.40.0
.craft.yml	Fixed Homebrew formula license FSL-1.1-MIT → FSL-1.1-Apache-2.0 (matches package.json and LICENSE.md)
agentic-usage.md	Expanded supported agent list from 2 (Claude Code, Cursor) to all 11 agents recognized by detect-agent.ts: Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Goose, Amp, Augment, OpenCode
auth.md fragment	Added examples for --read-only, --scope, and --url flags on sentry auth login

---

Full Gap Report

A. Undocumented or Missing Commands/Subcommands

No gaps. All 107 commands + 17 hidden aliases have auto-generated doc pages via generate-command-docs.ts. Hand-written fragments exist for every command group under apps/cli-docs/src/fragments/commands/.

B. Undocumented Flags

Fixed in this PR:

• sentry auth login --read-only — new flag for requesting read-only OAuth scopes, useful for AI agents and CI. Not previously documented with examples.
• sentry auth login --scope — new flag for requesting specific OAuth scopes. Not previously documented with examples.
• sentry auth login --url — existed but examples used SENTRY_URL env var syntax instead of the recommended --url flag.

Remaining (low priority — flags are visible in auto-generated Options tables):

• sentry auth login --force — re-authenticate without prompting. No example in fragment.
• sentry auth login --timeout — OAuth flow timeout. No example in fragment (default 900s is rarely changed).
• sentry help --json — new feature from feat(help): support JSON output for --help flags (#1337). Mentioned in fullDescription but no dedicated doc section yet.

C. Missing Usage Examples

All documented subcommands have bash examples. Minor gaps:

• sentry cli fix has an example but no flags documented in the fragment.
• sentry release propose-version only shown embedded in $(...) subshell, not standalone.

D. Stale Descriptions

No meaningful drift detected. The brief strings in code match the auto-generated doc descriptions. The doc generation pipeline keeps these in sync automatically.

E. Missing Route Mappings in Skill Generator

N/A. The ROUTE_TO_REFERENCE map was removed in favor of automatic 1:1 mapping via groupRoutesByReference() in script/generate-skill.ts. Every visible route automatically gets its own reference file.

F. Installation / Distribution Gaps

Fixed in this PR:

• getting-started.mdx claimed npm packages require "Node.js 22.15+" — actual engines.node is >=20.0. Fixed to say "Node.js 20+" with a note about 22.15+ for native sqlite.
• Version pin examples used 0.19.0 (current release is 0.40.0). Updated in getting-started.mdx, install script, and env-registry.ts.

Remaining (low priority):

• Install script flags --no-modify-path, --no-completions are documented in install --help but not in getting-started.mdx. These are advanced/niche.
• SENTRY_INSTALL_DIR env var is documented in install --help and env-registry.ts (generated into configuration.md) but not in getting-started.mdx.
• Two install URLs coexist: cli.sentry.dev/install and sentry.io/get-cli/ (the latter redirects — cosmetic only).

G. Undocumented Environment Variables

No gaps for user-facing variables. The env-registry.ts contains all 28 user-facing env vars and they are generated into configuration.md. Variables not in the registry are intentionally excluded:

• SENTRY_PIPELINE — internal CI variable used by build/upload.ts
• SENTRY_SPOTLIGHT — injected by local run, not user-set
• SENTRY_MONITOR_SLUG — injected into child processes by monitor run
• SENTRY_CLI_NO_EXIT_TRAP — bash hook internal
• SENTRY_STRICT_SILENT_CATCH — dev-only CI enforcement flag

H. Auth / Self-Hosted Gaps

Fixed in this PR:

• Auth fragment now shows --url flag syntax (recommended) alongside env var syntax for self-hosted.
• Added --read-only and --scope examples to auth fragment.

Remaining:

• OAuth --scope validation details (which scopes are valid) not documented in user docs — available via --help.
• Host-scoped tokens behavior (tokens are bound to the instance they were created on) is an internal safety mechanism, not documented for end users.

I. Plugin/Skills Gaps

Fixed in this PR:

• agentic-usage.md now lists all 11 detected agents instead of just Claude Code + Cursor.

Remaining:

• agent-skills.ts only installs to .claude and .agents directories — Windsurf, Copilot, Gemini, etc. are detected for telemetry but don't have skill installation paths yet. This is a feature gap, not a doc gap.
• plugins/README.md mentions Claude Code marketplace commands (claude plugin marketplace add) and Cursor — could mention the broader ~/.agents ecosystem.
• plugin.json version (0.41.0) is ahead of CLI version (0.40.0-dev.0) — likely intentional from the post-release bump.

J. README / DEVELOPMENT.md Drift

Fixed in this PR:

• .craft.yml Homebrew formula had FSL-1.1-MIT; all other files have FSL-1.1-Apache-2.0.

No drift detected in:

• Root README.md accurately describes the monorepo structure and delegates to packages/cli/README.md.
• packages/cli/README.md correctly states Node.js 20+ for npm, 22.15+ for dev, pnpm as package manager.
• DEVELOPMENT.md (at packages/cli/DEVELOPMENT.md) has generated sections for prerequisites, env vars, and OAuth scopes — these stay in sync via generate-docs-sections.ts.
• contributing.md has generated sections for prerequisites and project structure.

---

Top 5 Most Impactful Fixes (Prioritized)

1. Node.js version claim — getting-started.mdx said 22.15+ but engines.node >= 20.0. Users on Node 20/21 would skip the npm install path unnecessarily. Fixed.
2. License mismatch — .craft.yml Homebrew formula had wrong license identifier. Every Homebrew install showed FSL-1.1-MIT instead of FSL-1.1-Apache-2.0. Fixed.
3. Stale version pins — Example version 0.19.0 is 21 releases old (0.40.0 is current). Users copying examples would install very outdated versions. Fixed.
4. Agent coverage — agentic-usage.md only mentioned 2 of 11 supported agents. Users of Windsurf, Copilot, Gemini, Codex, Goose, Amp, etc. wouldn't know skill support exists. Fixed.
5. Auth flag examples — --read-only and --scope flags had no usage examples, making them hard to discover for users wanting scoped OAuth tokens. Fixed.

  

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1350/
Built to branch gh-pages at 2026-08-03 12:14 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8de813e. Configure here.}