docs: weekly documentation audit — XDG config paths, new agents, Local UI, env vars by cursor[bot] · Pull Request #1579 · getsentry/cli

cursor · 2026-09-14T12:13:05Z

Weekly Documentation Audit — 2026-09-14

This PR fixes documentation gaps found by cross-referencing the CLI implementation against its docs, focusing on changes since the last audit (2026-09-07).

Gap Report

A. Undocumented or missing commands/subcommands

No new undocumented commands found. All 112 commands have auto-generated doc pages. The local commands (serve, run) are fully documented.

B. Undocumented flags

--open flag on sentry local serve and sentry local run (added in #1560):

Both commands added an --open flag to launch the browser-based Sentry Local UI at local.sentry.dev
The flag was listed in auto-generated Options tables but had no examples or explanation in the hand-written fragment
Fixed: Added a "Browser UI" section to local.md with usage examples and constraints

C. Missing usage examples

The Local UI (--open) had no examples → added.

D. Stale descriptions

No stale brief strings found.

E. Missing route mappings in skill generator

All routes are covered — groupRoutesByReference() provides automatic 1:1 mapping.

F. Installation / distribution gaps

SENTRY_CONFIG_DIR stale default in env-registry.ts:

Source: packages/cli/src/lib/env-registry.ts line 151–154
The description said "Defaults to ~/.sentry/" and defaultValue was "~/.sentry/"
Since PR feat(config): follow XDG Base Directory spec for config location #1503 (XDG Base Directory migration), the actual default is $XDG_CONFIG_HOME/sentry/ (i.e. ~/.config/sentry/)
Fixed: Updated description, defaultValue, and devGuide to reflect XDG paths
Cascaded: Regenerated configuration.md and DEVELOPMENT.md (auto-generated from env-registry)

Curl install detection path stale in cli.md:

Source: apps/cli-docs/src/fragments/commands/cli.md line 56
The upgrade detection table said curl binary is "in ~/.sentry/bin" — this is the legacy path
The XDG-aligned default is ~/.local/bin
Fixed: Table now shows both paths: "XDG: ~/.local/bin; legacy: ~/.sentry/bin"

G. Undocumented environment variables

All SENTRY_* env vars in env-registry.ts are documented in configuration.md (auto-generated). The SENTRY_RELEASE var injected by local run was missing from the fragment's env var table → fixed.

Remaining intentionally excluded env vars (internal, test-only, or SDK-inherited): SENTRY_ENVIRONMENT, SENTRY_CLI_NO_EXIT_TRAP, SENTRY_SCAN_DISABLE_WORKERS, SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE, SENTRY_RN_*, SENTRY_TRACES_SAMPLE_RATE, SENTRY_MONITOR_SLUG, SENTRY_DIST.

H. Auth / self-hosted gaps

Auth credential storage path stale in auth.md:

Source: apps/cli-docs/src/fragments/commands/auth.md line 109
Said credentials stored in ~/.sentry/ — stale since XDG migration (feat(config): follow XDG Base Directory spec for config location #1503)
Fixed: Updated to $XDG_CONFIG_HOME/sentry/ with legacy fallback note

No other auth/self-hosted gaps found. OAuth scopes, trust anchor system, and self-hosted guide are current.

I. Plugin/skills gaps

Newly-detected agents missing from agentic-usage.md:

Source: packages/cli/src/lib/detect-agent.ts (ENV_VAR_AGENTS, PROCESS_NAME_AGENTS)
PR feat(telemetry): refresh coding agent detection #1571 added detection for Cline, OpenClaw, Kimi, Grok, and Junie
The Cowork variant of Claude Code was also undocumented
Fixed: Added all 5 new agents plus Cowork to both the intro paragraph and requirements section

Skill installation targets (~/.claude, ~/.agents) and embedded content system are correctly documented.

J. README / DEVELOPMENT.md drift

packages/cli/README.md correctly uses XDG paths — no drift
DEVELOPMENT.md env var table was auto-updated by the env-registry regeneration
Node.js version requirement (22.15+ dev, 20+ runtime) is correctly documented
Build/test commands in README.md and DEVELOPMENT.md match package.json

Top 5 Most Impactful Fixes (Prioritized)

SENTRY_CONFIG_DIR stale default — The env-registry (source of truth for generated docs) pointed users at the wrong directory. This cascaded to configuration.md, DEVELOPMENT.md, and the sentry --help output. High impact because it directly misleads users about where their credentials are stored.
Auth credential path stale — The auth command docs told users their tokens live in ~/.sentry/ when they actually live in ~/.config/sentry/. Users looking for their stored credentials would check the wrong directory.
5 newly-detected agents undocumented — Cline, Grok, Kimi, Junie, and OpenClaw users wouldn't know the CLI recognizes their agent, potentially causing confusion about skill installation behavior.
--open / Local UI undocumented in fragment — The browser-based Sentry Local UI is a significant new feature with no examples in the hand-written docs. Users wouldn't discover it without reading --help.
SENTRY_RELEASE env var missing from local run table — Minor but affects users who need to understand what environment variables are injected into their child process.

…l UI, env vars - Fix SENTRY_CONFIG_DIR description and default in env-registry.ts to reflect the XDG Base Directory migration (#1503): defaults to ~/.config/sentry/ instead of the stale ~/.sentry/ reference - Update auth.md credential storage section to use XDG paths - Update cli.md upgrade detection table to show both XDG and legacy paths - Add 5 newly-detected agents to agentic-usage.md: Cline, Grok, Kimi, Junie, OpenClaw (added in #1571), plus Cowork variant of Claude Code - Document --open flag and Sentry Local UI in local.md fragment (#1560) - Add SENTRY_RELEASE to local run injected env vars table - Regenerate configuration.md, DEVELOPMENT.md, and skill files Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>

vercel · 2026-09-14T12:13:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cli	Ready	Preview	Sep 14, 2026 12:13pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Sep 14, 2026 12:13pm UTC

…mand coverage, AGENTS.md update (#1602) ## Weekly Documentation Audit — 2026-09-21 Automated cross-reference of implementation vs documentation, covering commits since the last audit (`ca7ef6af3`, PR #1579). --- ## Gap Report ### A. Undocumented or Missing Commands/Subcommands Command docs are auto-generated from CLI metadata, so all commands have generated doc pages. However, the **hand-written feature pages** were missing coverage for recently-added commands: | Command | Source | Missing From | |---------|--------|--------------| | `agent-conversation list/view` | `src/commands/agent-conversation/` | `agentic-usage.md`, `agent-guidance.md` | | `wasm-split` | `src/commands/wasm-split.ts` (PR #1589) | `agentic-usage.md`, `agent-guidance.md` | | `status show` | `src/commands/status/show.ts` | `agentic-usage.md` capabilities | **Fixed in this PR**: Added all three to the Capabilities list in `agentic-usage.md` and added workflow patterns with bash examples in `agent-guidance.md`. ### B. Undocumented Flags No new gaps. All non-hidden flags are auto-documented in generated Options tables via `generate-command-docs.ts`. ### C. Missing Usage Examples All command groups have fragment files in `apps/cli-docs/src/fragments/commands/` with bash examples. The new `wasm-split.md` fragment was added alongside PR #1589. **Bug found**: The `agent-conversation.md` fragment had **incorrect positional syntax** — it showed `sentry agent-conversation view my-org conv-123` (two separate args) but the command accepts a single slash-separated positional `[<org>/]<conversation-id>`, so the correct form is `sentry agent-conversation view my-org/conv-123`. **Fixed in this PR.** ### D. Stale Descriptions No drift found. The `brief` strings in code match the auto-generated doc descriptions. ### E. Missing Route Mappings in Skill Generator N/A — the manual `ROUTE_TO_REFERENCE` map was removed in a prior audit. The skill generator now uses `groupRoutesByReference()` for automatic 1:1 route-to-file mapping. ### F. Installation / Distribution Gaps No new gaps. The install script, `getting-started.mdx`, and `README.md` all document: - `curl`, Homebrew, npm/pnpm/yarn/bun install methods - `--no-modify-path`, `--no-completions`, `--no-agent-skills` installer flags - `SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT` env vars - Supported platforms (macOS x64/arm64, Linux x64/arm64 glibc/musl, Windows x64) - Nightly channel via `--version nightly` ### G. Undocumented Environment Variables All `SENTRY_*` env vars accessed via `getEnv()` are registered in `env-registry.ts` and appear in the generated `configuration.md`. Intentionally excluded internal/test-only vars remain unchanged from prior audits: - `SENTRY_ENVIRONMENT` — bash-hook template only - `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook internal - `SENTRY_SCAN_DISABLE_WORKERS` — internal perf tuning - `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only - `SENTRY_RN_*` — React Native wrapper internals ### H. Auth / Self-Hosted Gaps No new gaps. Self-hosted docs cover OAuth 26.1.0+ requirement, token auth fallback, `SENTRY_HOST`/`SENTRY_URL`/`SENTRY_CLIENT_ID`/`SENTRY_CUSTOM_HEADERS`, TLS/CA certs, and `sentry cli defaults` for persistent proxy headers. ### I. Plugin/Skills Gaps The `plugins/README.md` accurately describes the skill installation flow and supported directories (`~/.claude`, `~/.agents`). The agent detection list in `agentic-usage.md` is current (includes Cline, Grok, Kimi, Junie, OpenClaw from PR #1571). No new gaps. ### J. README / DEVELOPMENT.md Drift No drift found: - Node.js version: `>=22.15` in devEngines, `>=20.0` in engines — matches docs - pnpm: `10.11.0` — matches docs - Build toolchain: esbuild + fossilize — matches GENERATED sections - OAuth scopes: auto-generated via GENERATED markers **AGENTS.md drift found**: The Architecture section's command group list was outdated — it listed a subset with `…` ellipsis, omitting `agent-conversation`, `alert`, `build`, `code-mappings`, `dart-symbol-map`, `debug-files`, `docs`, `feedback`, `snapshots`, `status`, `wasm-split`, and other groups. **Fixed in this PR**: Replaced with the full alphabetical list. --- ## Top 5 Most Impactful Fixes (Prioritized) 1. **`agent-conversation view` fragment had wrong positional syntax** — agents following the example would get a parse error. Fixed. 2. **`agent-conversation` missing from agentic docs** — AI agents had no guidance for browsing conversation transcripts, a feature specifically built for agent workflows. Fixed. 3. **`wasm-split` missing from agentic docs** — a new command (PR #1589) useful for WebAssembly projects had no agent guidance or workflow pattern. Fixed. 4. **AGENTS.md command group list was stale** — new contributors and agents referencing the Architecture section saw an incomplete picture. Fixed. 5. **`status` missing from agentic-usage.md capabilities** — the status command was already in agent-guidance.md workflow patterns but wasn't listed in the capabilities section. Fixed. <div><a href="https://cursor.com/agents/bc-65d7d00b-206a-420d-b8eb-d39cbd8ed041?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>

BYK approved these changes Sep 14, 2026

View reviewed changes

BYK marked this pull request as ready for review September 14, 2026 12:29

BYK merged commit ca7ef6a into main Sep 14, 2026
32 checks passed

BYK deleted the cursor/sentry-cli-documentation-audit-6ea3 branch September 14, 2026 12:32

cursor Bot mentioned this pull request Sep 21, 2026

docs: weekly documentation audit — agent-conversation syntax, new command coverage, AGENTS.md update #1602

Merged

Navigation Menu

Uh oh!

docs: weekly documentation audit — XDG config paths, new agents, Local UI, env vars - #1579

docs: weekly documentation audit — XDG config paths, new agents, Local UI, env vars#1579
BYK merged 1 commit into
mainfrom
cursor/sentry-cli-documentation-audit-6ea3

cursor Bot commented Sep 14, 2026

Uh oh!

vercel Bot commented Sep 14, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

cursor Bot commented Sep 14, 2026

Weekly Documentation Audit — 2026-09-14

Gap Report

A. Undocumented or missing commands/subcommands

B. Undocumented flags

C. Missing usage examples

D. Stale descriptions

E. Missing route mappings in skill generator

F. Installation / distribution gaps

G. Undocumented environment variables

H. Auth / self-hosted gaps

I. Plugin/skills gaps

J. README / DEVELOPMENT.md drift

Top 5 Most Impactful Fixes (Prioritized)

Uh oh!

vercel Bot commented Sep 14, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants