Skip to content

feat(cli): Add event analytics command - #1579

Closed
manessaraj wants to merge 6 commits into
mainfrom
sarajmanes/dain-1940-event-dropped-command
Closed

manessaraj wants to merge 6 commits into
mainfrom
sarajmanes/dain-1940-event-dropped-command

Conversation

@manessaraj

@manessaraj manessaraj commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Add support in Sentry CLI to show dropped events (e.g. rate-limited, invalid data ..etc. ).

Command: sentry events analytics

Command description should be enough be enough to let agents figure out the purpose of the command.

Adds human readable format (as table that mimics the UI a bit) and json output for agents.

Refs DAIN-1940

@vercel

vercel Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

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

1 Skipped Deployment
Project Deployment Actions Updated
sentry-local Skipped Skipped Oct 26, 2026 7:08pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 21, 2026

Copy link
Copy Markdown

DAIN-1940

Comment thread packages/cli/src/types/index.ts Resolved
@BYK

BYK commented Oct 21, 2026

Copy link
Copy Markdown
Member

Like the feature, not sure about the event dropped name. Sounds more like event analytics or something?

@manessaraj

Copy link
Copy Markdown
Contributor Author

Like the feature, not sure about the event dropped name. Sounds more like event analytics or something?

it lists all the categories of events that are dropped with reasons. There is no analysis. Also, the command event list lists all stored events, so it makes sense event dropped to list all dropped events.

@manessaraj
manessaraj marked this pull request as ready for review October 21, 2026 20:09
@manessaraj
manessaraj requested a review from BYK October 21, 2026 20:09
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Oct 21, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@BYK BYK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it lists all the categories of events that are dropped with reasons. There is no analysis.

I said analytics not analysis which I think is quite fitting for the data you are displaying.

Also, the command event list lists all stored events, so it makes sense event dropped to list all dropped events.

No it doesn't as event list or events lists you individual events with ids and information whereas what you added only shows aggregate data and there's no way to get individual information by definition as these are dropped events.

The command naming schema we follow is sentry <noun> <verb/action> so ideally this would be more like sentry event-analytics show or something along those lines. I'd still take sentry event analytics over that

manessaraj and others added 4 commits October 22, 2026 14:39
Summarize events Sentry received but dropped (rate-limited, filtered,
invalid, abuse, client-discarded, cardinality-limited), grouped by
outcome and reason, via the existing events-dropped endpoint. This is
the last client surface after the Explore flyout, MCP, and Seer.

Each reason carries its drop-classification tag (intentional vs
unintentional) in both the human Tags column and the JSON tags field.
--json/--fields come from the command output config, so the table and
machine-readable views share one summarizer and never diverge.

Refs DAIN-1940

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Map the `metrics` dataset alias to the `tracemetrics` API name in
getDroppedEvents so `event dropped --dataset metrics` no longer 400s,
and pass the full "event dropped" command path into project resolution
so error hints show the real command instead of "sentry dropped".

Also drops redundant comments and dead re-exports from the command.

Refs DAIN-1940

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The file is 164 lines; banner dividers are a navigation aid for the
repo's large formatters (human, dashboard), not small ones.

Refs DAIN-1940

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per CLI owner review: `event list` returns individual stored events, but
dropped events have no stored detail — this command only shows aggregate
counts, so `analytics` fits the `<noun> <verb>` scheme better than
`dropped`. "Dropped" stays in the brief/description, which feeds the CLI
skill, so agent discoverability is preserved.

Also makes the bucket `tags` field optional (default []) so a tags-less
API bucket no longer fails the whole response, matching find_dropped_events.

Refs DAIN-1940

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@manessaraj
manessaraj force-pushed the sarajmanes/dain-1940-event-dropped-command branch from 62d6d81 to c56bbb5 Compare October 22, 2026 19:05
@manessaraj manessaraj changed the title feat(cli): Add event dropped command feat(cli): Add event analytics command Oct 22, 2026
buildCommand routes human hints through writeFooter → plainSafeMuted,
which already mutes on a TTY and returns plain text under
SENTRY_PLAIN_OUTPUT=1. Pre-wrapping the empty-state hint with muted()
double-colored it, leaking ANSI into plain output.

Refs DAIN-1940

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

### `sentry event analytics [<org/project>]`

Analytics for events Sentry dropped

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's take a note to also add other kinds of analytics like accepted, rate limited etc so this is a real analytics command.


| Field | Type | Description |
|-------|------|-------------|
| `outcomes` | array | |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a useful output shape. Array of what? If outcomes is the only field that indicates that we should probably unwrap it and allow more granular selection?


const COMMAND_NAME = "event analytics";

const DATASETS = ["errors", "spans", "logs", "metrics"] as const;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to my comments in #1559 (review), we need a unified place for dataset list, not per-command.

"and the JSON `tags` field.\n\n" +
"Target the project with <org>/<project>, or omit it to detect from your " +
"config or a local DSN.\n\n" +
"Examples:\n" +

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, similar to my comments in #1559 (review) the examples have their own dedicated place.

@sentry-junior sentry-junior Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed at 150eeb4. The rename to event analytics, the metrics alias fix, optional tags, and the plain empty-state hint are all in. BYK's earlier comments are still open, and a couple of the same "use what already exists" patterns from #1559 show up here too:

  • Examples are hand-written in fullDescription. packages/cli/AGENTS.md ("Generated Docs & Skills") says examples belong in docs.examples ({ description, command }[], see agent-conversation/list.ts). From there they render in --help, the generated docs, and the skill reference. Move the four Examples: lines there. references/event.md will then regenerate with them, so it won't need to be edited by hand.
  • Dataset handling is now a fourth local copy. explore.ts (DATASET_ALIASES/VALID_DATASETS/parseDataset), dashboard/resolve.ts, and the alert helpers each have their own copy. This PR adds a local DATASETS tuple and hides the metrics → tracemetrics mapping inside getDroppedEvents. It has already drifted: explore accepts error/span/log, and this command rejects them. Please use the shared dataset module proposed in #1559 (one alias table, plus per-command allowed subsets). This command would take errors, spans, logs, metrics. Keep lib/api/dropped-events.ts a plain transport that receives the API name.
  • The JSON shape isn't selectable. The output is { outcomes: [...] } with nested reasons. So --fields has exactly one useful field, outcomes, which returns everything, and the generated docs show only outcomes | array. List commands like span list and agent-conversation list use an item schema plus jsonTransform. Do the same here and emit flat rows such as { outcome, label, reason, category, events, share, tags }. Then --fields outcome,reason,events works, and the docs table describes something real. The per-outcome subtotal can stay in the human formatter.
  • Smaller convention gaps in analytics.ts / dropped-events.ts:
    • The command calls getProject directly. That ignores projectData from the resolver and skips the cache-first fetchProjectId, which span list/trace list use via resolveLogProjectId. It also skips that helper's similar-project hint on a 404.
    • The 90d default is buried in the API helper, so --help shows no default for --period. Declare it on the flag. Either use LIST_PERIOD_FLAG, or put an explicit inline default: "90d" with a reason, the way issue list does.
    • DroppedEventsOptions.interval has no caller. Drop it.

As a follow-up (not blocking): the response already includes acceptedEvents, and share is computed against it. Surfacing accepted alongside the drop outcomes would be the first step toward the broader analytics BYK mentioned on event.md. Worth a ticket.

I didn't run the tests locally. CI is green on this commit.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit a2d437b. Configure here.

() =>
getDroppedEvents(org, {
dataset: flags.dataset,
projectId: projectId === undefined ? undefined : String(projectId),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Project ID fallback queries all projects

Medium Severity

resolveLogProjectId returns undefined on non-404 lookup failures, and getDroppedEvents treats a missing projectId as org-wide. A transient project lookup failure then returns every project's dropped events while the output still attributes them to the requested project.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit a2d437b. Configure here.

@manessaraj manessaraj closed this Oct 28, 2026
sentry-junior Bot added a commit that referenced this pull request Nov 5, 2026
event analytics only listed drops, though the endpoint returns the
accepted volume and share was already computed against it. BYK asked on
#1579 for accepted volume so this is a real analytics command.

- Accepted volume comes first as its own outcome row (Sentry reports
  outcome and reason `accepted`, no tags). Drop rows follow, sorted as
  before.
- The human output shows accepted as a header line with no reason table.
- The "No dropped events" hint now fires when only accepted rows exist.
- The row schema, summarizer and formatter are renamed from DroppedEvent*
  to EventOutcome*, since rows are no longer only drops.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
BYK added a commit that referenced this pull request Nov 5, 2026
Adds `sentry event analytics`, which reports events Sentry received but
dropped before storage (rate-limited, filtered, invalid, abuse,
client-discarded, cardinality-limited), one row per outcome and reason
with each slice's share of total volume. It is the CLI counterpart to
the `find_dropped_events` MCP tool, so an agent or a person working
headless can see data-fidelity gaps without the web UI.

This reopens the work previously attempted in #1579, redone from
scratch. The earlier attempt duplicated the dropped-events schema and
dataset handling inside the CLI, which drifted from the MCP
implementation and drew repeated review. The redo instead reuses the
now-shared pieces that landed since then — the `buildDatasetParser`
dataset map in `lib/datasets.ts` (so `metrics` normalizes to
`tracemetrics` at parse time) and the `find_dropped_events` MCP feedback
on response shape and tags — and builds on the standard command, target,
and completion primitives rather than hand-rolled ones. The schema
treats `tags` as optional, matching the endpoint and the MCP tool.

Verified end-to-end against production (project 1): the command resolves
the project, fetches dropped events, and renders both the grouped human
table and the JSON array, across the errors and spans datasets.

Refs DAIN-1940

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…l UI, env vars (getsentry#1579)

## 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 getsentry#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 getsentry#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
(getsentry#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 getsentry#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)

1. **`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.

2. **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.

3. **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.

4. **`--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`.

5. **`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.

<div><a
href="https://cursor.com/agents/bc-dcce6e5a-d036-4d6c-ba6c-54750bd16fdb?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>&nbsp;<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>&nbsp;</div>

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…l UI, env vars (getsentry#1579)

## 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 getsentry#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 getsentry#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
(getsentry#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 getsentry#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)

1. **`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.

2. **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.

3. **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.

4. **`--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`.

5. **`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.

<div><a
href="https://cursor.com/agents/bc-dcce6e5a-d036-4d6c-ba6c-54750bd16fdb?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>&nbsp;<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>&nbsp;</div>

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…l UI, env vars (getsentry#1579)

## 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 getsentry#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 getsentry#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
(getsentry#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 getsentry#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)

1. **`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.

2. **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.

3. **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.

4. **`--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`.

5. **`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.

<div><a
href="https://cursor.com/agents/bc-dcce6e5a-d036-4d6c-ba6c-54750bd16fdb?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>&nbsp;<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>&nbsp;</div>

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…l UI, env vars (getsentry#1579)

## 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 getsentry#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 getsentry#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
(getsentry#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 getsentry#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)

1. **`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.

2. **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.

3. **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.

4. **`--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`.

5. **`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.

<div><a
href="https://cursor.com/agents/bc-dcce6e5a-d036-4d6c-ba6c-54750bd16fdb?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>&nbsp;<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>&nbsp;</div>

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…mand coverage, AGENTS.md update (getsentry#1602)

## Weekly Documentation Audit — 2026-09-21

Automated cross-reference of implementation vs documentation, covering
commits since the last audit (`86767f6d2`, PR getsentry#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 getsentry#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 getsentry#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 getsentry#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 getsentry#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>&nbsp;<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>&nbsp;</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>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…mand coverage, AGENTS.md update (getsentry#1602)

## Weekly Documentation Audit — 2026-09-21

Automated cross-reference of implementation vs documentation, covering
commits since the last audit (`ca7ef6af3`, PR getsentry#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 getsentry#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 getsentry#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 getsentry#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 getsentry#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>&nbsp;<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>&nbsp;</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>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…mand coverage, AGENTS.md update (getsentry#1602)

## Weekly Documentation Audit — 2026-09-21

Automated cross-reference of implementation vs documentation, covering
commits since the last audit (`ca7ef6af3`, PR getsentry#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 getsentry#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 getsentry#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 getsentry#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 getsentry#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>&nbsp;<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>&nbsp;</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>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…mand coverage, AGENTS.md update (getsentry#1602)

## Weekly Documentation Audit — 2026-09-21

Automated cross-reference of implementation vs documentation, covering
commits since the last audit (`1804ddb52`, PR getsentry#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 getsentry#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 getsentry#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 getsentry#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 getsentry#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>&nbsp;<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>&nbsp;</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>

This branch was previously deployed

1 inactive deployment
Preview — a2d437bc Deployed Oct 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants