docs(deploy): document --property-graph schema-derived deploy mode (issue #286, PR 5) (#292)

Docs closeout for the scheduled-deploy parity. The bash deploy and Terraform
both now support schema-derived mode (#289-#291); document it as the simple
rename-free production path, with the explicit ontology/binding (migration-v5
compiled) path as the advanced override.

- Deployment README: new 'Schema-derived deploy (--property-graph)' section
  after the deploy command -- one-artifact flow (point --property-graph at a
  placeholdered property_graph.sql with a sibling table_ddl.sql), the
  placeholder + no-compiled-only requirements, the read-only-events /
  writable-graph split, and an advanced note for explicit ontology+binding.
- Terraform README: property_graph = true subsection (build with
  build_image.sh --property-graph; sets BQAA_PROPERTY_GRAPH; plan-time
  precondition vs compiled-only), plus tfvars override, the env-var list, and
  the build-image note.

Docs only; no code change. This is the last PR for #286.

Author: caohy1988

examples/migration_v5/periodic_materialization/README.md

@@ -272,6 +272,44 @@ the logs, so you find out *now* whether the deploy actually
 works — not when the first scheduled fire happens six hours
 later.
 
+### Schema-derived deploy (`--property-graph`)
+
+The deploy above bundles the MAKO `ontology.yaml` + `binding.yaml`. For a
+**rename-free, codelab-style graph** you can skip those entirely and deploy
+from just a property graph — the same one-artifact flow the
+[codelab](../../../docs/codelabs/periodic_materialization.md) uses locally:
+
+```bash
+./examples/migration_v5/periodic_materialization/deploy_cloud_run_job.sh \
+  --project your-project \
+  --region us-central1 \
+  --events-dataset your_events_dataset \
+  --graph-dataset your_graph_dataset \
+  --schedule "0 */6 * * *" \
+  --property-graph path/to/property_graph.sql
+```
+
+`--property-graph` points at a `CREATE PROPERTY GRAPH` `.sql`; a placeholdered
+(`${PROJECT_ID}` / `${DATASET}`) `table_ddl.sql` must sit **next to it**. The
+deploy stages both (no `ontology.yaml`/`binding.yaml`), sets
+`BQAA_PROPERTY_GRAPH=property_graph.sql`, and the runtime derives the ontology +
+binding from the property graph + your live table schemas at run time (#286).
+Events stay read-only in your events dataset; the graph tables, schema lookup,
+and the state table all target the graph dataset.
+
+Requirements / limits:
+
+* Both files must be **placeholdered** (`${PROJECT_ID}` / `${DATASET}`) — the
+  deploy refuses hardcoded references so the job can never derive against the
+  wrong dataset.
+* Not compatible with `--extraction-mode=compiled-only` (no reference
+  extractors are staged in derived mode); the deploy rejects that combination.
+
+**Advanced — explicit ontology + binding.** Omit `--property-graph` to keep the
+default MAKO path: descriptions for AI prompting, entity inheritance, derived
+properties, column renames, and the hand-authored compiled extractor. That is
+the right path for migration v5 and any graph that outgrows schema-derived mode.
+
 The script:
 
 1. **Pre-creates the graph dataset** (`bq mk`, idempotent) so

examples/migration_v5/periodic_materialization/terraform/README.md

@@ -11,15 +11,15 @@ Resolves [#186](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-
 | Graph dataset | `google_bigquery_dataset` | §1 — `bq mk` (pre-create so the runtime SA never needs `bigquery.datasets.create`) |
 | Runtime SA + scheduler-caller SA | `google_service_account` ×2 | §2 — `_ensure_sa` (split by default; `single_sa = true` collapses to one) |
 | Project + dataset IAM grants | `google_project_iam_member`, `google_bigquery_dataset_iam_member` | §3 — `_retry_iam gcloud projects add-iam-policy-binding` and the dataset-level grant block. Terraform's dependency graph handles the IAM-propagation race declaratively (the `depends_on` on the Cloud Run Job resource ensures grants land before the first invocation) |
-| Cloud Run v2 Job | `google_cloud_run_v2_job` | §4 — `gcloud run jobs deploy`. Same env-var set the bash deploy wires (`BQAA_PROJECT_ID`, `BQAA_EVENTS_DATASET_ID`, `BQAA_GRAPH_DATASET_ID`, `BQAA_LOCATION`, `BQAA_LOOKBACK_HOURS`, `BQAA_OVERLAP_MINUTES`, `BQAA_EXTRACTION_MODE`, `BQAA_MAX_RETRIES`, conditionally `BQAA_MAX_SESSIONS`, `BQAA_MAX_SESSION_AGE_HOURS`, `BQAA_REFERENCE_EXTRACTORS_MODULE`) |
+| Cloud Run v2 Job | `google_cloud_run_v2_job` | §4 — `gcloud run jobs deploy`. Same env-var set the bash deploy wires (`BQAA_PROJECT_ID`, `BQAA_EVENTS_DATASET_ID`, `BQAA_GRAPH_DATASET_ID`, `BQAA_LOCATION`, `BQAA_LOOKBACK_HOURS`, `BQAA_OVERLAP_MINUTES`, `BQAA_EXTRACTION_MODE`, `BQAA_MAX_RETRIES`, conditionally `BQAA_MAX_SESSIONS`, `BQAA_MAX_SESSION_AGE_HOURS`, `BQAA_REFERENCE_EXTRACTORS_MODULE`, and `BQAA_PROPERTY_GRAPH` when `property_graph = true`) |
 | `roles/run.invoker` on the job → scheduler SA | `google_cloud_run_v2_job_iam_member` | §5 — `_retry_iam gcloud run jobs add-iam-policy-binding` |
 | Cloud Scheduler trigger | `google_cloud_scheduler_job` | §6 — `gcloud scheduler jobs create http` with `--oauth-service-account-email` pointing at the scheduler SA |
 
 ## What's intentionally outside the module
 
 **Container image build + publish.** The bash deploy builds the image from local sources via Cloud Buildpacks (`gcloud run jobs deploy --source $STAGING`), assembling a staging directory with `run_job.py` + `reference_extractor.py` + the demo artifacts + the vendored SDK source + `Procfile` + `requirements.txt` before invoking the build. That staging step is non-trivial — pointing `gcloud builds submit` directly at the `periodic_materialization/` directory would build an image that's missing the SDK source, the demo artifacts, and the Procfile.
 
-The module takes the **published** image URI as the required `image_uri` variable. To produce a Terraform-compatible image, use the bundled [`../build_image.sh`](../build_image.sh) helper — it stages the exact layout `deploy_cloud_run_job.sh` produces in its temp dir, then runs `gcloud builds submit` against that staging dir. Same image contents either way; Terraform just consumes the publish artifact instead of doing the build inline.
+The module takes the **published** image URI as the required `image_uri` variable. To produce a Terraform-compatible image, use the bundled [`../build_image.sh`](../build_image.sh) helper — it stages the exact layout `deploy_cloud_run_job.sh` produces in its temp dir, then runs `gcloud builds submit` against that staging dir. Same image contents either way; Terraform just consumes the publish artifact instead of doing the build inline. For schema-derived deploys (`property_graph = true`), build the image with `build_image.sh --property-graph path/to/property_graph.sql` so the placeholdered `property_graph.sql` + `table_ddl.sql` are staged instead of `ontology.yaml`/`binding.yaml`.
 
 ```bash
 # From the repo root.
@@ -86,13 +86,29 @@ graph_dataset_id   = "migration_v5_graph"
 schedule           = "0 */6 * * *"
 image_uri          = "us-central1-docker.pkg.dev/my-project/bqaa/periodic-materialization:v1"
 # Optional overrides — defaults match the bash deploy
+# property_graph        = false   # true → schema-derived mode (see below)
 # extraction_mode       = "ai-fallback"
 # max_retries           = 2
 # max_session_age_hours = 24
 # single_sa             = false
 # location              = "US"
 ```
 
+#### Schema-derived mode (`property_graph = true`)
+
+For a **rename-free, codelab-style graph** you can skip the explicit
+`ontology.yaml` / `binding.yaml` and derive the spec from a property graph (the
+[#286](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/286)
+one-artifact flow). Set `property_graph = true` and build the image with
+`build_image.sh --property-graph path/to/property_graph.sql` (a placeholdered
+`${PROJECT_ID}` / `${DATASET}` `table_ddl.sql` must sit next to it). The module
+then sets `BQAA_PROPERTY_GRAPH=property_graph.sql` on the Job so the runtime
+derives the ontology + binding from the property graph + your live table
+schemas. `property_graph = true` is rejected at plan time with
+`extraction_mode = "compiled-only"` (no reference extractors are staged in
+derived mode). Leave `property_graph = false` (default) for the explicit MAKO /
+compiled-extractor path.
+
 ### 2. Init + plan + apply
 
 ```bash