ci(docs): Add agentic workflows for codebase documentation

.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.md

@@ -0,0 +1,146 @@
+---
+name: docs-codebase-refresh
+description: Full refresh of SDK codebase documentation on merge or manual trigger
+on:
+  push:
+    branches: [main, master]
+  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.