docs: weekly documentation audit — agent-conversation syntax, new command coverage, AGENTS.md update - #1602
Merged
Conversation
The fragment showed space-separated org and conversation ID (`sentry agent-conversation view my-org conv-123`) but the command accepts a single slash-separated positional (`my-org/conv-123`). Also added the no-org variant to show auto-detection. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
New commands added since the last audit were missing from the agentic usage and agent guidance pages: - agent-conversation (list/view): browse AI agent conversation transcripts - wasm-split: add build IDs to WebAssembly modules (no auth, local-only) - status: check Sentry service status (no auth) Added capabilities entries, 'How It Works' example, and workflow patterns with bash examples. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The Architecture section listed a subset of command groups with an ellipsis. Replaced with the full alphabetical list so new contributors find every group and standalone command file at a glance. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
BYK
approved these changes
Sep 21, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Weekly Documentation Audit — 2026-09-21
Automated cross-reference of implementation vs documentation, covering commits since the last audit (
ca7ef6af3, PR #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:
agent-conversation list/viewsrc/commands/agent-conversation/agentic-usage.md,agent-guidance.mdwasm-splitsrc/commands/wasm-split.ts(PR #1589)agentic-usage.md,agent-guidance.mdstatus showsrc/commands/status/show.tsagentic-usage.mdcapabilitiesFixed in this PR: Added all three to the Capabilities list in
agentic-usage.mdand added workflow patterns with bash examples inagent-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 newwasm-split.mdfragment was added alongside PR #1589.Bug found: The
agent-conversation.mdfragment had incorrect positional syntax — it showedsentry 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 issentry agent-conversation view my-org/conv-123.Fixed in this PR.
D. Stale Descriptions
No drift found. The
briefstrings in code match the auto-generated doc descriptions.E. Missing Route Mappings in Skill Generator
N/A — the manual
ROUTE_TO_REFERENCEmap was removed in a prior audit. The skill generator now usesgroupRoutesByReference()for automatic 1:1 route-to-file mapping.F. Installation / Distribution Gaps
No new gaps. The install script,
getting-started.mdx, andREADME.mdall document:curl, Homebrew, npm/pnpm/yarn/bun install methods--no-modify-path,--no-completions,--no-agent-skillsinstaller flagsSENTRY_INSTALL_DIR,SENTRY_VERSION,SENTRY_INITenv vars--version nightlyG. Undocumented Environment Variables
All
SENTRY_*env vars accessed viagetEnv()are registered inenv-registry.tsand appear in the generatedconfiguration.md. Intentionally excluded internal/test-only vars remain unchanged from prior audits:SENTRY_ENVIRONMENT— bash-hook template onlySENTRY_CLI_NO_EXIT_TRAP— bash-hook internalSENTRY_SCAN_DISABLE_WORKERS— internal perf tuningSENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE— test-onlySENTRY_RN_*— React Native wrapper internalsH. 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, andsentry cli defaultsfor persistent proxy headers.I. Plugin/Skills Gaps
The
plugins/README.mdaccurately describes the skill installation flow and supported directories (~/.claude,~/.agents). The agent detection list inagentic-usage.mdis current (includes Cline, Grok, Kimi, Junie, OpenClaw from PR #1571).No new gaps.
J. README / DEVELOPMENT.md Drift
No drift found:
>=22.15in devEngines,>=20.0in engines — matches docs10.11.0— matches docsAGENTS.md drift found: The Architecture section's command group list was outdated — it listed a subset with
…ellipsis, omittingagent-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)
agent-conversation viewfragment had wrong positional syntax — agents following the example would get a parse error. Fixed.agent-conversationmissing from agentic docs — AI agents had no guidance for browsing conversation transcripts, a feature specifically built for agent workflows. Fixed.wasm-splitmissing from agentic docs — a new command (PR feat(wasm-split): port Symbolicator wasm-split #1589) useful for WebAssembly projects had no agent guidance or workflow pattern. Fixed.statusmissing 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.