docs: add missing command pages for trace, span, sourcemap, repo, trial, schema#569
Merged
docs: add missing command pages for trace, span, sourcemap, repo, trial, schema#569
Conversation
Contributor
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨Dashboard
Init
Other
Bug Fixes 🐛Dashboard
Event
Other
Documentation 📚
Internal Changes 🔧Coverage
Event
Other
🤖 This preview updates automatically when you update the PR. |
Contributor
|
Contributor
Codecov Results 📊✅ 126 passed | Total: 126 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 1285 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 95.51% 95.51% —%
==========================================
Files 194 194 —
Lines 28590 28620 +30
Branches 0 0 —
==========================================
+ Hits 27305 27335 +30
- Misses 1285 1285 —
- Partials 0 0 —Generated by Codecov Action |
betegon
approved these changes
Mar 26, 2026
BYK
force-pushed
the
docs/add-missing-command-pages
branch
from
e805f7f to
4a1dc23
Compare
…al, schema 6 commands were implemented but had no website docs pages. Also adds dashboard, trace, span, sourcemap, repo, trial, and schema to the commands index table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace hand-written command doc pages with auto-generated reference sections extracted from Stricli route tree introspection. This fixes pervasive documentation drift: phantom flags (--include, --paginate, --channel), missing flags (--fresh, --fields, --cursor, --period, --spans), and missing aliases across all command pages. Each doc page now has two parts separated by a GENERATED:END marker: 1. Auto-generated reference (args, options tables) — from source code 2. Hand-written custom content (examples, guides) — preserved on regen New infrastructure: - script/generate-command-docs.ts: generates reference sections - script/check-command-docs.ts: CI freshness checker - src/lib/introspect.ts: add extractPositionals() for arg tables - CI auto-commits regenerated docs alongside skill files Also adds extractPositionals() and PositionalInfo type to introspect.ts for structured positional argument metadata.
BYK
force-pushed
the
docs/add-missing-command-pages
branch
from
4a1dc23 to
4ed54da
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Restore hand-written content that was lost during the migration to auto-generated reference sections: - dashboard.md: query/sort shorthand tables, detailed widget examples, sample terminal output for list/view/create - cli.md: release channels table, installation detection table, nightly migration note, channel switching examples - auth.md: OAuth flow walkthrough, self-hosted setup, environment variable precedence, auth status sample output - init.md: experimental warning, features table, target syntax table, what the wizard does, supported platforms - api.md: PUT/DELETE examples, verbose mode, API docs link - issue.md: explain/plan multi-format examples, behavioral notes - log.md: full sample output with section dividers, filter examples, jq pipe example - org.md, project.md: sample terminal output - event.md: Context section in output, open-in-browser example Also fix non-descriptive <args...> placeholders by adding descriptive placeholder values to 7 commands (dashboard view/create, widget add/edit/delete, event view, log view). Updates AGENTS.md to explicitly ban 'args' as a placeholder value.
The placeholder fix surfaced these commands to the drift detection test since they now have org-containing placeholders.
- api.md: remove /api/0/ prefix from all examples (endpoints are relative to /api/0/ as documented in the arguments table) - event.md: use full 32-char hex event ID in examples (was 12 chars) - init.md: fix feature name 'replays' -> 'replay' (singular) - log.md: fix jq example to use .data[] envelope and .severity field (not .level), fix misleading 'trace IDs in brackets' text
Contributor
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Array positionals unconditionally marked optional produces contradictory docs
- Updated extractPositionals to respect params.parameter.optional for array positionals instead of hardcoding true, preventing spurious '(optional)' in docs.
Or push these changes by commenting:
@cursor push 4bee79d0bf
Preview (4bee79d0bf)
diff --git a/src/lib/introspect.ts b/src/lib/introspect.ts
--- a/src/lib/introspect.ts
+++ b/src/lib/introspect.ts
@@ -231,7 +231,8 @@
{
placeholder: `${params.parameter.placeholder ?? "args"}...`,
brief: params.parameter.brief ?? "",
- optional: true,
+ // Respect the source definition if provided; default to required (false)
+ optional: params.parameter.optional ?? false,
},
];
}This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
…al args The brief text from source code already communicates optionality (e.g., 'Target (optional) and trace ID (required)'). Appending a blanket '(optional)' suffix to all array positionals produced contradictions like 'trace ID (required) (optional)'.
…om route tree
Two root causes for missing skill examples:
1. COMMAND_SECTION_REGEX used \S+ which matched <placeholder> text,
causing command paths like 'sentry api <endpoint>' instead of
'sentry api'. Fixed with [^\s<]+ to stop at angle brackets.
2. The regex only matched up to 2 words after 'sentry', missing
3-word paths like 'sentry dashboard widget add'. Fixed with
{1,3} quantifier.
3. extractSectionExamples only registered command paths when code
blocks existed in the section. Fixed to always register paths
so extractLooseExamples can match custom-section examples.
Also replaced the manual INDEX_ORDER constant in generate-command-docs.ts
with the natural order from extractAllRoutes() (preserves insertion
order from app.ts's buildRouteMap).
…check Replace fragile regex-based markdown parsing in generate-skill.ts with marked.lexer() AST walking for robust command heading detection and code block association. The old COMMAND_SECTION_REGEX was brittle with positional placeholders in headings and couldn't handle the split between auto-generated reference sections and hand-written custom sections. The new approach: 1. Parses the full document into an AST via marked.lexer() 2. Collects command paths from ### `sentry ...` headings 3. Walks tokens sequentially, associating bash code blocks with commands by heading context or content matching Also adds an examples completeness check to check-skill.ts that verifies every skill reference file contains at least one Examples section. This catches cases where doc pages are missing bash code blocks that the skill generator needs.
5 tasks
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Close automation gap from #569: make generate-skill.ts auto-update the REFERENCE_FILES array in agent-skills.ts so new command groups are automatically included in runtime skill installation. Extend check-skill.ts to detect drift in agent-skills.ts and update CI auto-commit to include the file.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Embed skill files at build time instead of fetching from GitHub: - generate-skill.ts now produces src/generated/skill-content.ts that inlines all skill file contents as a Map<string, string> - agent-skills.ts imports the embedded content and writes it directly to ~/.claude/skills/ — no network fetch, no URL construction, no REFERENCE_FILES array, no version-pinning logic - check-skill.ts verifies skill-content.ts stays in sync - generate:skill chained before build/dev/typecheck in package.json This eliminates the CLI -> GitHub -> CLI roundtrip where skill files generated from the source code were fetched back from GitHub at runtime.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Embed skill files at build time instead of fetching from GitHub: - generate-skill.ts now produces src/generated/skill-content.ts that inlines all skill file contents as a Map<string, string> - agent-skills.ts imports the embedded content and writes it directly to ~/.claude/skills/ — no network fetch, no URL construction, no REFERENCE_FILES array, no version-pinning logic - check-skill.ts verifies skill-content.ts stays in sync - generate:skill chained before build/dev/typecheck in package.json This eliminates the CLI -> GitHub -> CLI roundtrip where skill files generated from the source code were fetched back from GitHub at runtime.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Embed skill files at build time instead of fetching from GitHub: - generate-skill.ts now produces src/generated/skill-content.ts that inlines all skill file contents as a Map<string, string> - agent-skills.ts imports the embedded content and writes it directly to ~/.claude/skills/ — no network fetch, no URL construction, no REFERENCE_FILES array, no version-pinning logic - check-skill.ts verifies skill-content.ts stays in sync - generate:skill chained before build/dev/typecheck in package.json This eliminates the CLI -> GitHub -> CLI roundtrip where skill files generated from the source code were fetched back from GitHub at runtime.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Embed skill files at build time instead of fetching from GitHub: - generate-skill.ts now produces src/generated/skill-content.ts that inlines all skill file contents as a Map<string, string> - agent-skills.ts imports the embedded content and writes it directly to ~/.claude/skills/ — no network fetch, no URL construction, no REFERENCE_FILES array, no version-pinning logic - check-skill.ts verifies skill-content.ts stays in sync - generate:skill chained before build/dev/typecheck in package.json This eliminates the CLI -> GitHub -> CLI roundtrip where skill files generated from the source code were fetched back from GitHub at runtime.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
Fix genuine documentation gaps not covered by auto-generation (#569): - Add SENTRY_AUTH_TOKEN/SENTRY_TOKEN to configuration.md - Add SENTRY_INSTALL_DIR/SENTRY_NO_CACHE to configuration.md - Add project:admin scope to DEVELOPMENT.md and self-hosted.md - Expand README commands table from 6 to 14 entries - Fix credential storage path (config.db -> cli.db) in auth docs - Fix SENTRY_AUTH_TOKEN priority label (was marked legacy, is primary) - Add missing examples for auth logout/refresh/token, project create/delete, cli setup - Align curl install flags (-fsS) between README and docs site Embed skill files at build time instead of fetching from GitHub: - generate-skill.ts now produces src/generated/skill-content.ts that inlines all skill file contents as a Map<string, string> - agent-skills.ts imports the embedded content and writes it directly to ~/.claude/skills/ — no network fetch, no URL construction, no REFERENCE_FILES array, no version-pinning logic - check-skill.ts verifies skill-content.ts stays in sync - generate:skill chained before build/dev/typecheck in package.json This eliminates the CLI -> GitHub -> CLI roundtrip where skill files generated from the source code were fetched back from GitHub at runtime.
BYK
added a commit
that referenced
this pull request
Mar 30, 2026
## Summary Fix genuine documentation gaps not covered by the auto-generation infrastructure in #569, and eliminate the CLI → GitHub → CLI roundtrip for skill file installation. ## Documentation fixes - **Add `SENTRY_AUTH_TOKEN` and `SENTRY_TOKEN` to `configuration.md`** — primary CI/CD auth variables were missing from the env vars reference - **Add `SENTRY_INSTALL_DIR` and `SENTRY_NO_CACHE` to `configuration.md`** — undocumented env vars - **Add `project:admin` to OAuth scopes** in `DEVELOPMENT.md` and `self-hosted.md` — code requests 8 scopes but docs listed only 7; self-hosted users creating API tokens with the documented scopes would get permission errors - **Expand README commands table** from 6 to 14 entries - **Add missing examples** for `auth logout`, `auth refresh`, `auth token`, `project create`, `project delete`, `cli setup` - **Fix `config.db` → `cli.db`** in auth credential storage docs - **Fix `SENTRY_AUTH_TOKEN` priority label** — was incorrectly marked "legacy"; it is the primary env var - **Align curl install flags** (`-fsS`) between README and docs site ## Embed skill files at build time Previously, `sentry cli setup` fetched skill files from GitHub at runtime — fetching content that was generated from the CLI's own source code. This was a roundtrip: the CLI generates skill files from Stricli introspection, they live in the repo, and then the CLI fetches them back from GitHub by URL, using a hardcoded `REFERENCE_FILES` array that required codegen to keep in sync. Now: - `generate-skill.ts` produces `src/generated/skill-content.ts` that inlines all skill file contents (~47KB) as a `Map<string, string>` - `agent-skills.ts` imports the embedded content and writes it directly to `~/.claude/skills/` — no network fetch, no URL construction, no version-pinning logic - `REFERENCE_FILES` array, `getSkillUrl()`, `fetchSingleFile()`, `fetchAllSkillFiles()`, `fetchSkillContent()` — all removed - `generate:skill` is chained before `build`/`dev`/`typecheck`/`test` in `package.json` (like `generate:sdk`) - `check-skill.ts` verifies `skill-content.ts` stays in sync with generated markdown files Co-authored-by: Burak Yigit Kaya <byk@sentry.io>
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
3 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.
Summary
New pages:
trace.md,span.md,sourcemap.md,repo.md,trial.md,schema.mdAll content derived from source code
docsfields and flag definitions. Format matches existing pages (event.md, log.md, etc.).Audit findings:
Test plan
cd docs && bun run buildsentry <command> --help🤖 Generated with Claude Code