refactor(docs): gitignore generated command docs, extract fragments (#696)

## Summary

- Gitignore generated command docs (`docs/src/content/docs/commands/`) —
they're rebuilt at build time from CLI metadata + hand-written fragments
- Extract hand-written examples/guides into
`docs/src/fragments/commands/` (19 fragment files)
- Snap `PERIOD_BRIEF` example dates to 1st of month (~12 changes/year
instead of 365)
- Skill files (`plugins/sentry-cli/skills/sentry-cli/`) remain committed
for external plugin consumers, with slimmed CI auto-commit

## Motivation

Generated files with dynamic dates (`PERIOD_BRIEF` computed from `new
Date()`) caused daily churn in PRs via CI auto-commit. Command docs were
a mix of auto-generated flag tables and hand-written content, making
them impossible to gitignore without losing the custom parts.

## Changes

### Fragment extraction
- Split each command doc into: generated part (gitignored output) +
hand-written fragment (committed source)
- `generate-command-docs.ts` now reads custom content from
`docs/src/fragments/commands/{route}.md`
- New `check:fragments` script validates fragment ↔ route consistency

### Build pipeline
- New `generate:docs` composite script chains `generate:command-docs` →
`generate:skill`
- All dependent scripts (`dev`, `build`, `typecheck`, `test:*`) use
`generate:docs` instead of `generate:skill`
- CI `build-docs` and `docs-preview` jobs run generation before `astro
build`

### CI simplification
- `check-skill` job → `check-generated`: validates fragments,
auto-commits skill files only (not command docs)
- Deleted `generate-skill.yml` workflow (superseded by
`check-generated`)
- Deleted `check:skill` and `check:command-docs` scripts (replaced by
`check:fragments`)

Author: BYK

.github/workflows/ci.yml

@@ -42,8 +42,8 @@ jobs:
             skill:
               - 'src/**'
               - 'docs/**'
-              - 'plugins/**'
               - 'script/generate-skill.ts'
+              - 'script/generate-command-docs.ts'
               - 'script/eval-skill.ts'
               - 'test/skill-eval/**'
             code:
@@ -88,8 +88,8 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Nightly version: ${VERSION}"
 
-  check-skill:
-    name: Check skill files
+  check-generated:
+    name: Validate generated files
     needs: [changes]
     if: needs.changes.outputs.skill == 'true'
     runs-on: ubuntu-latest
@@ -116,25 +116,30 @@ jobs:
         run: bun install --frozen-lockfile
       - name: Generate API Schema
         run: bun run generate:schema
+      - name: Generate docs and skill files
+        run: bun run generate:docs
+      - name: Validate fragments
+        run: bun run check:fragments
       - name: Check skill files
         id: check-skill
-        run: bun run check:skill
-        continue-on-error: true
-      - name: Check command docs
-        id: check-docs
-        run: bun run check:command-docs
-        continue-on-error: true
-      - name: Auto-commit regenerated files
-        if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome == 'success'
+        run: |
+          if git diff --quiet plugins/sentry-cli/skills/sentry-cli/; then
+            echo "Skill files are up to date"
+          else
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            echo "Skill files are out of date"
+          fi
+      - name: Auto-commit regenerated skill files
+        if: steps.check-skill.outputs.stale == 'true' && steps.token.outcome == 'success'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json docs/src/content/docs/commands/
-          git diff --cached --quiet || (git commit -m "chore: regenerate skill files and command docs" && git push)
-      - name: Fail for fork PRs with stale generated files
-        if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome != 'success'
+          git add plugins/sentry-cli/skills/sentry-cli/
+          git diff --cached --quiet || (git commit -m "chore: regenerate skill files" && git push)
+      - name: Fail for fork PRs with stale skill files
+        if: steps.check-skill.outputs.stale == 'true' && steps.token.outcome != 'success'
         run: |
-          echo "::error::Generated files are out of date. Run 'bun run generate:skill' and 'bun run generate:command-docs' locally and commit the result."
+          echo "::error::Skill files are out of date. Run 'bun run generate:docs' locally and commit the result."
           exit 1
 
   eval-skill:
@@ -177,6 +182,9 @@ jobs:
           key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
       - if: steps.detect-fork.outputs.is_fork != 'true' && steps.cache.outputs.cache-hit != 'true'
         run: bun install --frozen-lockfile
+      - name: Generate docs and skill files
+        if: steps.detect-fork.outputs.is_fork != 'true'
+        run: bun run generate:schema && bun run generate:docs
       - name: Eval SKILL.md
         if: steps.detect-fork.outputs.is_fork != 'true'
         run: bun run eval:skill
@@ -659,6 +667,15 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
+      - uses: actions/cache@v5
+        id: cache
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
+      - if: steps.cache.outputs.cache-hit != 'true'
+        run: bun install --frozen-lockfile
+      - name: Generate docs content
+        run: bun run generate:schema && bun run generate:docs
       - name: Build Docs
         working-directory: docs
         run: |
@@ -677,15 +694,15 @@ jobs:
   ci-status:
     name: CI Status
     if: always()
-    needs: [changes, check-skill, eval-skill, build-binary, build-npm, build-docs, test-e2e, generate-patches, publish-nightly]
+    needs: [changes, check-generated, eval-skill, build-binary, build-npm, build-docs, test-e2e, generate-patches, publish-nightly]
     runs-on: ubuntu-latest
     permissions: {}
     steps:
       - name: Check CI status
         run: |
           # Check for explicit failures or cancellations in all jobs
           # generate-patches and publish-nightly are skipped on PRs — that's expected
-          results="${{ needs.check-skill.result }} ${{ needs.eval-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }} ${{ needs.publish-nightly.result }}"
+          results="${{ needs.check-generated.result }} ${{ needs.eval-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }} ${{ needs.publish-nightly.result }}"
           for result in $results; do
             if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
               echo "::error::CI failed"
@@ -699,8 +716,8 @@ jobs:
             echo "::error::CI failed - upstream job failed causing test-e2e to be skipped"
             exit 1
           fi
-          if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.check-skill.result }}" == "skipped" ]]; then
-            echo "::error::CI failed - upstream job failed causing check-skill to be skipped"
+          if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.check-generated.result }}" == "skipped" ]]; then
+            echo "::error::CI failed - upstream job failed causing check-generated to be skipped"
             exit 1
           fi
           if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.eval-skill.result }}" == "skipped" ]]; then

.github/workflows/docs-preview.yml

@@ -4,6 +4,9 @@ on:
   pull_request:
     paths:
       - 'docs/**'
+      - 'src/**'
+      - 'script/generate-command-docs.ts'
+      - 'script/generate-skill.ts'
       - '.github/workflows/docs-preview.yml'
 
 permissions:
@@ -18,6 +21,18 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
 
+      - uses: actions/cache@v5
+        id: cache
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
+
+      - if: steps.cache.outputs.cache-hit != 'true'
+        run: bun install --frozen-lockfile
+
+      - name: Generate docs content
+        run: bun run generate:schema && bun run generate:docs
+
       - name: Build Docs for Preview
         working-directory: docs
         env:

.github/workflows/generate-skill.yml

@@ -58,6 +58,12 @@ src/generated/
 src/sdk.generated.ts
 src/sdk.generated.d.cts
 
+# Generated command docs (rebuilt from fragments + CLI introspection)
+docs/src/content/docs/commands/
+
+# Generated discovery manifest (rebuilt by generate:skill, served via symlinked skill files)
+docs/public/.well-known/skills/index.json
+
 # OpenCode
 .opencode/
 opencode.json*

.gitignore

@@ -489,10 +489,14 @@ All normalize to lowercase. Throw `ValidationError` on invalid input.
 
 Use `"date"` for timestamp-based sort (not `"time"`). Export sort types from the API layer (e.g., `SpanSortValue` from `api/traces.ts`), import in commands. This matches `issue list`, `trace list`, and `span list`.
 
-### SKILL.md
+### Generated Docs & Skills
 
-- Run `bun run generate:skill` after changing any command parameters, flags, or docs.
-- CI check `bun run check:skill` will fail if SKILL.md is stale.
+All command docs and skill files are generated via `bun run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts.
+
+- **Command docs** (`docs/src/content/docs/commands/*.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `docs/src/fragments/commands/`.
+- **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale.
+- Edit fragments in `docs/src/fragments/commands/` for custom examples and guides.
+- `bun run check:fragments` validates fragment ↔ route consistency.
 - Positional `placeholder` values must be descriptive: `"org/project/trace-id"` not `"args"`.
 
 ### Zod Schemas for Validation
@@ -973,6 +977,7 @@ mock.module("./some-module", () => ({
 | Add E2E tests | `test/e2e/` |
 | Test helpers | `test/model-based/helpers.ts` |
 | Add documentation | `docs/src/content/docs/` |
+| Hand-written command doc content | `docs/src/fragments/commands/` |
 
 <!-- This section is maintained by the coding agent via lore (https://github.com/BYK/opencode-lore) -->
 ## Long-term Knowledge
@@ -1016,7 +1021,7 @@ mock.module("./some-module", () => ({
 * **Sentry trace-logs API is org-scoped, not project-scoped**: The Sentry trace-logs endpoint (\`/organizations/{org}/trace-logs/\`) is org-scoped, so \`trace logs\` uses \`resolveOrg()\` not \`resolveOrgAndProject()\`. The endpoint is PRIVATE in Sentry source, excluded from the public OpenAPI schema — \`@sentry/api\` has no generated types. The hand-written \`TraceLogSchema\` in \`src/types/sentry.ts\` is required until Sentry makes it public.
 
 <!-- lore:019d3ea5-fd4a-75b0-8dab-0b1f1cb96b0e -->
-* **SKILL.md is fully generated — edit source files, not output**: The skill files under \`plugins/sentry-cli/skills/sentry-cli/\` (SKILL.md + references/\*.md) are fully generated by \`bun run generate:skill\` (script/generate-skill.ts). CI runs this after every push via a \`github-actions\[bot]\` commit, overwriting any manual edits. To change skill content, edit the \*\*sources\*\*: (1) \`docs/src/content/docs/agent-guidance.md\` — embedded into SKILL.md's Agent Guidance section with heading levels bumped. (2) \`src/commands/\*/\` flag \`brief\` strings — generate the reference file flag descriptions. (3) \`docs/src/content/docs/commands/\*.md\` — examples extracted per command via marked AST parsing. After editing sources, run \`bun run generate:skill\` locally and commit both source and generated files. CI's \`bun run check:skill\` fails if generated files are stale.
+* **SKILL.md is fully generated — edit fragment files for custom content, not output**: The skill files under \`plugins/sentry-cli/skills/sentry-cli/\` (SKILL.md + references/\*.md) are fully generated by \`bun run generate:skill\` (script/generate-skill.ts). They are rebuilt automatically by \`bun run generate:docs\` which runs as part of \`dev\`, \`build\`, \`typecheck\`, and \`test\` scripts. To change skill content, edit the \*\*sources\*\*: (1) \`docs/src/content/docs/agent-guidance.md\` — embedded into SKILL.md's Agent Guidance section with heading levels bumped. (2) \`src/commands/\*/\` flag \`brief\` strings — generate the reference file flag descriptions. (3) \`docs/src/fragments/commands/\*.md\` — hand-written examples and guides appended to generated command docs. Command docs (\`docs/src/content/docs/commands/\*.md\`) are also gitignored and rebuilt from fragments + CLI metadata by \`generate:command-docs\`. \`bun run check:fragments\` validates fragment ↔ route consistency.
 
 <!-- lore:019d275c-7cf0-7e13-bdc8-10cbbdbda933 -->
 * **Stricli route errors are uninterceptable — only post-run detection works**: Stricli route errors, exit codes, and OutputError — error propagation gaps: (1) Route failures are uninterceptable — Stricli writes to stderr and returns \`ExitCode.UnknownCommand\` internally. Only post-\`run()\` \`process.exitCode\` check works. \`exceptionWhileRunningCommand\` only fires for errors in command \`func()\`. (2) \`ExitCode.UnknownCommand\` is \`-5\`. Bun reads \`251\` (unsigned byte), Node reads \`-5\` — compare both. (3) \`OutputError\` in \`handleOutputError\` calls \`process.exit()\` immediately, bypassing telemetry and \`exceptionWhileRunningCommand\`. Top-level typos via \`defaultCommand:help\` → \`OutputError\` → \`process.exit(1)\` skip all error reporting.