ci(docs): Add agentic workflows for codebase documentation (#5649)

## Summary

- Add two GitHub Agentic Workflows (`gh aw`) that auto-generate and
maintain developer-facing codebase documentation in `docs/codebase/`
- **`docs-codebase-refresh`**: full regeneration of every doc page,
triggered on merge to main/master or manual dispatch
- **`docs-codebase-update`**: incremental update of only affected pages,
triggered on merge when `sentry_sdk/**`, `MIGRATION_GUIDE.md`, or
`CHANGELOG.md` change
- Both workflows create PRs (never direct commits) for human review
- Includes a portable `BUILD_PLAN.md` designed for reuse across other
Sentry SDKs -- only the SDK Context block changes per language (will
remove later)

### How This Relates to Other Sentry Docs

- **[docs.sentry.io/platforms/\*](https://docs.sentry.io/)** tells users
*what to do* -- setup guides, config options, API usage.
- **[develop.sentry.dev/sdk/](https://develop.sentry.dev/sdk/)** tells
SDK authors *what to build* -- protocol spec, envelope format, required
behaviors.
- **API reference** (Sphinx, TypeDoc, Javadoc, etc.) tells developers
*what the API surface looks like* -- auto-generated from
docstrings/annotations. Lists signatures, parameters, return types.
- **`docs/codebase/*`** (this) explains *what was built and how it
works* -- architecture, data flow, how modules connect, and why.
Generated from full source analysis, not just docstrings. Aimed at SDK
contributors and maintainers.

### Files added

| File | Purpose |
|------|---------|
| `docs/codebase/BUILD_PLAN.md` | Portable blueprint with porting
checklist |
| `docs/codebase/_meta/style-guide.md` | SDK-agnostic formatting rules
and page templates |
| `docs/codebase/_meta/manifest.json` | Empty manifest (populated by
first workflow run) |
| `.github/workflows/docs-codebase-refresh.md` | Full refresh workflow
source |
| `.github/workflows/docs-codebase-update.md` | Incremental update
workflow source |
| `.github/workflows/docs-codebase-*.lock.yml` | Compiled Actions
workflows |
| `.gitattributes` | Marks `docs/codebase/**` as `linguist-generated` |

## Test plan

- [x] `gh aw compile` produces 0 errors, 0 warnings for both workflows
- [ ] Manual trigger via `gh aw run docs-codebase-refresh` generates
initial docs
- [ ] Verify generated pages cover all integrations in `_MIN_VERSIONS`
- [ ] Push a source change to main, verify incremental workflow updates
only affected pages
- [ ] Both workflows create PRs (not direct commits)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: dingsdax

.gitattributes

@@ -0,0 +1,4 @@
+# Auto-generated codebase documentation
+docs/codebase/** linguist-generated=true
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/aw/actions-lock.json

@@ -0,0 +1,14 @@
+{
+  "entries": {
+    "actions/github-script@v8": {
+      "repo": "actions/github-script",
+      "version": "v8",
+      "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
+    },
+    "github/gh-aw/actions/setup@v0.57.2": {
+      "repo": "github/gh-aw/actions/setup",
+      "version": "v0.57.2",
+      "sha": "32b3a711a9ee97d38e3989c90af0385aff0066a7"
+    }
+  }
+}

.github/workflows/docs-codebase-refresh.lock.yml

@@ -0,0 +1,144 @@
+---
+name: docs-codebase-refresh
+description: Full refresh of SDK codebase documentation (manual trigger only)
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+  pull-requests: read
+network: defaults
+safe-outputs:
+  create-pull-request:
+  add-labels:
+---
+
+# Full Codebase Documentation Refresh
+
+You are a documentation agent for the Sentry Python SDK. Your job is to
+generate comprehensive, accurate codebase-style documentation for every module
+and integration in the SDK.
+
+## SDK Context
+
+- Language: Python
+- Package: `sentry_sdk`
+- Integration location: `sentry_sdk/integrations/`
+- Test location: `tests/integrations/`
+- Integration registry: `sentry_sdk/integrations/__init__.py` (`_MIN_VERSIONS` dict)
+- Auto-enabling list: `sentry_sdk/integrations/__init__.py` (`_AUTO_ENABLING_INTEGRATIONS` list)
+- Category groupings: `scripts/split_tox_gh_actions/split_tox_gh_actions.py` (`GROUPS` dict)
+- Core modules: `sentry_sdk/client.py`, `sentry_sdk/scope.py`, `sentry_sdk/tracing.py`, `sentry_sdk/transport.py`
+- Public API: `sentry_sdk/api.py` (`__all__` list)
+- Configuration options: `sentry_sdk/consts.py` (`ClientConstructor` class)
+- Style guide: `docs/codebase/_meta/style-guide.md`
+- Manifest: `docs/codebase/_meta/manifest.json`
+
+## Instructions
+
+### Step 1: Discover All Sources
+
+1. Read `sentry_sdk/integrations/__init__.py` to extract `_MIN_VERSIONS` and
+   `_AUTO_ENABLING_INTEGRATIONS`.
+2. Read `scripts/split_tox_gh_actions/split_tox_gh_actions.py` to extract the
+   `GROUPS` dict for integration categorization.
+3. Read `sentry_sdk/consts.py` to extract all configuration options from the
+   `ClientConstructor` class.
+4. Read `sentry_sdk/api.py` to extract the public API surface from `__all__`.
+5. Enumerate all Python files in `sentry_sdk/` (excluding `__pycache__`) to
+   build a complete module map.
+
+### Step 2: Read the Style Guide
+
+Read `docs/codebase/_meta/style-guide.md` and follow all formatting rules exactly.
+
+### Step 3: Generate Core Pages
+
+Generate these pages by reading the corresponding source files:
+
+| Page | Primary Sources |
+|------|----------------|
+| `docs/codebase/overview.md` | `sentry_sdk/api.py`, `sentry_sdk/__init__.py`, `sentry_sdk/consts.py` |
+| `docs/codebase/architecture.md` | `sentry_sdk/client.py`, `sentry_sdk/scope.py`, `sentry_sdk/transport.py`, `sentry_sdk/tracing.py` |
+| `docs/codebase/core/client.md` | `sentry_sdk/client.py` |
+| `docs/codebase/core/scope.md` | `sentry_sdk/scope.py` |
+| `docs/codebase/core/transport.md` | `sentry_sdk/transport.py` |
+| `docs/codebase/core/tracing.md` | `sentry_sdk/tracing.py`, `sentry_sdk/tracing_utils.py` |
+| `docs/codebase/core/data-model.md` | `sentry_sdk/utils.py`, `sentry_sdk/envelope.py`, `sentry_sdk/attachments.py` |
+| `docs/codebase/core/configuration.md` | `sentry_sdk/consts.py` |
+
+### Step 4: Generate Telemetry Pages
+
+| Page | Primary Sources |
+|------|----------------|
+| `docs/codebase/telemetry/errors.md` | `sentry_sdk/client.py` (capture_event, capture_exception) |
+| `docs/codebase/telemetry/spans-and-traces.md` | `sentry_sdk/tracing.py`, `sentry_sdk/tracing_utils.py` |
+| `docs/codebase/telemetry/logs.md` | `sentry_sdk/logger.py` |
+| `docs/codebase/telemetry/profiling.md` | `sentry_sdk/profiler/` |
+| `docs/codebase/telemetry/sessions.md` | `sentry_sdk/sessions.py` |
+| `docs/codebase/telemetry/crons.md` | `sentry_sdk/crons/` |
+
+### Step 5: Generate Integration Pages
+
+For each integration in `_MIN_VERSIONS`:
+
+1. Map it to a category using `GROUPS`.
+2. Determine the subdirectory using the style guide's category mapping table.
+3. Read all Python files in `sentry_sdk/integrations/<name>/` (or the single
+   `<name>.py` file).
+4. Read the corresponding test files in `tests/integrations/<name>/` for
+   additional context on behavior.
+5. Generate the page following the integration page template from the style
+   guide.
+
+Also generate `docs/codebase/integrations/_index.md` describing the integration
+system: how integrations are discovered, auto-enabled, and configured.
+
+### Step 6: Generate Supplementary Pages
+
+- `docs/codebase/faq.md` -- Common questions derived from the codebase structure.
+- `docs/codebase/changelog-summary.md` -- High-level summary from `CHANGELOG.md`.
+
+### Step 7: Update Manifest
+
+After generating all pages, update `docs/codebase/_meta/manifest.json` with:
+
+```json
+{
+  "version": 1,
+  "sdk": "python",
+  "generated_at": "<current ISO timestamp>",
+  "pages": {
+    "<relative path from docs/codebase/>": {
+      "title": "<page title>",
+      "sources": ["<source file paths>"],
+      "sources_hash": "<SHA-256 of concatenated source contents>",
+      "last_updated": "<current ISO date>"
+    }
+  }
+}
+```
+
+### Step 8: Validate
+
+Before creating a PR, verify:
+
+- [ ] Every integration in `_MIN_VERSIONS` has a corresponding doc page.
+- [ ] All pages have valid YAML front-matter with all required fields.
+- [ ] All pages contain every required section from the style guide.
+- [ ] Source citations `[S#:L##]` reference valid files and approximate line numbers.
+- [ ] The manifest lists every generated page.
+- [ ] No placeholder or TODO text remains in any page.
+
+### Step 9: Create PR
+
+If any pages were created or changed compared to the existing `docs/codebase/`:
+
+1. Create a branch named `docs/codebase-refresh-<date>`.
+2. Commit all changes under `docs/codebase/`.
+3. Open a PR with:
+   - Title: `docs(codebase): full refresh <date>`
+   - Body: Summary of pages generated/updated, count of integrations covered,
+     and any integrations that could not be documented (with reasons).
+   - Label: `documentation`
+
+If no changes are needed (all pages are up-to-date), do not create a PR.