docs: comprehensive documentation audit report

[cursor]

Documentation Audit Report

Full cross-reference of the Sentry CLI implementation code vs. all documentation surfaces (README.md, DEVELOPMENT.md, AGENTS.md, docs site pages, command fragments).

Methodology

1. Read all root documentation (README.md, DEVELOPMENT.md, AGENTS.md, 9 docs site pages)
2. Read all 28 command doc fragments under docs/src/fragments/commands/
3. Read the full command implementation (src/app.ts + all ~100 leaf command files)
4. Read installation/distribution code (install script, .craft.yml, package.json, setup/upgrade)
5. Read auth/config code (auth commands, OAuth, constants, region, db/auth, config types)
6. Read plugin/skills system code (agent-skills, setup, plugin manifests, generate-skill)
7. Cross-referenced everything and produced the gap report below

---

A. Undocumented Commands/Subcommands

Command	Gap
sentry dashboard delete	Missing from dashboard fragment (only widget delete shown)
sentry dashboard edit	No examples for editing a dashboard itself
sentry proguard upload	Entire upload subcommand missing from proguard fragment
sentry release propose-version	Only in passing example; no dedicated section

B. Undocumented Flags

50+ non-hidden flags are defined in code but not mentioned in their doc fragments. Highlights:

• sentry auth login: --read-only, --scope/-s, --timeout, --force, --url (flag vs env)
• sentry auth refresh: --force, --read-only, --scope/-s
• sentry issue list: --compact, --period/-t
• sentry explore: --environment/-e
• sentry trace view: --full, --spans
• sentry event send: --no-environ, --logfile, --with-categories, --timestamp
• sentry monitor run: --check-in-margin, --failure-issue-threshold, --recovery-threshold
• sentry sourcemap inject/upload: --ignore, --ignore-file, --strip-prefix, --strip-common-prefix, --no-rewrite
• sentry release create: --ref, --url; deploy: --url, --started, --finished, --time
• sentry release list: --status, --environment, --period
• sentry local: --host/-H, --verify, --timeout

Full list in the audit report file.

C. Missing Usage Examples

• sentry dashboard delete (top-level, not widget)
• sentry proguard upload
• sentry release finalize with its flags
• sentry auth whoami (mentioned but no output example)

D. Stale Descriptions

No meaningfully stale brief strings found — generated docs are built from code metadata.

E. Missing Route Mappings in Skill Generator

No gaps found. ROUTE_TO_REFERENCE was replaced by automatic 1:1 mapping in groupRoutesByReference().

F. Installation / Distribution Gaps

• SENTRY_INSTALL_DIR and SENTRY_INIT env vars: missing from getting-started
• Installer flags (--no-modify-path, --no-completions, --no-agent-skills): missing from getting-started
• Musl/Alpine auto-detection: missing (important for Docker users)

G. Undocumented Environment Variables

• SENTRY_ENVIRONMENT: read in bash-hook but not in env registry
• SENTRY_SCAN_DISABLE_WORKERS: debug flag not in registry
• Variables injected into child processes (SPOTLIGHT, TRACES_SAMPLE_RATE, MONITOR_SLUG) are not user-facing config

H. Auth / Self-Hosted Gaps

• --read-only and --scope on auth login: missing from both auth and self-hosted docs
• Token precedence inconsistency: library-usage.md lists env vars before stored OAuth, contradicting the actual default priority (stored OAuth wins)

I. Plugin/Skills Gaps

• Uninstall cleanup of skill directories: not documented in agentic-usage.md

J. README / DEVELOPMENT.md / AGENTS.md Drift

Critical: AGENTS.md references Bun extensively but the project has migrated to pnpm/Node.js/vitest:

• AGENTS.md says bun test, bun run dev, bun install — package.json uses pnpm
• AGENTS.md references bun:test + fast-check — tests use vitest (zero bun:test imports, 385 vitest imports)
• AGENTS.md Bun API Reference table lists Bun.file(), Bun.write(), Bun.spawn(), etc.
• AGENTS.md testing section says "bun:test + fast-check" but tests use vitest

---

Top 5 Most Impactful Fixes (Prioritized)

1. AGENTS.md: Bun → pnpm/Node.js/vitest migration — AI agents following AGENTS.md will use wrong commands
2. library-usage.md token precedence inconsistency — Misleads library users about which token takes priority
3. Undocumented --read-only and --scope flags on auth login — Security-conscious users need scoped tokens
4. Missing proguard upload documentation — Android developers can't find upload docs
5. Missing install script flags in getting-started — Docker/CI users need --no-modify-path etc. for clean installs

  

[github-actions]

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

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 5052 uncovered lines.
❌ Project coverage is 81.23%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
- Coverage    81.24%    81.23%    -0.01%
==========================================
  Files          388       388         —
  Lines        26910     26910         —
  Branches     17481     17481         —
==========================================
+ Hits         21861     21858        -3
- Misses        5049      5052        +3
- Partials      1822      1824        +2

---

Generated by Codecov Action