Skip to content

docs: comprehensive documentation audit report #1117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cursor wants to merge 1 commit into
base: main
Choose a base branch
from
+240 −0
Draft

docs: comprehensive documentation audit report #1117

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 240 additions & 0 deletions docs/DOCUMENTATION_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
# Sentry CLI Documentation Audit Report

**Date:** 2026-06-22
**Scope:** Full cross-reference of implementation code vs. documentation

---

## A. Undocumented or Missing Commands/Subcommands

The command doc fragments cover all visible routes. However, several subcommands
lack explicit documentation in their respective fragments:

| Command | Source file | Fragment file | Gap |
|---------|-----------|---------------|-----|
| `sentry dashboard delete` | `src/commands/dashboard/delete.ts` | `docs/src/fragments/commands/dashboard.md` | Subcommand not mentioned in fragment (only widget delete is shown) |
| `sentry dashboard edit` | `src/commands/dashboard/edit.ts` | `docs/src/fragments/commands/dashboard.md` | No examples for editing a dashboard itself (only widget edit is covered) |
| `sentry proguard upload` | `src/commands/proguard/upload.ts` | `docs/src/fragments/commands/proguard.md` | Fragment only covers `proguard uuid`; upload subcommand is entirely missing |
| `sentry sourcemap resolve` | `src/commands/sourcemap/resolve.ts` | `docs/src/fragments/commands/sourcemap.md` | Covered in fragment (good) |
| `sentry release propose-version` | `src/commands/release/propose-version.ts` | `docs/src/fragments/commands/release.md` | Mentioned only in passing example; no dedicated section or flag docs |
| `sentry bash-hook` | `src/commands/bash-hook.ts` | None | Hidden command, intentionally undocumented — no action needed |

## B. Undocumented Flags

Non-hidden flags present in code but not mentioned in the corresponding doc fragment:

| Command | Flag | Default | Fragment file |
|---------|------|---------|---------------|
| `sentry auth login` | `--read-only` | `false` | `auth.md` — not mentioned |
| `sentry auth login` | `--scope` / `-s` | — | `auth.md` — not mentioned |
| `sentry auth login` | `--timeout` | `900` | `auth.md` — not mentioned |
| `sentry auth login` | `--force` | `false` | `auth.md` — not mentioned |
| `sentry auth login` | `--url` | — | `auth.md` — shows `SENTRY_URL` env only, not the `--url` flag |
| `sentry auth status` | `--show-token` | — | `auth.md` — mentioned briefly |
| `sentry auth status` | `--fresh` / `-f` | — | `auth.md` — not mentioned |
| `sentry auth refresh` | `--force` | — | `auth.md` — not mentioned |
| `sentry auth refresh` | `--read-only` | — | `auth.md` — not mentioned |
| `sentry auth refresh` | `--scope` / `-s` | — | `auth.md` — not mentioned |
| `sentry issue list` | `--compact` | — | `issue.md` — not mentioned |
| `sentry issue list` | `--period` / `-t` | `90d` | `issue.md` — not mentioned |
| `sentry explore` | `--environment` / `-e` | — | `explore.md` — not mentioned |
| `sentry trace view` | `--full` | — | `trace.md` — not mentioned |
| `sentry trace view` | `--spans` | `3` | `trace.md` — not mentioned |
| `sentry trace logs` | `--sort` / `-s` | `newest` | `trace.md` — not mentioned |
| `sentry event view` | `--spans` | `3` | `event.md` — not mentioned |
| `sentry event send` | `--no-environ` | — | `event.md` — not mentioned |
| `sentry event send` | `--logfile` | — | `event.md` — not mentioned |
| `sentry event send` | `--with-categories` | — | `event.md` — not mentioned |
| `sentry event send` | `--timestamp` | — | `event.md` — not mentioned |
| `sentry event send` | `--fingerprint` / `-f` | — | `event.md` — partially documented |
| `sentry monitor run` | `--check-in-margin` | — | `monitor.md` — not mentioned |
| `sentry monitor run` | `--failure-issue-threshold` | — | `monitor.md` — not mentioned |
| `sentry monitor run` | `--recovery-threshold` | — | `monitor.md` — not mentioned |
| `sentry sourcemap inject` | `--ignore` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap inject` | `--ignore-file` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap inject` | `--allow-empty` | — | `sourcemap.md` — only mentioned for upload |
| `sentry sourcemap upload` | `--ignore` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap upload` | `--ignore-file` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap upload` | `--strip-prefix` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap upload` | `--strip-common-prefix` | — | `sourcemap.md` — not mentioned |
| `sentry sourcemap upload` | `--no-rewrite` | — | `sourcemap.md` — not mentioned |
| `sentry cli setup` | `--install` | — | `cli.md` — not mentioned (internal flag) |
| `sentry cli setup` | `--method` | — | `cli.md` — not mentioned |
| `sentry cli setup` | `--channel` | — | `cli.md` — not mentioned |
| `sentry cli setup` | `--quiet` | — | `cli.md` — not mentioned |
| `sentry cli upgrade` | `--offline` | — | `cli.md` — not mentioned |
| `sentry cli upgrade` | `--method` | — | `cli.md` — not mentioned |
| `sentry cli uninstall` | `--keep-config` | — | `cli.md` — mentioned |
| `sentry release create` | `--ref` | — | `release.md` — not mentioned |
| `sentry release create` | `--url` | — | `release.md` — not mentioned |
| `sentry release finalize` | `--released` | — | `release.md` — not mentioned |
| `sentry release finalize` | `--url` | — | `release.md` — not mentioned |
| `sentry release deploy` | `--url` | — | `release.md` — not mentioned |
| `sentry release deploy` | `--started` | — | `release.md` — not mentioned |
| `sentry release deploy` | `--finished` | — | `release.md` — not mentioned |
| `sentry release deploy` | `--time` / `-t` | — | `release.md` — not mentioned |
| `sentry release set-commits` | `--initial-depth` | `20` | `release.md` — not mentioned |
| `sentry release list` | `--status` | `open` | `release.md` — not mentioned |
| `sentry release list` | `--environment` / `-e` | — | `release.md` — not mentioned |
| `sentry release list` | `--period` / `-t` | `90d` | `release.md` — not mentioned |
| `sentry replay list` | `--environment` / `-e` | — | `replay.md` — not mentioned |
| `sentry local serve` | `--host` / `-H` | `localhost` | `local.md` — not mentioned |
| `sentry local run` | `--host` | — | `local.md` — not mentioned |
| `sentry local run` | `--verify` / `-V` | — | `local.md` — not mentioned |
| `sentry local run` | `--timeout` / `-t` | `0` | `local.md` — not mentioned |

## C. Missing Usage Examples

Command fragments with no bash examples for specific subcommands:

| Command | Fragment | Missing example for |
|---------|----------|-------------------|
| `sentry dashboard delete` | `dashboard.md` | Top-level dashboard deletion (only widget delete shown) |
| `sentry proguard upload` | `proguard.md` | Entire upload subcommand |
| `sentry release finalize` | `release.md` | Standalone finalize with flags like `--released`, `--url` |
| `sentry release archive/restore` | `release.md` | Examples exist (good) |
| `sentry auth whoami` | `auth.md` | Mentioned but no example showing output |
| `sentry log view` | `log.md` | Has example (good) |

## D. Stale Descriptions

| Command | Code `brief` | Doc description | Issue |
|---------|-------------|-----------------|-------|
| `sentry local` (route) | "Sentry for local development" | Fragment says "runs a local development server that captures Sentry SDK envelopes" | Not stale — fragment is more detailed (OK) |
| `sentry debug-files check` | "Inspect a debug information file" | Fragment covers it | OK |
| `sentry debug-files bundle-jvm` | "Create a JVM source bundle for source context" | Fragment covers it | OK |
| `sentry init` | "Initialize Sentry in your project (experimental)" | Fragment matches | OK |

No meaningfully stale `brief` strings were found. The generated docs are built
from the code `brief`/`fullDescription`, so they cannot drift by design. The
hand-written fragments add examples and context but don't redefine the
descriptions.

## E. Missing Route Mappings in Skill Generator

`ROUTE_TO_REFERENCE` was replaced by automatic 1:1 route-to-file mapping in
`groupRoutesByReference()`. Every visible route produces its own
`references/{routeName}.md`. The `help` route is intentionally excluded.

**No gaps found.** All routes in `src/app.ts` are covered by the automatic
mapping.

## F. Installation / Distribution Gaps

| Topic | Code/Reality | Documentation | Gap |
|-------|-------------|---------------|-----|
| `SENTRY_INSTALL_DIR` env var | Supported by install script and `sentry cli setup` | Not in `getting-started.mdx` | **Missing** from getting-started |
| `SENTRY_INIT` env var | Supported by install script (`SENTRY_INIT=1` runs wizard) | Not in `getting-started.mdx` | **Missing** from getting-started |
| `SENTRY_CLI_NO_TELEMETRY` in installer | Install script respects this for error telemetry | Not mentioned in getting-started | Minor (telemetry opt-out) |
| `--no-modify-path` installer flag | Supported | Not in `getting-started.mdx` | **Missing** (only in `cli.md` fragment) |
| `--no-completions` installer flag | Supported | Not in `getting-started.mdx` | **Missing** |
| `--no-agent-skills` installer flag | Supported | Not in `getting-started.mdx` | **Missing** |
| Musl/Alpine auto-detection | Installer auto-detects musl, installs libstdc++ on Alpine | Not documented | **Missing** (important for Docker users) |
| Gzip-compressed downloads | Installer tries `.gz` first (~60% smaller) | Not documented | Minor |
| `yarn` package manager | `yarn global add sentry` in README, `yarn dlx sentry --help` in README | Missing from `getting-started.mdx` `PackageManagerCode` — only npm/pnpm/bun shown | **Inconsistency**: README includes yarn, `getting-started.mdx` includes yarn (actually it does via the component) |
| Windows support | Install script supports MINGW/MSYS/CYGWIN x64 only | Platform table in getting-started says "Via Git Bash, MSYS2, or WSL" | OK |

## G. Undocumented Environment Variables

The env-registry (`src/lib/env-registry.ts`) is the canonical source. The
generated `configuration.md` (gitignored) includes all registered variables.
However, some env vars used in source code are NOT in the registry:

| Variable | Used in | Purpose | In env registry? |
|----------|---------|---------|-----------------|
| `SENTRY_ENVIRONMENT` | `src/lib/bash-hook/traceback.ts` | Bash hook environment tag | **No** |
| `SENTRY_SPOTLIGHT` | `src/commands/local/run.ts`, `server.ts` | Injected for local dev server | **No** (injected, not read) |
| `SENTRY_TRACES_SAMPLE_RATE` | `src/lib/init/verify-setup.ts`, `local/run.ts` | Injected for init verification | **No** (injected, not read) |
| `SENTRY_MONITOR_SLUG` | `src/commands/monitor/run.ts` | Injected for wrapped command | **No** (injected, not read) |
| `SENTRY_SCAN_DISABLE_WORKERS` | `src/lib/scan/grep.ts` | Debug: disable parallel scanning | **No** |
| `SENTRY_RELEASE` | `src/lib/init/verify-setup.ts` | Injected for verification | **Yes** (registered) |

Variables that are injected into child processes (SPOTLIGHT, TRACES_SAMPLE_RATE,
MONITOR_SLUG) are arguably not user-facing config variables. However,
`SENTRY_ENVIRONMENT` and `SENTRY_SCAN_DISABLE_WORKERS` are read from the
user's environment and could be documented.

## H. Auth / Self-Hosted Gaps

| Topic | Code | Documentation | Gap |
|-------|------|---------------|-----|
| `--url` flag on `auth login` | Registers trust anchor; only way to trust new host | `self-hosted.md` documents it well | OK |
| `--read-only` on `auth login` | Requests read-only OAuth scopes | Not in `self-hosted.md` or `auth.md` examples | **Missing** — useful for self-hosted too |
| `--scope` on `auth login` | Custom OAuth scope selection | Not documented anywhere | **Missing** |
| Token storage in SQLite | `~/.sentry/cli.db`, table `auth`, host-scoped | `getting-started.mdx` says "SQLite database at `~/.sentry/`" | OK |
| `SENTRY_FORCE_ENV_TOKEN` | Forces env token over stored OAuth | `self-hosted.md` env table includes it | OK |
| Host scope refusal | CLI refuses login to untrusted hosts from `.sentryclirc` | `self-hosted.md` mentions `--url` as "most secure way" | OK |
| `.sentryclirc` import | `sentry cli import` migrates legacy config | `cli.md` fragment documents it | OK |
| `NODE_EXTRA_CA_CERTS` | For corporate TLS proxies | `self-hosted.md` documents it | OK |
| `sentry cli defaults ca-cert` | Persists CA cert path | `self-hosted.md` documents it | OK |
| `sentry cli defaults headers` | Persists custom headers | `self-hosted.md` documents it | OK |
| Token precedence (default) | Stored OAuth > `SENTRY_AUTH_TOKEN` > `SENTRY_TOKEN` | `auth.md` fragment documents it | OK, but... |
| Token precedence (auth.md vs library-usage.md) | Same | `auth.md` says "stored OAuth first"; `library-usage.md` says `SENTRY_AUTH_TOKEN` > `SENTRY_TOKEN` > stored | **Inconsistency**: `library-usage.md` lists env vars before stored OAuth, which contradicts the actual default priority |

## I. Plugin/Skills Gaps

| Topic | Code | Documentation | Gap |
|-------|------|---------------|-----|
| Install targets | `~/.agents` and `~/.claude` directories | `agentic-usage.md` says "~/.claude, ~/.agents" | OK |
| Cursor support | Via `~/.agents` path; also `.cursor/skills/` in repo | `plugins/README.md` says "automatically available in `.cursor/skills/`" | OK |
| Claude Code plugin marketplace | `claude plugin marketplace add getsentry/cli` | `plugins/README.md` documents it | OK |
| `npx skills add` | Referenced in `agentic-usage.md` | Works if `skills` CLI is installed | OK |
| Build-time embedding | Skills embedded in binary via `src/generated/skill-content.ts` | `agentic-usage.md` says "No network fetch is needed — skill files are embedded in the binary" | OK |
| `--no-agent-skills` | Supported by install script and `sentry cli setup` | `agentic-usage.md` documents it | OK |
| Uninstall cleanup | `sentry cli uninstall` removes skill directories | Not documented in `agentic-usage.md` | **Missing** — users should know uninstall cleans up |
| Cursor plugin.json | No Cursor-specific plugin manifest exists | `plugins/README.md` doesn't claim one exists | OK |

## J. README / DEVELOPMENT.md Drift

| Claim | Source | Reality | Issue |
|-------|--------|---------|-------|
| README uses `bun` commands | README `## Quick Reference: Commands` in AGENTS.md | `package.json` uses `pnpm` as packageManager; README correctly shows `pnpm` | OK |
| README: "Node.js 22.15+" | README dev prereqs | `package.json` `engines.node: ">=22.15"` | OK |
| DEVELOPMENT.md: "pnpm v10.11+" | DEVELOPMENT.md | `package.json` `packageManager: "pnpm@10.11.0"` | OK |
| AGENTS.md says use `bun` | AGENTS.md throughout | README and DEVELOPMENT.md say `pnpm`; `package.json` `packageManager` is pnpm | **Inconsistency**: AGENTS.md tells agents to use `bun` commands but the project uses `pnpm` |
| AGENTS.md: "Bun as runtime" | AGENTS.md | Build uses esbuild+fossilize (Node SEA), tests use vitest, runtime is Node.js >= 22.15 | **Stale**: AGENTS.md references Bun extensively but the project has migrated to pnpm/Node.js/vitest |
| AGENTS.md: `bun test`, `bun run` | AGENTS.md commands table | `package.json` scripts use `pnpm run`, tests use `vitest` not `bun test` | **Stale** |
| AGENTS.md: `Bun.file()`, `Bun.write()` etc. | AGENTS.md Bun API table | If running under pnpm/Node, Bun APIs are not available | **Potentially stale** — needs verification if Bun shims are still used |
| AGENTS.md: `bun:test` | Testing section header | Tests use `vitest` per `package.json` | **Stale** |
| README: `pnpm install` for setup | README | `package.json` `packageManager: "pnpm@10.11.0"` | OK |
| DEVELOPMENT.md: "build uses esbuild and fossilize" | DEVELOPMENT.md | `script/build.ts` uses esbuild + fossilize | OK |
| README license: "FSL-1.1-Apache-2.0" | README | `package.json`: "FSL-1.1-Apache-2.0" | OK |
| `configuration.md` referenced but not committed | `getting-started.mdx`, `self-hosted.md`, `features.md` | File is generated and gitignored | OK — expected behavior |

### AGENTS.md Bun references in detail

AGENTS.md contains extensive Bun-specific guidance that may be stale:

1. **Quick Bun API Reference table** — Lists `Bun.file()`, `Bun.write()`, `Bun.spawn()`, `Bun.$`, `Bun.which()`, `Bun.Glob()`, `Bun.sleep()` as the preferred APIs
2. **Testing section** — Says "bun:test + fast-check" but tests use vitest
3. **Commands** — Shows `bun test`, `bun run dev`, `bun install` but package.json uses pnpm
4. **Exception notes** — Mentions `Bun.$` shell limitations and node polyfill shims

---

## Top 5 Most Impactful Fixes (Prioritized)

### 1. AGENTS.md: Bun → pnpm/Node.js/vitest migration
**Impact:** High — AI agents following AGENTS.md will use wrong commands (`bun test` instead of `pnpm run test:unit`, `bun install` instead of `pnpm install`)
**Files:** `AGENTS.md`
**Action:** Update all command examples and API references to match the current pnpm/Node.js/vitest toolchain

### 2. `library-usage.md` token precedence inconsistency
**Impact:** Medium-High — Misleads library users about which token takes priority
**Files:** `docs/src/content/docs/library-usage.md`
**Action:** Fix the authentication priority list to match code: stored OAuth > `SENTRY_AUTH_TOKEN` > `SENTRY_TOKEN` (currently lists env vars first)

### 3. Undocumented `--read-only` and `--scope` flags on `auth login`
**Impact:** Medium-High — Security-conscious users and self-hosted admins need scoped tokens
**Files:** `docs/src/fragments/commands/auth.md`
**Action:** Add examples for `--read-only` (read-only agent tokens) and `--scope` (custom scope selection)

### 4. Missing `proguard upload` documentation
**Impact:** Medium — Android developers using ProGuard/R8 cannot find upload docs
**Files:** `docs/src/fragments/commands/proguard.md`
**Action:** Add upload subcommand examples with `--uuid`, `--no-upload`, `--require-one` flags

### 5. Missing install script flags in getting-started
**Impact:** Medium — Docker/CI users need `--no-modify-path`, `--no-completions`, `--no-agent-skills` for clean installs
**Files:** `docs/src/content/docs/getting-started.mdx`
**Action:** Add a section documenting installer flags and the `SENTRY_INSTALL_DIR`/`SENTRY_INIT` env vars
Loading