docs: documentation audit — fix toolchain drift, stale versions, and coverage gaps

[cursor]

Documentation Audit Report (2026-07-20)

Weekly automated audit comparing CLI implementation against documentation. This PR fixes the highest-impact gaps found.

---

Changes Made

1. AGENTS.md toolchain drift (bun → pnpm/vitest)

• Quick Reference section: all bun install/run/test → pnpm install/run + vitest
• "No Runtime Dependencies" section: bun run check:deps → pnpm run check:deps, bun add -d → pnpm add -D
• Generated Docs & Skills: bun run generate:docs → pnpm run generate:docs, bun run check:fragments → pnpm run check:fragments
• Error Handling CI enforcement: bun run check:errors → pnpm run check:errors
• Testing section: bun:test → vitest, mock.module() → vi.mock(), BUN_TEST_WORKER_ID → VITEST_POOL_ID
• Project overview: "built with Bun" → describes actual build pipeline (esbuild + fossilize for Node SEA)

2. Stale URL in upgrade.ts

• https://sentry.io/get-cli/ → https://cli.sentry.dev/install (SIGKILL recovery message)

3. Node.js version requirement fix (getting-started.mdx)

• Changed "Node.js 22.15+" to "Node.js 18+" with a note about WASM fallback on 18–22.14
• This matches package.json engines: ">=18.0" and README claims

4. Stale version pinning examples

• Updated 0.19.0 → 0.38.0 in install script help, getting-started docs, and env-registry

5. proguard upload fragment — missing examples

• Added bash examples for proguard upload (single/multi file, forced UUID, dry-run, require-one)

6. agentic-usage.md — expanded agent coverage

• Updated from "Claude Code and Cursor" to full list of 9+ detected agents
• Added "Supported Agents" section documenting install targets

---

Full Gap Report

A. Undocumented or Missing Commands/Subcommands

No gaps found. All 31 visible command groups have corresponding generated docs and fragment files. The check:fragments validation enforces 1:1 mapping.

B. Undocumented Flags

Flag documentation is auto-generated from Stricli command definitions. All non-hidden flags appear in the generated reference. No gaps in the generated layer.

Fragment coverage gaps (examples only, not reference docs):

• proguard upload flags (--uuid, --no-upload, --require-one) had no examples → Fixed
• alert issues edit — no dedicated example (low priority)

C. Missing Usage Examples

All command fragments have at least one bash example block. The only significant gap was:

• proguard upload — zero examples → Fixed (5 examples added)

D. Stale Descriptions

No meaningful drift found. The brief strings in code are used directly by the doc generator, ensuring they can't drift from the generated reference pages.

E. Missing Route Mappings in Skill Generator

Not applicable. The ROUTE_TO_REFERENCE map was removed in favor of automatic 1:1 mapping via groupRoutesByReference(). All routes are included automatically.

F. Installation / Distribution Gaps

Gap	Status
Node.js version: getting-started said 22.15+ but engines is >=18.0	Fixed
Version pin example showed 0.19.0, current release is 0.38.0	Fixed
Install script URL in upgrade.ts pointed to old sentry.io/get-cli/	Fixed
musl/Alpine support: docs claim it, install script expects -musl suffix binaries, but build pipeline only produces 5 non-musl targets	Info — functional because CI publishes musl binaries separately
Install script flags --no-modify-path, --no-completions not in getting-started	Low priority — documented in script's --help

G. Undocumented Environment Variables

The env-registry.ts is the source of truth for configuration.md (auto-generated). All SENTRY_* variables used in src/ that are user-facing are registered.

Intentionally excluded (internal):

• SENTRY_PIPELINE, SENTRY_MONITOR_SLUG — internal CI signals
• SENTRY_CLIENT_ID_BUILD — build-time define, not runtime env var

No gaps between code and generated config page.

H. Auth / Self-Hosted Gaps

Item	Status
OAuth scopes in DEVELOPMENT.md match OAUTH_SCOPES in oauth.ts	✓ In sync (auto-generated section)
Self-hosted OAuth 26.1.0+ requirement documented	✓ In self-hosted.md and env-registry
Token storage in SQLite (~/.sentry/cli.db)	✓ Documented in configuration fragment
Host-scoped tokens behavior	Not documented in user docs (low priority — internal safety mechanism)
--scope validation against canonical SENTRY_SCOPES	Not documented (low — advanced self-hosted use only)

I. Plugin/Skills Gaps

Gap	Status
agentic-usage.md only mentioned 2 agents, detect-agent.ts has 11+	Fixed
Skills install targets only ~/.claude and ~/.agents (not per-agent dirs)	Documented accurately now
npx skills add https://cli.sentry.dev manual install path	✓ Documented
Claude plugin marketplace install path	✓ Documented in plugins/README.md

J. README / DEVELOPMENT.md Drift

Item	Status
AGENTS.md said bun for all dev commands	Fixed
AGENTS.md overview said "built with Bun"	Fixed
README.md prereqs, scripts, library docs	✓ Auto-generated, in sync
DEVELOPMENT.md prereqs, env vars, build	✓ Auto-generated, in sync

---

Top 5 Most Impactful Fixes (all addressed in this PR)

1. AGENTS.md toolchain drift — AI agents using this file as a guide would run bun install / bun test which are wrong commands for this repo
2. Node.js version requirement — getting-started.mdx told users they need 22.15+ for npm installs, but the actual minimum is 18+ (with WASM fallback)
3. Stale install URL — upgrade failure message pointed to defunct sentry.io/get-cli/ URL
4. Agentic-usage agent coverage — only 2 of 11+ detected agents were mentioned, misleading users of other tools
5. proguard upload examples — no documentation coverage for a key Android workflow command

  

[github-actions]

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

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 5477 uncovered lines.
✅ Project coverage is 81.68%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.67%    81.68%    +0.01%
==========================================
  Files          426       426         —
  Lines        29896     29896         —
  Branches     19420     19420         —
==========================================
+ Hits         24416     24419        +3
- Misses        5480      5477        -3
- Partials      2035      2034        -1

---

Generated by Codecov Action