feat(docs): auto-generate driftable documentation sections

Eliminate documentation drift by generating content from source code:

- configuration.md: env var reference generated from new centralized
  registry (src/lib/env-registry.ts) using the fragment pattern.
  Adds 6 previously undocumented env vars (SENTRY_FORCE_ENV_TOKEN,
  SENTRY_OUTPUT_FORMAT, SENTRY_MAX_PAGINATION_PAGES, SENTRY_INIT,
  SENTRY_CLI_NO_AUTO_REPAIR, FORCE_COLOR).

- contributing.md: project structure tree generated from Stricli
  route tree (was listing 5 command dirs, now correctly shows 15+).

- DEVELOPMENT.md & self-hosted.md: OAuth scopes generated from
  exported OAUTH_SCOPES array in oauth.ts (fixes missing team:write).

- README.md: remove driftable commands table, point to docs site.

New infrastructure:
- src/lib/env-registry.ts: centralized env var metadata catalog
- script/generate-docs-sections.ts: marker-based injection for
  committed files (GENERATED:START/END named markers)
- generate-command-docs.ts extended to produce configuration.md
- CI check:docs-sections validates markers aren't stale

Author: BYK

.github/workflows/ci.yml

@@ -43,8 +43,11 @@ jobs:
               - 'src/**'
               - 'docs/**'
               - 'package.json'
+              - 'README.md'
+              - 'DEVELOPMENT.md'
               - 'script/generate-skill.ts'
               - 'script/generate-command-docs.ts'
+              - 'script/generate-docs-sections.ts'
               - 'script/eval-skill.ts'
               - 'test/skill-eval/**'
             code:
@@ -130,17 +133,26 @@ jobs:
             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'
+      - name: Check docs sections
+        id: check-sections
+        run: |
+          if git diff --quiet DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md; then
+            echo "Docs sections are up to date"
+          else
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            echo "Docs sections are out of date"
+          fi
+      - name: Auto-commit regenerated files
+        if: (steps.check-skill.outputs.stale == 'true' || steps.check-sections.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/
-          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'
+          git add plugins/sentry-cli/skills/sentry-cli/ DEVELOPMENT.md docs/src/content/docs/contributing.md docs/src/content/docs/self-hosted.md
+          git diff --cached --quiet || (git commit -m "chore: regenerate docs" && git push)
+      - name: Fail for fork PRs with stale generated files
+        if: (steps.check-skill.outputs.stale == 'true' || steps.check-sections.outputs.stale == 'true') && steps.token.outcome != 'success'
         run: |
-          echo "::error::Skill files are out of date. Run 'bun run generate:docs' locally and commit the result."
+          echo "::error::Generated files are out of date. Run 'bun run generate:docs' locally and commit the result."
           exit 1
 
   lint:

.gitignore

@@ -58,8 +58,9 @@ src/generated/
 src/sdk.generated.ts
 src/sdk.generated.d.cts
 
-# Generated command docs (rebuilt from fragments + CLI introspection)
+# Generated docs pages (rebuilt from fragments + CLI introspection / env registry)
 docs/src/content/docs/commands/
+docs/src/content/docs/configuration.md
 
 # Generated discovery manifest (rebuilt by generate:skill, served via symlinked skill files)
 docs/public/.well-known/skills/index.json

AGENTS.md

@@ -1053,8 +1053,11 @@ mock.module("./some-module", () => ({
 
 ### Pattern
 
+<!-- lore:019d86a1-f6f1-758e-accf-7300b82e0163 -->
+* **Bun global installs use .bun path segment for detection**: Bun global package installs place scripts under \`~/.bun/install/global/node\_modules/\`. The \`.bun\` directory in the path distinguishes bun from npm/yarn installs. In \`detectPackageManagerFromPath()\`, check \`segments.includes('.bun')\` before the npm fallback. Detection order: \`.pnpm\` → pnpm, \`.bun\` → bun, other \`node\_modules\` → npm. Yarn classic uses same flat layout as npm so falls through to npm detection — this is acceptable because path-based detection is a \*\*fallback\*\* after subprocess calls (which correctly identify yarn). Path detection must NOT be authoritative/override stored DB info, only serve as fallback when subprocess detection fails (e.g., Windows where .cmd files cause ENOENT).
+
 <!-- lore:d441d9e5-3638-4b5a-8148-f88c349b8979 -->
-* **Non-essential DB cache writes should be guarded with try-catch**: Non-essential DB cache writes (e.g., \`setUserInfo()\`) must be wrapped in try-catch so a broken DB doesn't crash a command whose primary operation succeeded. In login.ts, \`getCurrentUser()\` failure after token save must not block auth — log warning, continue. Exception: \`getUserRegions()\` failure should \`clearAuth()\` and fail hard (indicates invalid token).
+* **Non-essential DB cache writes should be guarded with try-catch**: Non-essential DB cache writes (e.g., \`setUserInfo()\`, \`setInstallInfo()\`) must be wrapped in try-catch so a broken/read-only DB doesn't crash a command whose primary operation succeeded. Pattern: \`try { setInstallInfo(...) } catch { log.debug(...) }\`. In login.ts, \`getCurrentUser()\` failure after token save must not block auth — log warning, continue. In upgrade.ts, \`setInstallInfo\` after legacy detection is guarded same way. Exception: \`getUserRegions()\` failure should \`clearAuth()\` and fail hard (indicates invalid token). This is enforced by BugBot reviews — any \`setInstallInfo\`/\`setUserInfo\` call outside setup.ts's \`bestEffort()\` wrapper needs its own try-catch.
 
 <!-- lore:019d2c91-bc3d-7be6-ac74-ce926182526d -->
 * **Sentry CLI command docs are auto-generated from Stricli route tree with CI freshness check**: Sentry CLI command docs are auto-generated from Stricli route tree: Docs in \`docs/src/content/docs/commands/\*.md\` and skill files in \`plugins/sentry-cli/skills/sentry-cli/references/\*.md\` are generated via \`bun run generate:docs\`. Content between \`\<!-- GENERATED:START/END -->\` markers is regenerated; hand-written examples go in \`docs/src/fragments/commands/\`. CI checks \`check:command-docs\` and \`check:skill\` fail if stale. Run generators after changing command parameters/flags/docs.

DEVELOPMENT.md

@@ -59,11 +59,13 @@ When creating your Sentry OAuth application:
 
 - **Redirect URI**: Not required for device flow
 - **Scopes**: The CLI requests these scopes:
+<!-- GENERATED:START oauth-scopes -->
   - `project:read`, `project:write`, `project:admin`
   - `org:read`
   - `event:read`, `event:write`
   - `member:read`
-  - `team:read`
+  - `team:read`, `team:write`
+<!-- GENERATED:END oauth-scopes -->
 
 ## Environment Variables
 

README.md

@@ -68,24 +68,7 @@ sentry issue plan PROJ-ABC
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `sentry auth` | Login, logout, check authentication status |
-| `sentry org` | List and view organizations |
-| `sentry project` | List, view, create, and delete projects |
-| `sentry issue` | List, view, explain, and plan issues |
-| `sentry event` | View event details |
-| `sentry trace` | List and view distributed traces |
-| `sentry span` | List and view spans |
-| `sentry log` | List and view logs (with streaming) |
-| `sentry dashboard` | List, view, and create dashboards with widgets |
-| `sentry sourcemap` | Inject debug IDs and upload sourcemaps |
-| `sentry init` | Initialize Sentry in your project |
-| `sentry schema` | Browse the Sentry API schema |
-| `sentry api` | Make direct API requests |
-| `sentry cli` | Upgrade, setup, fix, and send feedback |
-
-For detailed documentation, visit [cli.sentry.dev](https://cli.sentry.dev).
+Run `sentry --help` to see all available commands, or browse the [command reference](https://cli.sentry.dev/commands/).
 
 ## Configuration