Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual

# Tracking: expand `adk.dev/integrations/bigquery-agent-analytics/` into a full user manual

## Context

The integration page already exists at [`docs/integrations/bigquery-agent-analytics.md`](https://github.com/google/adk-docs/blob/main/docs/integrations/bigquery-agent-analytics.md) (≈59 KB, with `catalog_title: BigQuery Agent Analytics Plugin`, `catalog_tags: [observability, google]`). It currently scopes to the plugin itself — installing it, writing rows to `agent_events`, and the auto-schema-upgrade / tool-provenance / HITL features that ship with ADK Python ≥ 1.26.0.

What it does **not** yet cover is the consumption-layer surface that the blogpost will lean on:

- The scheduled context-graph materializer (currently [`examples/migration_v5/periodic_materialization/`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/migration_v5/periodic_materialization) in the SDK repo — about to be renamed; see SDK companion issue #282).
- The Cloud Run Job + Cloud Scheduler deployment pattern with the structured JSON log shape and Cloud Monitoring alerts.
- The context-graph concept doc (after the SDK-side consolidation into a single canonical `docs/context_graph.md` lands).
- The pluggable ontology pipeline (MAKO as load-bearing reference + the "drop in your own TTL" path).

This issue is the planning umbrella for promoting that consumption-layer content into the public adk-docs page so the blogpost can link to a single user-facing manual instead of pointing readers at the SDK repo's `examples/` tree.

## Coordination with the SDK cleanup (#282)

The SDK repo is being renamed and consolidated in companion issue [GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK#282](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/282). Specifically:

- `examples/migration_v5/` → `examples/context_graph_demo/` (Wave 3 of #282)
- `docs/context_graph_v{2,3}_design.md` → consolidated `docs/context_graph.md` + `docs/context_graph_design.md` (Wave 2 of #282)
- README rewrite for blogpost narrative (Wave 5 of #282)

**This adk-docs work should land *after* Wave 3 of #282 is merged** so the deep links on `adk.dev/integrations/bigquery-agent-analytics/` are stable from day one. Linking the published page at `examples/migration_v5/...` would break the day the SDK rename merges.

Earlier prep work (page outline, asset migration, mkdocs nav) can happen in parallel; only the cross-repo links should wait.

## Page-architecture decision (needs an answer first)

Two options for how the new content lands on the page. Pick before writing prose.

### Option A — single-page expansion (recommended for blogpost cadence)

Keep `docs/integrations/bigquery-agent-analytics.md` as one big page; append new top-level `##` sections for the consumption-layer content. Pros: one URL, one deep-link target, simplest to ship for a blogpost; matches the integration-page-per-tool convention the rest of `docs/integrations/` follows. Cons: page becomes ~120–150 KB; navigation inside the page relies on the right-side TOC.

### Option B — split into a sub-section (more like a real manual)

Convert the integration page into a section index that links into `docs/integrations/bigquery-agent-analytics/` (a sub-directory). One file per concern: `quickstart.md`, `configuration.md`, `periodic-materialization.md`, `context-graph.md`, `troubleshooting.md`. Pros: proper user-manual navigation. Cons: requires mkdocs nav restructuring, changes the existing canonical URL, breaks existing inbound links.

### Recommendation

**Option A.** The existing URL is already widely linked from the SDK repo (and is the URL the user wants in the blogpost). One large page with clear `##` anchors and the right-side mkdocs TOC is the lowest-risk path to ship before the blogpost. If page weight becomes a problem later, the split to Option B can happen as a follow-up without breaking the canonical URL (top-level page becomes an index that links to the per-concern children).

## Content scope — sections to add to the existing page

The existing page already covers (per the catalog frontmatter and the first ~2 KB I can see): the plugin itself, ADK version requirements, BigQuery Storage Write API, auto-schema-upgrade, tool-provenance tracking, HITL event tracing. v2 of the page should keep all of that and **append** these sections (proposed `##` anchors in order):

1. **`## What you can do with `agent_events`** — orient the reader. Tie the analytics columns to the questions they answer: token cost, tool fan-out, HITL frequency, A2A interactions, agent-team transfers. (Sourced from `SDK.md` and `README.md` after #282 Wave 5.)
2. **`## The context graph`** — concept doc. What it is, why it's separate from the row-level events, the ontology → binding → property-graph pipeline. (Sourced from consolidated `docs/context_graph.md` after #282 Wave 2.)
3. **`## Schedule it with Cloud Run + Cloud Scheduler` (the periodic materializer)** — the meat of the user manual. Sourced from `examples/context_graph_demo/periodic_materialization/README.md` (post-rename). The 9-step customer playbook from that README is the spine. Required content:
- Prerequisites (APIs, IAM)
- Datasets (events vs. graph)
- Local dry-run
- Recommended schedules
- Deploy with `--smoke`
- Expected JSON log shape
- Cloud Monitoring alerts on `ok=false`
- Inspecting results via the state-table audit log
- Troubleshooting / failure-mode surface
- Cleanup and redeploy
4. **`## Plug your own ontology in`** — the pluggable contract from `examples/context_graph_demo/README.md`. Walks through `OntologyConfig`, the three OWL-TTL normalizations, the four generated artifacts (`ontology.yaml` / `binding.yaml` / `table_ddl.sql` / `property_graph.sql`).
5. **`## Querying the property graph`** — sample SQL questions, with the MAKO ontology as the reference example.
6. **`## Where to file feedback / issues`** — links to the SDK repo issues, the public schema migration guide.

## Assets

The SDK repo has `docs/blog/images/context-graph-flow.png` and `docs/codelabs/images/context-graph-flow.png` (the same image in two places). Copy one into `docs/integrations/assets/bigquery-agent-analytics/context-graph-flow.png` and reference it from the new "The context graph" section.

The existing `docs/integrations/assets/bigquery.png` stays as the catalog icon (already referenced from the frontmatter as `/integrations/assets/bigquery.png`).

If the periodic-materialization "Production shape" ASCII diagram from the SDK README reads cleanly enough, keep it as a code block — no asset migration needed for that one.

## mkdocs and nav

- Page is already in `mkdocs.yml` nav (file exists, page is published). No nav change needed for Option A.
- `lychee.toml` link-check runs in CI; the new external links into the SDK repo will be checked. Ensure they're stable post-#282-rename **before** this PR merges (gated on #282 Wave 3).
- `netlify.toml` controls preview deploys; the PR will get a preview URL automatically.

## Source-of-truth + sync strategy

The content for the new sections lives in the SDK repo today. Three options for keeping the adk-docs page in sync as the SDK evolves:

| Strategy | Maintenance | Sync cadence | Verdict |
|---|---|---|---|
| Manual copy on each SDK release | Heavy | Per-release | Predictable but lossy; the doc rots between releases. |
| One-time copy + cross-repo link to the SDK README for deep dive | Light | Once | Recommended for the first cut. The adk-docs page covers the **stable user-facing surface** (concept, periodic-materialization recipe, ontology contract); the SDK README continues to be the **authoritative reference**. |
| Automated mirror (CI job that opens a sync PR into adk-docs) | Medium | Continuous | Worth investigating after the first cut ships; over-engineered for v2. |

**Recommended: one-time copy + clear "for the latest reference, see the SDK repo" pointers in each section.** Revisit after we see how often the content drifts in practice.

## Pull-request workflow

`google/adk-docs` is a Google-owned public repo; PRs go through Google's normal review. Two practical considerations:

- The PR should fit in a single reviewable chunk. Estimated diff: ~60 KB added to one file + one asset. That's at the upper bound of what a single reviewer wants to read; consider posting a section-by-section preview PR for sign-off first, then submitting the full version.
- Title format: existing adk-docs PRs use `docs: ...` prefix.
- The `CONTRIBUTING.md` in adk-docs lists the conventions (heading style, frontmatter, code-block languages).

## Plan — proposed wave order

| Wave | Scope | Repo | Depends on |
|---|---|---|---|
| 1 | Page outline + assets prep (copy `context-graph-flow.png` into `docs/integrations/assets/bigquery-agent-analytics/`); draft new sections in a local fork against the existing page. | adk-docs (draft) | — |
| 2 | Wait for SDK rename (`examples/migration_v5/` → `examples/context_graph_demo/`) to land. | — | #282 Wave 3 |
| 3 | Source-content extraction: pull the periodic-materialization README + consolidated context-graph concept doc into the draft. | adk-docs (draft) | #282 Wave 2 + Wave 3 |
| 4 | Cross-link audit: every link from the new page into the SDK repo points at the post-rename path. Run `lychee` locally. | adk-docs (draft) | Wave 3 |
| 5 | Section-by-section preview PR (or thread) for sign-off from the adk-docs maintainers. | adk-docs | Wave 4 |
| 6 | Full PR: page diff + asset. Address review feedback. | adk-docs | Wave 5 |
| 7 | Land. Verify preview, then merge. Add a follow-up issue in the SDK repo to keep the README "for the published user manual, see adk.dev/integrations/bigquery-agent-analytics/" pointer up to date. | adk-docs + SDK repo | Wave 6 |

## Acceptance

- `docs/integrations/bigquery-agent-analytics.md` covers, in order: plugin install + config, what `agent_events` answers, the context graph concept, the periodic-materialization recipe end-to-end, the pluggable ontology contract, sample queries, where to file feedback.
- A reader who lands on the page from the blogpost can deploy the periodic materializer against their own project without leaving the page.
- All deep links from the page into the SDK repo resolve under the post-rename paths (`examples/context_graph_demo/...`).
- `lychee` link-check passes in CI.
- The SDK repo's `README.md` (post #282 Wave 5) links to the published user manual.
- One asset (`context-graph-flow.png`) is committed under `docs/integrations/assets/bigquery-agent-analytics/`.

## Open questions for the team

1. **Page architecture** — confirm Option A (one big page) vs. Option B (sub-directory of per-concern pages). Recommended Option A.
2. **Section order** — does putting "periodic materialization" (the operational recipe) before "querying the property graph" (the conceptual payoff) match how operators read this, or should the order flip?
3. **Code-sample policy** — adk-docs renders Python with `=== "Python"` tabbed code blocks in some integrations. Match that style or use plain `python` fences?
4. **Blogpost timing** — what is the publish date the page needs to be live by? That sets how far in advance #282 Wave 3 has to merge.
5. **Sync ownership** — who in the team owns the periodic sync after v2 ships? Default: the same person who owns the SDK repo README.

## References

- Existing page: [`docs/integrations/bigquery-agent-analytics.md`](https://github.com/google/adk-docs/blob/main/docs/integrations/bigquery-agent-analytics.md) (~59 KB).
- Source content for the new "Schedule it..." section: [`examples/migration_v5/periodic_materialization/README.md`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/migration_v5/periodic_materialization/README.md) (to be `examples/context_graph_demo/periodic_materialization/README.md` post-rename).
- Companion SDK cleanup tracker: GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK#282.
- adk-docs contribution conventions: [`CONTRIBUTING.md`](https://github.com/google/adk-docs/blob/main/CONTRIBUTING.md).