docs: add migration v5 periodic materialization notes (#170)

Author: caohy1988

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Migration v5 periodic materialization playbook** in
+  [`examples/migration_v5/periodic_materialization/README.md`](examples/migration_v5/periodic_materialization/README.md)
+  (PR [#168](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/168)).
+  Documents the customer path for keeping the MAKO graph fresh on
+  a schedule: local dry-run via `run_job.py`, Cloud Run Job +
+  Cloud Scheduler deployment with `--smoke`, required APIs and
+  IAM, recommended schedules, Cloud Logging JSON report shape,
+  Cloud Monitoring alerts, state-table inspection, teardown, and
+  troubleshooting. Complements the migration v5 four-guarantee
+  notebook by covering the production cron path.
+
 ## [0.3.0] - 2026-05-15
 
 ### Release highlights

docs/README.md

@@ -61,6 +61,7 @@ architecture, rationale, and implementation plans behind key SDK features.
 
 | Document | Description |
 |----------|-------------|
+| [Migration v5 periodic materialization playbook](../examples/migration_v5/periodic_materialization/README.md) | Customer deployment path for keeping the MAKO migration v5 graph fresh on a schedule: local dry-run, Cloud Run Job + Cloud Scheduler deploy with `--smoke`, IAM matrix, schedule guidance, JSON log shape, Cloud Monitoring alert filters, state-table inspection, cleanup, and troubleshooting. |
 | [proposal_bigquery_agent_cli.md](proposal_bigquery_agent_cli.md) | CLI proposal and command design |
 | [python_udf_support_design.md](python_udf_support_design.md) | BigQuery Python UDF architecture |
 | [remote_function_rationale.md](remote_function_rationale.md) | Cloud Run remote function rationale |

examples/migration_v5/README.md

@@ -195,10 +195,6 @@ The flow customers actually follow:
 
 See **[`periodic_materialization/README.md`](./periodic_materialization/README.md)** for the full customer playbook: required APIs, IAM matrix, recommended schedules per latency target, Cloud Monitoring alert queries, state-table SQL, troubleshooting, and live-deployment evidence captured against the canonical test project.
 
-## What's NOT in this commit
-
-- `docs/README.md` / `CHANGELOG.md` entries — staged for a follow-up PR alongside the user-facing release notes.
-
 ## Related
 
 - [#107 storyboard](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/107) — per-cell plan the notebook implements.