api-reference-audit

# ADK API reference doc auditor (api-ref-audit) This skill audits the API reference documentation in the [adk-docs](https://github.com/google/adk-docs) repository across every language SDK and reports what is out of date. It is a **reporting and guidance** skill: it detects drift, recommends the correct per-surface release process, and emits an executable plan only when the user explicitly asks. It does **not** edit files, run generators, or open PRs by default. The audit covers three kinds of drift: 1. **Generated API reference docs** under `docs/api-reference/` that lag behind the latest SDK release. 2. **Hardcoded version strings** in prose and examples (dependency coordinates, `pom.xml` versions) that must be bumped with each Java/Kotlin release. 3. **Code-sample drift** (light flagging only): samples that reference pinned versions or obviously deprecated APIs. Deep sample verification is out of scope of this skill. > [!IMPORTANT] > The maps below are **hints, not ground truth**. File layouts, script paths, > and team processes change. At each step, verify the path or marker exists and > re-derive it if a lookup fails, rather than trusting the table blindly. ## Version map (in-repo version vs. upstream truth) Each **surface** is one API reference output this repo ships: Python API, Python CLI, Python REST API, Python Agent Config, TypeScript, Go, Java, and Kotlin. For each surface, read the in-repo version from the file listed, then compare it against the latest upstream release and package registry. | Surface | In-repo version marker | Upstream repo | Package registry | | --- | --- | --- | --- | | Python API | `docs/api-reference/python/_static/documentation_options.js` (`VERSION:`) | `google/adk-python` | PyPI `google-adk` | | Python CLI | `docs/api-reference/cli/_static/documentation_options.js` (`VERSION:`) and `docs/api-reference/cli/index.html` ("ADK X.Y.Z") | `google/adk-python` | PyPI `google-adk` | | Python REST API | `docs/api-reference/rest/openapi.json` (`info.version`) | `google/adk-python` | PyPI `google-adk` | | Python Agent Config | no version marker; diff the type set in `agentconfig/index.html` against upstream `AgentConfig.json` | `google/adk-python` (same release as Python API/CLI/REST) | n/a | | TypeScript | `docs/api-reference/typescript/variables/version.html` (the `version` const); cross-check `docs/api-reference/typescript/index.html` (`<title>` "... - vX.Y.Z") | `google/adk-js` (monorepo; see note) | npm `@google/adk` (authoritative) | | Go | external, hosted on `pkg.go.dev`; verify links in `docs/api-reference/index.md` | `google/adk-go` | `pkg.go.dev` | | Java | `docs/api-reference/java/index.html` (`<title>` "Maven Parent POM X.Y.Z API") | `google/adk-java` (authoritative) | Maven Central `com.google.adk:google-adk` (lags; cross-check only) | | Kotlin | `docs/api-reference/kotlin/index.html` (version string near the header) | `google/adk-kotlin` (authoritative) | Maven Central `com.google.adk:google-adk-kotlin-core` (lags; cross-check only) | Notes: - Python API, CLI, and REST all track the **same** `adk-python` release, so they usually move together. Flag it when they diverge. - Python Agent Config has no version field. Parse the **keys of the `$defs` object** (plus top-level `oneOf` variants) from the upstream `AgentConfig.json` at the target tag, e.g. `jq '."$defs" | keys'`. Do not substring-grep for `*Config`: that mixes property names (camelCase, e.g. `imageConfig`) with type names (PascalCase, e.g. `ImageConfig`) and produces false drift. Check each `$defs` key as a whole word against `agentconfig/index.html`; a key present upstream but missing in the page (or vice versa) is drift. - TypeScript: use npm `@google/adk` `dist-tags.latest` as the authoritative version. adk-js is a monorepo with package-prefixed tags (e.g. `main-v1.4.0`, `integrations-v1.4.0`), so `gh ... releases/latest` can return a release for a different package instead of `@google/adk`. The in-repo `version` const tracks the same `@google/adk` package npm publishes and releases together with it, so compare the two directly: any version difference means the docs are behind. The generate script clones the `adk-v<version>` tag (the core `@google/adk` package tag). - Go docs are not built into this repo. Confirm the release version and that the `index.md` links point at the correct major versions (e.g. v2.x and v1.x). Go versions are also pinned in `examples/go/go.mod` / `go.sum` and appear as `/adk/v2` import paths in prose (e.g. `docs/events/index.md`, `docs/2.0/`), so check those too. ## Hardcoded version references These version-pinned strings are intentional and useful: they show developers the exact dependency versions to use. The audit's job is to keep them current, not remove them. They drift with each Java/Kotlin release and are bumped in a separate PR (see the process map). Discover current occurrences by grep; do not trust the file list alone, as new pages might appear over time. - **Grep targets**: - `com.google.adk:google-adk` and `com.google.adk:google-adk-kotlin` across `docs/**/*.md` - `<google-adk.version>` across `docs/**/*.md` and `examples/java/**/pom.xml` - bare `google-adk>=X.Y.Z` pins in integration pages (report only; these are minimum-version pins, not doc-version bumps) - **Known files that carry these (verify, do not assume complete)**: - `docs/get-started/installation.md` - `docs/get-started/java.md` - `docs/get-started/kotlin.md` - `docs/live/get-started/streaming-java.md` - `docs/deploy/cloud-run.md` - `docs/agents/models/litert-lm.md` - `docs/integrations/firestore-session-service.md` - `examples/java/**/pom.xml` - **Never flag or bump language support tags.** Versions that are inside of `language-support-tag` spans (e.g. `<span class="lst-python">Python v1.32.0</span>`) mark the release a feature was *introduced* in, not the latest published version. Leave them untouched; bumping them misrepresents when the feature became available. ## Per-surface process map (owner, tooling, steps) Treat each entry as a starting hint. Before recommending it, confirm the script still exists and inspect the most recent matching bump PR to confirm the current process. - **Python API**: self-serve. Run `bash tools/python-api-docs/generate.sh <version>`, then open a PR (the script injects the Google Analytics tag via Sphinx). - **Python CLI**: self-serve. Run `bash tools/python-cli-docs/generate.sh <version>`, then open a PR. The GA tag is injected via a Sphinx layout template in the script. - **Python REST API**: self-serve. Run `bash tools/python-rest-api-docs/generate.sh <version>`, then open a PR. GA tag is baked into the generated `index.html`. - **Python Agent Config**: regenerated from the adk-python schema with `json-schema-for-humans`; no `tools/` generate script exists yet, so treat the update as manual. - **TypeScript**: self-serve, one PR. Run `bash tools/typescript-api-docs/generate.sh <version>` (where `<version>` is the npm `@google/adk` version from the audit), then open a PR. The script clones the adk-js `adk-v<version>` tag, adds the version to the page title via TypeDoc's `--includeVersion`, and injects the Google Analytics tag into every HTML file (awk post-processing). - **Java**: self-serve. Run `bash tools/java-api-docs/generate.sh <version>` to regenerate the Javadoc assets under `docs/api-reference/java/` (the GA tag is auto-injected into every HTML file), and bump the hardcoded dependency versions and `pom.xml` values. These can ship as two separate PRs (`chore: update ADK Java doc to version <X>` for the Javadoc assets and `Update ADK Java dependency versions to <X>` for the dependency pins) or bundled together. - **Kotlin**: self-serve, one PR. Run `bash tools/kotlin-api-docs/generate.sh <version>`, then open a PR that bundles the generated assets and the hardcoded Kotlin refs (`installation.md`, `get-started/kotlin.md`, `litert-lm.md`). The GA tag is auto-injected into every HTML file. ### Verify the process - Confirm each referenced script exists under `tools/` before recommending it. - Inspect the last matching bump to confirm the real, current process and the files it touched, for example: - `gh pr list --repo google/adk-docs --state merged --search "Kotlin"` - `gh pr list --repo google/adk-docs --state merged --search "CLI reference"` - `gh pr list --repo google/adk-docs --state merged --search "Java"` - `gh pr list --repo google/adk-docs --state merged --search "TypeScript"` ## Audit workflow ### Step 1: Read in-repo versions For every surface in the version map, read the marker file and record the current version. Use `grep`/`Read` for the JS and HTML markers and parse `info.version` from `rest/openapi.json`. If a marker path does not resolve, re-derive it (search the generated output) and note the discrepancy. ### Step 2: Fetch upstream releases and registry versions For each SDK, get the latest release and the latest published package: - GitHub latest release and tags: - `gh api repos/google/adk-python/releases/latest --jq .tag_name` - Repeat for `adk-go`, `adk-kotlin`, `adk-java`. - For `adk-js`, do not use `releases/latest` (monorepo tags are package-prefixed, e.g. `main-v1.4.0`); use npm `@google/adk` as the source of truth. - Package registries: - PyPI: fetch `https://pypi.org/pypi/google-adk/json` and read `info.version`. - npm: fetch `https://registry.npmjs.org/@google/adk` and read `dist-tags.latest`. - Maven Central: query `https://search.maven.org/solrsearch/select?q=g:com.google.adk+AND+a:google-adk&rows=1&wt=json` and read `latestVersion` (use `a:google-adk-kotlin-core` for Kotlin). - **For Java and Kotlin, treat the GitHub release/tag as authoritative.** The Maven Central search index frequently lags real releases (it has returned versions older than what is already shipped in this repo). Use the registry only as a cross-check, and when it disagrees with the GitHub tag, trust the tag and note the lag. - Note when a GitHub tag and its registry version disagree (a release may be tagged but not yet published, or vice versa); report both. ### Step 3: Classify each surface Mark each surface as one of: - **Up to date**: in-repo version equals the latest upstream release. - **Behind**: in-repo version is older than the latest release (report the gap, e.g. `2.3.0 -> 2.4.1`). - **Unknown / manual**: upstream lookup failed, or a surface with no automatable check. Agent Config is not "unknown"; classify it via the type-set diff (Behind if types were added or removed upstream). Call out the common case where Python API, CLI, and REST should share the same `adk-python` version but do not. For Agent Config, run the type-set diff described in the version map Notes to decide Up to date vs. Behind. ### Step 4: Check hardcoded version references Grep the targets in "Hardcoded version references" and compare each pinned version to the latest Java and Kotlin releases. List every file and line that needs a bump. Keep minimum-version pins (`google-adk>=X.Y.Z`) separate; only flag them if they reference a version newer than what is released or are clearly stale. ### Step 5: Light code-sample drift flag Do a quick scan (not a deep audit): note samples with hardcoded model or package versions, obviously deprecated imports, or patterns superseded by a new release's changelog. Report these as hints and recommend a dedicated sample-audit pass for deep verification. Do not attempt to rewrite samples here. ### Step 6: Verify Go links Confirm `docs/api-reference/index.md` links point at the correct Go major versions on `pkg.go.dev` and that the latest `adk-go` release is represented. Also check the pinned versions in `examples/go/go.mod` / `go.sum` and the `/adk/v2` import paths in prose (e.g. `docs/events/index.md`, `docs/2.0/`). ## Report format Produce a Markdown report. Lead with a status table, then prioritized findings. Status table (one row per surface): | Surface | In-repo | Latest upstream | Status | Recommended action | | --- | --- | --- | --- | --- | Prioritized findings after the table. List only items that require action; do not emit "no action" or "confirmed correct" lines anywhere, including inside an otherwise-actionable finding. If a surface needs nothing, its table row already says so. - 🔴 **Out of date / broken**: a surface multiple releases behind, a broken/incorrect API-reference link, or version markers that disagree with each other (e.g. Python API/CLI/REST on different versions). - 🟠 **Stale hardcoded versions**: `file:line` list of dependency coordinates and `pom.xml` values to bump, with old -> new. - 🟡 **Sample-drift hints**: samples that likely need updating; recommend the deep sample-audit pass. For each stale surface, name the **recommended process** from the process map (self-serve script, wait on team, or manual) so the user knows how to proceed. After the report, **stop**. Do not modify files, run generators, or open PRs unless the user explicitly asks. ## Executable plan (only when asked) When the user asks you to proceed, output concrete next actions per stale surface: - The exact command to run, when self-serve, for example: - `bash tools/python-api-docs/generate.sh <new-version>` - `bash tools/python-cli-docs/generate.sh <new-version>` - `bash tools/python-rest-api-docs/generate.sh <new-version>` - `bash tools/java-api-docs/generate.sh <new-version>` - `bash tools/kotlin-api-docs/generate.sh <new-version>` - `bash tools/typescript-api-docs/generate.sh <new-version>` - For hardcoded versions, the precise `file:line` edits (old -> new), including `examples/java/**/pom.xml`. - Which surfaces move together (Python API, CLI, and REST share one `adk-python` version) so they ship as separate PRs, one per surface, bumped in the same sitting. - A PR description per stale surface, following the repo convention: - a short bullet summary of what changed - `Rendered page:` <preview link, where applicable> - upstream release link and version - A final note telling the user how to proceed: self-run the commands, wait on the owning team, or have the agent execute the plan. ### PR title conventions Match the established titles so history stays searchable: - Python API: `Update API reference docs for ADK Python <X.Y.Z>` - Python CLI: `Update CLI reference docs for ADK Python <X.Y.Z>` - Python REST API: `Update REST API reference docs for ADK Python <X.Y.Z>` - TypeScript: `Update API reference docs for ADK TypeScript <X.Y.Z>` - Java API: `chore: update ADK Java doc to version <X.Y.Z>` - Java dependency bump: `Update ADK Java dependency versions to <X.Y.Z>` - Kotlin: `Update ADK Kotlin to <X.Y.Z>` ## Style rules to bake in - Report versions precisely as `old -> new`; never guess a version you did not read from a marker or fetch from upstream. - Do not invent links; use only markers you read and releases you fetched. - No em dashes or verbose AI-generated content. - The canonical source repositories are listed in `docs/community/contributing-guide.md`.