docs: weekly documentation audit — fix init features, explore replays, sourcemap auth, stale CONTRIBUTING ref

[cursor]

Documentation Audit Report — 2026-09-07

Weekly audit of the Sentry CLI documentation against the implementation. Covers all changes since the last audit (PR #1514, merged 2026-08-31).

---

Changes in This PR

1. init.md: Remove gated features and add mcp-observability

PR #1535 (fix(init): gate unsupported --features) removed metrics, sourcemaps, and attachments from SUPPORTED_FEATURE_NAMES because their setup isn't fully automated yet. The init fragment still listed metrics and sourcemaps as available features. Also, mcp-observability was added as a supported feature but was missing from the docs.

• Source: src/commands/init.ts lines 68–77 (SUPPORTED_FEATURE_NAMES)
• Doc file: apps/cli-docs/src/fragments/commands/init.md

2. explore.md: Add replays dataset documentation

The sentry explore command supports five datasets (errors, spans, metrics, logs, replays), but the explore fragment had zero documentation for the replays dataset — no examples, no mention in any dataset listing. Added a Replays example section and a complete Datasets reference table.

• Source: src/commands/explore.ts lines 100–106 (VALID_DATASETS)
• Doc file: apps/cli-docs/src/fragments/commands/explore.md

3. sourcemap.md: Note that sourcemap inject runs without authentication

PR #1526 (fix(sourcemap): let inject run without authentication) set auth: false on the inject command, making it explicit that it's a purely local file operation. The docs didn't mention this, which is important for CI pipelines where inject should run before auth.

• Source: src/commands/sourcemap/inject.ts line 74 (auth: false)
• Doc file: apps/cli-docs/src/fragments/commands/sourcemap.md

4. CONTRIBUTING.md: Fix stale sentry config set reference

The Context Resolution section referenced sentry config set, which was renamed to sentry cli defaults long ago.

• Source: src/commands/cli/defaults.ts (the actual command)
• Doc file: packages/cli/CONTRIBUTING.md line 47

---

Full Gap Report

A. Undocumented or Missing Commands/Subcommands

No gaps. All commands have auto-generated doc pages via generate-command-docs.ts, and every route in src/app.ts produces a page under commands/. The groupRoutesByReference() function creates an automatic 1:1 mapping.

B. Undocumented Flags

No new gaps. All non-hidden flags are auto-generated into the Options tables by the command doc generator. The only hidden flags (src/commands/cli/setup.ts, src/commands/bash-hook.ts) are intentionally hidden.

C. Missing Usage Examples

Gap	Status
sentry explore --dataset replays — no examples in fragment	Fixed in this PR

D. Stale Descriptions

Gap	Status
init.md listed metrics, sourcemaps as features — removed in PR #1535	Fixed in this PR
init.md missing mcp-observability feature — added in same PR	Fixed in this PR
CONTRIBUTING.md references sentry config set instead of sentry cli defaults	Fixed in this PR

E. Missing Route Mappings in Skill Generator

N/A — ROUTE_TO_REFERENCE was removed in a prior refactor. groupRoutesByReference() now automatically maps each visible route to its own reference file.

F. Installation / Distribution Gaps

No new gaps since last audit. The install script flags (--no-modify-path, --no-completions, --no-agent-skills) and env vars (SENTRY_INSTALL_DIR, SENTRY_VERSION, SENTRY_INIT) are documented in getting-started.mdx. The platform support table is auto-generated.

G. Undocumented Environment Variables

No new gaps. The env registry (src/lib/env-registry.ts) has 27 entries, all documented via auto-generation. Previously identified niche variables (SENTRY_ENVIRONMENT, SENTRY_DIST, SENTRY_CLI_NO_EXIT_TRAP, SENTRY_SCAN_DISABLE_WORKERS, SENTRY_RN_*) remain intentionally excluded as they are internal, test-only, or legacy bash-hook scoped.

H. Auth / Self-Hosted Gaps

No new gaps. The sourcemap inject auth-free change (PR #1526) is now documented.

I. Plugin/Skills Gaps

No new gaps since PR #1514. Skills install targets (~/.claude, ~/.agents), dotagents integration, and the automatic install on sentry cli setup / sentry cli upgrade are accurately documented. The plugins/README.md correctly references the current .claude-plugin structure.

J. README / DEVELOPMENT.md Drift

Claim	Status
README: Node.js 20+, dev 22.15+	Matches package.json (engines.node: ">=20.0", devEngines.runtime.version: ">=22.15")
README: pnpm 10.11+	Matches pnpm-workspace.yaml constraints
README: License FSL-1.1-Apache-2.0	Matches LICENSE.md
README: Build/test commands	Match package.json scripts
CONTRIBUTING.md: sentry config set	Fixed in this PR

---

Top 5 Most Impactful Fixes (Prioritized)

1. init.md feature list stale — Users/agents running sentry init --features metrics or sentry init --features sourcemaps would get a confusing Unknown init feature error. High-impact because init is the onboarding entry point.

2. explore replays undocumented — The entire replays dataset was silently available but had zero documentation. Users and agents had no way to discover this capability.

3. sourcemap inject auth note — CI pipelines commonly run inject before upload. Knowing inject doesn't need auth lets pipelines defer authentication, simplifying pipeline ordering.

4. CONTRIBUTING.md stale command reference — Contributors following the guide would try a non-existent sentry config set command.

5. mcp-observability feature undocumented — New init feature for MCP/agent observability was missing from docs, preventing discovery of this capability.

  

[vercel]

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

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