diff --git a/.gitignore b/.gitignore
index fb65cba..3d32425 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,4 @@
 .state/
-data/generator/cache/
 stages/agent.py
 
 *conf*.json
@@ -9,6 +8,7 @@ __pycache__
 .env
 .databricks
 .claude
+.cursor
 .bundle
 /.vscode/
 node_modules/
diff --git a/AGENTS.md b/AGENTS.md
index af121f0..25bddea 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,8 +51,11 @@ Running `databricks bundle destroy` only removes the Job definition - **all runt
 
 **Cleanup workflow**:
 ```bash
-databricks bundle run cleanup    # Delete runtime resources via uc_state
-databricks bundle destroy        # Delete bundle resources via DABs
+# Cleanup is a bundle SCRIPT, so the catalog override uses --var (not --params).
+# --params is for job tasks only; passing it to cleanup is silently ignored.
+# `--var catalog=X` on `bundle run cleanup` does NOT reach the script — use BUNDLE_VAR_catalog=.
+BUNDLE_VAR_catalog=<name> databricks bundle run cleanup -t <target>    # Delete runtime resources via uc_state
+databricks bundle destroy      -t <target>                         # Delete bundle resources via DABs
 ```
 
 **Location**: `/utils/uc_state/` - See `README.md` for API usage
@@ -320,8 +323,10 @@ rm -rf .databricks .bundle
 
 1. **Clean existing deployment**
    ```bash
-   databricks bundle run cleanup --params "CATALOG=testcatalog"
-   databricks bundle destroy -t <target>
+   # Cleanup is a script — use --var (not --params).  See the Quick Reference
+   # at the bottom of this doc for full details.
+   BUNDLE_VAR_catalog=testcatalog databricks bundle run cleanup -t <target>
+   databricks bundle destroy     -t <target>
    ```
 
 2. **Clear local cache** (if experiencing cache issues)
@@ -629,6 +634,40 @@ Use full redeploy instead if:
   - Ensure it's plumbed through all layers
   - Check `databricks.yml` parameters, stage parameter parsing, and implementation usage
 
+#### 5a. `--var catalog` vs `--params CATALOG` drift
+- **Why fragile**: Two separate dials use a catalog name and they can disagree.
+  - `bundle deploy --var catalog=X` → resolves `${var.catalog}` at deploy
+    time.  Bakes `X` into every DABs-managed resource name (e.g. the `all`
+    target's `caspers_ops_warehouse` becomes `X-ops-warehouse`), every
+    AI/BI dashboard name, every dashboard `dataset_catalog`, and every job
+    parameter `default: ${var.catalog}...` (incl. `CATALOG`,
+    `REFUND_AGENT_ENDPOINT_NAME`, `COMPLAINT_AGENT_ENDPOINT_NAME`,
+    `OPS_WAREHOUSE_NAME`, `SUPERVISOR_ENDPOINT_NAME`).
+  - `bundle run caspers --params "CATALOG=Y"` → overrides ONLY the
+    run-time `CATALOG` widget value inside stage notebooks.  Cannot rename
+    anything DABs already created.
+- **Symptom when they disagree**: stages that reconstruct a DABs-managed
+  resource name from the run-time `CATALOG` widget fail to find it.
+  Example: deploying with the default and then running
+  `--params CATALOG=mycatalog` against the `all` target makes
+  `stages/operational_app.ipynb` fail with
+  `RuntimeError: Warehouse 'mycatalog-ops-warehouse' not found` because
+  DABs created `caspersdev-ops-warehouse`.
+- **Best practice**:
+  - When in doubt, pass the same catalog to both:
+    `bundle deploy -t <target> --var catalog=X` then
+    `bundle run caspers --params "CATALOG=X"`.
+  - When adding a stage that needs the name of a DABs-managed resource,
+    do NOT reconstruct it from the `CATALOG` widget.  Add a dedicated job
+    parameter with a `${var.catalog}-...` default in `databricks.yml`
+    (this is how `OPS_WAREHOUSE_NAME`, `REFUND_AGENT_ENDPOINT_NAME` and
+    `COMPLAINT_AGENT_ENDPOINT_NAME` are wired), then read that parameter
+    via `dbutils.widgets.get(...)` in the stage.  The deploy-time value
+    rides through the job parameter into the run-time widget, so the two
+    dials physically cannot disagree.
+  - The long comment in `stages/operational_app.ipynb` cell 8 (the
+    `_agent_ep_name` helper) is the canonical example of this pattern.
+
 ### 6. Resource Dependencies
 - **Why fragile**: Stages create resources that others depend on (endpoints, tables, etc.)
 - **When touching**: Creation/deletion order, stage dependencies
@@ -754,8 +793,13 @@ databricks bundle run caspers [--params "CATALOG=mycatalog"]
 
 ### Cleanup
 ```bash
-databricks bundle run cleanup [--params "CATALOG=mycatalog"]
-databricks bundle destroy -t <target>
+# IMPORTANT: cleanup is a bundle SCRIPT, not a job task.
+#   Catalog override:  --var catalog=<name>   (NOT --params "CATALOG=...")
+#   Target selection:  -t <target>            (passes through normally)
+# --params is silently ignored by scripts; passing it will clean the
+# default catalog (caspersdev) which is rarely what you want.
+BUNDLE_VAR_catalog=<name> databricks bundle run cleanup -t <target>
+databricks bundle destroy     -t <target>
 rm -rf .databricks .bundle  # If cache issues
 ```
 
diff --git a/README.md b/README.md
index 8aa85e1..d3a2413 100644
--- a/README.md
+++ b/README.md
@@ -21,34 +21,76 @@ See the [`skill` branch](../../tree/skill) for details.
 
 ## Deploy
 
+Replace `all` and `mycatalog` with your target and catalog:
+
 ```bash
-databricks bundle deploy -t <target>
-databricks bundle run caspers
+databricks bundle deploy -t all --var catalog=mycatalog
+databricks bundle run caspers -t all --params "CATALOG=mycatalog"
 ```
 
+Use the same target for deploy and run. Omit `-t` to use `default` (refund demo only).
+
 Available targets:
 
 | Target | What it deploys |
 |--------|----------------|
-| `default` | Data generation, Lakeflow pipeline, refund agent, Lakebase + app |
-| `support` | Data generation, Lakeflow pipeline, support triage agent, Lakebase + app |
-| `complaints` | Data generation, Lakeflow pipeline, complaint agent, Lakebase |
-| `free` | Data generation, Lakeflow pipeline (Free Edition compatible) |
-| `menus` | Document intelligence, DLT pipeline, Genie, Knowledge Assistants, Multi-Agent Supervisor |
+| `default` | Canonical data replay, Lakeflow pipeline, refund agent + stream, Lakebase Autoscale reverse-ETL, Refund Manager app |
+| `support` | Canonical data replay, Lakeflow pipeline, support triage agent + streams, Lakebase + app |
+| `complaints` | Canonical data replay, Lakeflow pipeline, complaint agent + streams, Lakebase |
+| `free` | Canonical data replay, Lakeflow pipeline (Free Edition compatible) |
+| `all` | Full platform demo: refund + complaints paths above, document intelligence pipeline, 3 Genies + 6 Knowledge Assistants + Multi-Agent Supervisor, Operational Dashboard app (Lakebase-backed), 5 AI/BI dashboards. See [`demos/dais2026-runbooks/SETUP.ipynb`](demos/dais2026-runbooks/SETUP.ipynb) for workspace prep. |
+
+Refund and complaint evaluation tasks (`Refund_Evaluation`, `Complaint_Evaluation`) are **skipped by default** (`SKIP_EVAL=true`). Pass `--params "SKIP_EVAL=false"` to opt in. The supervisor/KA `Evaluation` task on `all` (`stages/operational_evaluation`) always runs — it is not gated by `SKIP_EVAL`.
+
+Optionally specify a catalog (default: `caspersdev`).  There are **two** dials
+that take a catalog name and they must agree:
 
-Optionally specify a catalog (default: `caspersdev`):
+| Dial | When | What it controls |
+|---|---|---|
+| `bundle deploy --var catalog=<name>` | deploy time | the catalog baked into every DABs-managed resource — the `all` target's `caspers_ops_warehouse` SQL warehouse, AI/BI dashboard names, dashboard `dataset_catalog`, and the *default* value of every job parameter that uses `${var.catalog}` (including `CATALOG`, `REFUND_AGENT_ENDPOINT_NAME`, `OPS_WAREHOUSE_NAME`, etc.) |
+| `bundle run caspers --params "CATALOG=<name>"` | run time | only the value of the `CATALOG` widget inside stage notebooks.  Cannot rename anything DABs already created. |
+
+If they disagree (e.g. `bundle deploy -t all` with the default + `bundle run
+--params CATALOG=mycatalog`), the `all` target will fail at the
+`Operational_App` stage because the warehouse DABs created (`caspersdev-ops-warehouse`)
+is not what the stage looks up (`mycatalog-ops-warehouse`).  The fix is to
+pass the same catalog to both:
 
 ```bash
-databricks bundle run caspers --params "CATALOG=mycatalog"
+databricks bundle deploy -t all --var catalog=mycatalog
+databricks bundle run caspers -t all --params "CATALOG=mycatalog"
 ```
 
+For targets other than `all` (no DABs-owned warehouse/dashboards),
+`--params CATALOG=mycatalog` alone usually works, but passing both keeps the
+deploy-time and run-time catalogs in sync and is the safer habit.
+
 ## Clean Up
 
+Cleanup is **destructive**: it runs `destroy.ipynb`, which `DROP CATALOG … CASCADE` on the catalog you pass. It does **not** rebuild data or schemas afterward.
+
+**Catalog default:** if you omit `BUNDLE_VAR_catalog=...`, cleanup uses `caspersdev` (the bundle default) — or whatever catalog was last passed to `bundle deploy --var catalog=...` on this machine.
+
+Cleanup is a bundle **script** — use `BUNDLE_VAR_catalog=...` on the command line (not `--params CATALOG=...`, which is ignored for scripts). **`--var catalog=...` on `bundle run cleanup` does not work** — the CLI does not pass it into the script.
+
 ```bash
-databricks bundle run cleanup
-databricks bundle destroy
+# 1. Delete runtime UC resources (catalog + everything in it)
+BUNDLE_VAR_catalog=mycatalog databricks bundle run cleanup -t all
+# With a non-default CLI profile, append --profile <name> at the end.
+
+# 2. Delete bundle-managed resources (job, warehouses, dashboards)
+databricks bundle destroy -t all
 ```
 
+To **rebuild** after cleanup, deploy and run the job again (deploy alone does not recreate the catalog):
+
+```bash
+databricks bundle deploy -t all --var catalog=mycatalog
+databricks bundle run caspers -t all --params "CATALOG=mycatalog"
+```
+
+The first task (`Canonical_Data`) runs `CREATE CATALOG IF NOT EXISTS` and repopulates schemas/tables.
+
 ## Blog
 
 Check out the [Casper's Kitchens Blog](https://databricks-solutions.github.io/caspers-kitchens/).
diff --git a/apps/caspers-ops-dashboard/app.yaml b/apps/caspers-ops-dashboard/app.yaml
new file mode 100644
index 0000000..db7cc0c
--- /dev/null
+++ b/apps/caspers-ops-dashboard/app.yaml
@@ -0,0 +1,56 @@
+command:
+  - uvicorn
+  - app.main:app
+env:
+  - name: LAKEBASE_ENDPOINT_PATH
+    value: ''
+  - name: LAKEBASE_DATABASE_NAME
+    value: 'caspers-ops'
+  - name: DATABRICKS_CATALOG
+    value: ''
+  - name: SUPERVISOR_ENDPOINT
+    value: ''
+  - name: SUPERVISOR_TILE_ID
+    value: ''
+  - name: SUPERVISOR_MLFLOW_EXPERIMENT_ID
+    value: ''
+  - name: GENIE_ID_REVENUE
+    value: ''
+  - name: GENIE_ID_OPS
+    value: ''
+  - name: GENIE_ID_MENU
+    value: ''
+  - name: KA_ID_INSPECTION
+    value: ''
+  - name: KA_ID_MENU
+    value: ''
+  - name: KA_ID_LEGAL
+    value: ''
+  - name: KA_ID_REGULATORY
+    value: ''
+  - name: KA_ID_AUDITS
+    value: ''
+  - name: KA_ID_CONSULTANCY
+    value: ''
+  - name: DATABRICKS_WAREHOUSE_ID
+    value: ''
+  # Operations dashboard is published in two variants — light + dark —
+  # because Databricks embedded dashboards always render in light mode
+  # regardless of the `?theme=` URL param.  The frontend swaps the iframe
+  # src between these two IDs when the user toggles the app theme.  The
+  # stage writes both runtime values; OPS_DASHBOARD_ID is the light variant.
+  - name: OPS_DASHBOARD_ID
+    value: ''
+  - name: OPS_DASHBOARD_ID_DARK
+    value: ''
+  # Multi-page dashboard — leave empty so the iframe URL doesn't append a
+  # #page= fragment and the user sees the dashboard's default landing page.
+  - name: OPS_DASHBOARD_PAGE
+    value: ''
+  # Custom agent endpoints — populated by operational_app stage from CATALOG
+  - name: REFUND_AGENT_ENDPOINT
+    value: ''
+  - name: COMPLAINT_AGENT_ENDPOINT
+    value: ''
+  - name: REFUND_MANAGER_APP_URL
+    value: ''
diff --git a/apps/caspers-ops-dashboard/app/__init__.py b/apps/caspers-ops-dashboard/app/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/caspers-ops-dashboard/app/db.py b/apps/caspers-ops-dashboard/app/db.py
new file mode 100644
index 0000000..712897b
--- /dev/null
+++ b/apps/caspers-ops-dashboard/app/db.py
@@ -0,0 +1,256 @@
+"""
+Lakebase (PostgreSQL) connection management with automatic token refresh
+and a ``psycopg_pool.ConnectionPool`` so chat traffic doesn't churn a fresh
+TCP+TLS handshake on every request.
+
+Connection strategy:
+
+- Resolve ``host`` and the current Postgres user once at startup.
+- Mint a fresh per-endpoint credential on every NEW psycopg connection via
+  a ``psycopg.Connection`` subclass whose ``connect()`` injects the password.
+  Tokens are short-lived (~1h); the pool's ``check`` hook (the
+  ``pool_pre_ping`` equivalent for psycopg-pool) recycles stale connections
+  before they're handed to a request, and ``max_idle`` evicts pooled
+  connections that have outlived their token cleanly.
+- A background thread refreshes the in-process token snapshot every ~48 min
+  so the connection factory always has a recent credential cached when the
+  pool needs to mint a brand-new socket (cold start, scale-out, or after
+  ``check`` discarded a stale connection).
+
+This mirrors the proven pattern in ``apps/refund-manager/app/db.py`` (which
+uses SQLAlchemy's ``do_connect`` hook for the same effect).  We use psycopg-
+pool directly here because ``main.py`` consumes connections via raw psycopg
+``with get_conn() as conn:`` blocks rather than SQLAlchemy sessions, so a
+SQLAlchemy migration would touch every call site.
+"""
+
+import os
+import time
+import logging
+import threading
+from contextlib import contextmanager
+
+import psycopg
+from psycopg_pool import ConnectionPool
+from databricks.sdk import WorkspaceClient
+
+log = logging.getLogger("caspers_ops_dashboard.db")
+
+ENDPOINT_PATH = os.environ.get("LAKEBASE_ENDPOINT_PATH", "")
+DB_NAME = os.environ.get("LAKEBASE_DATABASE_NAME", "databricks_postgres")
+
+# Pool sizing — tuned for a single uvicorn worker with chat + session CRUD
+# under modest demo load.  ``min_size=2`` keeps two warm connections so the
+# first chat message after an idle period doesn't pay the TCP+TLS cost,
+# ``max_size=10`` is well below Lakebase's per-endpoint cap, and ``max_idle``
+# evicts pooled connections that have outlived their token (1h) cleanly.
+POOL_MIN_SIZE = 2
+POOL_MAX_SIZE = 10
+POOL_MAX_IDLE_S = 1800            # 30 min — recycle well before the 1h token expiry
+POOL_CHECKOUT_TIMEOUT_S = 10.0    # max wait for a pooled connection
+POOL_OPEN_TIMEOUT_S = 30.0        # max wait when the pool is opened at startup
+
+# Background token refresh — keeps `_current_token` warm so the connection
+# factory always has a recent credential when minting new sockets.
+TOKEN_REFRESH_INTERVAL = 2900     # ~48 min between successful refreshes
+TOKEN_RETRY_BASE = 30             # first retry wait after a failure
+TOKEN_RETRY_MAX = 600             # cap retry waits at 10 min
+
+_w: WorkspaceClient | None = None
+_token_lock = threading.Lock()
+_current_token: str | None = None
+_host: str | None = None
+_user: str | None = None
+_pool: ConnectionPool | None = None
+
+
+def _workspace_client() -> WorkspaceClient:
+    global _w
+    if _w is None:
+        _w = WorkspaceClient()
+    return _w
+
+
+def _mint_token() -> str:
+    """Mint a fresh per-endpoint credential."""
+    w = _workspace_client()
+    cred = w.postgres.generate_database_credential(endpoint=ENDPOINT_PATH)
+    return cred.token
+
+
+def _resolve_host_and_user() -> tuple[str, str]:
+    w = _workspace_client()
+    ep = w.postgres.get_endpoint(name=ENDPOINT_PATH)
+    return ep.status.hosts.host, w.current_user.me().user_name
+
+
+def _refresh_token() -> bool:
+    """Best-effort token refresh — keeps a fresh password in `_current_token`
+    so the connection factory hands out valid credentials on new connections.
+    Returns True on success, False on any failure."""
+    global _current_token
+    try:
+        tok = _mint_token()
+    except Exception as e:
+        log.error(f"Lakebase token refresh failed: {type(e).__name__}: {e}")
+        return False
+    with _token_lock:
+        _current_token = tok
+    log.info("Lakebase token refreshed")
+    return True
+
+
+def _token_refresher() -> None:
+    """Background loop with exponential backoff on failures."""
+    retry_wait = TOKEN_RETRY_BASE
+    while True:
+        if _refresh_token():
+            retry_wait = TOKEN_RETRY_BASE
+            time.sleep(TOKEN_REFRESH_INTERVAL)
+        else:
+            log.warning(
+                f"Lakebase token refresh failed; retrying in {retry_wait}s "
+                f"(pooled connections continue using their existing tokens until then)"
+            )
+            time.sleep(retry_wait)
+            retry_wait = min(retry_wait * 2, TOKEN_RETRY_MAX)
+
+
+def _current_password() -> str:
+    """Snapshot the freshest token under the lock.  Falls back to a brand-new
+    mint if the background refresher hasn't populated `_current_token` yet
+    (cold start) so the pool's first connection doesn't block forever."""
+    with _token_lock:
+        tok = _current_token
+    if tok:
+        return tok
+    return _mint_token()
+
+
+class _TokenInjectingConnection(psycopg.Connection):
+    """psycopg ``Connection`` subclass that injects a fresh Lakebase token
+    on every new connection.
+
+    The pool calls ``cls.connect(conninfo, **kwargs)`` whenever it needs to
+    mint a brand-new socket (cold start, scale-out, or after the ``check``
+    hook discarded a stale one).  We inject the current password here —
+    rather than baking it into ``conninfo`` — so a stale token never lives
+    in the pool's connection string and every new connection sees a current
+    one without us having to recycle the entire pool on token refresh.
+    """
+
+    @classmethod
+    def connect(cls, conninfo: str = "", **kwargs):
+        kwargs.setdefault("password", _current_password())
+        return super().connect(conninfo, **kwargs)
+
+
+def _check_connection(conn: psycopg.Connection) -> None:
+    """psycopg-pool ``check`` hook = ``pool_pre_ping`` equivalent.  Runs on
+    each connection borrow; if the cheap ping fails (e.g. token expired,
+    server closed the socket), the pool will discard the connection and
+    open a new one via ``_TokenInjectingConnection.connect()``, which picks
+    up a fresh token."""
+    conn.execute("SELECT 1")
+
+
+def _build_conninfo() -> str:
+    """psycopg connection string.  Password is intentionally absent — the
+    connection-factory subclass injects a fresh one per new connection."""
+    return (
+        f"host={_host} port=5432 dbname={DB_NAME} user={_user} "
+        f"sslmode=require"
+    )
+
+
+def init_db() -> None:
+    """Resolve host/user, kick off the background refresher, open the pool.
+    Idempotent — safe to call multiple times during reload."""
+    global _host, _user, _pool
+
+    if not ENDPOINT_PATH:
+        log.warning("LAKEBASE_ENDPOINT_PATH not set — DB features disabled")
+        return
+    if _pool is not None:
+        return
+
+    try:
+        _host, _user = _resolve_host_and_user()
+    except Exception as e:
+        log.error(f"Could not resolve Lakebase host/user — DB features disabled: {e}")
+        return
+
+    # Prime the token cache before opening the pool so the very first
+    # `_TokenInjectingConnection.connect()` call doesn't have to mint
+    # synchronously inside the pool's open path.
+    _refresh_token()
+
+    t = threading.Thread(
+        target=_token_refresher, daemon=True, name="lakebase-token-refresher"
+    )
+    t.start()
+
+    try:
+        _pool = ConnectionPool(
+            conninfo=_build_conninfo(),
+            min_size=POOL_MIN_SIZE,
+            max_size=POOL_MAX_SIZE,
+            max_idle=POOL_MAX_IDLE_S,
+            timeout=POOL_OPEN_TIMEOUT_S,
+            connection_class=_TokenInjectingConnection,
+            check=_check_connection,
+            open=True,
+        )
+    except Exception as e:
+        log.error(f"Lakebase pool could not be opened — DB features disabled: {e}")
+        _pool = None
+        return
+
+    _ensure_schema()
+    log.info(
+        f"Lakebase pool opened (min={POOL_MIN_SIZE}, max={POOL_MAX_SIZE}, "
+        f"max_idle={POOL_MAX_IDLE_S}s)"
+    )
+
+
+@contextmanager
+def get_conn():
+    """Context manager yielding a pooled psycopg connection.
+
+    Drop-in replacement for the old ``psycopg.connect()`` per call — the
+    pool's ``check`` hook recycles stale connections automatically before
+    handing them out, and new connections get a freshly-minted password
+    via ``_TokenInjectingConnection.connect()``.
+    """
+    if _pool is None:
+        raise RuntimeError(
+            "Database not initialized. LAKEBASE_ENDPOINT_PATH may be missing, "
+            "or init_db() failed at startup — check the app logs for the "
+            "underlying error."
+        )
+    with _pool.connection(timeout=POOL_CHECKOUT_TIMEOUT_S) as conn:
+        yield conn
+
+
+def _ensure_schema() -> None:
+    """Ensure tables exist. Tables are created by operational_lakebase.ipynb (stage creator owns them).
+    Each statement runs independently so ownership errors on indexes don't block startup."""
+    statements = [
+        "CREATE TABLE IF NOT EXISTS sessions (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), title TEXT NOT NULL DEFAULT 'New Session', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW())",
+        "CREATE TABLE IF NOT EXISTS messages (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE, role TEXT NOT NULL CHECK (role IN ('user', 'assistant')), content TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), documents_referenced JSONB DEFAULT '[]'::jsonb)",
+        "CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at)",
+        "CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at DESC)",
+    ]
+    try:
+        with get_conn() as conn:
+            for stmt in statements:
+                try:
+                    with conn.cursor() as cur:
+                        cur.execute(stmt)
+                    conn.commit()
+                except Exception as e:
+                    conn.rollback()
+                    log.warning(f"DDL skipped (non-fatal): {e}")
+        log.info("Operational schema ensured")
+    except Exception as e:
+        log.error(f"Schema setup failed — DB features may be unavailable: {e}")
diff --git a/apps/caspers-ops-dashboard/app/main.py b/apps/caspers-ops-dashboard/app/main.py
new file mode 100644
index 0000000..0ae936e
--- /dev/null
+++ b/apps/caspers-ops-dashboard/app/main.py
@@ -0,0 +1,1443 @@
+"""
+Casper's Operational Dashboard — FastAPI backend
+
+Routes:
+  GET  /                          → serve index.html SPA
+  GET  /api/tech-info             → connected infrastructure metadata
+  GET  /api/sessions              → list chat sessions (Lakebase)
+  POST /api/sessions              → create a new session
+  PUT  /api/sessions/{id}         → rename a session
+  DELETE /api/sessions/{id}       → delete session + messages
+  GET  /api/sessions/{id}/messages → message history
+  POST /api/chat                  → stream chat to operational supervisor MAS
+  GET  /api/revenue               → revenue summary from SQL warehouse
+  GET  /api/locations             → location list with ops health indicators
+"""
+
+import os
+import re
+import json
+import time
+import uuid
+import logging
+import asyncio
+import threading
+from pathlib import Path
+from typing import AsyncIterator
+
+import httpx
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+from databricks.sdk import WorkspaceClient
+from databricks.sdk.core import Config
+
+from .db import init_db, get_conn
+
+log = logging.getLogger("caspers_ops_dashboard")
+logging.basicConfig(level=logging.INFO)
+
+app = FastAPI(title="Casper's Operational Dashboard", version="1.0.0")
+
+CATALOG              = os.environ.get("DATABRICKS_CATALOG", "").strip() or "caspersdev"
+# DATABRICKS_APP_NAME is auto-injected by the Apps runtime — used by the eval
+# notebook lookup below (P1-18). Fall back to a sane default for local dev
+# / unit tests where the runtime env isn't present.
+APP_NAME             = os.environ.get("DATABRICKS_APP_NAME", "").strip() or "ops-dashboard"
+SUPERVISOR_ENDPOINT       = os.environ.get("SUPERVISOR_ENDPOINT", "")
+SUPERVISOR_TILE_ID        = os.environ.get("SUPERVISOR_TILE_ID", "")          # written by operational_lakebase stage
+SUPERVISOR_MLFLOW_EXP_ID  = os.environ.get("SUPERVISOR_MLFLOW_EXPERIMENT_ID", "")  # written by operational_lakebase stage
+REFUND_AGENT_ENDPOINT     = os.environ.get("REFUND_AGENT_ENDPOINT", "")
+COMPLAINT_AGENT_ENDPOINT  = os.environ.get("COMPLAINT_AGENT_ENDPOINT", "")
+REFUND_MANAGER_APP_URL    = os.environ.get("REFUND_MANAGER_APP_URL", "")
+LAKEBASE_INSTANCE    = os.environ.get("LAKEBASE_ENDPOINT_PATH", "")   # non-empty = DB enabled
+WAREHOUSE_ID         = os.environ.get("DATABRICKS_WAREHOUSE_ID", "")
+GENIE_REVENUE_ID     = os.environ.get("GENIE_ID_REVENUE", "")
+GENIE_OPS_ID         = os.environ.get("GENIE_ID_OPS",     "")
+# Embedded AI/BI dashboard (Casper's Kitchen Operations) — written by the
+# operational_app stage at deploy time after publishing the dashboard.
+OPS_DASHBOARD_ID      = os.environ.get("OPS_DASHBOARD_ID", "")       # light variant (default)
+OPS_DASHBOARD_ID_DARK = os.environ.get("OPS_DASHBOARD_ID_DARK", "")  # dark variant
+OPS_DASHBOARD_PAGE    = os.environ.get("OPS_DASHBOARD_PAGE", "")
+
+_sdk_config = Config()
+_ws = WorkspaceClient()   # shared, reused across all requests
+
+STATIC_DIR = Path(__file__).parent.parent
+INDEX_HTML = STATIC_DIR / "index.html"
+
+
+# ─── Startup ─────────────────────────────────────────────────────────────────
+
+@app.on_event("startup")
+def _startup():
+    log.info(f"INDEX_HTML path: {INDEX_HTML} (exists={INDEX_HTML.exists()})")
+    log.info(f"CATALOG={CATALOG} SUPERVISOR={SUPERVISOR_ENDPOINT} LAKEBASE={bool(LAKEBASE_INSTANCE)}")
+    init_db()
+
+
+# ─── SPA ──────────────────────────────────────────────────────────────────────
+
+@app.get("/", include_in_schema=False)
+def index():
+    if not INDEX_HTML.exists():
+        raise HTTPException(404, "index.html not found")
+    # Always hand back fresh HTML — every deploy ships a new index.html and
+    # we don't want the browser caching the previous bundle, otherwise the
+    # user has to manually hard-refresh after every push.
+    return FileResponse(
+        str(INDEX_HTML),
+        headers={
+            "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
+            "Pragma": "no-cache",
+            "Expires": "0",
+        },
+    )
+
+
+# ─── Tech Info ────────────────────────────────────────────────────────────────
+#
+# `/api/tech-info` is called once per page load by every browser viewing
+# the app.  Each call makes 4-6 SDK round-trips (Lakebase endpoint, project
+# list, workspace metadata, MLflow experiment search, app deployment lookup)
+# that take ~0.5-1.5 s warm and ~3-5 s cold.  The values it returns —
+# Lakebase host, supervisor tile_id, dashboard IDs, etc. — are deploy-time
+# constants that don't change for the lifetime of the app process.
+#
+# A short TTL keeps page-load latency snappy without making the dashboard
+# completely stale during a redeploy (after a `bundle deploy` the new
+# values land within `_TECH_INFO_TTL_S`).  60 s is the same TTL as the
+# revenue cache and a comfortable upper bound on how long an audience will
+# stare at a stale debug footer during a demo.
+
+_TECH_INFO_TTL_S = 60
+_tech_info_cache: dict = {"data": None, "ts": 0.0}
+_tech_info_lock = threading.Lock()
+
+
+@app.get("/api/tech-info")
+def tech_info():
+    """Workspace + deployment metadata, served from a 60 s TTL cache.
+
+    Coalesced under a lock so a thundering herd of page loads after a cold
+    start hits the SDK at most once per TTL window.
+    """
+    now = time.time()
+    cached = _tech_info_cache["data"]
+    if cached is not None and (now - _tech_info_cache["ts"]) < _TECH_INFO_TTL_S:
+        return cached
+
+    with _tech_info_lock:
+        cached = _tech_info_cache["data"]
+        if cached is not None and (time.time() - _tech_info_cache["ts"]) < _TECH_INFO_TTL_S:
+            return cached
+        try:
+            data = _compute_tech_info()
+        except Exception as e:
+            # On hard failure, hand back the previous cached snapshot rather
+            # than 500-ing the whole page.  The debug footer becomes briefly
+            # stale; everything else keeps rendering.
+            log.error(f"tech_info compute failed: {e}")
+            if cached is not None:
+                log.warning("returning stale tech_info cache after refresh failure")
+                return cached
+            raise
+        _tech_info_cache["data"] = data
+        _tech_info_cache["ts"] = time.time()
+        return data
+
+
+def _compute_tech_info() -> dict:
+    """Underlying SDK-heavy implementation.  Kept separate from the route so
+    the TTL cache wrapper can stay focused on the cache logic."""
+    w = _ws
+    host = _sdk_config.host or ""
+    me = w.current_user.me()
+
+    # Parse project name from endpoint path: "projects/my-project/branches/..."
+    lakebase_project = ""
+    lakebase_project_uid = ""
+    lakebase_host = ""
+    lakebase_dbname = os.environ.get("LAKEBASE_DATABASE_NAME", "databricks_postgres")
+    lakebase_status = ""
+    lakebase_min_cu = 0.0
+    lakebase_max_cu = 0.0
+    lakebase_pg_version = 0
+
+    if LAKEBASE_INSTANCE:
+        parts = LAKEBASE_INSTANCE.split("/")
+        if len(parts) >= 2 and parts[0] == "projects":
+            lakebase_project = parts[1]
+
+        # Fetch live endpoint details (host, state, autoscaling)
+        try:
+            ep = w.postgres.get_endpoint(name=LAKEBASE_INSTANCE)
+            if ep.status:
+                lakebase_host = (ep.status.hosts.host if ep.status.hosts else "") or ""
+                lakebase_status = (ep.status.current_state.value
+                                   if ep.status.current_state else "UNKNOWN")
+                lakebase_min_cu = ep.status.autoscaling_limit_min_cu or 0.0
+                lakebase_max_cu = ep.status.autoscaling_limit_max_cu or 0.0
+        except Exception as e:
+            log.warning(f"Could not fetch Lakebase endpoint details: {e}")
+
+        # Fetch project UID (needed for the Databricks UI URL) + pg_version
+        try:
+            projects_resp = w.api_client.do("GET", "/api/2.0/postgres/projects")
+            for proj in (projects_resp.get("projects") or []):
+                if proj.get("name") == f"projects/{lakebase_project}":
+                    lakebase_project_uid = proj.get("uid", "")
+                    lakebase_pg_version = (proj.get("status") or {}).get("pg_version", 0)
+                    break
+        except Exception as e:
+            log.warning(f"Could not fetch Lakebase projects list: {e}")
+
+    # Supervisor tile_id — written to SUPERVISOR_TILE_ID env var by the operational_lakebase stage
+    supervisor_tile_id = SUPERVISOR_TILE_ID
+
+    # Workspace numeric ID for ?o= deep-link parameter — try several sources
+    workspace_id = os.environ.get("DATABRICKS_WORKSPACE_ID", "")
+    if not workspace_id:
+        try:
+            resp = w.api_client.do("GET", "/api/2.0/workspaces-metadata")
+            workspace_id = str(resp.get("workspace_id", ""))
+        except Exception:
+            pass
+    if not workspace_id:
+        # Azure workspaces encode the numeric ID in the hostname: adb-{id}.{n}.azuredatabricks.net
+        m = re.search(r"adb-(\d+)", host)
+        if m:
+            workspace_id = m.group(1)
+
+    # MLflow experiment — ID is written to SUPERVISOR_MLFLOW_EXPERIMENT_ID by the operational_lakebase stage.
+    # Fall back to name-based search if the env var isn't populated yet.
+    mlflow_experiment_id = SUPERVISOR_MLFLOW_EXP_ID
+    mlflow_experiment_url = ""
+    if mlflow_experiment_id:
+        org_param = f"?o={workspace_id}" if workspace_id else ""
+        mlflow_experiment_url = f"{host}/ml/experiments/{mlflow_experiment_id}/traces{org_param}"
+    elif SUPERVISOR_ENDPOINT:
+        try:
+            org_param = f"?o={workspace_id}" if workspace_id else ""
+            for _f in [
+                f"name = '/Serving/{SUPERVISOR_ENDPOINT}'",
+                f"name = '{SUPERVISOR_ENDPOINT}'",
+                f"name ILIKE '%{SUPERVISOR_ENDPOINT}%'",
+            ]:
+                exps = list(w.experiments.search_experiments(filter=_f, max_results=5))
+                if exps:
+                    mlflow_experiment_id = exps[0].experiment_id
+                    mlflow_experiment_url = f"{host}/ml/experiments/{mlflow_experiment_id}/traces{org_param}"
+                    log.info(f"MLflow experiment found: {exps[0].name} (filter={_f!r})")
+                    break
+            if not mlflow_experiment_id:
+                log.warning(f"No MLflow experiment found for endpoint '{SUPERVISOR_ENDPOINT}' — traces may not have been written yet")
+        except Exception as e:
+            log.warning(f"Could not fetch MLflow experiment: {e}")
+
+    # Evaluation notebook — bundle deploys to:
+    #   /Workspace/Users/{deploying_human}/caspers-kitchens-demo/apps/caspers-ops-dashboard
+    # Derive the notebook path from the app's own active deployment source_code_path,
+    # which always contains the real deploying user. This works because the app SP
+    # can query its own app object, even if it can't list /Users.
+    #
+    # P1-18: app name is no longer hardcoded — it's catalog-scoped at deploy time
+    # (e.g. `ops-dashboard-oleksandra`) and threaded through via the runtime
+    # `DATABRICKS_APP_NAME` env var.  The source directory is still
+    # `apps/caspers-ops-dashboard/` (bundle layout), so the suffix-strip below
+    # is independent of the app's runtime name.
+    eval_notebook_url = ""
+    if host:
+        try:
+            app_obj = w.apps.get(APP_NAME)
+            src = ""
+            ad = getattr(app_obj, "active_deployment", None)
+            if ad:
+                src = getattr(ad, "source_code_path", "") or ""
+            if not src:
+                for dep in w.apps.list_deployments(APP_NAME):
+                    s = getattr(dep, "source_code_path", "") or ""
+                    if s:
+                        src = s
+                        break
+            if src:
+                # src = "/Workspace/Users/{user}/caspers-kitchens-demo/apps/caspers-ops-dashboard"
+                # strip /apps/caspers-ops-dashboard suffix → bundle root (keep /Workspace prefix)
+                bundle_root = src.removesuffix("/apps/caspers-ops-dashboard")
+                nb_path = f"{bundle_root}/stages/operational_evaluation"
+                eval_notebook_url = f"{host}/#workspace{nb_path}"
+                log.info(f"Eval notebook URL derived from deployment: {eval_notebook_url}")
+            else:
+                log.warning("Could not find source_code_path in app deployment")
+        except Exception as e:
+            log.warning(f"Could not resolve eval notebook via app deployment: {e}")
+
+    # Full Operations dashboard embed URLs — used by the opt-in "Ops
+    # Dashboard" tab in the left sidebar.  Two variants are published
+    # (light + dark) because Databricks embedded dashboards always render
+    # their `light` theme slot regardless of the `?theme=` URL parameter.
+    # The frontend swaps the iframe `src` between these two URLs when the
+    # user toggles the app theme.  The Revenue card on the always-visible
+    # view uses Chart.js instead of an embed (the embed's other quirks —
+    # fixed canvas width, separate workspace login on first view — were
+    # deal-breakers there but acceptable for an opt-in tab).
+    def _embed_url(d_id: str) -> str:
+        if not (d_id and host):
+            return ""
+        org_param = f"?o={workspace_id}" if workspace_id else ""
+        page_frag = f"#page={OPS_DASHBOARD_PAGE}" if OPS_DASHBOARD_PAGE else ""
+        return f"{host}/embed/dashboardsv3/{d_id}{org_param}{page_frag}"
+
+    ops_dashboard_embed_url       = _embed_url(OPS_DASHBOARD_ID)
+    ops_dashboard_embed_url_dark  = _embed_url(OPS_DASHBOARD_ID_DARK or OPS_DASHBOARD_ID)
+    ops_dashboard_embed_url_light = ops_dashboard_embed_url
+
+    return {
+        "databricks_host": host,
+        "current_user": me.user_name,
+        "catalog": CATALOG,
+        "lakebase_endpoint": LAKEBASE_INSTANCE,
+        "lakebase_project": lakebase_project,
+        "lakebase_project_uid": lakebase_project_uid,
+        "lakebase_host": lakebase_host,
+        "lakebase_dbname": lakebase_dbname,
+        "lakebase_status": lakebase_status,
+        "lakebase_min_cu": lakebase_min_cu,
+        "lakebase_max_cu": lakebase_max_cu,
+        "lakebase_pg_version": lakebase_pg_version,
+        "supervisor_endpoint": SUPERVISOR_ENDPOINT,
+        "supervisor_tile_id": supervisor_tile_id,
+        "workspace_id": workspace_id,
+        "warehouse_id": WAREHOUSE_ID,
+        "db_enabled": bool(LAKEBASE_INSTANCE),
+        "supervisor_enabled": bool(SUPERVISOR_ENDPOINT),
+        "refund_agent_endpoint": REFUND_AGENT_ENDPOINT,
+        "complaint_agent_endpoint": COMPLAINT_AGENT_ENDPOINT,
+        "refund_manager_app_url": REFUND_MANAGER_APP_URL,
+        "mlflow_experiment_id": mlflow_experiment_id,
+        "mlflow_experiment_url": mlflow_experiment_url,
+        "eval_notebook_url": eval_notebook_url,
+        "ops_dashboard_id": OPS_DASHBOARD_ID,
+        "ops_dashboard_id_dark": OPS_DASHBOARD_ID_DARK,
+        "ops_dashboard_page": OPS_DASHBOARD_PAGE,
+        "ops_dashboard_embed_url": ops_dashboard_embed_url,
+        "ops_dashboard_embed_url_light": ops_dashboard_embed_url_light,
+        "ops_dashboard_embed_url_dark": ops_dashboard_embed_url_dark,
+    }
+
+
+# ─── Sessions ─────────────────────────────────────────────────────────────────
+
+class SessionCreate(BaseModel):
+    title: str = "New Session"
+
+
+class SessionRename(BaseModel):
+    title: str
+
+
+@app.get("/api/sessions")
+def list_sessions():
+    if not LAKEBASE_INSTANCE:
+        return []
+    try:
+        with get_conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "SELECT id, title, created_at, updated_at "
+                    "FROM sessions ORDER BY updated_at DESC LIMIT 50"
+                )
+                rows = cur.fetchall()
+        return [
+            {"id": str(r[0]), "title": r[1], "created_at": r[2].isoformat(), "updated_at": r[3].isoformat()}
+            for r in rows
+        ]
+    except Exception as e:
+        log.error(f"list_sessions: {e}")
+        return []
+
+
+@app.post("/api/sessions", status_code=201)
+def create_session(body: SessionCreate):
+    if not LAKEBASE_INSTANCE:
+        return {"id": str(uuid.uuid4()), "title": body.title}
+    with get_conn() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                "INSERT INTO sessions (title) VALUES (%s) RETURNING id, title, created_at, updated_at",
+                (body.title,),
+            )
+            row = cur.fetchone()
+        conn.commit()
+    return {"id": str(row[0]), "title": row[1], "created_at": row[2].isoformat(), "updated_at": row[3].isoformat()}
+
+
+@app.put("/api/sessions/{session_id}")
+def rename_session(session_id: str, body: SessionRename):
+    if not LAKEBASE_INSTANCE:
+        return {"ok": True}
+    with get_conn() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                "UPDATE sessions SET title=%s, updated_at=NOW() WHERE id=%s",
+                (body.title, session_id),
+            )
+        conn.commit()
+    return {"ok": True}
+
+
+@app.delete("/api/sessions/{session_id}")
+def delete_session(session_id: str):
+    if not LAKEBASE_INSTANCE:
+        return {"ok": True}
+    with get_conn() as conn:
+        with conn.cursor() as cur:
+            cur.execute("DELETE FROM sessions WHERE id=%s", (session_id,))
+        conn.commit()
+    return {"ok": True}
+
+
+@app.get("/api/sessions/{session_id}/messages")
+def get_messages(session_id: str):
+    if not LAKEBASE_INSTANCE:
+        return []
+    try:
+        with get_conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "SELECT id, role, content, created_at, documents_referenced "
+                    "FROM messages WHERE session_id=%s ORDER BY created_at ASC",
+                    (session_id,),
+                )
+                rows = cur.fetchall()
+        return [
+            {
+                "id": str(r[0]),
+                "role": r[1],
+                "content": r[2],
+                "created_at": r[3].isoformat(),
+                "documents_referenced": r[4] or [],
+            }
+            for r in rows
+        ]
+    except Exception as e:
+        log.error(f"get_messages: {e}")
+        return []
+
+
+def _save_message(session_id: str, role: str, content: str, docs: list) -> bool:
+    """Persist a message to Lakebase. Returns True on success, False on DB failure."""
+    if not LAKEBASE_INSTANCE:
+        return True
+    try:
+        with get_conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "INSERT INTO messages (session_id, role, content, documents_referenced) "
+                    "VALUES (%s, %s, %s, %s)",
+                    (session_id, role, content, json.dumps(docs)),
+                )
+                cur.execute(
+                    "UPDATE sessions SET updated_at=NOW() WHERE id=%s",
+                    (session_id,),
+                )
+            conn.commit()
+        return True
+    except Exception as e:
+        log.error(f"save_message: {e}")
+        return False
+
+
+# ─── Chat (streaming) ─────────────────────────────────────────────────────────
+
+class ChatRequest(BaseModel):
+    session_id: str
+    message: str
+
+
+def _extract_doc_refs(text: str) -> list[dict]:
+    """Extract document references by file-ID pattern (mirrors frontend findMentionedDocs).
+
+    Matches IDs like CK-04-0031, AUD-02-3006, REG-01-0002 that correspond to
+    actual filenames in the UC volumes. Avoids false positives from keyword-based
+    heuristics that trigger on any mention of "audit" or "legal".
+    """
+    pattern = re.compile(r'\b(CK|CON|AUD|REG|INS)-([\w-]+)', re.IGNORECASE)
+    seen: set[str] = set()
+    docs = []
+    for m in pattern.finditer(text):
+        ref_id = m.group(0).upper()
+        if ref_id not in seen:
+            seen.add(ref_id)
+            docs.append({"id": ref_id, "snippet": m.group(0)})
+        if len(docs) >= 5:
+            break
+    return docs
+
+
+# Known agent/supervisor labels injected inline by the MAS response
+_AGENT_LABELS = [
+    CATALOG + "-operational-supervisor",
+    "revenue-analytics",
+    "operations-intelligence",
+    "menu-analytics",
+    "inspection-reports",
+    "menu-document-search",
+    "legal-complaints",
+    "regulatory-compliance",
+    "audit-findings",
+    "consultancy-strategy",
+    "refund-agent",
+    "complaint-agent",
+]
+
+def _clean_mas_text(text: str) -> str:
+    """Clean up MAS response: strip injected agent labels, footnotes, and fix broken markdown tables.
+
+    The MAS concatenates content without newlines, producing patterns like:
+      '...sentence.agent-name||col1|col2| |-|-| |v1|v2| |v3|v4|Next sentence'
+    We strip the labels then restore proper table row newlines.
+
+    Knowledge Assistant responses include footnote citations like [^id] inline
+    and [^id]: <source content> definitions at the bottom — both are stripped
+    since marked.js doesn't render them as footnotes and the raw text is noisy.
+    """
+    # 1. Strip agent/supervisor labels that appear inline
+    for label in _AGENT_LABELS:
+        text = text.replace(label, "")
+
+    # 1b. Strip the MAS routing announcement that precedes the actual answer.
+    #     e.g. "I'll query the operations intelligence system to identify..."
+    #          "I'm going to check the legal complaints database..."
+    text = re.sub(
+        r"^I'(?:ll|m going to) (?:query|check|access|search|look up|pull|retrieve|examine|analyze|review|consult|use)[^.!?]*[.!?]\s*",
+        '', text, flags=re.IGNORECASE,
+    )
+
+    # 1c. Strip KA/Genie error lines that the MAS injects when a sub-agent fails
+    #     e.g. "Error: KA endpoint ka-XXXX-endpoint failed: unable to parse response..."
+    #          "Error: Failed to query Genie space XXXX: ..."
+    text = re.sub(r'Error:\s*KA endpoint [^\n]+\n?', '', text)
+    text = re.sub(r'Error:\s*Failed to query Genie space [^\n]+\n?', '', text)
+
+    # 2. Strip footnote definition lines (e.g. [^1]: Source...) — remove each line
+    #    individually rather than cutting the whole response, because KAs emit
+    #    citations inline (not just as a block at the bottom).
+    text = re.sub(r'(?m)^\[\^[^\]]+\]:.*$', '', text)
+
+    # 3. Strip any remaining inline footnote reference markers: [^id]
+    text = re.sub(r'\[\^[^\]]+\]', '', text)
+
+    # 4. Fix tables. After label removal, table blocks look like:
+    #      "||col1|col2| |-|-| |0|val1| |1|val2|Next text"
+    # a) "||" = agent-separator + table-start → blank line before table, single pipe
+    text = re.sub(r'\|\|', '\n\n|', text)
+    # b) "| |" = closing pipe + space + opening pipe of next row → single newline
+    #    (must be single, not double — blank lines between rows break markdown tables)
+    text = re.sub(r'\| \|', '|\n|', text)
+    # c) End of table: pipe followed by a markdown heading
+    text = re.sub(r'\|(#{1,6} )', r'|\n\n\1', text)
+    # d) Pipe + capital letter that is NOT a table cell value.
+    #    Use negative lookahead: only fires when no further pipe follows on the same line
+    #    (a table cell would have `|Capital...|` whereas end-of-table is `|Capital word...`).
+    text = re.sub(r'\|([A-Z*_\[])(?![^|\n]*\|)', r'|\n\n\1', text)
+    # e) Table header rows missing a leading pipe: Genie returns headers like
+    #    "col1|col2|col3|" without a leading |. marked.js requires it.
+    text = re.sub(r'(?m)^([A-Za-z_][^|\n]*(?:\|[^\n]*)+\|)\s*$', r'|\1', text)
+    # f) Strip pandas DataFrame integer row-index column.
+    #    Genie wraps results in a DataFrame whose index (0, 1, 2...) becomes an
+    #    unnamed first column: header has N cols, separator+data rows have N+1.
+    #    Detect this mismatch and strip the extra leading cell from separator and
+    #    data rows so marked.js sees consistent column counts.
+    _lines = text.split('\n')
+    _i = 0
+    while _i < len(_lines):
+        if (_i + 1 < len(_lines)
+                and _lines[_i].startswith('|')
+                and re.match(r'^\|[-: |]+\|$', _lines[_i + 1])):
+            _hdr_cols = _lines[_i].count('|') - 1
+            _sep_cols = _lines[_i + 1].count('|') - 1
+            if _sep_cols == _hdr_cols + 1:
+                _lines[_i + 1] = re.sub(r'^\|[^|]*', '', _lines[_i + 1])
+                _j = _i + 2
+                while _j < len(_lines) and _lines[_j].startswith('|'):
+                    _lines[_j] = re.sub(r'^\|\d+\|', '|', _lines[_j])
+                    _j += 1
+        _i += 1
+    text = '\n'.join(_lines)
+
+    # 5. Collapse 3+ blank lines → 2
+    text = re.sub(r'\n{3,}', '\n\n', text)
+
+    return text.strip()
+
+
+def _extract_delta(obj: dict) -> str:
+    """Extract text from one SSE event (Responses API or Chat Completions streaming format)."""
+    # OpenAI Responses API: response.output_text.delta
+    if obj.get("type") == "response.output_text.delta":
+        return obj.get("delta", "")
+    # Chat Completions streaming: choices[0].delta.content
+    choices = obj.get("choices", [])
+    if choices:
+        return choices[0].get("delta", {}).get("content", "") or ""
+    return ""
+
+
+# Vocabulary signals used to detect which sub-agent handled the response.
+# Ordered by specificity — more specific signals first so they don't shadow each other.
+_ROUTING_SIGNALS: list[tuple[str, list[str]]] = [
+    ("⚖️ Legal Complaints",  ["case no", "ck-", "risk level", "amount at stake", "legal counsel", "litigation", "plaintiff", "settlement amount"]),
+    ("📋 Regulatory",        ["permit no", "certificate no", "expiry date", "issuing authority", "fda registration", "zoning permit", "conditional status"]),
+    ("🔍 Audit Findings",    ["audit report", "auditor", "pwc", "deloitte", "kpmg", "critical finding", "significant finding", "remediation deadline"]),
+    ("💼 Consultancy",       ["consulting firm", "roi estimate", "mckinsey", "phase 1", "phase 2", "strategic recommendation", "projected saving"]),
+    ("🛡️ Inspections",       ["inspection report", "corrective action", "inspector", "food safety score", "inspection grade", "health permit"]),
+    ("📊 Revenue Analytics", ["cancellation rate", "avg order value", "orders placed", "total orders", "weekly revenue", "order count"]),
+    ("⚙️ Operations",        ["complaint rate", "cancel rate", "food safety grade", "kitchen throughput", "busiest hour", "operational risk"]),
+]
+
+
+def _detect_routing(text: str) -> str:
+    """Detect which sub-agent(s) handled a response from vocabulary signals in the text."""
+    lower = text.lower()
+    scored = sorted(
+        [(label, sum(1 for s in sigs if s in lower)) for label, sigs in _ROUTING_SIGNALS],
+        key=lambda x: -x[1],
+    )
+    hits = [(label, score) for label, score in scored if score >= 1]
+    if not hits:
+        return ""
+    # Three or more agents with meaningful signal → multi-agent synthesis
+    if len(hits) >= 3 and hits[2][1] >= 2:
+        return "🏗️ Multi-agent synthesis"
+    return hits[0][0]
+
+
+async def _stream_supervisor(message: str, session_id: str = "") -> AsyncIterator[str]:
+    """Stream the ops supervisor MAS endpoint, yielding SSE content chunks as tokens arrive.
+
+    MAS can take 30-90 s before sending the first token while it orchestrates
+    sub-agents. Without periodic activity the reverse proxy in front of the
+    Databricks App times out the idle connection. Every 5 s of silence we send
+    a {"thinking": true} SSE event so the frontend can show an animated dots
+    indicator to let the user know the agent is still working.
+    """
+    if not SUPERVISOR_ENDPOINT:
+        yield "data: " + json.dumps({"content": "⚠️ Supervisor endpoint not configured."}) + "\n\n"
+        yield "data: [DONE]\n\n"
+        return
+
+    url = f"{(_sdk_config.host or '').rstrip('/')}/serving-endpoints/{SUPERVISOR_ENDPOINT}/invocations"
+    headers = {"Content-Type": "application/json"}
+    headers.update(_sdk_config.authenticate())  # returns {"Authorization": "Bearer <token>"}
+    if session_id:
+        headers["Databricks-Source-Conversation-Id"] = session_id
+    body = {"input": [{"role": "user", "content": message}], "stream": True}
+
+    # Bridge the upstream httpx stream into an asyncio.Queue so we can inject
+    # thinking-indicator frames between chunks without blocking the generator.
+    _KEEPALIVE_S = 5
+    _SENTINEL = object()
+    queue: asyncio.Queue = asyncio.Queue()
+
+    async def _fetch():
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(300, connect=30.0)) as client:
+                async with client.stream("POST", url, headers=headers, json=body) as resp:
+                    resp.raise_for_status()
+                    async for line in resp.aiter_lines():
+                        await queue.put(line)
+        except Exception as exc:
+            log.error(f"Supervisor streaming error: {exc}", exc_info=True)
+            await queue.put(exc)
+        finally:
+            await queue.put(_SENTINEL)
+
+    task = asyncio.create_task(_fetch())
+    try:
+        while True:
+            try:
+                item = await asyncio.wait_for(queue.get(), timeout=_KEEPALIVE_S)
+            except asyncio.TimeoutError:
+                yield "data: " + json.dumps({"thinking": True}) + "\n\n"
+                continue
+
+            if item is _SENTINEL:
+                break
+            if isinstance(item, Exception):
+                yield "data: " + json.dumps({"content": f"\n\n⚠️ Error contacting supervisor: {item}"}) + "\n\n"
+                break
+
+            line = item
+            if not line.startswith("data:"):
+                continue
+            data = line[5:].strip()
+            if data == "[DONE]":
+                log.info("SSE stream ended with [DONE]")
+                break
+            try:
+                obj = json.loads(data)
+                text = _extract_delta(obj)
+                if text:
+                    yield "data: " + json.dumps({"content": text}) + "\n\n"
+            except json.JSONDecodeError:
+                pass
+    finally:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+    yield "data: [DONE]\n\n"
+
+
+@app.post("/api/chat")
+async def chat(req: ChatRequest):
+    asyncio.get_event_loop().run_in_executor(None, _save_message, req.session_id, "user", req.message, [])
+
+    full_response = []
+
+    async def generate():
+        async for chunk in _stream_supervisor(req.message, session_id=req.session_id):
+            if chunk.strip() == "data: [DONE]":
+                # Emit routing detection before DONE so the frontend can show which agent handled this
+                complete_text = "".join(full_response)
+                routing = _detect_routing(complete_text)
+                if routing:
+                    yield "data: " + json.dumps({"routing": routing}) + "\n\n"
+                docs = _extract_doc_refs(complete_text)
+                if not _save_message(req.session_id, "assistant", complete_text, docs):
+                    yield "data: " + json.dumps({"warning": "⚠️ Session history could not be saved."}) + "\n\n"
+                yield chunk
+                return
+            if chunk.startswith("data: "):
+                try:
+                    data = json.loads(chunk[6:].strip())
+                    full_response.append(data.get("content", ""))
+                except Exception:
+                    pass
+            yield chunk
+
+        # Stream ended without explicit [DONE] (connection drop) — still save
+        complete_text = "".join(full_response)
+        docs = _extract_doc_refs(complete_text)
+        _save_message(req.session_id, "assistant", complete_text, docs)
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",   # disable nginx buffering
+        },
+    )
+
+
+# ─── Revenue Data ─────────────────────────────────────────────────────────────
+#
+# Both `/api/revenue` (chart) and `/api/locations` (map) need the same
+# per-location aggregates.  They are fetched in parallel by the frontend on
+# every page load.  Two compounding problems used to make this slow:
+#   1. Each endpoint independently hit the warehouse with the same SQL —
+#      the locations route called revenue() inline.  Two warm queries per
+#      page load (~4-8 s total) for identical data.
+#   2. The SQL itself anti-joined two `SELECT DISTINCT` scans over 30 days
+#      of raw `lakeflow.all_events` to derive cancellation counts (no gold
+#      table covered the delivered/cancelled side).  That CTE alone was
+#      ~1.8 s of every query.
+#
+# Fixes (all permanent / survive `bundle destroy` → `deploy`):
+#   * The pipeline now publishes `gold_location_order_status_daily`
+#     (see pipelines/order_items/transformations/transformation.py) which
+#     pre-aggregates created/delivered/cancelled per location per day.
+#     The SQL below reads only gold tables — no `all_events` scan.
+#   * A thread-safe in-process TTL cache (`_REVENUE_TTL_S`) sits in front
+#     of the SQL.  `/api/locations` reuses the cached result via
+#     `_get_revenue_cached()`, so the warehouse is hit at most once per
+#     TTL window even under concurrent /api/revenue + /api/locations load.
+#   * On query failure we serve the previous cached snapshot (if any) so
+#     a transient warehouse hiccup doesn't flap the dashboard.  When even
+#     the cache is empty, the route raises 503 — by design, the frontend
+#     must NEVER silently show fabricated numbers during a live demo, so
+#     the old "_mock_revenue() fallback" was removed deliberately.
+
+_REVENUE_TTL_S = 60  # 30-day aggregates change very slowly; 60s is safe.
+_revenue_cache: dict = {"data": None, "ts": 0.0}
+_revenue_lock = threading.Lock()
+
+
+def _fetch_revenue_from_warehouse() -> list[dict]:
+    """Execute the revenue SQL against the ops warehouse.  Heavy: ~0.5-2 s warm.
+
+    Returns a list of dicts with revenue, revenue_prev, avg_order_value,
+    total_orders, completed_orders, cancelled_orders, complaints, and
+    cancel_rate_pct keyed by location.  Raises on any failure — the caller
+    (`_get_revenue_cached`) is responsible for the stale-cache fallback.
+    """
+    from databricks import sql as dbsql
+    # databricks-sql-connector expects `credentials_provider` to be a
+    # zero-arg callable that returns a *header factory* — itself a zero-arg
+    # callable that returns the Authorization header dict. Passing a dict
+    # directly (or a one-shot snapshot of `_sdk_config.token`) crashes the
+    # connector with `'dict' object is not callable` and breaks every
+    # OAuth-M2M refresh. `_sdk_config.authenticate` is the SDK's bound
+    # method that returns a fresh `{"Authorization": "Bearer …"}` each
+    # call, so handing it off as the header factory gets us auto-refresh.
+    conn = dbsql.connect(
+        server_hostname=_sdk_config.host.replace("https://", ""),
+        http_path=f"/sql/1.0/warehouses/{WAREHOUSE_ID}",
+        credentials_provider=lambda: _sdk_config.authenticate,
+    )
+    try:
+        cursor = conn.cursor()
+        # All four CTEs read from pre-aggregated gold tables.  The old
+        # anti-join over `all_events` is gone — see
+        # `gold_location_order_status_daily` in the order_items pipeline
+        # for how created/delivered/cancelled is now materialised.
+        cursor.execute(f"""
+            WITH current_period AS (
+                SELECT
+                    location_id,
+                    SUM(revenue)  AS revenue,
+                    SUM(orders)   AS total_orders
+                FROM {CATALOG}.lakeflow.gold_location_sales_hourly
+                WHERE hour_ts >= current_timestamp() - INTERVAL 30 DAYS
+                GROUP BY location_id
+            ),
+            prev_period AS (
+                SELECT
+                    location_id,
+                    SUM(revenue) AS revenue_prev
+                FROM {CATALOG}.lakeflow.gold_location_sales_hourly
+                WHERE hour_ts >= current_timestamp() - INTERVAL 60 DAYS
+                  AND hour_ts <  current_timestamp() - INTERVAL 30 DAYS
+                GROUP BY location_id
+            ),
+            avg_order AS (
+                SELECT
+                    location_id,
+                    ROUND(AVG(order_revenue), 2) AS avg_order_value
+                FROM {CATALOG}.lakeflow.gold_order_header
+                WHERE order_day >= current_date() - INTERVAL 30 DAYS
+                GROUP BY location_id
+            ),
+            cancel_stats AS (
+                SELECT
+                    CAST(location_id AS STRING) AS location_id,
+                    SUM(created_count)   AS created_total,
+                    SUM(cancelled_count) AS cancelled_orders
+                FROM {CATALOG}.lakeflow.gold_location_order_status_daily
+                WHERE day >= current_date() - INTERVAL 30 DAYS
+                GROUP BY location_id
+            )
+            SELECT
+                l.name            AS location,
+                l.location_id,
+                ROUND(COALESCE(c.revenue, 0), 0)       AS revenue,
+                ROUND(COALESCE(p.revenue_prev, 0), 0)  AS revenue_prev,
+                COALESCE(a.avg_order_value, 0)         AS avg_order_value,
+                COALESCE(c.total_orders, 0)            AS total_orders,
+                COALESCE(c.total_orders, 0) - COALESCE(cs.cancelled_orders, 0) AS completed_orders,
+                COALESCE(cs.cancelled_orders, 0)       AS cancelled_orders,
+                0                                      AS complaints,
+                CASE
+                    WHEN COALESCE(cs.created_total, 0) > 0
+                    THEN ROUND(100.0 * cs.cancelled_orders / cs.created_total, 1)
+                    ELSE 0.0
+                END                                    AS cancel_rate_pct
+            FROM {CATALOG}.simulator.locations l
+            LEFT JOIN current_period c  ON CAST(l.location_id AS STRING) = c.location_id
+            LEFT JOIN prev_period    p  ON CAST(l.location_id AS STRING) = p.location_id
+            LEFT JOIN avg_order      a  ON CAST(l.location_id AS STRING) = a.location_id
+            LEFT JOIN cancel_stats   cs ON CAST(l.location_id AS STRING) = cs.location_id
+            ORDER BY revenue DESC
+        """)
+        rows = cursor.fetchall()
+        cols = [d[0] for d in cursor.description]
+        cursor.close()
+        return [dict(zip(cols, r)) for r in rows]
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+
+
+def _get_revenue_cached() -> list[dict]:
+    """Return revenue rows from the TTL cache, refreshing if stale.
+
+    Falls back to the previous cached snapshot on warehouse failure (avoids
+    flapping the dashboard during a transient outage).  Raises ``RuntimeError``
+    when the cache is empty AND the live fetch fails — the route layer turns
+    that into a 503 so the dashboard surfaces "revenue unavailable" instead
+    of silently demoing fabricated numbers.
+    """
+    if not WAREHOUSE_ID:
+        raise RuntimeError(
+            "WAREHOUSE_ID env var is not set — the ops-dashboard app needs a "
+            "SQL warehouse to compute revenue.  Check the bundle's "
+            "operational_app stage and the app.yaml that it writes."
+        )
+
+    now = time.time()
+    cached = _revenue_cache["data"]
+    if cached is not None and (now - _revenue_cache["ts"]) < _REVENUE_TTL_S:
+        return cached
+
+    # Coalesce concurrent refreshers so the warehouse is hit at most once
+    # per TTL window even under simultaneous /api/revenue + /api/locations.
+    with _revenue_lock:
+        # Re-check under the lock — another thread may have refreshed.
+        cached = _revenue_cache["data"]
+        if cached is not None and (time.time() - _revenue_cache["ts"]) < _REVENUE_TTL_S:
+            return cached
+        try:
+            data = _fetch_revenue_from_warehouse()
+            _revenue_cache["data"] = data
+            _revenue_cache["ts"] = time.time()
+            return data
+        except Exception as e:
+            log.error(f"revenue query failed: {e}")
+            if cached is not None:
+                log.warning(
+                    "returning stale revenue cache after refresh failure "
+                    "(this is safer than mock data — but the next deploy "
+                    "should investigate why the warehouse query failed)"
+                )
+                return cached
+            # No cache to fall back on.  Raise so /api/revenue returns 503
+            # rather than silently rendering fabricated numbers — the latter
+            # is a worse demo failure mode than a visible "unavailable"
+            # banner, because the audience would never know the numbers are
+            # fake.
+            raise
+
+
+@app.get("/api/revenue")
+def revenue():
+    """Revenue summary by location, served from a 60 s TTL cache.
+
+    Returns the data list on success.  On hard failure (warehouse not
+    configured, query failed, AND no cached snapshot to fall back on) we
+    return a 503 with a structured ``{"error": ..., "detail": ...}`` body
+    so the frontend can render an explicit "revenue unavailable" banner
+    rather than fall back to hardcoded mock numbers.
+    """
+    try:
+        return _get_revenue_cached()
+    except Exception as e:
+        # Per the comment in `_get_revenue_cached()`, raising-not-mocking
+        # is intentional — fail visibly instead of silently demoing
+        # fabricated revenue figures.
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": "revenue_unavailable",
+                "message": (
+                    "Revenue analytics are temporarily unavailable.  This is "
+                    "usually a transient SQL warehouse hiccup; retry in a "
+                    "few seconds.  Persistent failures point to the gold "
+                    "tables (caspers.lakeflow.gold_location_sales_hourly, "
+                    "gold_order_header, gold_location_order_status_daily) "
+                    "not having materialised yet."
+                ),
+                "underlying": f"{type(e).__name__}: {e}",
+            },
+        ) from e
+
+
+# ─── Quick Actions (direct KA call, server-side cache) ───────────────────────
+
+_QUICK_ACTION_PROMPTS = {
+    "hire": "Which consultants should we bring in and why would they be worth the fees? Be concise — 3 bullet points max.",
+    "fire": "Which consulting engagements are burning cash without results? Be concise — 3 bullet points max.",
+    "ai":   "Where can we actually use AI — show me the ROI, not the buzzwords. Be concise — 3 bullet points max.",
+}
+
+# Populated at startup by background threads so button clicks are instant
+_action_cache: dict[str, str] = {}
+
+
+def _call_ka_direct(endpoint_id: str, question: str) -> str:
+    """Call a KA serving endpoint directly, bypassing the MAS supervisor.
+
+    KA endpoints accept the standard OpenAI messages format.
+    Calling KA directly removes two LLM hops (MAS routing + MAS synthesis).
+    """
+    w = _ws
+    ep_name = f"ka-{endpoint_id[:8]}-endpoint"
+    try:
+        data = w.api_client.do(
+            "POST",
+            f"/serving-endpoints/{ep_name}/invocations",
+            body={"messages": [{"role": "user", "content": question}]},
+        )
+        text = (data.get("choices", [{}])[0]
+                    .get("message", {})
+                    .get("content", ""))
+        if not text:
+            for out in data.get("output", []):
+                for part in out.get("content", []):
+                    text += part.get("text", "")
+        return _clean_mas_text(text)
+    except Exception as e:
+        log.error(f"Direct KA call failed for {ep_name}: {e}")
+        raise
+
+
+def _prefetch_action(action_type: str, ka_id: str) -> None:
+    """Call KA and store result in server-side cache. Runs in a background thread at startup."""
+    try:
+        text = _call_ka_direct(ka_id, _QUICK_ACTION_PROMPTS[action_type])
+        if text:
+            _action_cache[action_type] = text
+            log.info(f"Quick-action cache populated: '{action_type}' ({len(text)} chars)")
+    except Exception as e:
+        log.warning(f"Quick-action pre-fetch failed for '{action_type}': {e}")
+
+
+@app.get("/api/quick-action/{action_type}")
+def quick_action(action_type: str):
+    """Return a cached consultancy KA answer (populated at startup).
+
+    If the cache is still being built (server just started), calls KA directly
+    and caches the result for subsequent requests.
+    """
+    if action_type not in _QUICK_ACTION_PROMPTS:
+        raise HTTPException(status_code=404, detail="Unknown action type")
+
+    if action_type in _action_cache:
+        log.info(f"Quick-action cache hit: '{action_type}'")
+        return {"action": action_type, "content": _action_cache[action_type], "cached": True}
+
+    # Cache miss — call KA directly and populate cache for next time
+    ka_id = os.environ.get("KA_ID_CONSULTANCY", "")
+    try:
+        text = _call_ka_direct(ka_id, _QUICK_ACTION_PROMPTS[action_type])
+        if text:
+            _action_cache[action_type] = text
+        return {"action": action_type, "content": text or "No response from knowledge base."}
+    except Exception as e:
+        log.error(f"Quick-action live call failed for '{action_type}': {e}")
+        return {"action": action_type, "content": None, "error": str(e)}
+
+
+# ─── Custom Agents (Refund & Complaint) ──────────────────────────────────────
+
+class RefundRequest(BaseModel):
+    order_id: str
+    # Optional context surfaced from the upstream complaint-agent triage. When
+    # present, the refund agent's system prompt allows it to ratify a goodwill
+    # credit even on a non-late order. When absent, the agent falls back to its
+    # SLA-only behavior (the standalone "Process Refund" action-bar button).
+    complaint_text: str | None = None
+    complaint_category: str | None = None
+    complaint_rationale: str | None = None
+    suggest_credit: float | None = None
+
+
+class ComplaintRequest(BaseModel):
+    complaint_text: str
+    order_id: str = ""
+
+
+def _call_agent_endpoint(endpoint_name: str, payload: dict) -> dict:
+    """Call a model serving endpoint (ChatAgent or ResponsesAgent) and return the parsed response body."""
+    url = f"{(_sdk_config.host or '').rstrip('/')}/serving-endpoints/{endpoint_name}/invocations"
+    headers = {"Content-Type": "application/json"}
+    headers.update(_sdk_config.authenticate())
+    resp = httpx.post(url, headers=headers, json=payload, timeout=120.0)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _build_refund_user_message(req: "RefundRequest") -> str:
+    """Compose the user message sent to the refund agent.
+
+    Without complaint context: just the bare order_id (preserves original
+    standalone-button behavior). With context: a short labelled block the agent
+    can recognize per its system prompt to optionally ratify a goodwill credit.
+    """
+    if not (req.complaint_text or req.complaint_category or req.suggest_credit):
+        return req.order_id
+    lines = [f"Order ID: {req.order_id}"]
+    if req.complaint_text:
+        lines.append(f'Customer complaint: "{req.complaint_text}"')
+    if req.complaint_category:
+        lines.append(f"Complaint category: {req.complaint_category}")
+    if req.suggest_credit is not None:
+        try:
+            lines.append(f"Complaint agent suggested credit: ${float(req.suggest_credit):.2f}")
+        except (TypeError, ValueError):
+            pass
+    if req.complaint_rationale:
+        lines.append(f"Complaint agent rationale: {req.complaint_rationale}")
+    return "\n".join(lines)
+
+
+@app.post("/api/refund")
+def refund(req: RefundRequest):
+    """Call the refund agent for a given order_id and return a structured decision."""
+    if not REFUND_AGENT_ENDPOINT:
+        raise HTTPException(status_code=503, detail="Refund agent endpoint not configured.")
+    try:
+        user_msg = _build_refund_user_message(req)
+        data = _call_agent_endpoint(
+            REFUND_AGENT_ENDPOINT,
+            {"messages": [{"role": "user", "content": user_msg}]},
+        )
+        # Extract the last assistant message from the ChatAgent response
+        messages = data.get("messages") or []
+        for msg in reversed(messages):
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            if role == "assistant" and content:
+                # Robustly extract a JSON object from the assistant message:
+                # the agent's prompt asks for raw JSON, but LLMs often wrap it in
+                # ```json … ``` fences or sprinkle commentary around it. Try a
+                # bare json.loads first, then fall back to the first {...} match.
+                cleaned = content.strip()
+                if cleaned.startswith("```"):
+                    # strip markdown code fence (```json … ``` or ``` … ```)
+                    cleaned = cleaned.strip("`")
+                    if cleaned.lower().startswith("json"):
+                        cleaned = cleaned[4:]
+                    cleaned = cleaned.strip()
+                decision = None
+                try:
+                    decision = json.loads(cleaned)
+                except Exception:
+                    import re as _re
+                    m = _re.search(r"\{[\s\S]*\}", cleaned)
+                    if m:
+                        try:
+                            decision = json.loads(m.group(0))
+                        except Exception:
+                            decision = None
+                if decision is not None:
+                    return {
+                        "order_id": req.order_id,
+                        "refund_usd": float(decision.get("refund_usd", 0)),
+                        "refund_class": decision.get("refund_class", "none"),
+                        "reason": decision.get("reason", ""),
+                    }
+                # Last-resort fallback: surface raw text so the UI can show something.
+                return {"order_id": req.order_id, "raw": content}
+        raise HTTPException(status_code=502, detail="No assistant message in refund agent response.")
+    except HTTPException:
+        raise
+    except Exception as e:
+        log.error(f"Refund agent call failed: {e}", exc_info=True)
+        raise HTTPException(status_code=502, detail=str(e))
+
+
+@app.post("/api/complaint")
+def complaint(req: ComplaintRequest):
+    """Call the complaint agent for a raw complaint text and return a structured classification."""
+    if not COMPLAINT_AGENT_ENDPOINT:
+        raise HTTPException(status_code=503, detail="Complaint agent endpoint not configured.")
+    content = req.complaint_text
+    if req.order_id:
+        content = f"{content} (Order ID: {req.order_id})"
+    try:
+        data = _call_agent_endpoint(
+            COMPLAINT_AGENT_ENDPOINT,
+            {"input": [{"role": "user", "content": content}]},
+        )
+        # ResponsesAgent returns output list or choices
+        output_text = ""
+        for out in data.get("output", []):
+            for part in (out.get("content") or []):
+                output_text += part.get("text", "")
+        if not output_text:
+            choices = data.get("choices") or []
+            if choices:
+                output_text = (choices[0].get("message") or {}).get("content", "")
+        if output_text:
+            try:
+                result = json.loads(output_text)
+                decision = result.get("decision", "")
+                return {
+                    "order_id": req.order_id or result.get("order_id", ""),
+                    "category": result.get("complaint_category", ""),
+                    "decision": decision,
+                    "suggest_credit": result.get("credit_amount") or 0,
+                    "escalate": decision == "escalate",
+                    "rationale": result.get("rationale", ""),
+                }
+            except Exception:
+                return {"order_id": req.order_id, "raw": output_text}
+        raise HTTPException(status_code=502, detail="No output in complaint agent response.")
+    except HTTPException:
+        raise
+    except Exception as e:
+        log.error(f"Complaint agent call failed: {e}", exc_info=True)
+        raise HTTPException(status_code=502, detail=str(e))
+
+
+@app.get("/api/complaint-decisions")
+def complaint_decisions():
+    """Return the 10 most recent complaint agent decisions from the Delta table."""
+    if not WAREHOUSE_ID:
+        raise HTTPException(status_code=503, detail="DATABRICKS_WAREHOUSE_ID not configured.")
+    if not CATALOG:
+        raise HTTPException(status_code=503, detail="DATABRICKS_CATALOG not configured.")
+    try:
+        from databricks import sql as dbsql
+        conn = dbsql.connect(
+            server_hostname=_sdk_config.host.replace("https://", ""),
+            http_path=f"/sql/1.0/warehouses/{WAREHOUSE_ID}",
+            credentials_provider=lambda: _sdk_config.authenticate,
+        )
+        cursor = conn.cursor()
+        cursor.execute(f"""
+            SELECT complaint_id, order_id, ts, agent_response
+            FROM {CATALOG}.complaints.complaint_responses
+            ORDER BY ts DESC
+            LIMIT 10
+        """)
+        rows = cursor.fetchall()
+        cursor.close()
+        conn.close()
+        results = []
+        for complaint_id, order_id, ts, agent_response in rows:
+            try:
+                parsed = json.loads(agent_response or "{}")
+            except Exception:
+                parsed = {}
+            decision = parsed.get("decision", "")
+            results.append({
+                "complaint_id": complaint_id,
+                "order_id": order_id or parsed.get("order_id", ""),
+                "ts": str(ts) if ts else "",
+                "category": parsed.get("complaint_category", ""),
+                "decision": decision,
+                "suggest_credit": parsed.get("credit_amount", 0.0),
+                "escalate": decision == "escalate",
+                "rationale": parsed.get("rationale", ""),
+                "customer_response": parsed.get("customer_response", ""),
+            })
+        return results
+    except HTTPException:
+        raise
+    except Exception as e:
+        log.warning(f"complaint_decisions: {e}")
+        raise HTTPException(status_code=502, detail=str(e))
+
+
+# ─── Sub-Agents ───────────────────────────────────────────────────────────────
+
+# KA tile names as created by the stage notebooks
+# Tile/space IDs are stable after creation; they are used as fallback when
+# the app service principal lacks list permissions on the tiles/genie APIs.
+# Override via env vars if resources are recreated.
+_KA_AGENTS = [
+    {"name": "Inspection Reports",   "icon": "🏥", "id": os.environ.get("KA_ID_INSPECTION")},
+    {"name": "Menu Documents",       "icon": "📖", "id": os.environ.get("KA_ID_MENU")},
+    {"name": "Legal Complaints",     "icon": "⚖️",  "id": os.environ.get("KA_ID_LEGAL")},
+    {"name": "Regulatory Docs",      "icon": "📋", "id": os.environ.get("KA_ID_REGULATORY")},
+    {"name": "Audit Findings",       "icon": "🔍", "id": os.environ.get("KA_ID_AUDITS")},
+    {"name": "Consultancy Strategy", "icon": "💼", "id": os.environ.get("KA_ID_CONSULTANCY")},
+]
+_GENIE_AGENTS = [
+    {"name": "Revenue Analytics", "icon": "📈", "id": os.environ.get("GENIE_ID_REVENUE")},
+    {"name": "Operations Intel",  "icon": "⚙️",  "id": os.environ.get("GENIE_ID_OPS")},
+    {"name": "Menu & Safety",     "icon": "🍽️",  "id": os.environ.get("GENIE_ID_MENU")},
+]
+
+@app.get("/api/agents")
+def list_agents():
+    """Return sub-agent details with direct Databricks UI links.
+
+    Uses stable hardcoded IDs — avoids slow/hanging API calls to tiles/genie/serving-endpoints
+    that the app service principal may lack permission for or that may time out.
+    KA endpoint names follow the deterministic pattern: ka-{first-8-chars-of-tile-id}-endpoint.
+    """
+    host = (_sdk_config.host or "").rstrip("/")
+    agents = []
+
+    for g in _GENIE_AGENTS:
+        space_id = g["id"]
+        url = f"{host}/genie/rooms/{space_id}" if space_id and host else ""
+        agents.append({"name": g["name"], "icon": g["icon"], "type": "genie",
+                        "url": url, "id": space_id})
+
+    for ka in _KA_AGENTS:
+        tile_id = ka["id"]
+        ep_name = f"ka-{tile_id[:8]}-endpoint" if tile_id else ""
+        url = f"{host}/ml/endpoints/{ep_name}" if ep_name and host else ""
+        agents.append({"name": ka["name"], "icon": ka["icon"], "type": "ka",
+                        "url": url, "id": tile_id})
+
+    _CUSTOM_AGENTS = [
+        {"name": "Refund Agent",    "icon": "💳", "endpoint": REFUND_AGENT_ENDPOINT},
+        {"name": "Complaint Agent", "icon": "📬", "endpoint": COMPLAINT_AGENT_ENDPOINT},
+    ]
+    for ca in _CUSTOM_AGENTS:
+        ep = ca["endpoint"]
+        url = f"{host}/ml/endpoints/{ep}" if ep and host else ""
+        agents.append({"name": ca["name"], "icon": ca["icon"], "type": "agent",
+                        "url": url, "id": ep})
+
+    return agents
+
+
+# ─── Documents ────────────────────────────────────────────────────────────────
+
+_DOC_SOURCES = [
+    {"category": "Legal Complaints",   "type": "legal",       "volume": "legal_complaints/documents"},
+    {"category": "Regulatory Docs",    "type": "regulatory",  "volume": "regulatory/documents"},
+    {"category": "Audit Reports",      "type": "audit",       "volume": "audits/reports"},
+    {"category": "Consultancy Reports","type": "consultancy", "volume": "consultancy/reports"},
+    {"category": "Inspection Reports", "type": "inspection",  "volume": "food_safety/reports"},
+]
+
+@app.get("/api/documents")
+def list_documents():
+    """List all available PDFs from Unity Catalog volumes, grouped by category."""
+    w = _ws
+    result = []
+    for src in _DOC_SOURCES:
+        vol_path = f"/Volumes/{CATALOG}/{src['volume']}"
+        files = []
+        # Try Databricks Files API first (works inside App runtime with UC grants)
+        try:
+            entries = list(w.files.list_directory_contents(vol_path))
+            files = sorted([
+                e.name for e in entries
+                if e.name and e.name.lower().endswith(".pdf")
+            ])
+        except Exception as e1:
+            # Fallback to filesystem path
+            try:
+                p = Path(vol_path)
+                if p.exists():
+                    files = sorted([f.name for f in p.iterdir() if f.suffix.lower() == ".pdf"])
+                else:
+                    log.warning(f"Volume path not found: {vol_path} ({e1})")
+            except Exception as e2:
+                log.warning(f"Could not list {vol_path}: {e2}")
+        result.append({
+            "category": src["category"],
+            "type": src["type"],
+            "volume": src["volume"],
+            "files": files,
+            "count": len(files),
+        })
+    return result
+
+
+@app.get("/api/documents/{doc_type}/{filename}")
+def get_document(doc_type: str, filename: str):
+    """Serve a PDF document from a Unity Catalog volume via Databricks Files API."""
+    type_map = {s["type"]: s["volume"] for s in _DOC_SOURCES}
+    volume = type_map.get(doc_type)
+    if not volume:
+        raise HTTPException(status_code=404, detail="Unknown document type")
+
+    safe_name = Path(filename).name
+    if not safe_name.lower().endswith(".pdf"):
+        raise HTTPException(status_code=400, detail="Only PDF files supported")
+
+    vol_path = f"/Volumes/{CATALOG}/{volume}/{safe_name}"
+    w = _ws
+
+    try:
+        result = w.files.download(vol_path)
+        content = result.contents.read()
+        return Response(
+            content=content,
+            media_type="application/pdf",
+            headers={"Content-Disposition": f'inline; filename="{safe_name}"',
+                     "Cache-Control": "private, max-age=300"},
+        )
+    except Exception as e:
+        log.error(f"File download failed {vol_path}: {e}")
+        raise HTTPException(status_code=404, detail="File not found")
+
+
+# ─── Locations ────────────────────────────────────────────────────────────────
+
+@app.get("/api/locations")
+def locations():
+    """Location list with coordinates and operational health flags."""
+    base_locations = [
+        {"location_id": 1, "name": "San Francisco", "city": "San Francisco", "state": "CA",
+         "lat": 37.7734, "lng": -122.4195, "address": "1847 Market Street, San Francisco, CA 94103"},
+        {"location_id": 2, "name": "Silicon Valley", "city": "Santa Clara", "state": "CA",
+         "lat": 37.3541, "lng": -121.9552, "address": "2350 El Camino Real, Santa Clara, CA 95051"},
+        {"location_id": 3, "name": "Bellevue", "city": "Bellevue", "state": "WA",
+         "lat": 47.6101, "lng": -122.2015, "address": "10456 NE 8th Street, Bellevue, WA 98004"},
+        {"location_id": 4, "name": "Chicago", "city": "Chicago", "state": "IL",
+         "lat": 41.9027, "lng": -87.6733, "address": "872 N. Milwaukee Avenue, Chicago, IL 60642"},
+        # EMEA locations
+        {"location_id": 5, "name": "London", "city": "London", "state": "England",
+         "lat": 51.5245, "lng": -0.0822, "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK"},
+        {"location_id": 6, "name": "Munich", "city": "Munich", "state": "Bavaria",
+         "lat": 48.1612, "lng": 11.5888, "address": "Leopoldstrasse 75, 80802 Munich, Germany"},
+        {"location_id": 7, "name": "Amsterdam", "city": "Amsterdam", "state": "North Holland",
+         "lat": 52.3740, "lng": 4.8979, "address": "Damrak 66, 1012 LM Amsterdam, Netherlands"},
+        {"location_id": 8, "name": "Vianen", "city": "Vianen", "state": "Utrecht",
+         "lat": 51.9839, "lng": 5.0905, "address": "Voorstraat 78, 4131 LW Vianen, Netherlands"},
+    ]
+
+    # Merge with revenue data for health indicators.  Reads from the same
+    # TTL cache that backs /api/revenue, so the warehouse is hit at most
+    # once per cache window even though the frontend fetches both endpoints
+    # in parallel on every page load.
+    try:
+        rev_data = {r["location_id"]: r for r in _get_revenue_cached()}
+    except Exception:
+        rev_data = {}
+
+    # Compute per-location 30d revenue growth %.  Real data shows every
+    # location growing (synthetic dataset has no real decline) and cancel
+    # rates are tiny (0-0.2 %), so absolute thresholds like `cancel > 8`
+    # never trigger and the map ends up all-green with no "problem" pin.
+    # Instead we rank locations by growth and flag the bottom quartile as
+    # "high" risk and the next quartile as "medium" — guarantees the map
+    # always shows at least one underperformer for the demo while still
+    # honoring genuine cancel-rate spikes via the OR clauses below.
+    pct_changes = []
+    for loc in base_locations:
+        rev = rev_data.get(loc["location_id"], {})
+        rev_cur  = rev.get("revenue", 0)      or 0
+        rev_prev = rev.get("revenue_prev", 0) or 0
+        pct = (100.0 * (rev_cur - rev_prev) / rev_prev) if rev_prev > 0 else 0.0
+        pct_changes.append(pct)
+
+    sorted_pcts = sorted(pct_changes)
+    n = max(1, len(sorted_pcts))
+    p25 = sorted_pcts[max(0, n // 4 - 1)]
+    p50 = sorted_pcts[max(0, n // 2 - 1)]
+
+    result = []
+    for i, loc in enumerate(base_locations):
+        rev         = rev_data.get(loc["location_id"], {})
+        cancel_rate = rev.get("cancel_rate_pct", 0) or 0
+        complaints  = rev.get("complaints", 0) or 0
+        pct_change  = pct_changes[i]
+
+        if cancel_rate > 5 or complaints > 200 or pct_change <= p25:
+            risk = "high"
+        elif cancel_rate > 2 or complaints > 100 or pct_change <= p50:
+            risk = "medium"
+        else:
+            risk = "low"
+
+        result.append({
+            **loc,
+            "total_orders":    rev.get("total_orders", 0),
+            "complaints":      complaints,
+            "cancel_rate_pct": cancel_rate,
+            "revenue":         rev.get("revenue", 0),
+            "revenue_prev":    rev.get("revenue_prev", 0),
+            "revenue_change_pct": round(pct_change, 1),
+            "risk_level":      risk,
+        })
+
+    return result
diff --git a/apps/caspers-ops-dashboard/index.html b/apps/caspers-ops-dashboard/index.html
new file mode 100644
index 0000000..e74a75d
--- /dev/null
+++ b/apps/caspers-ops-dashboard/index.html
@@ -0,0 +1,3096 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Operational Dashboard — Casper's Kitchens</title>
+
+<!-- Map -->
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
+<!-- Charts -->
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<!-- Leaflet -->
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+<!-- Marked (for markdown rendering in chat) -->
+<script src="https://cdn.jsdelivr.net/npm/marked@11.1.1/marked.min.js"></script>
+
+<style>
+/* ── CSS Variables ── */
+:root {
+  --bg-primary:    #111113;
+  --bg-secondary:  #18181B;
+  --bg-tertiary:   #222226;
+  --bg-card:       #1E1E22;
+  --bg-input:      #26262C;
+  --border:        #303038;
+  --border-accent: #5A2E2A;
+  --text-primary:  #EDEDEF;
+  --text-secondary:#9898A2;
+  --text-muted:    #55555E;
+  --accent:        #E8341A;
+  --accent-light:  #F56248;
+  --accent-glow:   rgba(232,52,26,0.12);
+  --success: #3ecf8e;
+  --warning: #f5a623;
+  --danger:  #e85d5d;
+  --gold:    #f0c040;
+  --sidebar-w: 240px;
+  --right-sidebar-w: 220px;
+  --header-h: 54px;
+  --radius: 10px;
+  --radius-sm: 6px;
+  --shadow: 0 4px 24px rgba(0,0,0,0.4);
+  --transition: 0.18s ease;
+}
+
+[data-theme="light"] {
+  --bg-primary:    #F3F3F6;
+  --bg-secondary:  #FFFFFF;
+  --bg-tertiary:   #EAEAEF;
+  --bg-card:       #FFFFFF;
+  --bg-input:      #F7F7FA;
+  --border:        #DCDCE4;
+  --border-accent: #C4A0A0;
+  --text-primary:  #111116;
+  --text-secondary:#505058;
+  --text-muted:    #888892;
+  --accent:        #C42B12;
+  --accent-light:  #C42B12;
+  --accent-glow:   rgba(196,43,18,0.08);
+  --success: #1a8f5c;
+  --warning: #b56b10;
+  --danger:  #b02a2a;
+  --gold:    #a07008;
+  --shadow: 0 4px 24px rgba(0,0,0,0.08);
+}
+
+/* ── Reset ── */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { height: 100%; overflow: hidden; font-family: 'Inter', 'Segoe UI', system-ui, sans-serif; }
+body { background: var(--bg-primary); color: var(--text-primary); display: flex; flex-direction: column; }
+
+/* ── Header ── */
+.header {
+  height: var(--header-h);
+  background: var(--bg-secondary);
+  border-bottom: 1px solid var(--border);
+  display: flex; align-items: center; padding: 0 20px;
+  gap: 12px; flex-shrink: 0;
+  box-shadow: 0 1px 0 var(--border);
+}
+.header-logo {
+  font-size: 18px; font-weight: 700; letter-spacing: -0.3px;
+  background: linear-gradient(135deg, var(--accent-light), var(--gold));
+  -webkit-background-clip: text; -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+.header-subtitle { font-size: 12px; color: var(--text-muted); margin-left: 4px; }
+.header-spacer { flex: 1; }
+.header-badge {
+  font-size: 11px; padding: 3px 10px; border-radius: 20px;
+  border: 1px solid var(--border-accent); color: var(--text-secondary);
+  background: var(--bg-tertiary);
+}
+.header-badge.live::before {
+  content: "●"; color: var(--success); margin-right: 5px; font-size: 9px;
+}
+
+/* ── Layout ── */
+.layout {
+  display: flex; flex: 1; overflow: hidden;
+}
+
+/* ── Sidebar toggle strips (live outside the sidebars so they never collapse) ── */
+.sidebar-strip {
+  width: 14px; flex-shrink: 0; display: flex; align-items: center; justify-content: center;
+  background: var(--bg-secondary); cursor: pointer; border: none; padding: 0;
+  transition: background var(--transition);
+}
+.sidebar-strip:hover { background: var(--bg-tertiary); }
+.sidebar-strip-left  { border-right: 1px solid var(--border); }
+.sidebar-strip-right { border-left:  1px solid var(--border); }
+.sidebar-strip-icon {
+  font-size: 9px; color: var(--text-muted); writing-mode: vertical-rl;
+  user-select: none; pointer-events: none;
+}
+.sidebar-strip:hover .sidebar-strip-icon { color: var(--text-primary); }
+
+/* ── Left Sidebar ── */
+.left-sidebar {
+  width: var(--sidebar-w); flex-shrink: 0;
+  background: var(--bg-secondary);
+  border-right: 1px solid var(--border);
+  display: flex; flex-direction: column;
+  overflow: hidden;
+  transition: width 0.2s ease;
+}
+.left-sidebar.collapsed { width: 0; border-right: none; }
+
+.sidebar-nav {
+  padding: 12px 10px 0;
+  display: flex; flex-direction: column; gap: 2px;
+}
+
+.nav-item {
+  display: flex; align-items: center; gap: 10px;
+  padding: 9px 12px; border-radius: var(--radius-sm);
+  cursor: pointer; color: var(--text-secondary);
+  font-size: 13px; font-weight: 500;
+  transition: var(--transition); border: none; background: none; width: 100%; text-align: left;
+}
+.nav-item:hover { background: var(--bg-tertiary); color: var(--text-primary); }
+.nav-item.active { background: var(--accent-glow); color: var(--accent-light); }
+.nav-item .icon { font-size: 16px; width: 20px; text-align: center; }
+
+.sidebar-divider {
+  height: 1px; background: var(--border); margin: 10px 16px;
+}
+
+.sidebar-section-title {
+  font-size: 10px; font-weight: 600; letter-spacing: 0.8px;
+  color: var(--text-muted); text-transform: uppercase;
+  padding: 6px 16px 4px;
+}
+
+.new-session-btn {
+  margin: 8px 10px;
+  display: flex; align-items: center; justify-content: center; gap: 8px;
+  padding: 9px 12px; border-radius: var(--radius-sm);
+  background: var(--accent); color: #fff;
+  font-size: 13px; font-weight: 600; cursor: pointer;
+  border: none; transition: var(--transition);
+}
+.new-session-btn:hover { background: var(--accent-light); }
+
+.session-list { flex: 1; overflow-y: auto; padding: 0 6px; }
+.session-item {
+  padding: 8px 10px; border-radius: var(--radius-sm);
+  cursor: pointer; font-size: 12px; color: var(--text-secondary);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  transition: var(--transition); display: flex; align-items: center; gap: 6px;
+  border: none; background: none; width: 100%; text-align: left;
+}
+.session-item:hover { background: var(--bg-tertiary); color: var(--text-primary); }
+.session-item.active { color: var(--accent-light); background: var(--accent-glow); }
+.session-item .session-icon { font-size: 13px; flex-shrink: 0; }
+
+.sidebar-bottom {
+  padding: 10px; border-top: 1px solid var(--border); flex-shrink: 0;
+}
+.theme-toggle {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 8px 10px; border-radius: var(--radius-sm);
+  font-size: 12px; color: var(--text-secondary);
+}
+.theme-toggle-btn {
+  display: flex; gap: 4px; background: var(--bg-tertiary);
+  border-radius: 20px; padding: 3px; border: 1px solid var(--border);
+}
+.theme-btn {
+  padding: 3px 8px; border-radius: 16px; border: none; cursor: pointer;
+  font-size: 13px; background: none; color: var(--text-muted); transition: var(--transition);
+}
+.theme-btn.active { background: var(--accent); }
+
+/* ── Main Content ── */
+.main-content {
+  flex: 1; display: flex; overflow: hidden;
+}
+
+/* ── Left Main (Dashboard / Document Viewer) ── */
+.left-main {
+  flex: 1; display: flex; flex-direction: column; overflow: hidden;
+  min-width: 0; border-right: 1px solid var(--border);
+}
+
+/* Panel: Dashboard (Revenue top + Map bottom) */
+.dashboard-panel {
+  display: flex; flex-direction: column; height: 100%; overflow: hidden;
+}
+
+.dashboard-section {
+  flex: 1; overflow: hidden; padding: 14px 16px;
+  display: flex; flex-direction: column; min-height: 0;
+}
+.dashboard-section:first-child {
+  border-bottom: 1px solid var(--border); flex: 0 0 52%;
+}
+.dashboard-section:last-child { flex: 0 0 48%; }
+
+.section-title {
+  font-size: 12px; font-weight: 600; letter-spacing: 0.4px;
+  color: var(--text-secondary); text-transform: uppercase; margin-bottom: 10px;
+  display: flex; align-items: center; gap: 8px;
+}
+.section-title .pulse {
+  width: 7px; height: 7px; border-radius: 50%;
+  background: var(--success); animation: pulse 2s infinite;
+}
+@keyframes pulse {
+  0%, 100% { opacity: 1; } 50% { opacity: 0.4; }
+}
+
+/* Revenue cards row */
+.metric-row {
+  display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; margin-bottom: 10px;
+}
+.metric-card {
+  background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: var(--radius-sm); padding: 8px 10px;
+}
+.metric-label { font-size: 10px; color: var(--text-muted); margin-bottom: 2px; }
+.metric-value { font-size: 16px; font-weight: 700; color: var(--text-primary); }
+.metric-value.danger { color: var(--danger); }
+.metric-value.success { color: var(--success); }
+.metric-value.warning { color: var(--warning); }
+.metric-sub { font-size: 10px; color: var(--text-muted); margin-top: 1px; }
+
+/* Surfaced when /api/revenue returns 503.  Deliberately understated styling —
+   we want the audience to see "data unavailable" without it looking like the
+   entire app has died.  Pairs with the empty metric-row + empty chart so the
+   page layout stays stable. */
+.data-error {
+  margin: 4px 0 10px 0;
+  padding: 8px 12px;
+  background: color-mix(in srgb, var(--warning) 12%, transparent);
+  border: 1px solid color-mix(in srgb, var(--warning) 35%, transparent);
+  border-radius: var(--radius-sm);
+  font-size: 12px;
+  color: var(--text-primary);
+}
+.data-error-title { font-weight: 600; margin-bottom: 2px; }
+.data-error-body  { color: var(--text-secondary); font-size: 11px; }
+
+.chart-container {
+  flex: 1; min-height: 0; position: relative;
+}
+
+/* Full Operations dashboard tab — iframe takes the whole left-main area.
+   We accept the Lakeview embed quirks (fixed natural canvas width,
+   always-light rendering, requires a workspace login on first view in a
+   fresh browser session) for this opt-in tab. */
+.ops-dashboard-panel {
+  display: none; flex-direction: column; height: 100%; overflow: hidden;
+  background: var(--bg-secondary);
+}
+.ops-dashboard-panel.active { display: flex; }
+.ops-dashboard-header {
+  display: flex; align-items: center; gap: 10px;
+  padding: 12px 16px; border-bottom: 1px solid var(--border);
+}
+.ops-dashboard-title { font-weight: 600; font-size: 14px; color: var(--text-primary); flex: 1; }
+.ops-dashboard-close {
+  background: transparent; border: 1px solid var(--border);
+  color: var(--text-secondary); padding: 4px 10px; border-radius: var(--radius-sm);
+  font-size: 12px; cursor: pointer; transition: var(--transition);
+}
+.ops-dashboard-close:hover { background: var(--bg-tertiary); color: var(--text-primary); }
+.ops-dashboard-iframe-wrap {
+  flex: 1; min-height: 0; position: relative; display: flex;
+  background: var(--bg-card);
+}
+#ops-full-dashboard-iframe {
+  flex: 1; border: none; width: 100%; height: 100%; background: var(--bg-card);
+}
+
+/* Map */
+.map-container {
+  flex: 1; min-height: 0; border-radius: var(--radius-sm); overflow: hidden;
+  border: 1px solid var(--border);
+}
+#location-map { height: 100%; width: 100%; }
+
+/* ── Document Viewer Panel ── */
+.doc-viewer-panel {
+  display: none; flex-direction: column; height: 100%; overflow: hidden;
+  padding: 16px;
+}
+.doc-viewer-panel.active { display: flex; }
+
+.doc-viewer-header {
+  display: flex; align-items: center; gap: 10px; margin-bottom: 12px; flex-shrink: 0;
+}
+.doc-viewer-title { font-size: 14px; font-weight: 600; color: var(--text-primary); flex: 1; }
+.doc-viewer-close {
+  padding: 4px 10px; border-radius: var(--radius-sm);
+  background: var(--bg-tertiary); border: 1px solid var(--border);
+  color: var(--text-secondary); font-size: 12px; cursor: pointer;
+}
+.doc-viewer-close:hover { background: var(--border); }
+
+.doc-filter-bar {
+  display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 10px; flex-shrink: 0;
+}
+.doc-filter-btn {
+  padding: 4px 10px; border-radius: 12px; font-size: 11px; font-weight: 500;
+  border: 1px solid var(--border); background: var(--bg-tertiary);
+  color: var(--text-secondary); cursor: pointer; transition: var(--transition);
+}
+.doc-filter-btn:hover, .doc-filter-btn.active {
+  background: var(--accent-glow); border-color: var(--accent); color: var(--accent-light);
+}
+
+.doc-list { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 6px; }
+.doc-group-label {
+  font-size: 10px; font-weight: 700; color: var(--text-muted); text-transform: uppercase;
+  letter-spacing: 0.8px; padding: 6px 0 2px; display: flex; align-items: center; gap: 6px;
+}
+.doc-group-label span { background: var(--bg-tertiary); border-radius: 8px; padding: 1px 6px; font-size: 10px; }
+.doc-item {
+  background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: var(--radius-sm); padding: 9px 12px; cursor: pointer;
+  transition: var(--transition); display: flex; align-items: center; gap: 10px;
+}
+.doc-item:hover { border-color: var(--accent); background: var(--accent-glow); }
+.doc-item.chat-ref { border-color: var(--gold); }
+.doc-item-icon { font-size: 16px; flex-shrink: 0; }
+.doc-item-body { min-width: 0; flex: 1; }
+.doc-item-title { font-size: 12px; font-weight: 600; color: var(--text-primary); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.doc-item-meta { font-size: 10px; color: var(--text-muted); margin-top: 1px; }
+.doc-item-open { font-size: 11px; color: var(--accent-light); flex-shrink: 0; opacity: 0; transition: var(--transition); }
+.doc-item:hover .doc-item-open { opacity: 1; }
+
+.doc-empty {
+  flex: 1; display: flex; flex-direction: column; align-items: center;
+  justify-content: center; gap: 8px; color: var(--text-muted);
+}
+.doc-empty-icon { font-size: 40px; opacity: 0.4; }
+
+/* ── Right Main (Chat) ── */
+.right-main {
+  flex: 1; min-width: 340px;
+  display: flex; flex-direction: column;
+  overflow: hidden; background: var(--bg-secondary);
+  position: relative;
+}
+
+.chat-header {
+  padding: 12px 16px; border-bottom: 1px solid var(--border);
+  font-size: 13px; font-weight: 600; color: var(--text-primary);
+  display: flex; align-items: center; gap: 8px; flex-shrink: 0;
+}
+.chat-header-icon { font-size: 18px; }
+.chat-header-sub { font-size: 11px; color: var(--text-muted); margin-left: auto; }
+
+.chat-messages {
+  flex: 1; overflow-y: auto; padding: 14px;
+  display: flex; flex-direction: column; gap: 12px;
+}
+
+.message {
+  display: flex; gap: 10px; align-items: flex-start;
+}
+.message.user { flex-direction: row-reverse; }
+
+.message-avatar {
+  width: 28px; height: 28px; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center;
+  font-size: 13px; flex-shrink: 0; font-weight: 700;
+}
+.message.user .message-avatar { background: var(--accent); color: #fff; }
+.message.assistant .message-avatar {
+  background: linear-gradient(135deg, #B02810, #E8341A);
+  color: #fff;
+}
+
+.message-bubble {
+  max-width: 85%; padding: 9px 13px; border-radius: 14px;
+  font-size: 13px; line-height: 1.6;
+}
+.message.user .message-bubble {
+  background: var(--accent); color: #fff;
+  border-bottom-right-radius: 4px;
+}
+.message.assistant .message-bubble {
+  background: var(--bg-card); border: 1px solid var(--border); color: var(--text-primary);
+  border-bottom-left-radius: 4px;
+}
+.message.assistant .message-bubble p { margin: 0 0 6px; }
+.message.assistant .message-bubble p:last-child { margin-bottom: 0; }
+.message.assistant .message-bubble ul, .message.assistant .message-bubble ol {
+  padding-left: 16px; margin: 4px 0;
+}
+.message.assistant .message-bubble strong { color: var(--accent-light); }
+.message.assistant .message-bubble code {
+  background: var(--bg-tertiary); padding: 1px 5px; border-radius: 3px;
+  font-size: 12px;
+}
+
+.doc-ref-btn {
+  display: inline-flex; align-items: center; gap: 4px;
+  margin: 4px 0; padding: 3px 9px; border-radius: 12px;
+  background: var(--accent-glow); border: 1px solid var(--border-accent);
+  color: var(--accent-light); font-size: 11px; cursor: pointer;
+  transition: var(--transition);
+}
+.doc-ref-btn:hover { background: var(--accent); color: #fff; }
+
+/* ── Impatient bunny ── */
+#impatient-bunny {
+  position: absolute; top: 54px; right: 14px; z-index: 9999;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 8px;
+  pointer-events: none;
+  animation: bunny-slide-in 0.5s cubic-bezier(0.34,1.56,0.64,1) both;
+}
+@keyframes bunny-slide-in {
+  from { transform: translateY(-40px); opacity: 0; }
+  to   { transform: translateY(0);     opacity: 1; }
+}
+.bunny-bubble {
+  background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: 14px; border-bottom-right-radius: 3px;
+  padding: 8px 13px; font-size: 12px; color: var(--text-secondary);
+  max-width: 200px; text-align: center; line-height: 1.4;
+  box-shadow: 0 4px 16px rgba(0,0,0,0.25);
+  animation: bunny-msg-pop 0.3s ease both;
+}
+@keyframes bunny-msg-pop {
+  from { transform: scale(0.7); opacity: 0; }
+  to   { transform: scale(1);   opacity: 1; }
+}
+.bunny-emoji-wrap {
+  font-size: 48px; line-height: 1;
+  animation: bunny-hop 0.6s ease-in-out infinite alternate;
+  filter: drop-shadow(0 4px 6px rgba(0,0,0,0.3));
+}
+@keyframes bunny-hop {
+  from { transform: translateY(0) rotate(-3deg); }
+  to   { transform: translateY(-8px) rotate(3deg); }
+}
+/* ── Wait-or-stop prompt (appears at 200s) ── */
+#wait-or-stop {
+  position: absolute; top: 54px; left: 50%; transform: translateX(-50%);
+  z-index: 9998; display: none;
+  background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: var(--radius); padding: 10px 16px;
+  box-shadow: 0 4px 20px rgba(0,0,0,0.35);
+  font-size: 12px; color: var(--text-secondary);
+  align-items: center; gap: 10px; white-space: nowrap;
+  animation: bunny-msg-pop 0.3s ease both;
+  pointer-events: all;
+}
+#wait-or-stop .wos-label { font-weight: 500; }
+#wait-or-stop .wos-btn {
+  padding: 4px 12px; border-radius: var(--radius-sm); font-size: 12px;
+  font-weight: 600; cursor: pointer; border: 1px solid var(--border);
+  transition: var(--transition);
+}
+#wait-or-stop .wos-btn.wait {
+  background: rgba(255,255,255,0.06); color: var(--text-secondary);
+}
+#wait-or-stop .wos-btn.wait:hover { background: rgba(255,255,255,0.14); color: var(--text-primary); }
+#wait-or-stop .wos-btn.stop {
+  background: rgba(232,93,93,0.12); color: var(--danger);
+  border-color: rgba(232,93,93,0.35);
+}
+#wait-or-stop .wos-btn.stop:hover { background: rgba(232,93,93,0.25); }
+
+/* Inline document reference chips inside chat bubbles */
+.chat-doc-refs {
+  margin-top: 10px; padding-top: 10px;
+  border-top: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+}
+.chat-doc-refs-label {
+  font-size: 10px; font-weight: 700; color: var(--text-muted);
+  text-transform: uppercase; letter-spacing: 0.6px; margin-bottom: 6px;
+  display: flex; align-items: center; gap: 5px;
+}
+.chat-doc-refs-label::before { content: '📎'; font-size: 11px; }
+.chat-doc-chips { display: flex; flex-direction: column; gap: 4px; }
+.chat-doc-chip {
+  display: flex; align-items: center; gap: 8px; width: 100%;
+  padding: 7px 10px; border-radius: var(--radius-sm);
+  border: 1px solid var(--border-accent);
+  background: var(--accent-glow);
+  color: var(--accent-light); font-size: 12px; font-family: inherit;
+  cursor: pointer; transition: var(--transition); text-align: left;
+}
+.chat-doc-chip:hover {
+  background: var(--accent); color: #fff;
+  border-color: var(--accent); transform: translateX(2px);
+}
+.chat-doc-chip-icon { font-size: 14px; flex-shrink: 0; }
+.chat-doc-chip-name {
+  flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  font-weight: 500;
+}
+.chat-doc-chip-type {
+  font-size: 10px; opacity: 0.7; flex-shrink: 0; text-transform: uppercase;
+  letter-spacing: 0.4px;
+}
+
+.typing-indicator {
+  display: inline-flex;
+  padding: 12px 14px;
+  background: var(--bg-card); border: 1px solid var(--border);
+  border-radius: 14px; border-bottom-left-radius: 4px;
+}
+.typing-dots { display: flex; gap: 4px; align-items: center; }
+.typing-dot {
+  width: 6px; height: 6px; border-radius: 50%;
+  background: var(--accent); animation: typing 1.2s infinite;
+}
+.typing-dot:nth-child(2) { animation-delay: 0.2s; }
+.typing-dot:nth-child(3) { animation-delay: 0.4s; }
+@keyframes map-pulse {
+  0%   { transform: scale(0.6); opacity: 0.9; }
+  100% { transform: scale(2.2); opacity: 0; }
+}
+@keyframes typing { 0%, 100% { transform: translateY(0); opacity: 0.5; } 50% { transform: translateY(-4px); opacity: 1; } }
+
+
+/* Inline "thinking" dots shown inside a streaming bubble while waiting for the next chunk */
+.stream-thinking {
+  display: flex; gap: 5px; align-items: center; padding: 8px 0 2px 0;
+}
+.stream-thinking-dot {
+  width: 5px; height: 5px; border-radius: 50%; background: var(--accent);
+  animation: typing 1.2s infinite; opacity: 0.7;
+}
+.stream-thinking-dot:nth-child(2) { animation-delay: 0.2s; }
+.stream-thinking-dot:nth-child(3) { animation-delay: 0.4s; }
+.typing-status-text {
+  font-size: 11px; color: var(--text-muted); margin-top: 5px;
+  font-style: italic; animation: fadeIn 0.3s ease;
+}
+@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+
+/* Action buttons */
+.action-buttons {
+  padding: 8px 14px; display: flex; gap: 6px; flex-wrap: wrap;
+  border-top: 1px solid var(--border); flex-shrink: 0;
+  background: var(--bg-secondary);
+}
+.action-btn {
+  flex: 1; min-width: 0; padding: 7px 10px; border-radius: var(--radius-sm);
+  font-size: 11px; font-weight: 600; cursor: pointer; border: none;
+  transition: var(--transition); white-space: nowrap;
+  display: flex; align-items: center; justify-content: center; gap: 5px;
+}
+.action-btn.briefing {
+  background: rgba(99,102,241,0.12); color: #a5b4fc;
+  border: 1px solid rgba(99,102,241,0.35);
+}
+.action-btn.briefing:hover { background: rgba(99,102,241,0.25); }
+.action-btn.risk {
+  background: rgba(232,93,93,0.1); color: var(--danger);
+  border: 1px solid rgba(232,93,93,0.25);
+}
+.action-btn.risk:hover { background: rgba(232,93,93,0.2); }
+.action-btn.board {
+  background: rgba(62,207,142,0.12); color: var(--success);
+  border: 1px solid rgba(62,207,142,0.3);
+}
+.action-btn.board:hover { background: rgba(62,207,142,0.25); }
+.action-btn.refund {
+  background: rgba(240,192,64,0.1); color: var(--gold);
+  border: 1px solid rgba(240,192,64,0.3);
+}
+.action-btn.refund:hover { background: rgba(240,192,64,0.2); }
+.action-btn.complaints {
+  background: rgba(232,52,26,0.08); color: var(--accent-light);
+  border: 1px solid rgba(232,52,26,0.25);
+}
+.action-btn.complaints:hover { background: rgba(232,52,26,0.18); }
+
+/* Agent result card — shown inline in chat */
+.agent-result-card {
+  margin-top: 10px; padding-top: 10px;
+  border-top: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+}
+.agent-result-card-header {
+  font-size: 10px; font-weight: 700; color: var(--text-muted);
+  text-transform: uppercase; letter-spacing: 0.6px; margin-bottom: 8px;
+  display: flex; align-items: center; gap: 5px;
+}
+.agent-result-body {
+  background: var(--bg-tertiary); border: 1px solid var(--border);
+  border-radius: var(--radius-sm); padding: 10px 12px;
+  display: flex; flex-direction: column; gap: 6px;
+}
+.agent-result-row {
+  display: flex; align-items: baseline; gap: 8px; font-size: 12px;
+}
+.agent-result-key { color: var(--text-muted); min-width: 80px; flex-shrink: 0; }
+.agent-result-val { color: var(--text-primary); font-weight: 500; }
+.agent-result-val.decision-none    { color: var(--success); }
+.agent-result-val.decision-partial { color: var(--warning); }
+.agent-result-val.decision-full    { color: var(--danger); }
+.agent-result-val.escalate-true    { color: var(--danger); font-weight: 700; }
+.agent-result-val.escalate-false   { color: var(--success); }
+.complaint-row { cursor: pointer; border-radius: var(--radius-sm); padding: 6px 4px; transition: background 0.12s; }
+.complaint-row:hover { background: color-mix(in srgb, var(--border) 30%, transparent); }
+.complaint-detail {
+  display: none; margin: 6px 0 8px 0; padding: 10px 12px;
+  background: color-mix(in srgb, var(--bg-primary) 60%, transparent);
+  border-left: 3px solid var(--gold); border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+  font-size: 11px; color: var(--text-secondary); line-height: 1.6;
+}
+.complaint-detail.open { display: block; }
+.complaint-detail-label { color: var(--text-muted); font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; margin-top: 6px; }
+.complaint-refund-btn {
+  display: inline-flex; align-items: center; gap: 5px; margin-top: 8px;
+  padding: 5px 10px; background: var(--gold); color: #111; border: none;
+  border-radius: var(--radius-sm); font-size: 11px; font-weight: 700;
+  cursor: pointer; transition: var(--transition);
+}
+.complaint-refund-btn:hover { opacity: 0.85; }
+
+/* Refund modal overlay */
+.refund-modal-overlay {
+  position: fixed; inset: 0; z-index: 2100;
+  background: rgba(0,0,0,0.65); backdrop-filter: blur(3px);
+  display: flex; align-items: center; justify-content: center;
+  animation: fadeIn 0.15s ease;
+}
+.refund-modal {
+  width: 380px; background: var(--bg-secondary);
+  border: 1px solid var(--border); border-radius: var(--radius);
+  box-shadow: 0 20px 60px rgba(0,0,0,0.5);
+  animation: slideUp 0.18s ease; overflow: hidden;
+}
+.refund-modal-header {
+  padding: 14px 16px; border-bottom: 1px solid var(--border);
+  display: flex; align-items: center; gap: 10px;
+}
+.refund-modal-title { font-size: 14px; font-weight: 600; flex: 1; }
+.refund-modal-close {
+  background: none; border: none; color: var(--text-muted);
+  font-size: 16px; cursor: pointer; padding: 0 4px; line-height: 1;
+}
+.refund-modal-close:hover { color: var(--text-primary); }
+.refund-modal-body { padding: 16px; display: flex; flex-direction: column; gap: 12px; }
+.refund-input-row { display: flex; gap: 8px; }
+.refund-input {
+  flex: 1; background: var(--bg-input); border: 1px solid var(--border);
+  border-radius: var(--radius-sm); padding: 8px 12px;
+  color: var(--text-primary); font-size: 13px; font-family: inherit;
+}
+.refund-input:focus { outline: none; border-color: var(--gold); }
+.refund-submit-btn {
+  padding: 8px 14px; background: var(--gold); color: #111; border: none;
+  border-radius: var(--radius-sm); font-size: 12px; font-weight: 700;
+  cursor: pointer; transition: var(--transition); white-space: nowrap;
+}
+.refund-submit-btn:hover:not(:disabled) { opacity: 0.85; }
+.refund-submit-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+.refund-result { display: none; }
+.refund-result.visible { display: block; }
+
+/* Retry button on connection-error messages */
+.retry-btn {
+  padding: 4px 12px; border-radius: var(--radius-sm);
+  font-size: 12px; font-weight: 600; cursor: pointer;
+  background: rgba(255,255,255,0.07); color: var(--text-secondary);
+  border: 1px solid var(--border); transition: var(--transition);
+  white-space: nowrap; flex-shrink: 0;
+}
+.retry-btn:hover {
+  background: rgba(255,255,255,0.14); color: var(--text-primary);
+  border-color: var(--accent);
+}
+
+/* Suggested follow-up question chips */
+.suggested-questions {
+  margin-top: 10px;
+  padding-top: 10px;
+  border-top: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+}
+.suggested-questions-label {
+  font-size: 10px; font-weight: 700; color: var(--text-muted);
+  text-transform: uppercase; letter-spacing: 0.6px; margin-bottom: 6px;
+  display: flex; align-items: center; gap: 5px;
+}
+.suggested-questions-label::before { content: '💡'; font-size: 11px; }
+.question-chips { display: flex; flex-direction: column; gap: 5px; }
+.question-chip {
+  display: block; width: 100%; text-align: left;
+  padding: 6px 10px; border-radius: var(--radius-sm);
+  border: 1px solid var(--border);
+  background: color-mix(in srgb, var(--bg-input) 80%, transparent);
+  color: var(--text-secondary); font-size: 11.5px; font-family: inherit;
+  cursor: pointer; transition: var(--transition); line-height: 1.4;
+}
+.question-chip:hover {
+  border-color: var(--accent); color: var(--accent-light);
+  background: var(--accent-glow); transform: translateX(2px);
+}
+.question-chip::before { content: '→ '; opacity: 0.5; font-size: 10px; }
+
+/* Routing attribution pill — shown at top of each AI response bubble */
+.routing-pill {
+  display: inline-flex; align-items: center; gap: 5px;
+  padding: 3px 9px; border-radius: 10px; margin-bottom: 10px;
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+  border: 1px solid color-mix(in srgb, var(--accent) 25%, transparent);
+  font-size: 10.5px; font-weight: 600; color: var(--text-muted);
+  letter-spacing: 0.3px;
+}
+.routing-pill::before { content: 'via '; opacity: 0.6; font-weight: 400; }
+
+/* Briefing alert card shown in welcome message */
+.briefing-alerts {
+  margin: 10px 0 8px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+}
+.briefing-alert-item {
+  display: flex; align-items: center; gap: 8px;
+  padding: 8px 11px; font-size: 12.5px; cursor: pointer;
+  border-bottom: 1px solid var(--border); transition: background 0.15s;
+  color: var(--text-secondary);
+}
+.briefing-alert-item:last-child { border-bottom: none; }
+.briefing-alert-item:hover { background: var(--bg-tertiary); color: var(--text-primary); }
+.alert-dot {
+  width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0;
+}
+.alert-dot.red  { background: var(--danger); box-shadow: 0 0 5px var(--danger); }
+.alert-dot.yellow { background: var(--warning); box-shadow: 0 0 5px var(--warning); }
+.alert-arrow { margin-left: auto; opacity: 0.4; font-size: 11px; }
+
+/* Board meeting CTA button in welcome message */
+.board-meeting-btn {
+  width: 100%; margin-top: 10px; padding: 9px 14px;
+  background: var(--accent); color: #fff; border: none;
+  border-radius: var(--radius-sm); font-size: 12.5px; font-weight: 700;
+  cursor: pointer; font-family: inherit; transition: opacity 0.15s;
+  text-align: left; display: flex; align-items: center; gap: 8px;
+}
+.board-meeting-btn:hover { opacity: 0.85; }
+.board-meeting-btn .bmb-arrow { margin-left: auto; opacity: 0.8; }
+
+/* Demo breaking-alert toast */
+.demo-alert-toast {
+  position: fixed; bottom: 24px; right: 24px; z-index: 9999;
+  background: var(--bg-secondary);
+  border: 1px solid rgba(232,93,93,0.6);
+  border-radius: var(--radius-sm);
+  padding: 12px 12px 12px 14px;
+  display: flex; align-items: center; gap: 10px;
+  box-shadow: 0 4px 24px rgba(0,0,0,0.45), 0 0 0 1px rgba(232,93,93,0.2);
+  max-width: 340px; min-width: 280px;
+  animation: toast-in 0.45s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+@keyframes toast-in {
+  from { transform: translateY(120%); opacity: 0; }
+  to   { transform: translateY(0);    opacity: 1; }
+}
+.demo-alert-toast-dot {
+  width: 9px; height: 9px; border-radius: 50%;
+  background: var(--danger); flex-shrink: 0;
+}
+.demo-alert-toast-body { flex: 1; min-width: 0; }
+.demo-alert-toast-title {
+  font-size: 10.5px; font-weight: 700; color: var(--danger);
+  text-transform: uppercase; letter-spacing: 0.4px; margin-bottom: 3px;
+}
+.demo-alert-toast-text { font-size: 12px; color: var(--text-secondary); line-height: 1.4; }
+.demo-alert-toast-cta {
+  padding: 5px 10px; background: var(--danger); color: #fff;
+  border: none; border-radius: 4px; font-size: 11px; font-weight: 600;
+  cursor: pointer; white-space: nowrap; flex-shrink: 0; font-family: inherit;
+}
+.demo-alert-toast-cta:hover { opacity: 0.85; }
+.demo-alert-toast-close {
+  background: none; border: none; color: var(--text-muted);
+  cursor: pointer; font-size: 16px; line-height: 1; padding: 0 2px;
+  flex-shrink: 0;
+}
+.demo-alert-toast-close:hover { color: var(--text-primary); }
+
+/* Chat input */
+.chat-input-area {
+  padding: 10px 14px; border-top: 1px solid var(--border);
+  display: flex; gap: 8px; align-items: flex-end; flex-shrink: 0;
+}
+.chat-textarea {
+  flex: 1; background: var(--bg-input); border: 1px solid var(--border);
+  border-radius: var(--radius-sm); padding: 9px 12px;
+  color: var(--text-primary); font-size: 13px; resize: none;
+  font-family: inherit; line-height: 1.5; max-height: 120px;
+  transition: var(--transition);
+}
+.chat-textarea:focus { outline: none; border-color: var(--accent); }
+.chat-textarea::placeholder { color: var(--text-muted); }
+.send-btn {
+  padding: 9px 14px; background: var(--accent); color: #fff;
+  border: none; border-radius: var(--radius-sm); cursor: pointer;
+  font-size: 16px; transition: var(--transition); flex-shrink: 0;
+  display: flex; align-items: center; justify-content: center;
+}
+.send-btn:hover:not(:disabled) { background: var(--accent-light); }
+.send-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+.cancel-btn {
+  padding: 9px 14px; background: #fee2e2; color: #dc2626;
+  border: 1px solid #fca5a5; border-radius: var(--radius-sm); cursor: pointer;
+  font-size: 13px; font-weight: 600; transition: var(--transition); flex-shrink: 0;
+  display: none; align-items: center; justify-content: center; gap: 5px;
+}
+.cancel-btn:hover { background: #fecaca; }
+
+/* ── Right Sidebar ── */
+.right-sidebar {
+  width: var(--right-sidebar-w); flex-shrink: 0;
+  background: var(--bg-secondary);
+  border-left: 1px solid var(--border);
+  display: flex; flex-direction: column; overflow-y: auto;
+  transition: width 0.2s ease;
+}
+.right-sidebar.collapsed { width: 0; border-left: none; overflow: hidden; }
+
+/* Sub-agent items in right sidebar */
+.agent-item {
+  display: flex; align-items: center; gap: 6px;
+  padding: 4px 0; font-size: 11px; color: var(--text-secondary);
+  text-decoration: none; border-radius: 4px;
+  transition: var(--transition);
+}
+.agent-item:hover { color: var(--accent-light); }
+.agent-item .agent-icon { font-size: 12px; flex-shrink: 0; }
+.agent-item .agent-name { flex: 1; }
+.agent-item .agent-arrow { font-size: 10px; opacity: 0; transition: var(--transition); }
+.agent-item:hover .agent-arrow { opacity: 1; }
+.agent-group-label {
+  font-size: 9px; font-weight: 700; color: var(--text-muted);
+  text-transform: uppercase; letter-spacing: 0.7px;
+  margin: 6px 0 3px; padding-top: 4px; border-top: 1px solid var(--border);
+}
+.agent-group-label:first-child { border-top: none; margin-top: 2px; }
+
+/* Lakebase detail sub-rows */
+.tech-sub-row {
+  display: flex; justify-content: space-between; align-items: baseline;
+  font-size: 10px; color: var(--text-secondary); padding: 2px 0;
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 50%, transparent);
+}
+.tech-sub-row:last-child { border-bottom: none; }
+.tech-sub-key { color: var(--text-muted); flex-shrink: 0; margin-right: 6px; }
+.tech-sub-val { text-align: right; word-break: break-all; font-family: monospace; font-size: 9.5px; }
+.lakebase-status-badge {
+  display: inline-block; padding: 1px 6px; border-radius: 3px;
+  font-size: 9px; font-weight: 700; letter-spacing: 0.4px; text-transform: uppercase;
+}
+.lakebase-status-badge.active { background: rgba(52,199,89,0.15); color: #34C759; }
+.lakebase-status-badge.inactive { background: rgba(255,159,10,0.15); color: #FF9F0A; }
+
+/* Clickable tech resource links — must override .tech-value color */
+.tech-section .tech-link {
+  color: var(--accent-light) !important; text-decoration: none;
+  font-size: 11px; word-break: break-all; line-height: 1.5;
+  display: inline; cursor: pointer;
+}
+.tech-section .tech-link:hover { color: var(--accent) !important; text-decoration: underline; }
+
+.right-sidebar-title {
+  padding: 14px 14px 6px;
+  font-size: 10px; font-weight: 700; letter-spacing: 0.8px;
+  color: var(--text-muted); text-transform: uppercase;
+  border-bottom: 1px solid var(--border); flex-shrink: 0;
+}
+
+.tech-section { padding: 12px 14px; border-bottom: 1px solid var(--border); }
+.tech-label { font-size: 10px; color: var(--text-muted); margin-bottom: 4px; font-weight: 600; }
+.tech-value {
+  font-size: 11px; color: var(--text-secondary); word-break: break-all;
+  line-height: 1.5; font-family: 'SF Mono', 'Cascadia Code', monospace;
+}
+.tech-value.ok { color: var(--success); }
+.tech-value.warn { color: var(--warning); }
+
+.status-dot {
+  display: inline-block; width: 7px; height: 7px; border-radius: 50%;
+  margin-right: 5px;
+}
+.status-dot.green { background: var(--success); }
+.status-dot.yellow { background: var(--warning); }
+.status-dot.red { background: var(--danger); }
+
+/* ── Location markers ── */
+.loc-marker-risk-high { color: #e85d5d; }
+.loc-marker-risk-medium { color: #f5a623; }
+.loc-marker-risk-low { color: #3ecf8e; }
+
+/* ── Scrollbar ── */
+::-webkit-scrollbar { width: 5px; height: 5px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: var(--border-accent); }
+
+/* ── PDF Viewer Modal ── */
+.pdf-modal-overlay {
+  position: fixed; inset: 0; z-index: 2000;
+  background: rgba(0,0,0,0.7); backdrop-filter: blur(4px);
+  display: flex; align-items: center; justify-content: center;
+  animation: fadeIn 0.15s ease;
+}
+.pdf-modal {
+  width: 88vw; height: 90vh; max-width: 1100px;
+  background: var(--bg-secondary); border: 1px solid var(--border);
+  border-radius: var(--radius); box-shadow: 0 24px 80px rgba(0,0,0,0.5);
+  display: flex; flex-direction: column; overflow: hidden;
+  animation: slideUp 0.18s ease;
+}
+@keyframes slideUp { from { transform: translateY(20px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+@keyframes fadeIn  { from { opacity: 0; } to { opacity: 1; } }
+
+.pdf-modal-header {
+  display: flex; align-items: center; gap: 12px;
+  padding: 12px 16px; border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+.pdf-modal-icon { font-size: 20px; }
+.pdf-modal-title {
+  font-size: 14px; font-weight: 600; color: var(--text-primary);
+  flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.pdf-modal-type {
+  font-size: 10px; font-weight: 600; letter-spacing: 0.6px;
+  text-transform: uppercase; color: var(--text-muted);
+  background: var(--bg-tertiary); border: 1px solid var(--border);
+  padding: 2px 8px; border-radius: 10px;
+}
+.pdf-modal-actions { display: flex; gap: 6px; }
+.pdf-modal-btn {
+  padding: 5px 12px; border-radius: var(--radius-sm); border: 1px solid var(--border);
+  background: var(--bg-tertiary); color: var(--text-secondary);
+  font-size: 12px; cursor: pointer; transition: var(--transition);
+  text-decoration: none; display: inline-flex; align-items: center; gap: 5px;
+}
+.pdf-modal-btn:hover { background: var(--border); color: var(--text-primary); }
+.pdf-modal-btn.close { background: var(--danger); border-color: var(--danger); color: #fff; }
+.pdf-modal-btn.close:hover { opacity: 0.85; }
+
+.pdf-modal-body { flex: 1; overflow: hidden; background: #525659; }
+.pdf-modal-body iframe {
+  width: 100%; height: 100%; border: none;
+}
+.pdf-modal-loading {
+  display: flex; flex-direction: column; align-items: center;
+  justify-content: center; height: 100%; gap: 12px;
+  color: var(--text-muted); font-size: 14px;
+}
+.pdf-spin {
+  width: 36px; height: 36px; border: 3px solid var(--border);
+  border-top-color: var(--accent); border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* ── Toast ── */
+.toast {
+  position: fixed; bottom: 20px; right: 20px;
+  background: var(--bg-card); border: 1px solid var(--border);
+  color: var(--text-primary); padding: 10px 16px; border-radius: var(--radius);
+  font-size: 13px; box-shadow: var(--shadow); z-index: 1000;
+  animation: slideIn 0.2s ease;
+}
+@keyframes slideIn { from { transform: translateY(20px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+
+/* ── Leaflet dark mode ── */
+[data-theme="dark"] .leaflet-tile { filter: brightness(0.65) invert(1) contrast(3) hue-rotate(200deg) saturate(0.3) brightness(0.7); }
+[data-theme="light"] .leaflet-tile { filter: none; }
+</style>
+</head>
+
+<body>
+<!-- ── Header ── -->
+<header class="header">
+  <span class="header-logo">📊 Operational Dashboard</span>
+  <span class="header-subtitle">Casper's Kitchens</span>
+  <div class="header-spacer"></div>
+  <span class="header-badge" id="location-count-badge">8 Locations · 16 Brands</span>
+</header>
+
+<div class="layout">
+
+  <!-- ── Left Sidebar ── -->
+  <aside class="left-sidebar" id="left-sidebar">
+    <!-- Nav tabs -->
+    <nav class="sidebar-nav">
+      <button class="nav-item active" id="nav-dashboard" onclick="switchView('dashboard')">
+        <span class="icon">📊</span> Dashboard
+      </button>
+      <button class="nav-item" id="nav-documents" onclick="switchView('documents')">
+        <span class="icon">📄</span> Document Viewer
+        <span id="doc-badge" style="display:none; margin-left:auto; background:var(--accent); color:#fff; font-size:10px; padding:1px 6px; border-radius:10px;"></span>
+      </button>
+      <button class="nav-item" id="nav-ops-dashboard" onclick="switchView('ops-dashboard')">
+        <span class="icon">📈</span> Ops Dashboard
+      </button>
+      <a class="nav-item" id="nav-refund-manager" href="#" target="_blank" rel="noopener"
+         style="display:none; text-decoration:none;">
+        <span class="icon">💳</span> Refund Manager ↗
+      </a>
+    </nav>
+
+    <div class="sidebar-divider"></div>
+
+    <!-- New session -->
+    <button class="new-session-btn" onclick="createSession()">
+      <span>＋</span> New Session
+    </button>
+
+    <div class="sidebar-section-title">Conversations</div>
+    <div class="session-list" id="session-list">
+      <!-- dynamically populated -->
+    </div>
+
+    <!-- Bottom: theme -->
+    <div class="sidebar-bottom">
+      <div class="theme-toggle">
+        <span style="font-size:12px; color:var(--text-muted);">Theme</span>
+        <div class="theme-toggle-btn">
+          <button class="theme-btn" id="theme-dark" onclick="setTheme('dark')">🌙</button>
+          <button class="theme-btn active" id="theme-light" onclick="setTheme('light')">☀️</button>
+        </div>
+      </div>
+    </div>
+  </aside>
+
+  <!-- Left sidebar toggle strip -->
+  <button class="sidebar-strip sidebar-strip-left" id="left-toggle" onclick="toggleLeftSidebar()" title="Toggle left sidebar">
+    <span class="sidebar-strip-icon" id="left-toggle-icon">◀</span>
+  </button>
+
+  <!-- ── Main Content ── -->
+  <main class="main-content">
+
+    <!-- ── Left Main ── -->
+    <div class="left-main">
+
+      <!-- Dashboard Panel -->
+      <div class="dashboard-panel" id="view-dashboard">
+
+        <!-- Revenue Section (top half) — Chart.js KPIs + revenue trend -->
+        <div class="dashboard-section">
+          <div class="section-title">
+            <div class="pulse"></div>
+            Revenue Performance · Current vs Prior Period
+          </div>
+          <div class="metric-row" id="metric-row">
+            <!-- populated by renderMetrics() from /api/revenue -->
+          </div>
+          <!-- Shown when /api/revenue returns 503.  We intentionally do NOT
+               fall back to fabricated numbers — a visible "unavailable"
+               banner is far safer than silently demoing fake data. -->
+          <div id="revenue-error" class="data-error" style="display:none;">
+            <div class="data-error-title">
+              <span>⚠</span> Revenue analytics temporarily unavailable
+            </div>
+            <div class="data-error-body" id="revenue-error-body">
+              Retry in a few seconds, or check the SQL warehouse status.
+            </div>
+          </div>
+          <div class="chart-container">
+            <canvas id="revenue-chart"></canvas>
+          </div>
+        </div>
+
+        <!-- Location Map (bottom half) -->
+        <div class="dashboard-section">
+          <div class="section-title">
+            <span>📍</span> Location Health Map
+          </div>
+          <div class="map-container">
+            <div id="location-map"></div>
+          </div>
+        </div>
+
+      </div>
+
+      <!-- Ops Dashboard Panel (full embedded AI/BI dashboard).
+           Lakeview embed iframe — `caspers_kitchen_operations` is a multi-page
+           dashboard so we render it full-bleed in its own tab.  Accepts a
+           workspace-domain login flow on first view (no shortcut around
+           Databricks' embed auth), but it's expected behaviour for a tab
+           that the user opts into, unlike the always-visible Revenue panel
+           where double-login was a deal-breaker. -->
+      <div class="ops-dashboard-panel" id="view-ops-dashboard">
+        <div class="ops-dashboard-header">
+          <span style="font-size:20px;">📈</span>
+          <span class="ops-dashboard-title">Casper's Kitchen Operations</span>
+          <button class="ops-dashboard-close" onclick="switchView('dashboard')">← Back</button>
+        </div>
+        <div class="ops-dashboard-iframe-wrap">
+          <iframe
+            id="ops-full-dashboard-iframe"
+            title="Casper's Kitchen Operations dashboard"
+            loading="lazy"
+            allowfullscreen
+            style="display:none;"
+          ></iframe>
+          <div id="ops-full-dashboard-empty" style="display:flex; align-items:center; justify-content:center; height:100%; color:var(--text-muted); font-size:13px; padding:20px; text-align:center;">
+            Loading dashboard…
+          </div>
+        </div>
+      </div>
+
+      <!-- Document Viewer Panel -->
+      <div class="doc-viewer-panel" id="view-documents">
+        <div class="doc-viewer-header">
+          <span style="font-size:20px;">📄</span>
+          <span class="doc-viewer-title">Document Library</span>
+          <span id="doc-total-count" style="font-size:11px;color:var(--text-muted);"></span>
+          <button class="doc-viewer-close" onclick="switchView('dashboard')">← Back</button>
+        </div>
+        <div class="doc-filter-bar" id="doc-filter-bar">
+          <button class="doc-filter-btn active" onclick="filterDocs('all')" data-filter="all">All</button>
+        </div>
+        <div class="doc-list" id="doc-list">
+          <div class="doc-empty">
+            <span class="doc-empty-icon">⏳</span>
+            <span>Loading documents…</span>
+          </div>
+        </div>
+      </div>
+
+    </div><!-- /left-main -->
+
+    <!-- ── Right Main (Chat) ── -->
+    <div class="right-main">
+      <div class="chat-header">
+        <span class="chat-header-icon">🤖</span>
+        Ops Intelligence
+        <span class="chat-header-sub" id="chat-session-label">No session</span>
+      </div>
+
+      <div class="chat-messages" id="chat-messages">
+        <!-- Welcome message -->
+        <div class="message assistant">
+          <div class="message-avatar">AI</div>
+          <div class="message-bubble">
+            <p>Good morning. I'm your Ops Intelligence assistant for <strong>Casper's Kitchens</strong>.</p>
+            <p>I have access to your <strong>revenue analytics</strong>, <strong>operations data</strong>, <strong>food safety inspections</strong>, <strong>legal exposure</strong>, <strong>regulatory compliance</strong>, <strong>audit findings</strong>, and <strong>consultancy reports</strong> across all 8 locations (US + EMEA).</p>
+            <p>What would you like to know?</p>
+          </div>
+        </div>
+      </div>
+
+      <!-- Action buttons: 3 always-visible Supervisor shortcuts (from the DAIS
+           runbook) + Review Complaints (always visible, real backend) + Process
+           Refund (only shown when the AI mentions a refund-shaped topic). -->
+      <div class="action-buttons" id="action-buttons" style="display:flex;">
+        <button class="action-btn briefing" id="btn-briefing" onclick="askSuggestion('Give me the executive briefing on the state of the business.')">
+          📊 Executive briefing
+        </button>
+        <button class="action-btn risk" id="btn-risk" onclick="askSuggestion('Which location is the highest combined legal and operational risk right now?')">
+          ⚠️ Highest combined risk
+        </button>
+        <button class="action-btn board" id="btn-board" onclick="askSuggestion('What are the top 3 things to know before the board call tomorrow?')">
+          🎯 Top 3 for the board
+        </button>
+        <button class="action-btn refund" id="btn-refund" style="display:none;" onclick="openRefundModal()">
+          💳 Process Refund
+        </button>
+        <button class="action-btn complaints" id="btn-complaints" onclick="triggerComplaintSummary()">
+          📬 Review Complaints
+        </button>
+      </div>
+
+      <div class="chat-input-area">
+        <textarea
+          class="chat-textarea"
+          id="chat-input"
+          placeholder="Ask about revenue, operations, legal, compliance, audits…"
+          rows="2"
+          onkeydown="handleKey(event)"
+        ></textarea>
+        <button class="send-btn" id="send-btn" onclick="sendMessage()">➤</button>
+        <button class="cancel-btn" id="cancel-btn" onclick="cancelStream()" title="Cancel">✕ Stop</button>
+      </div>
+
+      <!-- Impatient bunny – anchored to top-right of chat panel -->
+      <div id="impatient-bunny" style="display:none">
+        <div class="bunny-bubble" id="bunny-msg">Still waiting… 🙄</div>
+        <div class="bunny-emoji-wrap">🐰</div>
+      </div>
+
+      <!-- Wait-or-stop prompt – appears at 200s -->
+      <div id="wait-or-stop">
+        <span class="wos-label">Taking longer than a Chicago health inspection…</span>
+        <button class="wos-btn wait" onclick="dismissWaitPrompt()">Keep waiting</button>
+        <button class="wos-btn stop"  onclick="stopStreaming()">Stop</button>
+      </div>
+
+    </div><!-- /right-main -->
+
+  </main>
+
+  <!-- Right sidebar toggle strip -->
+  <button class="sidebar-strip sidebar-strip-right" id="right-toggle" onclick="toggleRightSidebar()" title="Toggle right sidebar">
+    <span class="sidebar-strip-icon" id="right-toggle-icon">▶</span>
+  </button>
+
+  <!-- ── Right Sidebar (Tech Info) ── -->
+  <aside class="right-sidebar" id="right-sidebar">
+    <div class="right-sidebar-title">System Info</div>
+    <div id="tech-info-panels">
+      <!-- populated by JS -->
+    </div>
+  </aside>
+
+</div><!-- /layout -->
+
+<!-- ── Refund Modal ── -->
+<div class="refund-modal-overlay" id="refund-modal" style="display:none;" onclick="closeRefundModal(event)">
+  <div class="refund-modal" onclick="event.stopPropagation()">
+    <div class="refund-modal-header">
+      <span style="font-size:20px;">💳</span>
+      <span class="refund-modal-title">Refund Decision Engine</span>
+      <button class="refund-modal-close" onclick="closeRefundModal()">✕</button>
+    </div>
+    <div class="refund-modal-body">
+      <div style="font-size:12px; color:var(--text-muted);">
+        Enter an order ID to get an instant refund recommendation based on delivery time vs. location benchmarks.
+      </div>
+      <div class="refund-input-row">
+        <input class="refund-input" id="refund-order-id" placeholder="Order ID (e.g. ORD-001234)" onkeydown="if(event.key==='Enter')submitRefund()" />
+        <button class="refund-submit-btn" id="refund-submit-btn" onclick="submitRefund()">Evaluate</button>
+      </div>
+      <div class="refund-result" id="refund-result"></div>
+    </div>
+  </div>
+</div>
+
+<!-- ── PDF Viewer Modal ── -->
+<div class="pdf-modal-overlay" id="pdf-modal" style="display:none;" onclick="closePdfModal(event)">
+  <div class="pdf-modal" onclick="event.stopPropagation()">
+    <div class="pdf-modal-header">
+      <span class="pdf-modal-icon" id="pdf-modal-icon">📄</span>
+      <span class="pdf-modal-title" id="pdf-modal-title">Document</span>
+      <span class="pdf-modal-type" id="pdf-modal-type">PDF</span>
+      <div class="pdf-modal-actions">
+        <a class="pdf-modal-btn" id="pdf-modal-download" href="#" download target="_blank">⬇ Download</a>
+        <button class="pdf-modal-btn close" onclick="closePdfModal()">✕ Close</button>
+      </div>
+    </div>
+    <div class="pdf-modal-body" id="pdf-modal-body">
+      <div class="pdf-modal-loading" id="pdf-modal-loading">
+        <div class="pdf-spin"></div>
+        <span>Loading document…</span>
+      </div>
+      <iframe id="pdf-modal-iframe" style="display:none;" onload="onPdfLoaded()"></iframe>
+    </div>
+  </div>
+</div>
+
+<script>
+// ────────────────────────────────────────────────────────────────────────────
+// Markdown pre-processing
+// ────────────────────────────────────────────────────────────────────────────
+function cleanMarkdown(text) {
+  if (!text) return text;
+
+  // Strip footnote definition lines (e.g. [^1]: Source doc...) — remove each line
+  // rather than cutting the whole response, because KAs emit citations inline.
+  text = text.replace(/^\[\^[^\]]+\]:.*$/gm, '');
+  // Strip remaining inline footnote reference markers like [^id]
+  text = text.replace(/\[\^[^\]]+\]/g, '');
+
+  // Strip the MAS routing announcement ("I'll query the X system to...")
+  // These appear before the actual answer and are just noise to the user.
+  text = text.replace(/^I'(?:ll|m going to) (?:query|check|access|search|look up|pull|retrieve|examine|analyze|review|consult|use)[^.!?]*[.!?]\s*/i, '');
+
+  // Strip KA/Genie error lines injected by MAS when a sub-agent fails
+  text = text.replace(/Error:\s*KA endpoint [^\n]+\n?/g, '');
+  text = text.replace(/Error:\s*Failed to query Genie space [^\n]+\n?/g, '');
+
+  // Fix MAS table formatting — the MAS concatenates rows on one line:
+  //   "||col1|col2| |-|-| |v1|v2| |v3|v4|Next paragraph"
+  // a) "||" = agent-label separator + table start → blank line + table
+  text = text.replace(/\|\|/g, '\n\n|');
+  // b) "| |" = end of one row + start of next → newline between rows
+  text = text.replace(/\| \|/g, '|\n|');
+  // c) Pipe + capital letter = end of table followed by new paragraph.
+  //    Use negative lookahead to avoid firing inside table cells:
+  //    only matches when the capital-letter word is NOT followed by another pipe
+  //    on the same line (which would indicate it's a cell value, not new text).
+  text = text.replace(/\|([A-Z*_\[])(?![^|\n]*\|)/g, '|\n\n$1');
+  // d) Table header rows that are missing a leading pipe (Genie returns headers
+  //    like "col1|col2|col3|" without the leading |). marked.js requires the
+  //    leading pipe to recognise the row as part of a GFM table.
+  text = text.replace(/^([A-Za-z_][^|\n]*(?:\|[^\n]*)+\|)\s*$/gm, '|$1');
+  // e) Strip pandas DataFrame integer row-index column.
+  //    Genie wraps results in a DataFrame whose index (0, 1, 2...) is an unnamed
+  //    first column: header has N cells, separator+data rows have N+1 cells.
+  //    marked.js rejects the table when cell counts don't match.
+  //    Fix: detect header/separator mismatch, strip the extra leading cell from
+  //    the separator row and the leading integer from each data row.
+  const _allLines = text.split('\n');
+  for (let _i = 0; _i < _allLines.length; _i++) {
+    if (_i + 1 < _allLines.length
+        && _allLines[_i].startsWith('|')
+        && /^\|[-: |]+\|$/.test(_allLines[_i + 1])) {
+      const _hdrCols = (_allLines[_i].match(/\|/g) || []).length - 1;
+      const _sepCols = (_allLines[_i + 1].match(/\|/g) || []).length - 1;
+      if (_sepCols === _hdrCols + 1) {
+        _allLines[_i + 1] = _allLines[_i + 1].replace(/^\|[^|]*/, '');
+        for (let _j = _i + 2; _j < _allLines.length && _allLines[_j].startsWith('|'); _j++) {
+          _allLines[_j] = _allLines[_j].replace(/^\|\d+\|/, '|');
+        }
+      }
+    }
+  }
+  text = _allLines.join('\n');
+
+  // Collapse 3+ blank lines to 2
+  text = text.replace(/\n{3,}/g, '\n\n');
+
+  return text.trim();
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// State
+// ────────────────────────────────────────────────────────────────────────────
+let currentView = 'dashboard';
+let currentSessionId = null;
+let isStreaming = false;
+let lastUserMessage = '';
+let _streamAbortController = null;
+let _waitPromptTimer = null;
+let revenueChart = null;
+let locationMap = null;
+// Hoisted above setTheme() — `let` creates a temporal dead zone, and
+// initTheme() invokes setTheme() before loadRevenue() ever runs, so this
+// declaration must come early.  Populated by loadRevenue() and reused by
+// setTheme() on theme toggle to re-paint chart palette without re-fetching.
+let _lastRevenueData = null;
+let referencedDocs = [];
+let sessions = [];
+let techInfo = {};
+let lastAssistantText = '';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Theme
+// ────────────────────────────────────────────────────────────────────────────
+function setTheme(theme) {
+  document.documentElement.setAttribute('data-theme', theme);
+  localStorage.setItem('ceo-theme', theme);
+  document.getElementById('theme-dark').classList.toggle('active', theme === 'dark');
+  document.getElementById('theme-light').classList.toggle('active', theme === 'light');
+  if (locationMap) {
+    // Re-render tiles by invalidating map size (the Leaflet tile filter is
+    // already swapped via the [data-theme] CSS selectors above).
+    setTimeout(() => locationMap.invalidateSize(), 100);
+  }
+  // Re-render the Chart.js Revenue panel so the bar/grid/label colors pick
+  // up the new palette.  The chart reads `data-theme` at render time, so
+  // a destroy+recreate cycle is sufficient — no /api/revenue refetch.
+  if (typeof renderRevenueChart === 'function' && _lastRevenueData) {
+    renderMetrics(_lastRevenueData);
+    renderRevenueChart(_lastRevenueData);
+  }
+  // Swap the embedded ops dashboard iframe to the matching light/dark
+  // variant.  Databricks embeds always render their `light` theme slot,
+  // so we publish two dashboards with different palettes baked in.
+  if (typeof mountOpsFullDashboardIframe === 'function' && currentView === 'ops-dashboard') {
+    mountOpsFullDashboardIframe();
+  }
+}
+
+(function initTheme() {
+  const saved = localStorage.getItem('ceo-theme') || 'dark';
+  setTheme(saved);
+})();
+
+// ────────────────────────────────────────────────────────────────────────────
+// View switching
+// ────────────────────────────────────────────────────────────────────────────
+function switchView(view) {
+  currentView = view;
+  document.getElementById('view-dashboard').style.display    = view === 'dashboard' ? 'flex' : 'none';
+  document.getElementById('view-documents').classList.toggle('active',      view === 'documents');
+  document.getElementById('view-ops-dashboard').classList.toggle('active',  view === 'ops-dashboard');
+  document.getElementById('nav-dashboard').classList.toggle('active',      view === 'dashboard');
+  document.getElementById('nav-documents').classList.toggle('active',      view === 'documents');
+  document.getElementById('nav-ops-dashboard').classList.toggle('active',  view === 'ops-dashboard');
+  if (view === 'dashboard' && locationMap) {
+    setTimeout(() => locationMap.invalidateSize(), 200);
+  }
+  if (view === 'ops-dashboard') {
+    mountOpsFullDashboardIframe();
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Sessions
+// ────────────────────────────────────────────────────────────────────────────
+async function loadSessions() {
+  try {
+    const res = await fetch('/api/sessions');
+    sessions = await res.json();
+    renderSessionList();
+    // On initial load (no session selected yet), auto-open the most recent session
+    if (!currentSessionId) {
+      if (sessions.length) {
+        await selectSession(sessions[0].id, sessions[0].title);
+      } else {
+        renderWelcome();
+      }
+    }
+  } catch (e) { console.error(e); renderWelcome(); }
+}
+
+function renderSessionList() {
+  const list = document.getElementById('session-list');
+  if (!sessions.length) {
+    list.innerHTML = '<div style="padding:8px 16px; font-size:11px; color:var(--text-muted);">No sessions yet</div>';
+    return;
+  }
+  list.innerHTML = sessions.map(s => `
+    <button class="session-item ${s.id === currentSessionId ? 'active' : ''}"
+            onclick="selectSession('${s.id}', '${escHtml(s.title)}')">
+      <span class="session-icon">💬</span>
+      ${escHtml(s.title)}
+    </button>
+  `).join('');
+}
+
+async function createSession() {
+  try {
+    const res = await fetch('/api/sessions', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({title: 'Ops Session'}),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const session = await res.json();
+    if (!session?.id) throw new Error('Invalid session response');
+    currentSessionId = session.id;
+    sessions.unshift(session);
+    renderSessionList();
+    clearChat();
+    updateChatLabel(session.title);
+    showToast('New session started');
+  } catch (e) { console.error('createSession:', e); }
+}
+
+async function selectSession(id, title) {
+  currentSessionId = id;
+  renderSessionList();
+  updateChatLabel(title);
+  referencedDocs = [];
+  renderDocList();
+
+  const msgs = document.getElementById('chat-messages');
+  msgs.innerHTML = '';
+  try {
+    const res = await fetch(`/api/sessions/${id}/messages`);
+    const messages = await res.json();
+    if (!messages.length) {
+      renderWelcome();
+      return;
+    }
+    messages.forEach(m => {
+      if (m.documents_referenced?.length) {
+        referencedDocs.push(...m.documents_referenced);
+      }
+      appendMessage(m.role, m.content, false);
+    });
+    renderDocList();
+    msgs.scrollTop = msgs.scrollHeight;
+  } catch (e) {
+    renderWelcome();
+  }
+}
+
+function updateChatLabel(title) {
+  document.getElementById('chat-session-label').textContent = title;
+}
+
+function clearChat() {
+  document.getElementById('chat-messages').innerHTML = '';
+  renderWelcome();
+  // Only hide the conditional refund button. The other 4 (briefing / risk /
+  // board / complaints) are always-visible by HTML default; the container
+  // must stay display:flex.
+  document.getElementById('btn-refund').style.display = 'none';
+  referencedDocs = [];
+  renderDocList();
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Chat
+// ────────────────────────────────────────────────────────────────────────────
+function handleKey(e) {
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault();
+    sendMessage();
+  }
+}
+
+async function sendMessage() {
+  const input = document.getElementById('chat-input');
+  const text = input.value.trim();
+  if (!text || isStreaming) return;
+
+  if (!currentSessionId) {
+    await createSession();
+  }
+
+  input.value = '';
+  input.style.height = 'auto';
+  lastUserMessage = text;
+  appendMessage('user', text, false);
+
+  isStreaming = true;
+  document.getElementById('send-btn').style.display = 'none';
+  document.getElementById('cancel-btn').style.display = 'flex';
+  startBunny();
+
+  // Show typing indicator
+  const typingEl = showTyping();
+
+  const bubbleEl = document.createElement('div');
+  bubbleEl.className = 'message assistant';
+  // Use a unique per-message ID to avoid conflicts with previous messages
+  const streamId = 'sb-' + Date.now();
+  let rawContent = '';
+  let streamBubble = null;
+  let inlinePendingEl = null;
+  let routingLabel = '';
+  let warningText = '';
+
+  _streamAbortController = new AbortController();
+  // After 200s, show the wait-or-stop prompt
+  _waitPromptTimer = setTimeout(() => showWaitPrompt(), 200_000);
+
+  try {
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({session_id: currentSessionId, message: text}),
+      signal: _streamAbortController.signal,
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let started = false;
+    let streamDone = false;
+
+    while (!streamDone) {
+      const {done, value} = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, {stream: true});
+      const lines = buffer.split('\n');
+      buffer = lines.pop();
+
+      for (const line of lines) {
+        if (line.startsWith('data:')) {
+          const data = line.slice(5).trim();
+          if (data === '[DONE]') { streamDone = true; break; }
+          try {
+            const obj = JSON.parse(data);
+            const msgs = document.getElementById('chat-messages');
+            if (obj.routing) {
+              routingLabel = obj.routing;
+            } else if (obj.warning) {
+              warningText = obj.warning;
+            } else if (obj.thinking) {
+              // Show animated dots inside the bubble while waiting for the next chunk.
+              // Require 80+ chars already visible so dots never appear right after the
+              // typing indicator clears (which would look like two loading states in a row).
+              if (started && streamBubble && !inlinePendingEl && rawContent.length > 80) {
+                inlinePendingEl = document.createElement('div');
+                inlinePendingEl.className = 'stream-thinking';
+                inlinePendingEl.innerHTML = '<span class="stream-thinking-dot"></span><span class="stream-thinking-dot"></span><span class="stream-thinking-dot"></span>';
+                streamBubble.appendChild(inlinePendingEl);
+                msgs.scrollTop = msgs.scrollHeight;
+              }
+            } else if (obj.content) {
+              rawContent += obj.content;
+              if (!started) {
+                let _earlyRendered = '';
+                try { _earlyRendered = marked.parse(cleanMarkdown(rawContent)); } catch (_me) {}
+                if (_earlyRendered.trim()) {
+                  // Real content arrived — clear typing indicator and open the response bubble
+                  clearTyping(typingEl);
+                  stopBunny();
+                  document.getElementById('chat-messages').appendChild(bubbleEl);
+                  bubbleEl.innerHTML = `
+                    <div class="message-avatar">AI</div>
+                    <div class="message-bubble" id="${streamId}"></div>
+                  `;
+                  streamBubble = document.getElementById(streamId);
+                  streamBubble.innerHTML = _earlyRendered;
+                  started = true;
+                } else {
+                  // Still in routing-announcement phase — keep typing indicator visible
+                  // but update it to show which agent is being consulted
+                  const _consultLabel = _extractConsultingLabel(rawContent);
+                  if (_consultLabel) _updateTypingStatus(typingEl, `Consulting ${_consultLabel}…`);
+                }
+              } else if (streamBubble) {
+                let _rendered = '';
+                try { _rendered = marked.parse(cleanMarkdown(rawContent)); } catch (_me) {}
+                if (_rendered.trim()) {
+                  streamBubble.innerHTML = _rendered;
+                  inlinePendingEl = null;
+                }
+              }
+              msgs.scrollTop = msgs.scrollHeight;
+            }
+          } catch (_) {}
+        }
+      }
+    }
+  } catch (e) {
+    clearTyping(typingEl);
+    const wasCancelled = e.name === 'AbortError';
+    if (wasCancelled) {
+      // User cancelled — show partial response with a note, or remove the bubble
+      if (rawContent && streamBubble) {
+        const note = document.createElement('div');
+        note.style.cssText = 'font-size:11px;color:var(--text-muted);margin-top:6px;';
+        note.textContent = '⏹ Stopped.';
+        streamBubble.appendChild(note);
+      } else {
+        bubbleEl.remove();
+      }
+    } else if (!rawContent) {
+      // No content received — show error with a retry button
+      const msgs = document.getElementById('chat-messages');
+      const errEl = document.createElement('div');
+      errEl.className = 'message assistant';
+      errEl.innerHTML = `
+        <div class="message-avatar">AI</div>
+        <div class="message-bubble" style="display:flex;align-items:center;gap:10px;flex-wrap:wrap;">
+          <span>⚠️ Connection dropped before a response arrived.</span>
+          <button class="retry-btn" onclick="retryLastMessage(this)">↺ Retry</button>
+        </div>
+      `;
+      msgs.appendChild(errEl);
+      msgs.scrollTop = msgs.scrollHeight;
+    } else if (streamBubble) {
+      const warn = document.createElement('div');
+      warn.style.cssText = 'font-size:11px;color:var(--warning);margin-top:6px;';
+      warn.textContent = '⚠️ Connection dropped — response may be incomplete.';
+      streamBubble.appendChild(warn);
+    }
+  }
+
+  // If stream ended but typing indicator was never replaced (empty response)
+  if (document.contains(typingEl)) clearTyping(typingEl);
+
+  stopBunny();
+  clearTimeout(_waitPromptTimer);
+  hideWaitPrompt();
+  _streamAbortController = null;
+  isStreaming = false;
+  document.getElementById('send-btn').style.display = 'flex';
+  document.getElementById('cancel-btn').style.display = 'none';
+  lastAssistantText = rawContent;
+  updateActionButtons(rawContent);
+
+  // Routing attribution pill — shows which sub-agent handled this response
+  if (streamBubble && routingLabel) {
+    const pill = document.createElement('div');
+    pill.className = 'routing-pill';
+    pill.textContent = routingLabel;
+    streamBubble.insertBefore(pill, streamBubble.firstChild);
+  }
+
+  // Session persistence warning — shown when Lakebase write failed
+  if (streamBubble && warningText) {
+    const warnEl = document.createElement('div');
+    warnEl.style.cssText = 'font-size:11px;color:var(--warning,#f59e0b);margin-top:6px;';
+    warnEl.textContent = warningText;
+    streamBubble.appendChild(warnEl);
+  }
+
+  // Append referenced document buttons (before suggestions)
+  // Pass lastUserMessage so matching works even when the answer is very concise.
+  if (streamBubble && rawContent) appendDocButtons(streamBubble, rawContent, lastUserMessage);
+
+  // Append contextual follow-up suggestions inside the last bubble
+  if (streamBubble && rawContent) appendSuggestions(streamBubble, rawContent);
+
+  // Extract doc refs from response (highlights in the doc viewer tab)
+  extractAndShowDocs(rawContent);
+
+  // Re-fetch tech info if the MLflow experiment URL is not yet known — Databricks
+  // auto-creates the experiment on the first trace write, so it may appear shortly
+  // after the first chat response completes.
+  if (!techInfo.mlflow_experiment_url) {
+    setTimeout(() => loadTechInfo().then(() => loadAgents()), 3000);
+  }
+
+  // Auto-name session if first message
+  if (sessions.find(s => s.id === currentSessionId)?.title === 'Ops Session' && text.length > 10) {
+    const shortTitle = text.slice(0, 35) + (text.length > 35 ? '…' : '');
+    fetch(`/api/sessions/${currentSessionId}`, {
+      method: 'PUT',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({title: shortTitle}),
+    }).then(() => loadSessions()).catch(() => {});
+  }
+}
+
+// Extract which sub-agent is being consulted from an early routing announcement.
+// Returns a label string or null if the text isn't a recognisable routing sentence.
+function _extractConsultingLabel(text) {
+  if (text.length > 350) return null;
+  const t = text.toLowerCase();
+  const hasVerb = /\b(consult|query|check|look into|search|retriev|examin|access|review|use|using)\b/.test(t);
+  if (!hasVerb) return null;
+  if (/\blegal|litigation|complaint|lawsuit\b/.test(t))          return '⚖️ Legal Complaints';
+  if (/\bregulat|permit|certif|compliance|fda|zoning\b/.test(t)) return '📋 Regulatory';
+  if (/\baudit|auditor|finding\b/.test(t))                        return '🔍 Audit Findings';
+  if (/\bconsultan|strateg|advisor|mckinsey\b/.test(t))           return '💼 Consultancy';
+  if (/\binspect|violation|food safety\b/.test(t))                return '🛡️ Inspections';
+  if (/\brevenue|sales|order|financial perf\b/.test(t))           return '📊 Revenue Analytics';
+  if (/\boperat|kitchen|throughput\b/.test(t))                    return '⚙️ Operations';
+  return null;
+}
+
+// Update (or create) the status line inside the typing indicator bubble.
+function _updateTypingStatus(typingEl, text) {
+  if (!typingEl) return;
+  let statusEl = typingEl.querySelector('.typing-status-text');
+  if (!statusEl) {
+    statusEl = document.createElement('div');
+    statusEl.className = 'typing-status-text';
+    const indicator = typingEl.querySelector('.typing-indicator');
+    if (indicator) indicator.appendChild(statusEl);
+  }
+  statusEl.textContent = text;
+}
+
+function showTyping() {
+  const msgs = document.getElementById('chat-messages');
+  const el = document.createElement('div');
+  el.className = 'message assistant';
+
+  el.innerHTML = `
+    <div class="message-avatar">AI</div>
+    <div class="typing-indicator">
+      <div class="typing-dots">
+        <div class="typing-dot"></div>
+        <div class="typing-dot"></div>
+        <div class="typing-dot"></div>
+      </div>
+    </div>`;
+
+  msgs.appendChild(el);
+  msgs.scrollTop = msgs.scrollHeight;
+
+  el._stageTimers = [];
+
+  return el;
+}
+
+function clearTyping(el) {
+  el.remove();
+}
+
+function cancelStream() {
+  if (_streamAbortController) {
+    _streamAbortController.abort();
+  }
+}
+
+function retryLastMessage(btnEl) {
+  if (!lastUserMessage || isStreaming) return;
+  // Remove the error bubble
+  btnEl.closest('.message').remove();
+  // Re-inject the message into the input and send
+  const input = document.getElementById('chat-input');
+  input.value = lastUserMessage;
+  sendMessage();
+}
+
+function appendMessage(role, content, scroll = true) {
+  const msgs = document.getElementById('chat-messages');
+  const el = document.createElement('div');
+  el.className = `message ${role}`;
+  const avatar = role === 'user' ? 'You' : 'AI';
+  const bubbleContent = role === 'assistant' ? marked.parse(cleanMarkdown(content)) : escHtml(content);
+  el.innerHTML = `
+    <div class="message-avatar">${avatar}</div>
+    <div class="message-bubble">${bubbleContent}</div>
+  `;
+  msgs.appendChild(el);
+  if (scroll) msgs.scrollTop = msgs.scrollHeight;
+}
+
+const STARTER_QUESTIONS = [
+  // Multi-agent synthesis
+  'Give me a one-page board deck summary: revenue performance, top operational risk, legal exposure, and one strategic recommendation.',
+  // KA questions (fast, ~5s) — clearly single-agent
+  'What are our top 3 active legal cases by financial exposure?',
+  'What are the highest-severity findings across our audit reports?',
+  'What is the #1 strategic recommendation from our consultancy reports?',
+  'Which location has the most critical food safety violations?',
+  // Genie questions (need warm warehouse, ~15s) — specific to Gold tables
+  'What is the total revenue and order count per location for the last 7 days?',
+  'Which brand generated the highest revenue this week?',
+];
+
+function renderWelcome() {
+  const msgs = document.getElementById('chat-messages');
+  const el = document.createElement('div');
+  el.className = 'message assistant';
+  const bubble = document.createElement('div');
+  bubble.className = 'message-bubble';
+  const _hr = new Date().getHours();
+  const _greeting = _hr < 12 ? 'Good morning' : _hr < 17 ? 'Good afternoon' : 'Good evening';
+
+  // Greeting line
+  const header = document.createElement('div');
+  header.innerHTML = marked.parse(cleanMarkdown(`${_greeting}. Here's what needs your attention today.`));
+  bubble.appendChild(header);
+
+  // Hardcoded alert items — each fires a specific question into chat
+  const ALERTS = [
+    { dot: 'red',    text: 'Chicago cancel rate up 14.2% WoW — highest in the network',
+      q: "What's driving the high cancellation rate in Chicago and what should we do about it?" },
+    { dot: 'red',    text: 'HIGH-risk legal case CK-04-0031 open — financial exposure unresolved',
+      q: "Tell me about case CK-04-0031 and our total active legal exposure across all locations." },
+    { dot: 'yellow', text: '2 regulatory permits expiring within 60 days',
+      q: "Which permits or regulatory certificates are expiring in the next 60 days, and which locations are affected?" },
+  ];
+
+  const alertsDiv = document.createElement('div');
+  alertsDiv.className = 'briefing-alerts';
+  alertsDiv.innerHTML = ALERTS.map(a =>
+    `<div class="briefing-alert-item" onclick="askSuggestion(${escHtml(JSON.stringify(a.q))})">
+       <span class="alert-dot ${a.dot}"></span>
+       <span>${escHtml(a.text)}</span>
+       <span class="alert-arrow">→</span>
+     </div>`
+  ).join('');
+  bubble.appendChild(alertsDiv);
+
+  // Board meeting CTA
+  const boardBtn = document.createElement('button');
+  boardBtn.className = 'board-meeting-btn';
+  boardBtn.innerHTML = '📋 I have a board meeting in 30 minutes — brief me <span class="bmb-arrow">→</span>';
+  boardBtn.onclick = () => askSuggestion(
+    'Give me the full board briefing: revenue performance across all locations, top operational risk, legal exposure summary, and the single most important thing we need to fix in the next 90 days.'
+  );
+  bubble.appendChild(boardBtn);
+
+  // Starter question chips (skip first entry — it's covered by the board meeting button)
+  const starterDiv = document.createElement('div');
+  starterDiv.className = 'suggested-questions';
+  starterDiv.style.marginTop = '10px';
+  starterDiv.innerHTML = `
+    <div class="suggested-questions-label">Or ask something specific</div>
+    <div class="question-chips">
+      ${STARTER_QUESTIONS.slice(1).map(q =>
+        `<button class="question-chip" onclick="askSuggestion(${escHtml(JSON.stringify(q))})">${escHtml(q)}</button>`
+      ).join('')}
+    </div>`;
+  bubble.appendChild(starterDiv);
+
+  const avatar = document.createElement('div');
+  avatar.className = 'message-avatar';
+  avatar.textContent = 'AI';
+  el.appendChild(avatar);
+  el.appendChild(bubble);
+  msgs.appendChild(el);
+}
+
+// ── Impatient bunny ────────────────────────────────────────────────────────
+const BUNNY_MSGS = [
+  "Still waiting… 🙄",
+  "Is this thing on? 📡",
+  "I could've grown lettuce by now 🥬",
+  "*taps foot impatiently*",
+  "My Wi-Fi is faster than this ⚡",
+  "I have a very important carrot meeting 🥕",
+  "Bro, I'm literally a bunny and I'm faster than this",
+  "Sir, this is a Wendy's… 😐",
+  "Maybe try turning it off and on again? 💻",
+  "Still here. Still waiting. Still a bunny. 🐰",
+  "At this point I've read War and Peace 📖",
+  "I've hopped to the moon and back 🌕",
+];
+let _bunnyAppearTimer = null;
+let _bunnyMsgTimer = null;
+let _bunnyMsgIdx = 0;
+
+function startBunny() {
+  _bunnyMsgIdx = 0;
+  _bunnyAppearTimer = setTimeout(() => {
+    const el = document.getElementById('impatient-bunny');
+    el.style.display = 'flex';
+    // Cycle messages every 12 seconds
+    _bunnyMsgTimer = setInterval(() => {
+      _bunnyMsgIdx = (_bunnyMsgIdx + 1) % BUNNY_MSGS.length;
+      const msgEl = document.getElementById('bunny-msg');
+      if (msgEl) {
+        msgEl.style.animation = 'none';
+        msgEl.offsetHeight; // reflow to restart animation
+        msgEl.style.animation = '';
+        msgEl.textContent = BUNNY_MSGS[_bunnyMsgIdx];
+      }
+    }, 12_000);
+  }, 120_000);
+}
+
+function stopBunny() {
+  clearTimeout(_bunnyAppearTimer);
+  clearInterval(_bunnyMsgTimer);
+  const el = document.getElementById('impatient-bunny');
+  if (el) el.style.display = 'none';
+}
+
+function showWaitPrompt() {
+  const el = document.getElementById('wait-or-stop');
+  if (el) el.style.display = 'flex';
+}
+
+function hideWaitPrompt() {
+  const el = document.getElementById('wait-or-stop');
+  if (el) el.style.display = 'none';
+}
+
+function dismissWaitPrompt() {
+  hideWaitPrompt();
+  // Restart the timer — prompt again after another 200s if still waiting
+  _waitPromptTimer = setTimeout(() => showWaitPrompt(), 200_000);
+}
+
+function stopStreaming() {
+  hideWaitPrompt();
+  if (_streamAbortController) {
+    _streamAbortController.abort();
+    _streamAbortController = null;
+  }
+}
+
+function updateActionButtons(text) {
+  // The briefing/risk/board shortcut buttons and Review Complaints are always
+  // visible — they all send real Supervisor prompts. Only Process Refund is
+  // keyword-driven, surfaced when the AI mentions a refund-shaped topic.
+  if (!text || text.trim().length < 20) return;
+  const t = text.toLowerCase();
+  const refundKeywords = ['refund', 'late delivery', 'late order', 'delivery time', 'compensation', 'reimburse'];
+  document.getElementById('btn-refund').style.display =
+    refundKeywords.some(k => t.includes(k)) ? 'flex' : 'none';
+}
+
+// ── Refund Modal ───────────────────────────────────────────────────────────────
+
+// Optional complaint context surfaced from the complaint-list card. When set,
+// it's forwarded to /api/refund so the refund agent can ratify a goodwill
+// credit on otherwise-on-time orders. The standalone "Process Refund" button in
+// the action bar leaves this null, preserving the original SLA-only behavior.
+let _refundComplaintCtx = null;
+
+function openRefundModal(prefillOrderId, complaintCtx) {
+  const modal = document.getElementById('refund-modal');
+  modal.style.display = 'flex';
+  document.getElementById('refund-order-id').value = prefillOrderId || '';
+  document.getElementById('refund-result').className = 'refund-result';
+  document.getElementById('refund-result').innerHTML = '';
+  document.getElementById('refund-submit-btn').disabled = false;
+  _refundComplaintCtx = complaintCtx || null;
+  setTimeout(() => document.getElementById('refund-order-id').focus(), 50);
+}
+
+function closeRefundModal(e) {
+  if (e && e.target !== document.getElementById('refund-modal')) return;
+  document.getElementById('refund-modal').style.display = 'none';
+  _refundComplaintCtx = null;
+}
+
+async function submitRefund() {
+  const orderId = document.getElementById('refund-order-id').value.trim();
+  if (!orderId) return;
+  const btn = document.getElementById('refund-submit-btn');
+  const resultEl = document.getElementById('refund-result');
+  btn.disabled = true;
+  btn.textContent = '…';
+  resultEl.className = 'refund-result';
+  resultEl.innerHTML = '<div style="color:var(--text-muted);font-size:12px;">Calling refund agent…</div>';
+  resultEl.className = 'refund-result visible';
+  try {
+    const body = {order_id: orderId};
+    const ctx = _refundComplaintCtx;
+    if (ctx) {
+      // Forward complaint context so the refund agent can consider the
+      // upstream complaint-agent triage alongside its SLA-based reasoning.
+      if (ctx.customer_response) body.complaint_text     = ctx.customer_response;
+      if (ctx.category)          body.complaint_category = ctx.category;
+      if (ctx.rationale)         body.complaint_rationale = ctx.rationale;
+      if (ctx.suggest_credit)    body.suggest_credit     = Number(ctx.suggest_credit);
+    }
+    const res = await fetch('/api/refund', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({detail: res.statusText}));
+      throw new Error(err.detail || res.statusText);
+    }
+    const d = await res.json();
+    const cls = d.refund_class || 'none';
+    const clsLabel = cls === 'full' ? '🔴 FULL' : cls === 'partial' ? '🟡 PARTIAL' : '🟢 NONE';
+    const amount = d.refund_usd != null ? `$${Number(d.refund_usd).toFixed(2)}` : '—';
+    resultEl.innerHTML = `
+      <div class="agent-result-body">
+        <div class="agent-result-row">
+          <span class="agent-result-key">Decision</span>
+          <span class="agent-result-val decision-${cls}">${clsLabel}</span>
+        </div>
+        <div class="agent-result-row">
+          <span class="agent-result-key">Amount</span>
+          <span class="agent-result-val">${amount}</span>
+        </div>
+        <div class="agent-result-row" style="align-items:flex-start;">
+          <span class="agent-result-key">Reason</span>
+          <span class="agent-result-val" style="font-weight:400;color:var(--text-secondary);">${escHtml(d.reason || d.raw || '—')}</span>
+        </div>
+      </div>`;
+    // Also inject a summary card into the chat as a record
+    _appendRefundCardToChat(orderId, d);
+    _refreshLastComplaintCard();
+  } catch (e) {
+    resultEl.innerHTML = `<div style="color:var(--danger);font-size:12px;">⚠️ ${escHtml(e.message)}</div>`;
+  } finally {
+    btn.disabled = false;
+    btn.textContent = 'Evaluate';
+  }
+}
+
+function _appendRefundCardToChat(orderId, d) {
+  const msgs = document.getElementById('chat-messages');
+  const cls = d.refund_class || 'none';
+  const clsLabel = cls === 'full' ? '🔴 Full refund' : cls === 'partial' ? '🟡 Partial refund' : '🟢 No refund';
+  const amount = d.refund_usd != null ? ` — $${Number(d.refund_usd).toFixed(2)}` : '';
+  const el = document.createElement('div');
+  el.className = 'message assistant';
+  el.innerHTML = `
+    <div class="message-avatar">💳</div>
+    <div class="message-bubble">
+      <div class="agent-result-card">
+        <div class="agent-result-card-header">💳 Refund Decision · Order ${escHtml(orderId)}</div>
+        <div class="agent-result-body">
+          <div class="agent-result-row">
+            <span class="agent-result-key">Decision</span>
+            <span class="agent-result-val decision-${cls}">${clsLabel}${amount}</span>
+          </div>
+          <div class="agent-result-row" style="align-items:flex-start;">
+            <span class="agent-result-key">Reason</span>
+            <span class="agent-result-val" style="font-weight:400;color:var(--text-secondary);">${escHtml(d.reason || d.raw || '—')}</span>
+          </div>
+        </div>
+      </div>
+    </div>`;
+  msgs.appendChild(el);
+  msgs.scrollTop = msgs.scrollHeight;
+  document.getElementById('refund-modal').style.display = 'none';
+}
+
+// ── Complaint Summary ─────────────────────────────────────────────────────────
+
+let _lastComplaintsBody = null;
+
+function _toggleComplaintDetail(idx) {
+  const detail = document.getElementById(`complaint-detail-${idx}`);
+  if (!detail) return;
+  detail.classList.toggle('open');
+  const arrow = document.getElementById(`complaint-arrow-${idx}`);
+  if (arrow) arrow.textContent = detail.classList.contains('open') ? '▾' : '▸';
+}
+
+function _renderComplaintRows(decisions, uid) {
+  if (!decisions.length) {
+    return '<div style="color:var(--text-muted);font-size:12px;">No complaint decisions found. The complaint stream may not have run yet.</div>';
+  }
+  return decisions.map((d, i) => {
+    const key = `${uid}-${i}`;
+    const creditLabel = d.suggest_credit ? `<span style="color:var(--gold);font-size:11px;flex-shrink:0;margin-left:8px;">$${Number(d.suggest_credit).toFixed(2)}</span>` : '';
+    const refundBtn = (!d.escalate && d.suggest_credit && d.order_id)
+      ? `<button class="complaint-refund-btn" onclick="event.stopPropagation();openRefundModal('${escHtml(d.order_id)}', window._complaintDecisions && window._complaintDecisions[${i}])">💳 Process Refund for $${Number(d.suggest_credit).toFixed(2)}</button>`
+      : '';
+    const detailTs       = d.ts            ? `<div><span class="complaint-detail-label">Time</span><br>${escHtml(d.ts)}</div>` : '';
+    const detailOrderId  = d.order_id      ? `<div><span class="complaint-detail-label">Order ID</span><br>${escHtml(d.order_id)}</div>` : '';
+    const detailRationale= d.rationale     ? `<div style="margin-top:4px;"><span class="complaint-detail-label">Rationale</span><br>${escHtml(d.rationale)}</div>` : '';
+    const detailResponse = d.customer_response ? `<div style="margin-top:4px;"><span class="complaint-detail-label">Customer Response</span><br>${escHtml(d.customer_response)}</div>` : '';
+    return `
+      <div style="border-bottom:1px solid color-mix(in srgb, var(--border) 50%, transparent); margin-bottom:2px;">
+        <div class="agent-result-row complaint-row" onclick="_toggleComplaintDetail('${key}')">
+          <span style="color:var(--text-muted);font-size:11px;margin-right:2px;" id="complaint-arrow-${key}">▸</span>
+          <span class="agent-result-key" style="min-width:80px;">${escHtml(d.category || '—')}</span>
+          <span class="agent-result-val" style="font-size:11px;font-weight:400;color:var(--text-secondary);flex:1;">${escHtml((d.rationale || '').slice(0, 70))}${(d.rationale||'').length > 70 ? '…' : ''}</span>
+          <span class="agent-result-val" style="color:${d.escalate ? 'var(--danger)' : 'var(--success)'}; font-size:11px; flex-shrink:0; margin-left:8px;">${d.escalate ? '🔴 Escalate' : '🟢 Credit'}</span>
+          ${creditLabel}
+        </div>
+        <div class="complaint-detail" id="complaint-detail-${key}">
+          ${detailOrderId}${detailTs}${detailRationale}${detailResponse}
+          ${refundBtn}
+        </div>
+      </div>`;
+  }).join('');
+}
+
+async function _refreshLastComplaintCard() {
+  if (!_lastComplaintsBody) return;
+  try {
+    const res = await fetch('/api/complaint-decisions');
+    if (!res.ok) return;
+    const decisions = await res.json();
+    window._complaintDecisions = decisions;
+    const uid = Date.now();
+    _lastComplaintsBody.innerHTML = _renderComplaintRows(decisions, uid);
+  } catch (_) {}
+}
+
+async function triggerComplaintSummary() {
+  if (!currentSessionId) await createSession();
+  appendMessage('user', 'Show me the latest complaint decisions from the agent.', false);
+  const typingEl = showTyping();
+  try {
+    const res = await fetch('/api/complaint-decisions');
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.detail || `HTTP ${res.status}`);
+    }
+    const decisions = await res.json();
+    window._complaintDecisions = decisions;
+    clearTyping(typingEl);
+    const msgs = document.getElementById('chat-messages');
+    const el = document.createElement('div');
+    el.className = 'message assistant';
+    const uid = Date.now();
+    el.innerHTML = `
+      <div class="message-avatar">📬</div>
+      <div class="message-bubble">
+        <div class="agent-result-card">
+          <div class="agent-result-card-header">📬 Latest Complaint Decisions <span style="font-size:10px;font-weight:400;color:var(--text-muted);margin-left:6px;">click row to expand</span></div>
+          <div class="agent-result-body" id="complaints-body-${uid}" style="gap:0;">${_renderComplaintRows(decisions, uid)}</div>
+        </div>
+      </div>`;
+    msgs.appendChild(el);
+    _lastComplaintsBody = el.querySelector(`#complaints-body-${uid}`);
+    msgs.scrollTop = msgs.scrollHeight;
+  } catch (e) {
+    clearTyping(typingEl);
+    appendMessage('assistant', `⚠️ Could not load complaint decisions: ${e.message}`, true);
+  }
+}
+
+// ── Inline document buttons in chat messages ───────────────────────────────
+
+// question is the user's original message — used for additional ID scanning.
+// Only returns documents when a specific file ID (e.g. CK-01-1001, AUD-02-3006)
+// from the response maps to an actual file in the library. Keyword-based guessing
+// is intentionally omitted — it caused false positives whenever the supervisor
+// mentioned legal / audit topics without retrieving a document.
+function findMentionedDocs(text, question = '') {
+  if (!allDocGroups.length) return [];
+  const combined = text + ' ' + question;
+
+  // Extract document IDs mentioned in the response.
+  // e.g. "AUD-02-3006" → matches audit_aud_02_3006.pdf
+  //      "CK-02-1005"  → matches legal_ck_02_1005.pdf
+  const idPattern = /\b(?:CK|CON|AUD|REG|INS)-[\w-]+/gi;
+  const mentionedIds = [...new Set((combined.match(idPattern) || [])
+    .map(m => m.toLowerCase().replace(/-/g, '_')))];
+
+  if (!mentionedIds.length) return [];
+
+  // Find files whose name contains one of the extracted IDs.
+  const matches = [];
+  for (const group of allDocGroups) {
+    for (const filename of group.files) {
+      const fl = filename.toLowerCase();
+      if (mentionedIds.some(id => fl.includes(id))) {
+        matches.push({ type: group.type, filename });
+        if (matches.length >= 3) return matches;
+      }
+    }
+  }
+  return matches;
+}
+
+function appendDocButtons(bubbleEl, text, question = '') {
+  if (!bubbleEl || !text) return;
+  const docs = findMentionedDocs(text, question);
+  if (!docs.length) return;
+
+  const div = document.createElement('div');
+  div.className = 'chat-doc-refs';
+  div.innerHTML = `
+    <div class="chat-doc-refs-label">Referenced documents</div>
+    <div class="chat-doc-chips">
+      ${docs.map(({ type, filename }) => {
+        const displayName = filename.replace(/\.pdf$/i, '').replace(/_/g, ' ')
+          .replace(/\b\w/g, c => c.toUpperCase());
+        const icon = DOC_ICONS[type] || '📄';
+        const label = DOC_FILTER_LABELS[type] || type;
+        // Escape single quotes as HTML entities — backslash-escaping is invalid in HTML attributes
+        const safeType = type.replace(/'/g, "&#39;");
+        const safeName = filename.replace(/'/g, "&#39;");
+        return `<button class="chat-doc-chip"
+          onclick="openDocument('${safeType}', '${safeName}')">
+          <span class="chat-doc-chip-icon">${icon}</span>
+          <span class="chat-doc-chip-name">${escHtml(displayName)}</span>
+          <span class="chat-doc-chip-type">${escHtml(label)}</span>
+        </button>`;
+      }).join('')}
+    </div>`;
+  bubbleEl.appendChild(div);
+}
+
+// ── Suggested follow-up questions ──────────────────────────────────────────
+const QUESTION_POOLS = [
+  // Revenue pool → revenue-analytics Genie (needs warm warehouse)
+  { tags: ['revenue', 'sales', 'financial', 'profit', 'earn', 'pricing'],
+    questions: [
+      'What is total revenue by location for the last 7 days?',
+      'Which brand generated the highest revenue this week?',
+      'What is the average order value at each location this month?',
+      'How does revenue compare across locations this week?',
+    ]},
+  // Orders pool → revenue-analytics or operations-intelligence Genie
+  { tags: ['order', 'throughput', 'volume', 'count', 'cancel'],
+    questions: [
+      'What is the order count by location for the last 7 days?',
+      'Which location had the highest order throughput this week?',
+      'Which brand had the most orders this week?',
+      'How many orders were completed at each location yesterday?',
+    ]},
+  // Legal pool → legal-complaints KA (fast)
+  { tags: ['legal', 'lawsuit', 'litigation', 'case', 'settle', 'dispute', 'claim', 'liability'],
+    questions: [
+      'What are our top 3 active legal cases by financial exposure?',
+      'Which location has the most active legal cases?',
+      'What employment claims are currently open?',
+      'What is the status of the highest-risk lawsuit?',
+    ]},
+  // Inspection pool → inspection-reports KA (fast)
+  { tags: ['inspection', 'food safety', 'violation', 'health', 'haccp', 'grade', 'sanit'],
+    questions: [
+      'Which location has the most critical food safety violations?',
+      'What corrective actions are required at our locations based on inspection findings?',
+      'What violations were cited most often across all inspections?',
+      'Which food safety violations are classified as high severity?',
+    ]},
+  // Audit pool → audit-findings KA (fast)
+  { tags: ['audit', 'finding', 'internal control', 'material weakness', 'significant', 'remediat'],
+    questions: [
+      'What are the highest-severity findings across our audit reports?',
+      'Which audit findings require immediate corrective action?',
+      'What internal control weaknesses were identified in the audits?',
+      'Which location has the most significant audit findings?',
+    ]},
+  // Regulatory pool → regulatory-compliance KA (fast)
+  { tags: ['regulat', 'compliance', 'permit', 'license', 'requirement', 'statute', 'policy', 'fda', 'fire code', 'zoning', 'renewal'],
+    questions: [
+      'What permits or licenses are pending renewal across our locations?',
+      'Which regulatory requirements carry the highest penalty if missed?',
+      'What certifications does each location currently hold?',
+      'Are there any open regulatory compliance gaps at our locations?',
+    ]},
+  // Consultancy pool → consultancy-strategy KA (fast)
+  { tags: ['consultant', 'consult', 'strategy', 'recommend', 'roadmap', 'growth', 'initiative', 'invest', 'transform', 'expansion', 'priority'],
+    questions: [
+      'What is the #1 strategic recommendation from our consultancy reports?',
+      'Which strategic initiative has the fastest payback period?',
+      'What cost reduction opportunities have consultants identified?',
+      'Which location is prioritised for investment in the consultancy report?',
+    ]},
+  { tags: ['ai', 'databricks', 'automation', 'technology', 'machine learning', 'ml', 'data', 'model'],
+    questions: [
+      'What AI opportunities are identified in our consultancy reports?',
+      'Which operational process would benefit most from automation?',
+      'What data infrastructure improvements are recommended?',
+      'What is the projected ROI of the AI transformation programme?',
+    ]},
+];
+const DEFAULT_QUESTIONS = [
+  'What are our top 3 active legal cases by financial exposure?',
+  'What are the highest-severity findings across our audit reports?',
+  'What is the #1 strategic recommendation from our consultancy reports?',
+  'Which location has the most critical food safety violations?',
+];
+
+function pickSuggestions(text) {
+  const lower = text.toLowerCase();
+  // Score each pool by how many tags match
+  const scored = QUESTION_POOLS.map(pool => ({
+    pool,
+    score: pool.tags.filter(t => lower.includes(t)).length,
+  })).filter(x => x.score > 0).sort((a, b) => b.score - a.score);
+
+  // Collect candidates from top pools, dedup
+  const candidates = [];
+  const seen = new Set();
+  for (const { pool } of scored.slice(0, 2)) {
+    for (const q of pool.questions) {
+      if (!seen.has(q)) { seen.add(q); candidates.push(q); }
+    }
+  }
+  const pool = candidates.length >= 3 ? candidates : DEFAULT_QUESTIONS;
+  // Shuffle and pick 3
+  const shuffled = pool.slice().sort(() => Math.random() - 0.5);
+  return shuffled.slice(0, 3);
+}
+
+function appendSuggestions(bubbleEl, text) {
+  if (!bubbleEl || !text || text.trim().length < 30) return;
+  const questions = pickSuggestions(text);
+  const div = document.createElement('div');
+  div.className = 'suggested-questions';
+  div.innerHTML = `
+    <div class="suggested-questions-label">Try these questions</div>
+    <div class="question-chips">
+      ${questions.map(q => `<button class="question-chip" onclick="askSuggestion(${escHtml(JSON.stringify(q))})">${escHtml(q)}</button>`).join('')}
+    </div>`;
+  bubbleEl.appendChild(div);
+}
+
+function askSuggestion(text) {
+  const input = document.getElementById('chat-input');
+  input.value = text;
+  sendMessage();
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Document Library
+// ────────────────────────────────────────────────────────────────────────────
+let allDocGroups = [];      // [{category, type, files:[...]}]
+let chatRefFilenames = new Set();  // filenames mentioned in chat
+let activeFilter = 'all';
+
+const DOC_ICONS = {
+  legal: '⚖️', regulatory: '📋', audit: '🔍', consultancy: '💼', inspection: '🏥',
+};
+const DOC_FILTER_LABELS = {
+  legal: 'Legal', regulatory: 'Regulatory', audit: 'Audits',
+  consultancy: 'Consultancy', inspection: 'Inspections',
+};
+
+async function loadDocuments() {
+  try {
+    const res = await fetch('/api/documents');
+    allDocGroups = await res.json();
+    buildFilterBar();
+    renderDocList();
+    const total = allDocGroups.reduce((s, g) => s + g.count, 0);
+    document.getElementById('doc-total-count').textContent = `${total} documents`;
+  } catch (e) {
+    document.getElementById('doc-list').innerHTML = `
+      <div class="doc-empty"><span class="doc-empty-icon">⚠️</span><span>Could not load documents.</span></div>`;
+  }
+}
+
+function buildFilterBar() {
+  const bar = document.getElementById('doc-filter-bar');
+  const total = allDocGroups.reduce((s, g) => s + g.count, 0);
+  bar.innerHTML = `<button class="doc-filter-btn ${activeFilter==='all'?'active':''}" onclick="filterDocs('all')" data-filter="all">All (${total})</button>` +
+    allDocGroups.map(g => `
+      <button class="doc-filter-btn ${activeFilter===g.type?'active':''}" onclick="filterDocs('${g.type}')" data-filter="${g.type}">
+        ${DOC_FILTER_LABELS[g.type]||g.category} (${g.count})
+      </button>`).join('');
+}
+
+function filterDocs(filter) {
+  activeFilter = filter;
+  document.querySelectorAll('.doc-filter-btn').forEach(b => {
+    b.classList.toggle('active', b.dataset.filter === filter);
+  });
+  renderDocList();
+}
+
+function renderDocList() {
+  const list = document.getElementById('doc-list');
+  const groups = activeFilter === 'all' ? allDocGroups : allDocGroups.filter(g => g.type === activeFilter);
+
+  if (!groups.length || groups.every(g => !g.files.length)) {
+    list.innerHTML = `<div class="doc-empty"><span class="doc-empty-icon">🗂</span><span>No documents found.</span></div>`;
+    return;
+  }
+
+  let html = '';
+  for (const group of groups) {
+    if (!group.files.length) continue;
+    if (activeFilter === 'all') {
+      html += `<div class="doc-group-label">${DOC_ICONS[group.type]||'📄'} ${escHtml(group.category)} <span>${group.count}</span></div>`;
+    }
+    for (const filename of group.files) {
+      const isChatRef = chatRefFilenames.has(filename);
+      const displayName = filename.replace(/\.(pdf)$/i, '').replace(/_/g, ' ');
+      html += `
+        <div class="doc-item ${isChatRef ? 'chat-ref' : ''}" onclick="openDocument('${group.type}', '${escHtml(filename)}')">
+          <span class="doc-item-icon">${DOC_ICONS[group.type]||'📄'}</span>
+          <div class="doc-item-body">
+            <div class="doc-item-title">${escHtml(displayName)}</div>
+            <div class="doc-item-meta">${escHtml(group.category)}${isChatRef ? ' · Referenced in chat' : ''}</div>
+          </div>
+          <span class="doc-item-open">↗</span>
+        </div>`;
+    }
+  }
+  list.innerHTML = html;
+}
+
+function openDocument(type, filename) {
+  const url = `/api/documents/${type}/${encodeURIComponent(filename)}`;
+  const displayName = filename.replace(/\.pdf$/i, '').replace(/_/g, ' ');
+  const icon = DOC_ICONS[type] || '📄';
+  const label = DOC_FILTER_LABELS[type] || type;
+
+  document.getElementById('pdf-modal-title').textContent = displayName;
+  document.getElementById('pdf-modal-icon').textContent = icon;
+  document.getElementById('pdf-modal-type').textContent = label;
+  document.getElementById('pdf-modal-download').href = url;
+  document.getElementById('pdf-modal-download').download = filename;
+
+  const iframe = document.getElementById('pdf-modal-iframe');
+  const loading = document.getElementById('pdf-modal-loading');
+  iframe.style.display = 'none';
+  loading.style.display = 'flex';
+  iframe.src = url;
+
+  document.getElementById('pdf-modal').style.display = 'flex';
+  document.body.style.overflow = 'hidden';
+}
+
+function onPdfLoaded() {
+  document.getElementById('pdf-modal-iframe').style.display = 'block';
+  document.getElementById('pdf-modal-loading').style.display = 'none';
+}
+
+function closePdfModal(e) {
+  if (e && e.target !== document.getElementById('pdf-modal')) return;
+  document.getElementById('pdf-modal').style.display = 'none';
+  document.getElementById('pdf-modal-iframe').src = '';
+  document.body.style.overflow = '';
+}
+
+// Close on Escape key
+document.addEventListener('keydown', e => {
+  if (e.key === 'Escape') closePdfModal();
+});
+
+// Extract filenames mentioned in AI responses and highlight them in the doc viewer
+const DOC_PATTERNS = [
+  { re: /inspection_[\w-]+\.pdf/gi },
+  { re: /legal_[\w-]+\.pdf/gi },
+  { re: /regulatory_[\w-]+\.pdf/gi },
+  { re: /audit_[\w-]+\.pdf/gi },
+  { re: /consultancy_[\w-]+\.pdf/gi },
+];
+
+function extractAndShowDocs(text) {
+  let found = false;
+  for (const {re} of DOC_PATTERNS) {
+    for (const m of text.matchAll(re)) {
+      chatRefFilenames.add(m[0]);
+      found = true;
+    }
+  }
+  if (found) {
+    renderDocList();
+    updateDocBadge();
+  }
+}
+
+function updateDocBadge() {
+  const badge = document.getElementById('doc-badge');
+  const total = allDocGroups.reduce((s, g) => s + g.count, 0);
+  if (total > 0) {
+    badge.style.display = 'inline-block';
+    badge.textContent = total;
+  } else {
+    badge.style.display = 'none';
+  }
+}
+
+function viewDoc(i) {
+  switchView('documents');
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Revenue Chart
+// ────────────────────────────────────────────────────────────────────────────
+// `_lastRevenueData` is declared near the top of the module so setTheme()
+// can read it without hitting a temporal-dead-zone error at page load.
+//
+// On 503 the frontend deliberately does NOT fall back to fabricated demo
+// numbers — we show an explicit "Revenue analytics unavailable" banner so
+// the audience never sees fake figures presented as real.  The audience
+// noticing a banner is much less painful than the audience NOT noticing
+// fake numbers and asking pointed follow-up questions about them.
+async function loadRevenue() {
+  const errBox  = document.getElementById('revenue-error');
+  const errBody = document.getElementById('revenue-error-body');
+  try {
+    const res = await fetch('/api/revenue');
+    if (!res.ok) {
+      // Surface the backend's structured error message (503 from
+      // /api/revenue when the warehouse fetch fails and there's no
+      // cached snapshot to fall back on).
+      let detail = '';
+      try {
+        const body = await res.json();
+        detail = (body && body.detail && body.detail.message) ||
+                 (body && body.detail) || `HTTP ${res.status}`;
+      } catch (_) {
+        detail = `HTTP ${res.status}`;
+      }
+      _lastRevenueData = [];
+      if (errBox) {
+        errBox.style.display = 'block';
+        if (errBody) errBody.textContent = String(detail);
+      }
+      renderMetrics(_lastRevenueData);
+      renderRevenueChart(_lastRevenueData);
+      return;
+    }
+    _lastRevenueData = await res.json();
+    if (errBox) errBox.style.display = 'none';
+  } catch (e) {
+    // Network-level failure (offline, app down, etc.) — same UX treatment.
+    _lastRevenueData = [];
+    if (errBox) {
+      errBox.style.display = 'block';
+      if (errBody) errBody.textContent = 'Could not reach the dashboard backend. Check your connection and refresh.';
+    }
+  }
+  renderMetrics(_lastRevenueData);
+  renderRevenueChart(_lastRevenueData);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Embedded AI/BI Operations Dashboard (opt-in "Ops Dashboard" tab)
+// ────────────────────────────────────────────────────────────────────────────
+// We publish the dashboard in TWO variants — light + dark — because
+// Databricks embedded dashboards always render their `light` theme slot
+// (the `?theme=` URL param is ignored).  The dark variant bakes dark-
+// palette tokens into the light slot; the iframe just needs the right ID,
+// which the frontend swaps when the user toggles the app theme.
+//
+// We deliberately do NOT embed in the always-visible Revenue card — the
+// embed has four hard limitations (fixed canvas width → whitespace, no
+// anonymous viewing, separate workspace login on first view, no dynamic
+// theming) that are deal-breakers for an always-visible panel but
+// acceptable for an opt-in tab the user explicitly navigates to.
+function mountOpsFullDashboardIframe() {
+  const iframe = document.getElementById('ops-full-dashboard-iframe');
+  const empty  = document.getElementById('ops-full-dashboard-empty');
+  if (!iframe || !empty) return;
+  if (!techInfo) {
+    iframe.style.display = 'none';
+    empty.style.display  = 'flex';
+    return;
+  }
+  const isDark   = (document.documentElement.getAttribute('data-theme') || 'dark') === 'dark';
+  const darkUrl  = techInfo.ops_dashboard_embed_url_dark  || '';
+  const lightUrl = techInfo.ops_dashboard_embed_url_light || techInfo.ops_dashboard_embed_url || '';
+  const url      = isDark ? (darkUrl || lightUrl) : (lightUrl || darkUrl);
+  if (!url) {
+    iframe.style.display = 'none';
+    empty.style.display  = 'flex';
+    empty.textContent    = 'Operations dashboard URL not configured. Check OPS_DASHBOARD_ID in app.yaml.';
+    return;
+  }
+  if (iframe.src !== url) iframe.src = url;
+  iframe.style.display = 'block';
+  empty.style.display  = 'none';
+}
+
+// _mockRevenue() was deliberately removed — see the comment on loadRevenue()
+// above.  The dashboard now shows an explicit "unavailable" banner rather
+// than substituting fabricated numbers when /api/revenue 503s.
+
+function fmt$(n) {
+  if (n >= 1_000_000) return '$' + (n/1_000_000).toFixed(2) + 'M';
+  if (n >= 1_000) return '$' + (n/1_000).toFixed(1) + 'K';
+  return '$' + n.toFixed(0);
+}
+function fmtTrend(curr, prev) {
+  if (!prev) return '';
+  const pct = ((curr - prev) / prev * 100).toFixed(1);
+  const up = pct >= 0;
+  return `<span style="color:var(--${up?'success':'danger'});font-size:11px;">${up?'▲':'▼'} ${Math.abs(pct)}% vs prev</span>`;
+}
+
+function renderMetrics(data) {
+  const row = document.getElementById('metric-row');
+  if (!row) return;
+  // Empty `data` happens when /api/revenue 503'd — paint placeholder cards
+  // so the layout stays stable and the "unavailable" banner above isn't
+  // floating in a void.
+  if (!Array.isArray(data) || data.length === 0) {
+    const ph = `<div class="metric-card">
+      <div class="metric-label">—</div>
+      <div class="metric-value" style="color:var(--text-muted);">—</div>
+      <div class="metric-sub">data unavailable</div>
+    </div>`;
+    row.innerHTML = ph.repeat(4);
+    return;
+  }
+  const totalRevenue = data.reduce((s, d) => s + (d.revenue || 0), 0);
+  const totalRevenuePrev = data.reduce((s, d) => s + (d.revenue_prev || 0), 0);
+  const avgOrderValue = data.reduce((s, d) => s + (d.avg_order_value || 0), 0) / data.length;
+  const totalOrders = data.reduce((s, d) => s + (d.completed_orders || 0), 0);
+  const worstLoc = data.reduce((a, b) => (b.cancel_rate_pct || 0) > (a.cancel_rate_pct || 0) ? b : a);
+  const bestLoc = data.reduce((a, b) => (b.revenue || 0) > (a.revenue || 0) ? b : a);
+
+  document.getElementById('metric-row').innerHTML = `
+    <div class="metric-card">
+      <div class="metric-label">Total Revenue</div>
+      <div class="metric-value success">${fmt$(totalRevenue)}</div>
+      <div class="metric-sub">${fmtTrend(totalRevenue, totalRevenuePrev) || 'All locations'}</div>
+    </div>
+    <div class="metric-card">
+      <div class="metric-label">Top Location</div>
+      <div class="metric-value">${bestLoc.location?.split(' ')[0] || '—'}</div>
+      <div class="metric-sub">${fmt$(bestLoc.revenue || 0)} revenue</div>
+    </div>
+    <div class="metric-card">
+      <div class="metric-label">Avg Order Value</div>
+      <div class="metric-value">$${avgOrderValue.toFixed(2)}</div>
+      <div class="metric-sub">${totalOrders.toLocaleString()} orders completed</div>
+    </div>
+    <div class="metric-card">
+      <div class="metric-label">Attention Needed</div>
+      <div class="metric-value ${worstLoc.cancel_rate_pct > 8 ? 'danger' : 'warning'}">${worstLoc.location?.split(' ')[0] || '—'}</div>
+      <div class="metric-sub">${(worstLoc.cancel_rate_pct || 0).toFixed(1)}% cancel rate</div>
+    </div>
+  `;
+}
+
+function renderRevenueChart(data) {
+  const canvas = document.getElementById('revenue-chart');
+  if (!canvas) return;
+  const ctx = canvas.getContext('2d');
+  if (revenueChart) revenueChart.destroy();
+  // Empty `data` happens when /api/revenue 503'd — clear the canvas and
+  // bail so we don't render a chart of zeros that the audience might
+  // misread as "real data showing zero revenue".  The error banner above
+  // already explains what happened.
+  if (!Array.isArray(data) || data.length === 0) {
+    revenueChart = null;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    return;
+  }
+
+  const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+  const gridColor = isDark ? 'rgba(255,255,255,0.05)' : 'rgba(0,0,0,0.05)';
+  const labelColor = isDark ? '#9898A2' : '#505058';
+  const colors = ['#FF3621', '#3ecf8e', '#f5a623', '#FF6B50'];
+  const sorted = [...data].sort((a, b) => (b.revenue || 0) - (a.revenue || 0));
+
+  revenueChart = new Chart(ctx, {
+    type: 'bar',
+    data: {
+      labels: sorted.map(d => d.location.replace('Silicon Valley', 'Sil. Valley')),
+      datasets: [
+        {
+          label: 'Revenue (This Period)',
+          data: sorted.map(d => d.revenue || 0),
+          backgroundColor: colors.map(c => c + 'cc'),
+          borderColor: colors,
+          borderWidth: 1.5,
+          borderRadius: 5,
+          order: 1,
+        },
+        {
+          label: 'Revenue (Prev Period)',
+          data: sorted.map(d => d.revenue_prev || 0),
+          backgroundColor: isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.06)',
+          borderColor: isDark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.15)',
+          borderWidth: 1,
+          borderRadius: 5,
+          order: 2,
+        },
+      ],
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      interaction: { mode: 'index', intersect: false },
+      plugins: {
+        legend: { labels: { color: labelColor, font: { size: 11 }, boxWidth: 10, padding: 12 } },
+        tooltip: {
+          backgroundColor: isDark ? '#191512' : '#ffffff',
+          borderColor: isDark ? '#2E2018' : '#E2CEC6',
+          borderWidth: 1,
+          titleColor: labelColor,
+          bodyColor: labelColor,
+          callbacks: {
+            label: ctx => ` ${ctx.dataset.label}: ${fmt$(ctx.raw)}`,
+          },
+        },
+      },
+      scales: {
+        x: { ticks: { color: labelColor, font: { size: 10 } }, grid: { color: gridColor } },
+        y: {
+          ticks: {
+            color: labelColor, font: { size: 10 },
+            callback: v => fmt$(v),
+          },
+          grid: { color: gridColor },
+        },
+      },
+    },
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Location Map
+// ────────────────────────────────────────────────────────────────────────────
+async function initMap() {
+  locationMap = L.map('location-map', {
+    center: [40, -20], zoom: 2,
+    zoomControl: true,
+  });
+
+  L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
+    attribution: '© OpenStreetMap contributors'
+  }).addTo(locationMap);
+
+  try {
+    const res = await fetch('/api/locations');
+    const locs = await res.json();
+
+    const markers = [];
+    for (const loc of locs) {
+      const riskColor = { high: '#e85d5d', medium: '#f5a623', low: '#3ecf8e' }[loc.risk_level] || '#FF3621';
+      const _isHighRisk = loc.risk_level === 'high';
+      const icon = L.divIcon({
+        className: '',
+        html: `
+          <div style="position:relative; width:14px; height:14px;">
+            ${_isHighRisk ? `<div style="
+              position:absolute; top:-6px; left:-6px;
+              width:26px; height:26px; border-radius:50%;
+              background:${riskColor}; opacity:0.35;
+              animation:map-pulse 1.8s ease-out infinite;
+            "></div>` : ''}
+            <div style="
+              position:relative; z-index:1;
+              background:${riskColor};
+              width:14px; height:14px; border-radius:50%;
+              border:2px solid #fff;
+              box-shadow:0 0 0 3px ${riskColor}44, 0 2px 8px rgba(0,0,0,0.5);
+            "></div>
+          </div>`,
+        iconSize: [14, 14],
+        iconAnchor: [7, 7],
+      });
+
+      const marker = L.marker([loc.lat, loc.lng], { icon });
+      const riskEmoji = { high: '🔴', medium: '🟡', low: '🟢' }[loc.risk_level] || '⚪';
+      const _locNameEnc = encodeURIComponent(loc.name);
+      marker.bindPopup(`
+        <div style="font-family: 'Inter', sans-serif; min-width: 190px; padding: 4px;">
+          <div style="font-weight: 700; font-size: 13px; margin-bottom: 6px;">
+            ${riskEmoji} ${loc.name}
+          </div>
+          <div style="font-size: 11px; color: #666; margin-bottom: 8px;">${loc.address}</div>
+          <div style="font-size: 11px; margin-bottom: 10px;">
+            <b>Orders:</b> ${(loc.total_orders || 0).toLocaleString()}<br>
+            <b>Revenue Δ vs prior 30d:</b> <span style="color:${(loc.revenue_change_pct ?? 0) < 20 ? '#e85d5d' : '#3ecf8e'}; font-weight:600;">${(loc.revenue_change_pct ?? 0) > 0 ? '+' : ''}${(loc.revenue_change_pct ?? 0).toFixed(1)}%</span><br>
+            <b>Cancel Rate:</b> ${(loc.cancel_rate_pct || 0).toFixed(1)}%<br>
+            <b>Risk:</b> <span style="color:${riskColor}; font-weight:600;">${loc.risk_level?.toUpperCase()}</span>
+          </div>
+          <button onclick="window._briefLocation(decodeURIComponent('${_locNameEnc}'))"
+            style="width:100%;padding:6px 10px;background:#FF3621;color:#fff;border:none;
+                   border-radius:4px;font-size:11px;font-weight:600;cursor:pointer;font-family:inherit;">
+            Brief me on this location →
+          </button>
+        </div>
+      `, { maxWidth: 230 });
+      marker.addTo(locationMap);
+      markers.push(marker);
+    }
+
+    // Auto-fit to show all locations (US + EMEA)
+    if (markers.length > 0) {
+      const group = L.featureGroup(markers);
+      locationMap.fitBounds(group.getBounds().pad(0.15));
+    }
+  } catch (e) {
+    console.error('Map data error:', e);
+  }
+}
+
+// Global helper called from Leaflet popup buttons (inline onclick can't use closures)
+window._briefLocation = function(name) {
+  if (locationMap) locationMap.closePopup();
+  askSuggestion(`What's the full status for ${name}? Cover revenue performance, operational risks, any legal exposure, and upcoming compliance issues.`);
+};
+
+// Demo breaking-alert toast — fires 35 s after load to simulate a proactive alert
+window._demoAlertDismiss = function() {
+  const t = document.getElementById('demo-alert-toast');
+  if (t) { t.style.animation = 'none'; t.style.opacity = '0'; t.style.transition = 'opacity 0.2s'; setTimeout(() => t.style.display = 'none', 200); }
+};
+window._demoAlertInvestigate = function() {
+  window._demoAlertDismiss();
+  askSuggestion('What happened in the Munich food safety inspection? List the critical violations and what we need to fix immediately.');
+};
+if (new URLSearchParams(location.search).get('demo') === '1') {
+  setTimeout(() => {
+    const t = document.getElementById('demo-alert-toast');
+    if (t) t.style.display = 'flex';
+  }, 35_000);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Tech Info
+// ────────────────────────────────────────────────────────────────────────────
+async function loadTechInfo() {
+  try {
+    const res = await fetch('/api/tech-info');
+    techInfo = await res.json();
+    renderTechInfo(techInfo);
+    const rmLink = document.getElementById('nav-refund-manager');
+    if (rmLink && techInfo.refund_manager_app_url) {
+      rmLink.href = techInfo.refund_manager_app_url;
+      rmLink.style.display = '';
+    }
+  } catch (e) {
+    renderTechInfo({
+      catalog: 'caspersdev',
+      lakebase_instance: 'Not configured',
+      supervisor_endpoint: 'Not configured',
+      warehouse_id: 'Not configured',
+      db_enabled: false,
+      supervisor_enabled: false,
+    });
+  }
+}
+
+function renderTechInfo(info) {
+  const panel = document.getElementById('tech-info-panels');
+  const host = (info.databricks_host || '').replace(/\/$/, '');
+
+  // Plain row (no link)
+  const row = (label, value, ok) => `
+    <div class="tech-section">
+      <div class="tech-label">${label}</div>
+      <div class="tech-value ${ok === true ? 'ok' : ok === false ? 'warn' : ''}">
+        ${ok === true ? '<span class="status-dot green"></span>' : ok === false ? '<span class="status-dot yellow"></span>' : ''}
+        ${escHtml(String(value || '—'))}
+      </div>
+    </div>`;
+
+  // Row with a clickable link
+  const rowLink = (label, url, displayText, ok) => `
+    <div class="tech-section">
+      <div class="tech-label">${label}</div>
+      <div class="tech-value ${ok === true ? 'ok' : ok === false ? 'warn' : ''}">
+        ${ok === true ? '<span class="status-dot green"></span>' : ok === false ? '<span class="status-dot yellow"></span>' : ''}
+        ${url
+          ? `<a class="tech-link" href="${url}" target="_blank">${escHtml(displayText)} ↗</a>`
+          : escHtml(displayText || '—')}
+      </div>
+    </div>`;
+
+  // Databricks UI URL patterns
+  const hostShort   = host.replace('https://', '');
+  const catalogUrl  = host ? `${host}/explore/data/${info.catalog}` : '';
+  const orgParam    = info.workspace_id ? `?o=${info.workspace_id}` : '';
+  const supervisorUrl = host && info.supervisor_tile_id
+    ? `${host}/ml/bricks/sa/configure/${info.supervisor_tile_id}${orgParam}`
+    : '';
+  const supervisorLabel = info.supervisor_endpoint || 'Not configured';
+  // Use UID for Lakebase URL (Databricks UI uses UID, not project name)
+  const lakebaseUrlId = info.lakebase_project_uid || info.lakebase_project || '';
+  const lakebaseUrl = host && lakebaseUrlId
+    ? `${host}/lakebase/projects/${lakebaseUrlId}`
+    : (host ? `${host}/lakebase/projects` : '');
+  const lakebaseLabel = info.lakebase_project || (info.lakebase_endpoint ? 'Connected ✓' : 'Not configured');
+  // SQL warehouse
+  const warehouseUrl = host && info.warehouse_id
+    ? `${host}/sql/warehouses/${info.warehouse_id}` : '';
+
+  // Lakebase expanded config block
+  const lakebaseStatus = (info.lakebase_status || '').toUpperCase();
+  const lakebaseActive = lakebaseStatus === 'ACTIVE';
+  const lakebaseBlock = info.db_enabled ? `
+    <div class="tech-section">
+      <div class="tech-label">
+        Lakebase &nbsp;
+        ${lakebaseStatus ? `<span class="lakebase-status-badge ${lakebaseActive ? 'active' : 'inactive'}">${lakebaseStatus}</span>` : ''}
+      </div>
+      <div style="margin-top:4px;">
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">Project</span>
+          <span class="tech-sub-val">
+            ${lakebaseUrl
+              ? `<a class="tech-link" href="${lakebaseUrl}" target="_blank">${escHtml(info.lakebase_project || '—')} ↗</a>`
+              : escHtml(info.lakebase_project || '—')}
+          </span>
+        </div>
+        ${info.lakebase_host ? `
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">Host</span>
+          <span class="tech-sub-val" title="${escHtml(info.lakebase_host)}">${escHtml(info.lakebase_host.split('.')[0])}…</span>
+        </div>` : ''}
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">Port</span>
+          <span class="tech-sub-val">5432</span>
+        </div>
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">Database</span>
+          <span class="tech-sub-val">${escHtml(info.lakebase_dbname || 'databricks_postgres')}</span>
+        </div>
+        ${info.lakebase_pg_version ? `
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">PostgreSQL</span>
+          <span class="tech-sub-val">v${info.lakebase_pg_version}</span>
+        </div>` : ''}
+        ${info.lakebase_min_cu ? `
+        <div class="tech-sub-row">
+          <span class="tech-sub-key">Autoscaling</span>
+          <span class="tech-sub-val">${info.lakebase_min_cu}–${info.lakebase_max_cu} CU</span>
+        </div>` : ''}
+      </div>
+    </div>` :
+    row('Lakebase', 'Not configured', false);
+
+  const mlflowBlock =
+    rowLink('Supervisor Traces', info.mlflow_experiment_url, info.mlflow_experiment_url ? 'Supervisor Traces' : '—', info.mlflow_experiment_url ? true : null) +
+    rowLink('Evaluation Notebook', info.eval_notebook_url, info.eval_notebook_url ? 'Evaluation Notebook' : '—', info.eval_notebook_url ? true : null);
+
+  panel.innerHTML =
+    rowLink('Databricks Workspace', host, hostShort.slice(0, 26) + (hostShort.length > 26 ? '…' : ''), true) +
+    row('Current User', (info.current_user || '—').split('@')[0]) +
+    rowLink('Catalog', catalogUrl, info.catalog || '—', true) +
+    lakebaseBlock +
+    rowLink('Supervisor Agent', supervisorUrl, supervisorLabel, info.supervisor_enabled) +
+    mlflowBlock +
+    (info.warehouse_id ? rowLink('SQL Warehouse', warehouseUrl, info.warehouse_id.slice(0, 14) + '…', true) : '') +
+    `<div class="tech-section" id="agents-panel">
+      <div class="tech-label">Sub-Agents</div>
+      <div class="tech-value" style="font-size:10px; line-height:1.8; color:var(--text-muted);">Loading…</div>
+    </div>`;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Utils
+// ────────────────────────────────────────────────────────────────────────────
+function escHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function showToast(msg) {
+  const t = document.createElement('div');
+  t.className = 'toast';
+  t.textContent = msg;
+  document.body.appendChild(t);
+  setTimeout(() => t.remove(), 2500);
+}
+
+// Auto-resize textarea
+document.getElementById('chat-input').addEventListener('input', function() {
+  this.style.height = 'auto';
+  this.style.height = Math.min(this.scrollHeight, 120) + 'px';
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Sub-Agents panel
+// ────────────────────────────────────────────────────────────────────────────
+async function loadAgents() {
+  try {
+    const res = await fetch('/api/agents');
+    const agents = await res.json();
+    const panel = document.getElementById('agents-panel');
+    if (!panel) return;
+
+    const makeItem = a => {
+      const inner = `
+        <span class="agent-icon">${a.icon}</span>
+        <span class="agent-name">${escHtml(a.name)}</span>
+        <span class="agent-arrow">↗</span>`;
+      return a.url
+        ? `<a class="agent-item" href="${escHtml(a.url)}" target="_blank" title="Open in Databricks ↗">${inner}</a>`
+        : `<div class="agent-item" style="cursor:default;opacity:0.5;" title="URL not available">${inner.replace('<span class="agent-arrow">↗</span>','')}</div>`;
+    };
+
+    const genieAgents = agents.filter(a => a.type === 'genie');
+    const kaAgents    = agents.filter(a => a.type === 'ka');
+
+    const genieHtml = genieAgents.length
+      ? `<div class="agent-group-label">Genie Spaces</div>` + genieAgents.map(makeItem).join('')
+      : '';
+    const kaHtml = kaAgents.length
+      ? `<div class="agent-group-label">Knowledge Assistants</div>` + kaAgents.map(makeItem).join('')
+      : '';
+
+    const noLinks = agents.every(a => !a.url);
+    const hint = noLinks
+      ? `<div style="font-size:9px;color:var(--text-muted);margin-top:6px;">Links unavailable — check app permissions</div>`
+      : '';
+
+    panel.innerHTML = `
+      <div class="tech-label">Sub-Agents (${agents.length})</div>
+      <div style="padding-top:4px;">${genieHtml}${kaHtml}${hint}</div>`;
+  } catch(e) {
+    console.error('loadAgents:', e);
+    const panel = document.getElementById('agents-panel');
+    if (panel) panel.innerHTML = `<div class="tech-label">Sub-Agents</div><div style="font-size:10px;color:var(--text-muted);">Failed to load</div>`;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Sidebar toggles
+// ────────────────────────────────────────────────────────────────────────────
+function toggleLeftSidebar() {
+  const sidebar = document.getElementById('left-sidebar');
+  const icon = document.getElementById('left-toggle-icon');
+  const collapsed = sidebar.classList.toggle('collapsed');
+  icon.textContent = collapsed ? '▶' : '◀';
+  if (locationMap) setTimeout(() => locationMap.invalidateSize(), 220);
+}
+
+function toggleRightSidebar() {
+  const sidebar = document.getElementById('right-sidebar');
+  const icon = document.getElementById('right-toggle-icon');
+  const collapsed = sidebar.classList.toggle('collapsed');
+  icon.textContent = collapsed ? '◀' : '▶';
+  if (locationMap) setTimeout(() => locationMap.invalidateSize(), 220);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Init
+// ────────────────────────────────────────────────────────────────────────────
+async function init() {
+  await Promise.all([
+    loadSessions(),
+    loadRevenue(),
+    initMap(),
+    loadTechInfo().then(() => loadAgents()),
+    loadDocuments(),
+  ]);
+  // Pre-fetch consultancy KA answers in background so hire/fire/ai buttons respond instantly
+}
+
+init();
+</script>
+
+  <!-- Demo breaking alert toast — fires 35s after page load -->
+  <div id="demo-alert-toast" class="demo-alert-toast" style="display:none;">
+    <div class="demo-alert-toast-dot"></div>
+    <div class="demo-alert-toast-body">
+      <div class="demo-alert-toast-title">🔴 New alert</div>
+      <div class="demo-alert-toast-text">Munich food safety inspection failed — grade C, 3 critical violations</div>
+    </div>
+    <button class="demo-alert-toast-cta" onclick="window._demoAlertInvestigate()">Investigate →</button>
+    <button class="demo-alert-toast-close" onclick="window._demoAlertDismiss()">✕</button>
+  </div>
+</body>
+</html>
diff --git a/apps/caspers-ops-dashboard/requirements.txt b/apps/caspers-ops-dashboard/requirements.txt
new file mode 100644
index 0000000..1b053bf
--- /dev/null
+++ b/apps/caspers-ops-dashboard/requirements.txt
@@ -0,0 +1,8 @@
+fastapi==0.115.6
+uvicorn[standard]==0.32.1
+databricks-sdk>=0.81.0
+databricks-sql-connector
+psycopg[binary]==3.2.3
+psycopg-pool==3.3.1
+httpx==0.28.1
+python-multipart==0.0.20
diff --git a/apps/refund-manager/app.yaml b/apps/refund-manager/app.yaml
index b60875e..52b7c37 100644
--- a/apps/refund-manager/app.yaml
+++ b/apps/refund-manager/app.yaml
@@ -1,8 +1,12 @@
 command:
-  - uvicorn 
+  - uvicorn
   - app.main:app
 env:
   - name: DATABRICKS_WAREHOUSE_ID
-    value: 'e1a2914f603fc607'
+    value: ''
   - name: DATABRICKS_CATALOG
-    value: 'cazzper'
+    value: ''
+  - name: LAKEBASE_ENDPOINT_PATH
+    value: ''
+  - name: LAKEBASE_DATABASE_NAME
+    value: ''
diff --git a/apps/refund-manager/app/db.py b/apps/refund-manager/app/db.py
index 93b5064..5776e4e 100644
--- a/apps/refund-manager/app/db.py
+++ b/apps/refund-manager/app/db.py
@@ -1,24 +1,79 @@
 # app/db.py
+"""SQLAlchemy + Lakebase Autoscaling connection management.
+
+Switched from Provisioned (PGHOST + app-OAuth) to Autoscaling
+(LAKEBASE_ENDPOINT_PATH + per-endpoint credentials) when the bundle's
+Lakebase resources were consolidated onto a single shared Autoscale project.
+
+Connection strategy:
+
+- Resolve ``host`` and the current Postgres user once at startup, using the
+  endpoint path declared in ``LAKEBASE_ENDPOINT_PATH``.
+- On every new SQLAlchemy connection, mint a fresh per-endpoint credential
+  via ``w.postgres.generate_database_credential(endpoint=...)`` and pass it
+  as the password.  Tokens are short-lived (~1h), but ``pool_pre_ping``
+  ensures stale tokens are replaced before a request fails.
+
+A background refresher thread is *not* required because the ``do_connect``
+hook re-mints on every new psycopg connection; with ``pool_pre_ping``
+SQLAlchemy will recycle dead pooled connections transparently.
+"""
+
 import os
+import logging
+import threading
+from typing import Optional
+
 from sqlalchemy import create_engine, event
-from databricks.sdk.core import Config
 from databricks.sdk import WorkspaceClient
 
-_cfg = Config()
-_w = WorkspaceClient()  # caches & refreshes tokens
+log = logging.getLogger("refund_manager.db")
 
-PGHOST = os.environ["PGHOST"]
+LAKEBASE_ENDPOINT_PATH = os.environ.get("LAKEBASE_ENDPOINT_PATH", "")
+# Lakebase Autoscale requires DNS-safe DB names (no underscores).
+LAKEBASE_DATABASE_NAME = os.environ.get("LAKEBASE_DATABASE_NAME", "caspers-refund")
 PGPORT = os.environ.get("PGPORT", "5432")
-PGDATABASE = os.environ["PGDATABASE"]
 PGSSLMODE = os.environ.get("PGSSLMODE", "require")
-# default to app client_id unless PGUSER is provided explicitly
-PGUSER = os.environ.get("PGUSER", _cfg.client_id)
 
-DSN = f"postgresql+psycopg://{PGUSER}:@{PGHOST}:{PGPORT}/{PGDATABASE}?sslmode={PGSSLMODE}"
+if not LAKEBASE_ENDPOINT_PATH:
+    raise RuntimeError(
+        "LAKEBASE_ENDPOINT_PATH is required; the refund-manager app must "
+        "be configured against a Lakebase Autoscaling endpoint path of the "
+        "form 'projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}'."
+    )
+
+_w = WorkspaceClient()
+_lock = threading.Lock()
+
+# Resolved once at startup.  The host doesn't change for the lifetime of an
+# endpoint, and the user (the app's service principal name returned by
+# current_user.me()) doesn't change for the lifetime of the app.
+_endpoint = _w.postgres.get_endpoint(name=LAKEBASE_ENDPOINT_PATH)
+PGHOST = _endpoint.status.hosts.host
+PGUSER = _w.current_user.me().user_name
+
+DSN = (
+    f"postgresql+psycopg://{PGUSER}:"
+    f"@{PGHOST}:{PGPORT}/{LAKEBASE_DATABASE_NAME}?sslmode={PGSSLMODE}"
+)
 
 engine = create_engine(DSN, future=True, pool_pre_ping=True)
 
+
+def _fresh_token() -> str:
+    """Mint a new per-endpoint credential.  Serialised so we don't burn
+    multiple credentials on every connection burst."""
+    with _lock:
+        cred = _w.postgres.generate_database_credential(endpoint=LAKEBASE_ENDPOINT_PATH)
+    return cred.token
+
+
 @event.listens_for(engine, "do_connect")
 def _provide_token(dialect, conn_rec, cargs, cparams):
-    # Pass the app OAuth token as the password
-    cparams["password"] = _w.config.oauth_token().access_token
+    """Hand SQLAlchemy a fresh password for every new psycopg connection.
+
+    ``pool_pre_ping`` (set on ``create_engine`` above) guarantees that
+    pooled connections holding expired tokens are recycled before a query
+    runs against them, so this hook is the single source of token freshness.
+    """
+    cparams["password"] = _fresh_token()
diff --git a/apps/refund-manager/app/main.py b/apps/refund-manager/app/main.py
index 03b8c1b..5a0baa5 100644
--- a/apps/refund-manager/app/main.py
+++ b/apps/refund-manager/app/main.py
@@ -28,26 +28,36 @@ def _qi(name: str) -> str:
 RECS_TABLE    = f"{_qi(RECS_SCHEMA)}.pg_recommendations"
 
 # ─── Startup: ensure refunds table ────────────────────────────────────────────
-DDL = f"""
-CREATE SCHEMA IF NOT EXISTS {_qi(REFUNDS_SCHEMA)};
+# Run each DDL statement in its own transaction. Lakebase's DATABRICKS_SUPERUSER
+# role does NOT bypass per-table ownership checks (unlike a real Postgres
+# SUPERUSER), so an idempotent `CREATE INDEX IF NOT EXISTS` against a table that
+# was created by an earlier deploy's app SP raises `must be owner of table …`
+# and crashes startup. The objects already exist in that case, so we log and
+# continue. Mirrors the pattern used in apps/caspers-ops-dashboard/app/db.py.
+DDL_STATEMENTS = [
+    f"CREATE SCHEMA IF NOT EXISTS {_qi(REFUNDS_SCHEMA)}",
+    f"""CREATE TABLE IF NOT EXISTS {REFUNDS_TABLE} (
+        id BIGSERIAL PRIMARY KEY,
+        order_id TEXT NOT NULL,
+        decided_ts TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        amount_usd NUMERIC(10,2) NOT NULL CHECK (amount_usd >= 0),
+        refund_class TEXT NOT NULL CHECK (refund_class IN ('none','partial','full')),
+        reason TEXT NOT NULL,
+        decided_by TEXT,
+        source_suggestion JSONB
+    )""",
+    f"CREATE INDEX IF NOT EXISTS idx_refund_decisions_order_id ON {REFUNDS_TABLE}(order_id)",
+]
 
-CREATE TABLE IF NOT EXISTS {REFUNDS_TABLE} (
-    id BIGSERIAL PRIMARY KEY,
-    order_id TEXT NOT NULL,
-    decided_ts TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    amount_usd NUMERIC(10,2) NOT NULL CHECK (amount_usd >= 0),
-    refund_class TEXT NOT NULL CHECK (refund_class IN ('none','partial','full')),
-    reason TEXT NOT NULL,
-    decided_by TEXT,
-    source_suggestion JSONB
-);
-CREATE INDEX IF NOT EXISTS idx_refund_decisions_order_id ON {REFUNDS_TABLE}(order_id);
-"""
 
 @app.on_event("startup")
 def _startup():
-    with engine.begin() as conn:
-        conn.exec_driver_sql(DDL)
+    for stmt in DDL_STATEMENTS:
+        try:
+            with engine.begin() as conn:
+                conn.exec_driver_sql(stmt)
+        except Exception as e:
+            log.warning(f"Refunds DDL skipped (non-fatal): {e}")
 
 # ─── Static SPA ───────────────────────────────────────────────────────────────
 @app.get("/")
diff --git a/apps/refund-manager/requirements.txt b/apps/refund-manager/requirements.txt
index 19ef92e..1bb8f17 100644
--- a/apps/refund-manager/requirements.txt
+++ b/apps/refund-manager/requirements.txt
@@ -2,5 +2,7 @@ fastapi
 uvicorn[standard]
 sqlalchemy
 psycopg[binary]
-databricks-sdk
+# Autoscale per-endpoint credentials & w.postgres.get_endpoint require SDK
+# 0.81.0+ (Apps base image often pins an older version that lacks `w.postgres`).
+databricks-sdk>=0.81.0
 databricks-sql-connector
diff --git a/data/audits/audit_metadata.json b/data/audits/audit_metadata.json
new file mode 100644
index 0000000..a67f8af
--- /dev/null
+++ b/data/audits/audit_metadata.json
@@ -0,0 +1,586 @@
+{
+  "audits": [
+    {
+      "audit_id": "AUD-01-3001",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "audit_type": "Financial Statement Audit",
+      "audit_firm": "Deloitte & Touche LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-04-26",
+      "scope": "Revenue recognition, accounts payable, payroll, inventory valuation, and internal controls over financial reporting.",
+      "standards": "GAAS (AICPA AU-C Section 700); PCAOB AS 2201",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Internal Controls \u2014 Segregation of Duties",
+          "severity": "Significant",
+          "detail": "Single approver for both purchase orders and payments. Recommend adding a secondary approval for transactions over $5,000."
+        },
+        {
+          "title": "Inventory Valuation",
+          "severity": "Significant",
+          "detail": "Food inventory not written down for spoilage within the 90-day period. Requires a $28,700 reserve adjustment."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-01-3002",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "audit_type": "Operational Compliance Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q3 2023",
+      "period_start": "2023-07-01",
+      "period_end": "2023-09-30",
+      "report_date": "2023-10-19",
+      "scope": "HR practices, vendor contract compliance, operating procedures, health & safety protocols, and regulatory adherence.",
+      "standards": "ISO 9001:2015 Quality Management Systems; OSHA 29 CFR Part 1910",
+      "opinion": "Unqualified (Clean) Opinion",
+      "findings": [
+        {
+          "title": "Incident Reporting",
+          "severity": "Informational",
+          "detail": "2 minor kitchen burns not formally logged in safety system within required 24-hour window."
+        },
+        {
+          "title": "Standard Operating Procedures",
+          "severity": "Minor",
+          "detail": "4 SOPs out of 18 not updated to reflect Q3 2023 process changes. Recommend quarterly SOP review cycle."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 0
+    },
+    {
+      "audit_id": "AUD-01-3003",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "audit_type": "Food Safety Management System Audit",
+      "audit_firm": "Ernst & Young LLP",
+      "period": "Q1 2023",
+      "period_start": "2023-01-01",
+      "period_end": "2023-03-31",
+      "report_date": "2023-05-15",
+      "scope": "HACCP plan validation, temperature monitoring, supplier qualification, allergen management, and traceability.",
+      "standards": "FSMA 21 CFR Part 117; ISO 22000:2018; GFSI Benchmark",
+      "opinion": "Unqualified Opinion with Emphasis of Matter",
+      "findings": [
+        {
+          "title": "Traceability Records",
+          "severity": "Informational",
+          "detail": "Forward traceability test completed in 4.2 hours vs. 4-hour target. Minor process adjustment recommended."
+        },
+        {
+          "title": "Allergen Management",
+          "severity": "Significant",
+          "detail": "Cross-contamination risk identified for tree nut allergens; shared equipment cleaning protocol insufficient. Requires dedicated utensils for allergen-free items."
+        },
+        {
+          "title": "Corrective Action Records",
+          "severity": "Significant",
+          "detail": "Corrective action forms for 3 prior findings not closed out within the required 30-day period."
+        },
+        {
+          "title": "HACCP Temperature Log Gaps",
+          "severity": "Critical",
+          "detail": "Temperature logs show 4 instances of missing readings during evening shifts at this location. Corrective action: automated monitoring system recommended."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 1,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-01-3004",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "audit_type": "Supply Chain & Procurement Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-05-11",
+      "scope": "Vendor performance, contract compliance, purchasing controls, and supplier risk management.",
+      "standards": "ISO 28000:2022 Supply Chain Security; COSO Internal Control Framework",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Contract Renewal Management",
+          "severity": "Minor",
+          "detail": "2 vendor contracts expired 30\u201345 days before renewal. Automated renewal alerts not configured in procurement system."
+        },
+        {
+          "title": "Purchasing Approvals",
+          "severity": "Minor",
+          "detail": "6 purchases between $3,000\u2013$5,000 approved without required dual-sign-off per policy. Purchasing card policy refresh required."
+        },
+        {
+          "title": "Minority & Sustainable Supplier Targets",
+          "severity": "Informational",
+          "detail": "Diverse supplier spend at 11% vs. 15% corporate target. Progress noted; trajectory suggests target achievable by Q3 2024."
+        },
+        {
+          "title": "Vendor Concentration Risk",
+          "severity": "Significant",
+          "detail": "62% of fresh produce sourced from single vendor. Continuity risk in case of supplier disruption. Recommend dual-sourcing strategy."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-02-3005",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "audit_type": "Financial Statement Audit",
+      "audit_firm": "KPMG LLP",
+      "period": "Q4 2023",
+      "period_start": "2023-10-01",
+      "period_end": "2023-12-31",
+      "report_date": "2024-01-17",
+      "scope": "Revenue recognition, accounts payable, payroll, inventory valuation, and internal controls over financial reporting.",
+      "standards": "GAAS (AICPA AU-C Section 700); PCAOB AS 2201",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Internal Controls \u2014 Segregation of Duties",
+          "severity": "Significant",
+          "detail": "Single approver for both purchase orders and payments. Recommend adding a secondary approval for transactions over $5,000."
+        },
+        {
+          "title": "Revenue Recognition Timing",
+          "severity": "Minor",
+          "detail": "Delivery fee revenue recorded at order placement vs. delivery completion. Immaterial adjustment of $12,400 required."
+        },
+        {
+          "title": "Inventory Valuation",
+          "severity": "Significant",
+          "detail": "Food inventory not written down for spoilage within the 90-day period. Requires a $28,700 reserve adjustment."
+        },
+        {
+          "title": "Payroll Accrual",
+          "severity": "Informational",
+          "detail": "Payroll cut-off difference of $4,200 noted; immaterial and corrected in subsequent period."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 0,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-02-3006",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "audit_type": "Operational Compliance Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q1 2023",
+      "period_start": "2023-01-01",
+      "period_end": "2023-03-31",
+      "report_date": "2023-04-23",
+      "scope": "HR practices, vendor contract compliance, operating procedures, health & safety protocols, and regulatory adherence.",
+      "standards": "ISO 9001:2015 Quality Management Systems; OSHA 29 CFR Part 1910",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Employee Training Records",
+          "severity": "Minor",
+          "detail": "Training completion rate at 87% vs. 95% target. 6 employees missing mandatory food handler certification renewal."
+        },
+        {
+          "title": "Standard Operating Procedures",
+          "severity": "Minor",
+          "detail": "4 SOPs out of 18 not updated to reflect Q3 2023 process changes. Recommend quarterly SOP review cycle."
+        },
+        {
+          "title": "Waste Disposal Compliance",
+          "severity": "Significant",
+          "detail": "Grease trap disposal records incomplete for August and September 2023. Environmental compliance risk."
+        },
+        {
+          "title": "Vendor SLA Compliance",
+          "severity": "Significant",
+          "detail": "Primary produce vendor delivered out-of-spec temperature goods on 3 occasions. Formal corrective action plan required."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 0,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-02-3007",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "audit_type": "Food Safety Management System Audit",
+      "audit_firm": "Deloitte & Touche LLP",
+      "period": "Q1 2023",
+      "period_start": "2023-01-01",
+      "period_end": "2023-03-31",
+      "report_date": "2023-04-29",
+      "scope": "HACCP plan validation, temperature monitoring, supplier qualification, allergen management, and traceability.",
+      "standards": "FSMA 21 CFR Part 117; ISO 22000:2018; GFSI Benchmark",
+      "opinion": "Unqualified Opinion with Emphasis of Matter",
+      "findings": [
+        {
+          "title": "Allergen Management",
+          "severity": "Significant",
+          "detail": "Cross-contamination risk identified for tree nut allergens; shared equipment cleaning protocol insufficient. Requires dedicated utensils for allergen-free items."
+        },
+        {
+          "title": "Traceability Records",
+          "severity": "Informational",
+          "detail": "Forward traceability test completed in 4.2 hours vs. 4-hour target. Minor process adjustment recommended."
+        },
+        {
+          "title": "HACCP Temperature Log Gaps",
+          "severity": "Critical",
+          "detail": "Temperature logs show 4 instances of missing readings during evening shifts at this location. Corrective action: automated monitoring system recommended."
+        },
+        {
+          "title": "Corrective Action Records",
+          "severity": "Significant",
+          "detail": "Corrective action forms for 3 prior findings not closed out within the required 30-day period."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 1,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-02-3008",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "audit_type": "Supply Chain & Procurement Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q3 2023",
+      "period_start": "2023-07-01",
+      "period_end": "2023-09-30",
+      "report_date": "2023-11-14",
+      "scope": "Vendor performance, contract compliance, purchasing controls, and supplier risk management.",
+      "standards": "ISO 28000:2022 Supply Chain Security; COSO Internal Control Framework",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Contract Renewal Management",
+          "severity": "Minor",
+          "detail": "2 vendor contracts expired 30\u201345 days before renewal. Automated renewal alerts not configured in procurement system."
+        },
+        {
+          "title": "Minority & Sustainable Supplier Targets",
+          "severity": "Informational",
+          "detail": "Diverse supplier spend at 11% vs. 15% corporate target. Progress noted; trajectory suggests target achievable by Q3 2024."
+        },
+        {
+          "title": "Pricing Compliance",
+          "severity": "Informational",
+          "detail": "3 invoices priced above contracted rates by $140\u2013$280. Vendors corrected upon notification. No material impact."
+        },
+        {
+          "title": "Vendor Concentration Risk",
+          "severity": "Significant",
+          "detail": "62% of fresh produce sourced from single vendor. Continuity risk in case of supplier disruption. Recommend dual-sourcing strategy."
+        }
+      ],
+      "finding_count": 4,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-03-3009",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "audit_type": "Financial Statement Audit",
+      "audit_firm": "KPMG LLP",
+      "period": "Q3 2023",
+      "period_start": "2023-07-01",
+      "period_end": "2023-09-30",
+      "report_date": "2023-10-16",
+      "scope": "Revenue recognition, accounts payable, payroll, inventory valuation, and internal controls over financial reporting.",
+      "standards": "GAAS (AICPA AU-C Section 700); PCAOB AS 2201",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Revenue Recognition Timing",
+          "severity": "Minor",
+          "detail": "Delivery fee revenue recorded at order placement vs. delivery completion. Immaterial adjustment of $12,400 required."
+        },
+        {
+          "title": "Inventory Valuation",
+          "severity": "Significant",
+          "detail": "Food inventory not written down for spoilage within the 90-day period. Requires a $28,700 reserve adjustment."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-03-3010",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "audit_type": "Operational Compliance Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-04-16",
+      "scope": "HR practices, vendor contract compliance, operating procedures, health & safety protocols, and regulatory adherence.",
+      "standards": "ISO 9001:2015 Quality Management Systems; OSHA 29 CFR Part 1910",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Employee Training Records",
+          "severity": "Minor",
+          "detail": "Training completion rate at 87% vs. 95% target. 6 employees missing mandatory food handler certification renewal."
+        },
+        {
+          "title": "Vendor SLA Compliance",
+          "severity": "Significant",
+          "detail": "Primary produce vendor delivered out-of-spec temperature goods on 3 occasions. Formal corrective action plan required."
+        },
+        {
+          "title": "Standard Operating Procedures",
+          "severity": "Minor",
+          "detail": "4 SOPs out of 18 not updated to reflect Q3 2023 process changes. Recommend quarterly SOP review cycle."
+        }
+      ],
+      "finding_count": 3,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-03-3011",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "audit_type": "Food Safety Management System Audit",
+      "audit_firm": "PricewaterhouseCoopers LLP",
+      "period": "Q1 2023",
+      "period_start": "2023-01-01",
+      "period_end": "2023-03-31",
+      "report_date": "2023-04-27",
+      "scope": "HACCP plan validation, temperature monitoring, supplier qualification, allergen management, and traceability.",
+      "standards": "FSMA 21 CFR Part 117; ISO 22000:2018; GFSI Benchmark",
+      "opinion": "Unqualified Opinion with Emphasis of Matter",
+      "findings": [
+        {
+          "title": "Allergen Management",
+          "severity": "Significant",
+          "detail": "Cross-contamination risk identified for tree nut allergens; shared equipment cleaning protocol insufficient. Requires dedicated utensils for allergen-free items."
+        },
+        {
+          "title": "Traceability Records",
+          "severity": "Informational",
+          "detail": "Forward traceability test completed in 4.2 hours vs. 4-hour target. Minor process adjustment recommended."
+        },
+        {
+          "title": "HACCP Temperature Log Gaps",
+          "severity": "Critical",
+          "detail": "Temperature logs show 4 instances of missing readings during evening shifts at this location. Corrective action: automated monitoring system recommended."
+        }
+      ],
+      "finding_count": 3,
+      "critical_findings": 1,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-03-3012",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "audit_type": "Supply Chain & Procurement Audit",
+      "audit_firm": "Ernst & Young LLP",
+      "period": "Q3 2023",
+      "period_start": "2023-07-01",
+      "period_end": "2023-09-30",
+      "report_date": "2023-10-29",
+      "scope": "Vendor performance, contract compliance, purchasing controls, and supplier risk management.",
+      "standards": "ISO 28000:2022 Supply Chain Security; COSO Internal Control Framework",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Purchasing Approvals",
+          "severity": "Minor",
+          "detail": "6 purchases between $3,000\u2013$5,000 approved without required dual-sign-off per policy. Purchasing card policy refresh required."
+        },
+        {
+          "title": "Minority & Sustainable Supplier Targets",
+          "severity": "Informational",
+          "detail": "Diverse supplier spend at 11% vs. 15% corporate target. Progress noted; trajectory suggests target achievable by Q3 2024."
+        },
+        {
+          "title": "Vendor Concentration Risk",
+          "severity": "Significant",
+          "detail": "62% of fresh produce sourced from single vendor. Continuity risk in case of supplier disruption. Recommend dual-sourcing strategy."
+        }
+      ],
+      "finding_count": 3,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-04-3013",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "audit_type": "Financial Statement Audit",
+      "audit_firm": "BDO USA LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-05-13",
+      "scope": "Revenue recognition, accounts payable, payroll, inventory valuation, and internal controls over financial reporting.",
+      "standards": "GAAS (AICPA AU-C Section 700); PCAOB AS 2201",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Inventory Valuation",
+          "severity": "Significant",
+          "detail": "Food inventory not written down for spoilage within the 90-day period. Requires a $28,700 reserve adjustment."
+        },
+        {
+          "title": "Internal Controls \u2014 Segregation of Duties",
+          "severity": "Significant",
+          "detail": "Single approver for both purchase orders and payments. Recommend adding a secondary approval for transactions over $5,000."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-04-3014",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "audit_type": "Operational Compliance Audit",
+      "audit_firm": "Ernst & Young LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-04-17",
+      "scope": "HR practices, vendor contract compliance, operating procedures, health & safety protocols, and regulatory adherence.",
+      "standards": "ISO 9001:2015 Quality Management Systems; OSHA 29 CFR Part 1910",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Employee Training Records",
+          "severity": "Minor",
+          "detail": "Training completion rate at 87% vs. 95% target. 6 employees missing mandatory food handler certification renewal."
+        },
+        {
+          "title": "Vendor SLA Compliance",
+          "severity": "Significant",
+          "detail": "Primary produce vendor delivered out-of-spec temperature goods on 3 occasions. Formal corrective action plan required."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 1
+    },
+    {
+      "audit_id": "AUD-04-3015",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "audit_type": "Food Safety Management System Audit",
+      "audit_firm": "Ernst & Young LLP",
+      "period": "Q3 2023",
+      "period_start": "2023-07-01",
+      "period_end": "2023-09-30",
+      "report_date": "2023-10-20",
+      "scope": "HACCP plan validation, temperature monitoring, supplier qualification, allergen management, and traceability.",
+      "standards": "FSMA 21 CFR Part 117; ISO 22000:2018; GFSI Benchmark",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Allergen Management",
+          "severity": "Significant",
+          "detail": "Cross-contamination risk identified for tree nut allergens; shared equipment cleaning protocol insufficient. Requires dedicated utensils for allergen-free items."
+        },
+        {
+          "title": "Corrective Action Records",
+          "severity": "Significant",
+          "detail": "Corrective action forms for 3 prior findings not closed out within the required 30-day period."
+        },
+        {
+          "title": "Supplier Qualification",
+          "severity": "Minor",
+          "detail": "2 of 8 active suppliers lack current third-party food safety audit on file. Supplier portal update required within 30 days."
+        }
+      ],
+      "finding_count": 3,
+      "critical_findings": 0,
+      "significant_findings": 2
+    },
+    {
+      "audit_id": "AUD-04-3016",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "audit_type": "Supply Chain & Procurement Audit",
+      "audit_firm": "Ernst & Young LLP",
+      "period": "Q1 2024",
+      "period_start": "2024-01-01",
+      "period_end": "2024-03-30",
+      "report_date": "2024-05-09",
+      "scope": "Vendor performance, contract compliance, purchasing controls, and supplier risk management.",
+      "standards": "ISO 28000:2022 Supply Chain Security; COSO Internal Control Framework",
+      "opinion": "Qualified Opinion \u2014 Scope Limitation",
+      "findings": [
+        {
+          "title": "Pricing Compliance",
+          "severity": "Informational",
+          "detail": "3 invoices priced above contracted rates by $140\u2013$280. Vendors corrected upon notification. No material impact."
+        },
+        {
+          "title": "Vendor Concentration Risk",
+          "severity": "Significant",
+          "detail": "62% of fresh produce sourced from single vendor. Continuity risk in case of supplier disruption. Recommend dual-sourcing strategy."
+        }
+      ],
+      "finding_count": 2,
+      "critical_findings": 0,
+      "significant_findings": 1
+    }
+  ],
+  "locations": [
+    {
+      "location_id": 1,
+      "name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103"
+    },
+    {
+      "location_id": 2,
+      "name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051"
+    },
+    {
+      "location_id": 3,
+      "name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004"
+    },
+    {
+      "location_id": 4,
+      "name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/data/audits/generate_audit_reports.py b/data/audits/generate_audit_reports.py
new file mode 100644
index 0000000..0946f93
--- /dev/null
+++ b/data/audits/generate_audit_reports.py
@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""
+Generate audit report PDFs for Casper's Kitchens.
+
+Produces realistic audit documents: financial audits, operational compliance
+audits, food safety management system audits, and supply chain audits.
+Reports cover Q1–Q4 2023 and Q1 2024.
+
+Outputs:
+  - data/audits/pdfs/*.pdf
+  - data/audits/audit_metadata.json
+
+Requirements:
+  pip install fpdf2
+"""
+
+import json
+import random
+import textwrap
+from datetime import date, timedelta
+from pathlib import Path
+
+from fpdf import FPDF
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def _safe(text: str) -> str:
+    return (
+        str(text)
+        .replace("\u2014", "--")
+        .replace("\u2013", "-")
+        .replace("\u2018", "'")
+        .replace("\u2019", "'")
+        .replace("\u201c", '"')
+        .replace("\u201d", '"')
+        .replace("\u2026", "...")
+        .replace("\u2022", "-")
+        .replace("\u00d7", "x")
+        .replace("\u2192", "->")
+        .replace("\u2190", "<-")
+        .encode("latin-1", errors="replace")
+        .decode("latin-1")
+    )
+PDF_DIR = SCRIPT_DIR / "pdfs"
+METADATA_PATH = SCRIPT_DIR / "audit_metadata.json"
+
+random.seed(99)
+
+LOCATIONS = [
+    {"location_id": 1, "name": "San Francisco", "address": "1847 Market Street, San Francisco, CA 94103"},
+    {"location_id": 2, "name": "Silicon Valley", "address": "2350 El Camino Real, Santa Clara, CA 95051"},
+    {"location_id": 3, "name": "Bellevue", "address": "10456 NE 8th Street, Bellevue, WA 98004"},
+    {"location_id": 4, "name": "Chicago", "address": "872 N. Milwaukee Avenue, Chicago, IL 60642"},
+    {"location_id": 5, "name": "London", "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK"},
+    {"location_id": 6, "name": "Munich", "address": "Leopoldstrasse 75, 80802 Munich, Germany"},
+    {"location_id": 7, "name": "Amsterdam", "address": "Damrak 66, 1012 LM Amsterdam, Netherlands"},
+    {"location_id": 8, "name": "Vianen", "address": "Voorstraat 78, 4131 LW Vianen, Netherlands"},
+]
+
+AUDIT_FIRMS = [
+    "PricewaterhouseCoopers LLP",
+    "Deloitte & Touche LLP",
+    "Ernst & Young LLP",
+    "KPMG LLP",
+    "BDO USA LLP",
+    "RSM US LLP",
+]
+
+AUDIT_TYPES = [
+    {
+        "type": "Financial Statement Audit",
+        "scope": "Revenue recognition, accounts payable, payroll, inventory valuation, and internal controls over financial reporting.",
+        "standards": "GAAS (AICPA AU-C Section 700); PCAOB AS 2201",
+        "findings_pool": [
+            ("Revenue Recognition Timing", "Minor", "Delivery fee revenue recorded at order placement vs. delivery completion. Immaterial adjustment of $12,400 required."),
+            ("Inventory Valuation", "Significant", "Food inventory not written down for spoilage within the 90-day period. Requires a $28,700 reserve adjustment."),
+            ("Payroll Accrual", "Informational", "Payroll cut-off difference of $4,200 noted; immaterial and corrected in subsequent period."),
+            ("Accounts Payable Completeness", "Minor", "Three vendor invoices totaling $8,900 not recorded until following month. Consistent with historical patterns."),
+            ("Internal Controls — Segregation of Duties", "Significant", "Single approver for both purchase orders and payments. Recommend adding a secondary approval for transactions over $5,000."),
+        ],
+    },
+    {
+        "type": "Operational Compliance Audit",
+        "scope": "HR practices, vendor contract compliance, operating procedures, health & safety protocols, and regulatory adherence.",
+        "standards": "ISO 9001:2015 Quality Management Systems; OSHA 29 CFR Part 1910",
+        "findings_pool": [
+            ("Employee Training Records", "Minor", "Training completion rate at 87% vs. 95% target. 6 employees missing mandatory food handler certification renewal."),
+            ("Vendor SLA Compliance", "Significant", "Primary produce vendor delivered out-of-spec temperature goods on 3 occasions. Formal corrective action plan required."),
+            ("Incident Reporting", "Informational", "2 minor kitchen burns not formally logged in safety system within required 24-hour window."),
+            ("Standard Operating Procedures", "Minor", "4 SOPs out of 18 not updated to reflect Q3 2023 process changes. Recommend quarterly SOP review cycle."),
+            ("Waste Disposal Compliance", "Significant", "Grease trap disposal records incomplete for August and September 2023. Environmental compliance risk."),
+        ],
+    },
+    {
+        "type": "Food Safety Management System Audit",
+        "scope": "HACCP plan validation, temperature monitoring, supplier qualification, allergen management, and traceability.",
+        "standards": "FSMA 21 CFR Part 117; ISO 22000:2018; GFSI Benchmark",
+        "findings_pool": [
+            ("HACCP Temperature Log Gaps", "Critical", "Temperature logs show 4 instances of missing readings during evening shifts at this location. Corrective action: automated monitoring system recommended."),
+            ("Allergen Management", "Significant", "Cross-contamination risk identified for tree nut allergens; shared equipment cleaning protocol insufficient. Requires dedicated utensils for allergen-free items."),
+            ("Supplier Qualification", "Minor", "2 of 8 active suppliers lack current third-party food safety audit on file. Supplier portal update required within 30 days."),
+            ("Traceability Records", "Informational", "Forward traceability test completed in 4.2 hours vs. 4-hour target. Minor process adjustment recommended."),
+            ("Corrective Action Records", "Significant", "Corrective action forms for 3 prior findings not closed out within the required 30-day period."),
+        ],
+    },
+    {
+        "type": "Supply Chain & Procurement Audit",
+        "scope": "Vendor performance, contract compliance, purchasing controls, and supplier risk management.",
+        "standards": "ISO 28000:2022 Supply Chain Security; COSO Internal Control Framework",
+        "findings_pool": [
+            ("Vendor Concentration Risk", "Significant", "62% of fresh produce sourced from single vendor. Continuity risk in case of supplier disruption. Recommend dual-sourcing strategy."),
+            ("Contract Renewal Management", "Minor", "2 vendor contracts expired 30–45 days before renewal. Automated renewal alerts not configured in procurement system."),
+            ("Pricing Compliance", "Informational", "3 invoices priced above contracted rates by $140–$280. Vendors corrected upon notification. No material impact."),
+            ("Minority & Sustainable Supplier Targets", "Informational", "Diverse supplier spend at 11% vs. 15% corporate target. Progress noted; trajectory suggests target achievable by Q3 2024."),
+            ("Purchasing Approvals", "Minor", "6 purchases between $3,000–$5,000 approved without required dual-sign-off per policy. Purchasing card policy refresh required."),
+        ],
+    },
+]
+
+QUARTERS = [
+    ("Q1 2023", date(2023, 1, 1), date(2023, 3, 31)),
+    ("Q3 2023", date(2023, 7, 1), date(2023, 9, 30)),
+    ("Q4 2023", date(2023, 10, 1), date(2023, 12, 31)),
+    ("Q1 2024", date(2024, 1, 1), date(2024, 3, 30)),
+]
+
+OPINIONS = [
+    "Unqualified (Clean) Opinion",
+    "Qualified Opinion — Scope Limitation",
+    "Unqualified Opinion with Emphasis of Matter",
+]
+
+
+def generate_audit_data() -> list[dict]:
+    audits = []
+    audit_counter = 3001
+
+    for loc in LOCATIONS:
+        for audit_type in AUDIT_TYPES:
+            quarter_label, q_start, q_end = random.choice(QUARTERS)
+            report_date = q_end + timedelta(days=random.randint(15, 45))
+            num_findings = random.randint(2, 4)
+            findings = random.sample(audit_type["findings_pool"], min(num_findings, len(audit_type["findings_pool"])))
+            has_significant = any(f[1] == "Significant" for f in findings)
+            has_critical = any(f[1] == "Critical" for f in findings)
+            opinion = OPINIONS[2] if has_critical else (OPINIONS[1] if has_significant else OPINIONS[0])
+
+            audits.append({
+                "audit_id": f"AUD-{loc['location_id']:02d}-{audit_counter}",
+                "location_id": loc["location_id"],
+                "location_name": loc["name"],
+                "address": loc["address"],
+                "audit_type": audit_type["type"],
+                "audit_firm": random.choice(AUDIT_FIRMS),
+                "period": quarter_label,
+                "period_start": q_start.isoformat(),
+                "period_end": q_end.isoformat(),
+                "report_date": report_date.isoformat(),
+                "scope": audit_type["scope"],
+                "standards": audit_type["standards"],
+                "opinion": opinion,
+                "findings": [
+                    {"title": f[0], "severity": f[1], "detail": f[2]}
+                    for f in findings
+                ],
+                "finding_count": len(findings),
+                "critical_findings": sum(1 for f in findings if f[1] == "Critical"),
+                "significant_findings": sum(1 for f in findings if f[1] == "Significant"),
+            })
+            audit_counter += 1
+
+    return audits
+
+
+class AuditPDF(FPDF):
+    def __init__(self, firm: str):
+        super().__init__()
+        self.firm = firm
+        self.set_auto_page_break(auto=True, margin=22)
+
+    def header(self):
+        self.set_font("Helvetica", "B", 13)
+        self.cell(0, 7, self.firm.upper(), new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "B", 10)
+        self.cell(0, 6, "INDEPENDENT AUDITOR'S REPORT", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "I", 8)
+        self.cell(0, 5, "Prepared for Casper's Kitchens Inc. -- Confidential", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.ln(2)
+        self.set_line_width(0.5)
+        self.line(10, self.get_y(), 200, self.get_y())
+        self.ln(4)
+
+    def footer(self):
+        self.set_y(-15)
+        self.set_font("Helvetica", "I", 7)
+        self.cell(0, 4, f"{self.firm} -- Confidential Audit Report", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.cell(0, 4, f"Page {self.page_no()}", align="C")
+
+
+AUDIT_PROCEDURES = {
+    "Financial Statement Audit": [
+        ("Revenue Recognition", "Tested 45 revenue transactions selected via random sampling; verified delivery completion timestamps against recorded revenue dates; reviewed journal entry approval workflow."),
+        ("Accounts Payable Completeness", "Performed search for unrecorded liabilities; matched 30-day post-period invoices to accrual schedule; confirmed vendor statement reconciliations for top 10 suppliers by spend volume."),
+        ("Payroll & Compensation", "Traced payroll records to HR system for all active employees; recalculated gross-to-net for a sample of 15 employees; verified payroll tax filings and remittances to tax authorities."),
+        ("Inventory Valuation", "Performed physical count observation on unannounced basis; tested FIFO costing methodology; assessed spoilage write-off procedures and compared to industry norms."),
+        ("Bank Reconciliation", "Obtained bank statements independently; traced all reconciling items; confirmed year-end balances with issuing bank via direct confirmation."),
+        ("Management Representations", "Obtained signed management representation letter covering completeness of records, disclosure of related-party transactions, and acknowledgment of audit findings."),
+    ],
+    "Operational Compliance Audit": [
+        ("HR Policy Compliance", "Reviewed 100% of employee files for required I-9 documentation; tested 25 files for training completion; compared compensation to approved pay scales."),
+        ("Vendor Contract Compliance", "Pulled contracts for top 15 vendors by spend; tested delivery records against SLA requirements; reviewed non-conformance logs and corrective action documentation."),
+        ("Health & Safety", "Inspected facility against OSHA 29 CFR Part 1910 requirements; reviewed OSHA 300 log; verified first aid kit inventory and emergency contact postings."),
+        ("Standard Operating Procedures", "Reviewed all 18 active SOPs for revision dates; tested adherence to 5 SOPs through direct staff observation; identified 4 SOPs requiring update."),
+        ("Regulatory Correspondence", "Confirmed all required licenses and permits are current; reviewed agency correspondence for any open compliance matters."),
+        ("Waste Management", "Reviewed grease trap service records; confirmed hazardous waste manifests for applicable materials; inspected waste storage areas."),
+    ],
+    "Food Safety Management System Audit": [
+        ("HACCP Plan Review", "Examined HACCP plan documentation; verified all critical control points identified; reviewed monitoring log completeness for the prior 90 days."),
+        ("Temperature Monitoring", "Downloaded data from digital temperature monitoring system; analyzed for excursions; cross-referenced against manual log entries."),
+        ("Supplier Qualification", "Reviewed supplier approval files for all 8 active suppliers; confirmed current third-party audit or equivalent on file for 6 of 8."),
+        ("Allergen Management", "Reviewed allergen control procedures; tested label accuracy on 10 menu items; assessed shared equipment cleaning protocol effectiveness."),
+        ("Corrective Action Records", "Reviewed all corrective action forms from prior 6 months; tested closure verification; assessed root cause analysis quality."),
+        ("Traceability Exercise", "Conducted forward traceability exercise using lot code from incoming produce delivery; traced to final menu items within 4.2 hours."),
+    ],
+    "Supply Chain & Procurement Audit": [
+        ("Vendor Master Maintenance", "Reviewed vendor onboarding process; confirmed segregation of duties between vendor setup and payment approval; checked for duplicate vendor records."),
+        ("Purchase Order Controls", "Tested 40 purchase orders for proper authorization; verified three-way match (PO / receiving / invoice) for all transactions above $1,000."),
+        ("Contract Management", "Reviewed contract repository; identified 2 expired contracts; confirmed renewal notifications are configured in procurement system."),
+        ("Supplier Performance", "Analyzed delivery performance data for top 10 suppliers; calculated on-time delivery rate (87.3%); reviewed formal supplier scorecards."),
+        ("Pricing Compliance", "Selected 50 invoices for price testing; confirmed pricing matches contracted rates for 47 of 50; escalated 3 exceptions to finance for credit resolution."),
+        ("Minority & Sustainable Sourcing", "Calculated diverse supplier spend as percentage of addressable spend; compared to corporate target; identified pipeline opportunities."),
+    ],
+}
+
+MGMT_RESPONSE_TEMPLATES = [
+    "Management acknowledges this finding and agrees with the recommendation. A corrective action plan has been developed and implementation is underway. Expected completion date: within 30 days of this report.",
+    "Management concurs with this finding. The identified gap has been escalated to the relevant department head. A formal remediation plan will be submitted to Internal Audit within 14 days.",
+    "Management partially concurs with this finding. While we agree with the factual observation, we believe the risk is mitigated by compensating controls not within the scope of this audit. A formal response will be provided within 10 business days.",
+    "Management acknowledges this finding and notes that a system upgrade planned for Q3 2024 will address the underlying process control gap. Interim manual controls have been implemented effective immediately.",
+    "Management concurs and has already taken corrective action since the audit fieldwork concluded. Evidence of remediation will be provided to Internal Audit for verification within 5 business days.",
+]
+
+
+def generate_pdf(audit: dict) -> str:
+    pdf = AuditPDF(audit["audit_firm"])
+    pdf.add_page()
+
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.set_fill_color(235, 235, 248)
+        pdf.cell(0, 7, _safe(f"  {title}"), new_x="LMARGIN", new_y="NEXT", fill=True)
+        pdf.set_line_width(0.3)
+        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
+        pdf.ln(2)
+
+    def kv(label: str, value: str, label_w: int = 60):
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(label_w, 5.5, _safe(label))
+        pdf.set_font("Helvetica", "", 9)
+        pdf.cell(0, 5.5, _safe(value), new_x="LMARGIN", new_y="NEXT")
+
+    def para(text: str):
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(text), width=100):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Cover Block ───────────────────────────────────────────────────────────
+    pdf.set_fill_color(230, 230, 248)
+    pdf.rect(10, pdf.get_y(), 190, 22, "F")
+    pdf.set_font("Helvetica", "B", 13)
+    pdf.cell(0, 8, _safe(audit["audit_type"].upper()), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "B", 10)
+    pdf.cell(0, 7, _safe(f"Casper's Kitchens -- {audit['location_name']} | {audit['period']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    opinion_color = (180, 30, 30) if "Qualified" in audit["opinion"] else (0, 120, 60)
+    pdf.set_text_color(*opinion_color)
+    pdf.cell(0, 6, _safe(f"Auditor's Opinion: {audit['opinion']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_text_color(0, 0, 0)
+    pdf.ln(5)
+
+    # ── Section 1: Engagement Details ────────────────────────────────────────
+    section("I. AUDIT ENGAGEMENT DETAILS")
+    kv("Audit ID:", audit["audit_id"])
+    kv("Audit Type:", audit["audit_type"])
+    kv("Auditing Firm:", audit["audit_firm"])
+    kv("Audit Period:", f"{audit['period_start']} to {audit['period_end']} ({audit['period']})")
+    kv("Report Date:", audit["report_date"])
+    kv("Audited Entity:", f"Casper's Kitchens -- {audit['location_name']} Location")
+    kv("Address:", audit["address"])
+    kv("Engagement Partner:", random.choice(["Jennifer Walsh, CPA", "David Okonkwo, CPA", "Sarah Tanaka, CPA, CISA"]))
+    kv("Auditor's Opinion:", audit["opinion"])
+    kv("Total Findings:", f"{audit['finding_count']} ({audit['critical_findings']} Critical, {audit['significant_findings']} Significant)")
+
+    # ── Section 2: Scope & Standards ─────────────────────────────────────────
+    section("II. SCOPE OF AUDIT & APPLICABLE STANDARDS")
+    para(
+        f"This audit was conducted in accordance with Generally Accepted Auditing Standards (GAAS) as established "
+        f"by the American Institute of Certified Public Accountants (AICPA) and applicable professional standards. "
+        f"The scope of this engagement covers the following areas of Casper's Kitchens -- {audit['location_name']} "
+        f"operations for the period {audit['period_start']} through {audit['period_end']}:"
+    )
+    pdf.set_font("Helvetica", "", 9)
+    for line in textwrap.wrap(_safe(audit["scope"]), width=98):
+        pdf.cell(0, 5, f"  - {line}", new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(2)
+    para(f"Standards and frameworks applied: {audit['standards']}")
+    para(
+        f"The audit was planned and performed to obtain reasonable assurance about whether the subject matter "
+        f"is free from material misstatement or non-compliance, whether due to error or irregularity. Our procedures "
+        f"included inquiry, observation, inspection of documents, and analytical review. The nature and extent of "
+        f"procedures performed are described in Section III below."
+    )
+
+    # ── Section 3: Audit Procedures Performed ────────────────────────────────
+    section("III. AUDIT PROCEDURES PERFORMED")
+    procedures = AUDIT_PROCEDURES.get(audit["audit_type"], AUDIT_PROCEDURES["Financial Statement Audit"])
+    for proc_name, proc_desc in procedures:
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(0, 6, _safe(f"  {proc_name}"), new_x="LMARGIN", new_y="NEXT")
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(proc_desc), width=98):
+            pdf.cell(0, 5, f"    {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Section 4: Findings ───────────────────────────────────────────────────
+    section(f"IV. AUDIT FINDINGS ({audit['finding_count']} FINDINGS)")
+    severity_colors = {"Critical": (200, 40, 40), "Significant": (180, 90, 0), "Minor": (40, 130, 40), "Informational": (60, 60, 200)}
+    for i, finding in enumerate(audit["findings"], 1):
+        col = severity_colors.get(finding["severity"], (80, 80, 80))
+        pdf.set_text_color(*col)
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(0, 6, _safe(f"  Finding {i}: [{finding['severity'].upper()}]  {finding['title']}"), new_x="LMARGIN", new_y="NEXT")
+        pdf.set_text_color(0, 0, 0)
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(f"Observation: {finding['detail']}"), width=97):
+            pdf.cell(0, 5, f"    {line}", new_x="LMARGIN", new_y="NEXT")
+        # Risk & Recommendation
+        risk = "high" if finding["severity"] == "Critical" else "medium" if finding["severity"] == "Significant" else "low"
+        pdf.set_font("Helvetica", "I", 9)
+        pdf.cell(0, 5, _safe(f"    Risk Level: {risk.upper()}"), new_x="LMARGIN", new_y="NEXT")
+        mgmt_resp = random.choice(MGMT_RESPONSE_TEMPLATES)
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(f"Management Response: {mgmt_resp}"), width=97):
+            pdf.cell(0, 5, f"    {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(3)
+
+    # ── Section 5: Risk Summary Table ────────────────────────────────────────
+    section("V. FINDINGS RISK SUMMARY")
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 248)
+    pdf.cell(60, 6, "Finding Title", fill=True, border=1)
+    pdf.cell(28, 6, "Severity", fill=True, border=1)
+    pdf.cell(28, 6, "Risk Level", fill=True, border=1)
+    pdf.cell(0, 6, "Remediation Owner", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    owners = ["Finance Director", "Operations Manager", "HR Director", "Supply Chain Lead", "Food Safety Manager", "General Manager"]
+    fill = False
+    for finding in audit["findings"]:
+        risk = "HIGH" if finding["severity"] == "Critical" else "MEDIUM" if finding["severity"] == "Significant" else "LOW"
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(60, 5.5, _safe(finding["title"][:36]), fill=True, border=1)
+        pdf.cell(28, 5.5, _safe(finding["severity"]), fill=True, border=1)
+        pdf.cell(28, 5.5, _safe(risk), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(random.choice(owners)), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+
+    # ── Section 6: Remediation Timeline ──────────────────────────────────────
+    section("VI. REMEDIATION TIMELINE & FOLLOW-UP SCHEDULE")
+    from datetime import date as date_cls
+    rpt_date = date_cls.fromisoformat(audit["report_date"])
+    para("The following remediation schedule has been agreed between management and the audit team. Completion will be verified during the follow-up review.")
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 248)
+    pdf.cell(60, 6, "Finding", fill=True, border=1)
+    pdf.cell(28, 6, "Priority", fill=True, border=1)
+    pdf.cell(0, 6, "Target Completion Date", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for finding in audit["findings"]:
+        days = {"Critical": 14, "Significant": 45, "Minor": 90, "Informational": 120}[finding["severity"]]
+        target = rpt_date + timedelta(days=days)
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(60, 5.5, _safe(finding["title"][:36]), fill=True, border=1)
+        pdf.cell(28, 5.5, _safe(finding["severity"]), fill=True, border=1)
+        pdf.cell(0, 5.5, target.strftime("%b %d, %Y"), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    follow_up_date = rpt_date + timedelta(days=90)
+    pdf.ln(2)
+    para(f"A formal follow-up review is scheduled for {follow_up_date.strftime('%B %d, %Y')} to verify remediation of all findings. Management is required to provide status updates on open items 30 days prior to the follow-up review.")
+
+    # ── Section 7: Auditor's Opinion ──────────────────────────────────────────
+    section("VII. AUDITOR'S OPINION")
+    para(
+        f"To the Management and Board of Casper's Kitchens Inc.: "
+        f"{audit['audit_firm']} has completed the {audit['audit_type'].lower()} of Casper's Kitchens -- "
+        f"{audit['location_name']} for the period {audit['period_start']} through {audit['period_end']}. "
+        f"Our engagement was conducted in accordance with {audit['standards']}."
+    )
+    if "Unqualified" in audit["opinion"] and "Emphasis" not in audit["opinion"]:
+        para(
+            f"In our opinion, the subject matter presents fairly, in all material respects, the {audit['audit_type'].lower()} "
+            f"position of Casper's Kitchens -- {audit['location_name']} as of the period end date, "
+            f"in accordance with applicable standards and the criteria established by management."
+        )
+    elif "Emphasis" in audit["opinion"]:
+        para(
+            f"In our opinion, the subject matter presents fairly, in all material respects; however, we draw attention "
+            f"to the finding(s) identified in Section IV above. Our opinion is not modified with respect to this matter, "
+            f"but we wish to emphasize the importance of timely remediation."
+        )
+    else:
+        para(
+            f"Except for the matter(s) described in the Basis for Qualified Opinion paragraph above, in our opinion "
+            f"the subject matter presents fairly in all material respects. The qualification arises from the Critical "
+            f"and/or Significant findings identified in Section IV, which management has committed to remediate."
+        )
+    para(f"Management is responsible for the implementation of corrective actions. A follow-up review will be conducted approximately 90 days from the report date ({follow_up_date.strftime('%B %d, %Y')}).")
+
+    # ── Signature Block ───────────────────────────────────────────────────────
+    pdf.ln(8)
+    pdf.set_line_width(0.3)
+    pdf.line(10, pdf.get_y(), 100, pdf.get_y())
+    pdf.ln(3)
+    pdf.set_font("Helvetica", "", 9)
+    pdf.cell(0, 5, _safe(f"Engagement Partner, {audit['audit_firm']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(audit["report_date"]), new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.cell(0, 5, "This report is confidential and prepared solely for the use of Casper's Kitchens Inc.", new_x="LMARGIN", new_y="NEXT")
+
+    out_path = PDF_DIR / f"audit_{audit['audit_id'].replace('-', '_').lower()}.pdf"
+    pdf.output(str(out_path))
+    return str(out_path)
+
+
+def main():
+    PDF_DIR.mkdir(parents=True, exist_ok=True)
+    audits = generate_audit_data()
+
+    for a in audits:
+        path = generate_pdf(a)
+        print(f"  Generated: {path}")
+
+    with open(METADATA_PATH, "w") as f:
+        json.dump({"audits": audits, "locations": LOCATIONS}, f, indent=2)
+    print(f"  Metadata: {METADATA_PATH}")
+    print(f"\nDone! Generated {len(audits)} audit reports.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/data/audits/pdfs/audit_aud_01_3001.pdf b/data/audits/pdfs/audit_aud_01_3001.pdf
new file mode 100644
index 0000000..02a5bea
Binary files /dev/null and b/data/audits/pdfs/audit_aud_01_3001.pdf differ
diff --git a/data/audits/pdfs/audit_aud_01_3002.pdf b/data/audits/pdfs/audit_aud_01_3002.pdf
new file mode 100644
index 0000000..f42afb4
Binary files /dev/null and b/data/audits/pdfs/audit_aud_01_3002.pdf differ
diff --git a/data/audits/pdfs/audit_aud_01_3003.pdf b/data/audits/pdfs/audit_aud_01_3003.pdf
new file mode 100644
index 0000000..17cf202
Binary files /dev/null and b/data/audits/pdfs/audit_aud_01_3003.pdf differ
diff --git a/data/audits/pdfs/audit_aud_01_3004.pdf b/data/audits/pdfs/audit_aud_01_3004.pdf
new file mode 100644
index 0000000..50e7cee
Binary files /dev/null and b/data/audits/pdfs/audit_aud_01_3004.pdf differ
diff --git a/data/audits/pdfs/audit_aud_02_3005.pdf b/data/audits/pdfs/audit_aud_02_3005.pdf
new file mode 100644
index 0000000..b1b5e91
Binary files /dev/null and b/data/audits/pdfs/audit_aud_02_3005.pdf differ
diff --git a/data/audits/pdfs/audit_aud_02_3006.pdf b/data/audits/pdfs/audit_aud_02_3006.pdf
new file mode 100644
index 0000000..d57d8af
Binary files /dev/null and b/data/audits/pdfs/audit_aud_02_3006.pdf differ
diff --git a/data/audits/pdfs/audit_aud_02_3007.pdf b/data/audits/pdfs/audit_aud_02_3007.pdf
new file mode 100644
index 0000000..9907e25
Binary files /dev/null and b/data/audits/pdfs/audit_aud_02_3007.pdf differ
diff --git a/data/audits/pdfs/audit_aud_02_3008.pdf b/data/audits/pdfs/audit_aud_02_3008.pdf
new file mode 100644
index 0000000..f55a163
Binary files /dev/null and b/data/audits/pdfs/audit_aud_02_3008.pdf differ
diff --git a/data/audits/pdfs/audit_aud_03_3009.pdf b/data/audits/pdfs/audit_aud_03_3009.pdf
new file mode 100644
index 0000000..3f8d1c6
Binary files /dev/null and b/data/audits/pdfs/audit_aud_03_3009.pdf differ
diff --git a/data/audits/pdfs/audit_aud_03_3010.pdf b/data/audits/pdfs/audit_aud_03_3010.pdf
new file mode 100644
index 0000000..d9c23e7
Binary files /dev/null and b/data/audits/pdfs/audit_aud_03_3010.pdf differ
diff --git a/data/audits/pdfs/audit_aud_03_3011.pdf b/data/audits/pdfs/audit_aud_03_3011.pdf
new file mode 100644
index 0000000..3dcca91
Binary files /dev/null and b/data/audits/pdfs/audit_aud_03_3011.pdf differ
diff --git a/data/audits/pdfs/audit_aud_03_3012.pdf b/data/audits/pdfs/audit_aud_03_3012.pdf
new file mode 100644
index 0000000..fd4f5f0
Binary files /dev/null and b/data/audits/pdfs/audit_aud_03_3012.pdf differ
diff --git a/data/audits/pdfs/audit_aud_04_3013.pdf b/data/audits/pdfs/audit_aud_04_3013.pdf
new file mode 100644
index 0000000..ce1b3ce
Binary files /dev/null and b/data/audits/pdfs/audit_aud_04_3013.pdf differ
diff --git a/data/audits/pdfs/audit_aud_04_3014.pdf b/data/audits/pdfs/audit_aud_04_3014.pdf
new file mode 100644
index 0000000..d4184ff
Binary files /dev/null and b/data/audits/pdfs/audit_aud_04_3014.pdf differ
diff --git a/data/audits/pdfs/audit_aud_04_3015.pdf b/data/audits/pdfs/audit_aud_04_3015.pdf
new file mode 100644
index 0000000..b02564a
Binary files /dev/null and b/data/audits/pdfs/audit_aud_04_3015.pdf differ
diff --git a/data/audits/pdfs/audit_aud_04_3016.pdf b/data/audits/pdfs/audit_aud_04_3016.pdf
new file mode 100644
index 0000000..8e25c4b
Binary files /dev/null and b/data/audits/pdfs/audit_aud_04_3016.pdf differ
diff --git a/data/canonical/.gitignore b/data/canonical/.gitignore
new file mode 100644
index 0000000..fa79d70
--- /dev/null
+++ b/data/canonical/.gitignore
@@ -0,0 +1,10 @@
+# Local virtualenv created by regenerate.sh
+.venv/
+
+# OSM road-network caches downloaded by generate_canonical_dataset.py.
+# These regenerate on demand; keeping them out of git so the repo stays small.
+cache_*_graph.pkl
+
+# osmnx's own raw OSM JSON response cache (separate from the pickle graph cache).
+# Auto-populated on download from openstreetmap.org.
+cache/
diff --git a/data/canonical/README.md b/data/canonical/README.md
index f91d3bf..2ccacf3 100644
--- a/data/canonical/README.md
+++ b/data/canonical/README.md
@@ -22,17 +22,19 @@ This approach provides:
 ```
 canonical/
 ├── README.md                           # This file
+├── regenerate.sh                       # One-shot regen helper (venv + run)
 ├── generate_canonical_dataset.py       # Offline dataset generator
-├── caspers_data_source.py             # Standalone Python streaming source
-├── caspers_streaming_notebook.py      # Databricks notebook version
+├── update_locations_parquet.py         # Add/edit locations (dim parquet only)
+├── caspers_data_source.py              # Standalone Python streaming source
+├── caspers_streaming_notebook.py       # Databricks notebook version
 └── canonical_dataset/
-    ├── events.parquet                 # 1M+ events, 75K+ orders (34.5 MB)
-    ├── locations.parquet              # 4 ghost kitchen locations (6 KB)
-    ├── brands.parquet                 # 24 food brands (4 KB)
-    ├── brand_locations.parquet        # Brand availability by city/time (5 KB)
-    ├── categories.parquet             # 112 menu categories (4 KB)
-    ├── menus.parquet                  # 24 menus (3 KB)
-    └── items.parquet                  # 181 menu items with prices (9 KB)
+    ├── events.parquet                  # All events, orders + driver pings
+    ├── locations.parquet               # Ghost kitchen locations (4 US + 4 EMEA)
+    ├── brands.parquet                  # 24 food brands (4 KB)
+    ├── brand_locations.parquet         # Brand availability by city/time
+    ├── categories.parquet              # 112 menu categories (4 KB)
+    ├── menus.parquet                   # 24 menus (3 KB)
+    └── items.parquet                   # 181 menu items with prices (9 KB)
 ```
 
 ---
@@ -82,6 +84,7 @@ python3 caspers_data_source.py
 
 ### Cities & Narratives
 
+US (original 4):
 | City | Location ID | Growth | Daily Orders | Narrative |
 |------|-------------|--------|--------------|-----------|
 | **San Francisco** | 1 | +74% | 171 → 297 | Health-focused brands, steady growth |
@@ -89,6 +92,16 @@ python3 caspers_data_source.py
 | **Bellevue** | 3 | +2% (flat) | 230 → 234 | Suburban comfort food, stagnant |
 | **Chicago** | 4 | -25% | 318 → 240 | Legacy operation, declining quality |
 
+EMEA (added for operational dashboard demo):
+| City | Location ID | Growth | Daily Orders | Notes |
+|------|-------------|--------|--------------|-------|
+| **London** | 5 | +0.3%/day | ~22 baseline | Shoreditch, UK |
+| **Munich** | 6 | +0.2%/day | ~18 baseline | Schwabing, Germany |
+| **Amsterdam** | 7 | +0.25%/day | ~20 baseline | City center, Netherlands |
+| **Vianen** | 8 | +0.4%/day | ~10 baseline | Smallest, fastest growth |
+
+EMEA locations all inherit the location-1 (SF) brand mix in `brand_locations.parquet`. To customise per-city, edit `update_locations_parquet.py` (or hand-edit `brand_locations.parquet` after regen).
+
 ### Event Types
 
 | Event | Count | % | Description |
@@ -229,24 +242,55 @@ Each run automatically processes the correct amount based on elapsed time.
 
 ## Dataset Generation
 
-### Prerequisites
+### One-shot regen (recommended)
+
+```bash
+cd data/canonical
+./regenerate.sh
+```
+
+This creates a local `.venv`, installs deps, runs `update_locations_parquet.py`,
+then `generate_canonical_dataset.py`. Takes **~15–25 min for 8 cities** (longer
+than the original ~10 min for 4 because of the EMEA OSM downloads), and needs
+internet to fetch OSM road networks via `osmnx`.
+
+When done, commit the updated parquets:
 
 ```bash
-pip install pandas pyarrow osmnx networkx geopy scikit-learn
+git add data/canonical/canonical_dataset/locations.parquet \
+        data/canonical/canonical_dataset/brand_locations.parquet \
+        data/canonical/canonical_dataset/events.parquet
+git commit -m "regenerate canonical dataset"
 ```
 
-### Regenerate Dataset
+### Manual two-step (advanced)
 
 ```bash
+cd data/canonical
+pip install pandas pyarrow osmnx networkx geopy
+
+# 1. Add/edit locations (only updates dim parquets)
+python3 update_locations_parquet.py
+
+# 2. Regenerate events for ALL locations present in locations.parquet
 python3 generate_canonical_dataset.py
 ```
 
-**Takes ~10 minutes** to:
+### What the generator does
+
 1. Load dimension tables (brands, locations, items)
-2. Download/cache OpenStreetMap road networks for 4 cities
-3. Generate 90 days of orders with realistic demand patterns
-4. Calculate real shortest-path routes using OSM
-5. Output compact parquet format (34.5 MB)
+2. Download/cache OpenStreetMap road networks (one cache file per city, `cache_<code>_graph.pkl`)
+3. Generate 90 days of orders with realistic demand patterns per location
+4. Calculate real shortest-path routes via OSM + NetworkX
+5. Output compact `events.parquet`
+
+### Adding a new location
+
+1. Edit `NEW_LOCATIONS` in `update_locations_parquet.py` (set a fresh `location_id`).
+2. Run `./regenerate.sh`.
+3. Commit the updated parquet files.
+
+That's the only step required — `stages/canonical_data.ipynb` loads whatever is in `locations.parquet` and the lakeflow pipeline will naturally produce silver/gold rows for every city present in `events.parquet`.
 
 ### Data Features
 
diff --git a/data/canonical/canonical_dataset/brand_locations.parquet b/data/canonical/canonical_dataset/brand_locations.parquet
index 9b9593b..8fc56dc 100644
Binary files a/data/canonical/canonical_dataset/brand_locations.parquet and b/data/canonical/canonical_dataset/brand_locations.parquet differ
diff --git a/data/canonical/canonical_dataset/events.parquet b/data/canonical/canonical_dataset/events.parquet
index 2c5f412..c8cc5f4 100644
Binary files a/data/canonical/canonical_dataset/events.parquet and b/data/canonical/canonical_dataset/events.parquet differ
diff --git a/data/canonical/canonical_dataset/locations.parquet b/data/canonical/canonical_dataset/locations.parquet
index baafab3..644e188 100644
Binary files a/data/canonical/canonical_dataset/locations.parquet and b/data/canonical/canonical_dataset/locations.parquet differ
diff --git a/data/canonical/generate_canonical_dataset.py b/data/canonical/generate_canonical_dataset.py
index 4e8d7fa..a1d906d 100644
--- a/data/canonical/generate_canonical_dataset.py
+++ b/data/canonical/generate_canonical_dataset.py
@@ -1,9 +1,14 @@
 """
 Canonical Dataset Generator for Casper's Kitchens
-Generates 90 days of realistic ghost kitchen event data across 4 cities.
+Generates 90 days of realistic ghost kitchen event data across all locations
+defined in canonical_dataset/locations.parquet.
 
 Uses real OpenStreetMap road networks for routing.
-Outputs compact parquet files (orders.parquet, events.parquet).
+Outputs compact parquet files (events.parquet).
+
+To extend with new locations:
+  1. Edit and run `update_locations_parquet.py` to add new rows.
+  2. Re-run this script to regenerate events.parquet for all locations.
 """
 
 import datetime as dt
@@ -11,9 +16,14 @@
 import math
 import pickle
 import random
+import sys
+import time
 from pathlib import Path
 from typing import Dict, List, Tuple
 
+# Force line-buffered stdout so progress is visible when run under a pipe/CI.
+sys.stdout.reconfigure(line_buffering=True)
+
 import networkx as nx
 import numpy as np
 import osmnx as ox
@@ -63,6 +73,8 @@
 BRANDS_BY_ID = brands_df.set_index('brand_id').to_dict('index')
 ITEMS_BY_BRAND = {bid: grp.to_dict('records') for bid, grp in items_df.groupby('brand_id')}
 
+print(f"   {len(LOCATIONS)} locations: " + ", ".join(l['name'] for l in LOCATIONS))
+
 # ============================================================================
 # DEMAND PATTERNS
 # ============================================================================
@@ -420,14 +432,15 @@ def add_event(ts, event_type_id, **kwargs):
 # MAIN GENERATION LOOP
 # ============================================================================
 
-print(f"\n🏭 Generating {DAYS} days of orders across 4 cities...")
+print(f"\n🏭 Generating {DAYS} days of orders across {len(LOCATIONS)} cities...")
 
 all_events = []
 generated_order_ids = set()  # Track to ensure uniqueness
+_t0 = time.time()
 
 for day in range(DAYS):
-    if day % 10 == 0:
-        print(f"  Day {day}/{DAYS}...")
+    _day_start = time.time()
+    _day_events_before = len(all_events)
 
     for location in LOCATIONS:
         loc_code = location['location_code']
@@ -457,6 +470,16 @@ def add_event(ts, event_type_id, **kwargs):
                 if events:
                     all_events.extend(events)
 
+    _day_elapsed = time.time() - _day_start
+    _day_events = len(all_events) - _day_events_before
+    _total_elapsed = time.time() - _t0
+    _eta_remaining = _total_elapsed / (day + 1) * (DAYS - day - 1)
+    print(
+        f"  Day {day+1:2d}/{DAYS} done in {_day_elapsed:5.1f}s "
+        f"(+{_day_events:>6,} events, total {len(all_events):>8,}; "
+        f"elapsed {_total_elapsed/60:5.1f}m, ETA {_eta_remaining/60:5.1f}m)"
+    )
+
 # Count unique orders
 unique_orders = len(set(e['order_id'] for e in all_events))
 print(f"\n✅ Generated {unique_orders} orders with {len(all_events)} events")
diff --git a/data/canonical/regenerate.sh b/data/canonical/regenerate.sh
new file mode 100755
index 0000000..e27f01f
--- /dev/null
+++ b/data/canonical/regenerate.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Regenerate the canonical dataset (parquet files in canonical_dataset/).
+#
+# Usage:
+#   cd data/canonical
+#   ./regenerate.sh
+#
+# Requirements (auto-installed into a local .venv):
+#   pandas, pyarrow, networkx, osmnx, geopy
+#
+# Takes ~15–25 min for 8 cities; needs internet to fetch OSM road networks
+# from openstreetmap.org via osmnx + geopy/Nominatim.
+#
+# What it does:
+#   1. Create .venv in this directory if not present, install deps
+#   2. Add any missing locations to locations.parquet + brand_locations.parquet
+#      (via update_locations_parquet.py — edit that file to change which ones)
+#   3. Regenerate events.parquet with 90 days of orders for ALL locations
+#      now present in locations.parquet (via generate_canonical_dataset.py)
+#
+# Idempotent — re-run anytime after editing NEW_LOCATIONS in
+# update_locations_parquet.py.
+
+set -eo pipefail
+cd "$(dirname "$0")"
+
+PIP_INDEX="${PIP_INDEX_URL:-https://pypi-proxy.dev.databricks.com/simple}"
+
+if [ ! -d ".venv" ]; then
+    echo "📦 Creating .venv and installing deps (one-time, ~3 min)..."
+    python3 -m venv .venv
+    .venv/bin/pip install --quiet --upgrade pip --index-url "$PIP_INDEX"
+    .venv/bin/pip install --quiet --index-url "$PIP_INDEX" \
+        pandas pyarrow networkx osmnx geopy scikit-learn
+fi
+
+echo ""
+echo "🧭 Step 1/2: update_locations_parquet.py"
+.venv/bin/python update_locations_parquet.py
+
+echo ""
+echo "🏭 Step 2/2: generate_canonical_dataset.py (this takes a while)"
+.venv/bin/python generate_canonical_dataset.py
+
+echo ""
+echo "✅ Done. Commit the updated parquet files:"
+echo "    git add canonical_dataset/locations.parquet \\"
+echo "            canonical_dataset/brand_locations.parquet \\"
+echo "            canonical_dataset/events.parquet"
+echo "    git commit -m 'regenerate canonical dataset with N locations'"
diff --git a/data/canonical/update_locations_parquet.py b/data/canonical/update_locations_parquet.py
new file mode 100644
index 0000000..509b511
--- /dev/null
+++ b/data/canonical/update_locations_parquet.py
@@ -0,0 +1,100 @@
+"""
+Add EMEA locations (5-8) to locations.parquet and brand_locations.parquet.
+
+Run this locally once whenever the location set changes:
+    cd data/canonical
+    python3 update_locations_parquet.py
+
+This only updates the *dimension* parquets. To regenerate the matching
+events.parquet (orders + driver pings + routes for these new cities) you
+must then re-run `generate_canonical_dataset.py`.
+
+Idempotent — safe to re-run; existing locations are skipped.
+"""
+import sys
+from pathlib import Path
+
+try:
+    import pandas as pd
+except ModuleNotFoundError:
+    sys.exit("ERROR: pandas not installed. Run: pip install pandas pyarrow")
+
+# Resolve paths relative to this script (so it works from any cwd)
+HERE = Path(__file__).resolve().parent
+LOCATIONS_PATH = HERE / "canonical_dataset" / "locations.parquet"
+BRAND_LOCATIONS_PATH = HERE / "canonical_dataset" / "brand_locations.parquet"
+
+# ── New locations to add ────────────────────────────────────────────────────
+# Edit this list to add or change locations. `location_id` must be unique.
+NEW_LOCATIONS = [
+    {"location_id": 5, "name": "London",    "location_code": "lon",
+     "lat": 51.5248, "lon": -0.0796,
+     "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+     "narrative": "growing",
+     "base_orders_day": 22, "growth_rate_daily": 0.003},
+    {"location_id": 6, "name": "Munich",    "location_code": "muc",
+     "lat": 48.1601, "lon": 11.5874,
+     "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+     "narrative": "stable",
+     "base_orders_day": 18, "growth_rate_daily": 0.002},
+    {"location_id": 7, "name": "Amsterdam", "location_code": "ams",
+     "lat": 52.3745, "lon": 4.8979,
+     "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+     "narrative": "growing",
+     "base_orders_day": 20, "growth_rate_daily": 0.0025},
+    {"location_id": 8, "name": "Vianen",    "location_code": "via",
+     "lat": 51.9880, "lon": 5.0895,
+     "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+     "narrative": "growing_fast",
+     "base_orders_day": 10, "growth_rate_daily": 0.004},
+]
+
+# ── locations.parquet ───────────────────────────────────────────────────────
+locs = pd.read_parquet(LOCATIONS_PATH)
+print(f"Before: {len(locs)} locations → {sorted(locs['location_id'].tolist())}")
+existing_ids = set(locs["location_id"])
+to_add = [l for l in NEW_LOCATIONS if l["location_id"] not in existing_ids]
+if to_add:
+    new_df = pd.DataFrame(to_add)
+    for col in locs.columns:
+        if col not in new_df.columns:
+            new_df[col] = None
+    new_df = new_df[locs.columns]
+    for col in locs.columns:
+        try:
+            new_df[col] = new_df[col].astype(locs[col].dtype)
+        except Exception:
+            pass
+    locs = pd.concat([locs, new_df], ignore_index=True)
+    locs.to_parquet(LOCATIONS_PATH, index=False)
+    print(f"✅ Added {len(to_add)} locations → {[l['name'] for l in to_add]}")
+else:
+    print("ℹ️  locations already complete")
+
+print()
+print(locs[["location_id", "name", "location_code", "lat", "lon"]].to_string(index=False))
+print()
+
+# ── brand_locations.parquet ─────────────────────────────────────────────────
+# Each new location inherits the brand mix from location 1 (SF) by default.
+bl = pd.read_parquet(BRAND_LOCATIONS_PATH)
+print(f"brand_locations before: {len(bl)} rows across {bl['location_id'].nunique()} locations")
+existing_bl = set(bl["location_id"])
+new_loc_ids = [l["location_id"] for l in NEW_LOCATIONS if l["location_id"] not in existing_bl]
+if new_loc_ids:
+    base = bl[bl["location_id"] == 1].copy()
+    frames = []
+    for lid in new_loc_ids:
+        copy = base.copy()
+        copy["location_id"] = lid
+        frames.append(copy)
+    bl = pd.concat([bl] + frames, ignore_index=True)
+    bl.to_parquet(BRAND_LOCATIONS_PATH, index=False)
+    print(f"✅ Added brand assignments for location IDs: {new_loc_ids}")
+else:
+    print("ℹ️  brand_locations already complete")
+print(f"brand_locations after:  {len(bl)} rows across {bl['location_id'].nunique()} locations")
+
+print()
+print("Done. Next: run `python3 generate_canonical_dataset.py` to regenerate")
+print("events.parquet so the new locations have realistic orders + driver pings.")
diff --git a/data/consultancy/consultancy_metadata.json b/data/consultancy/consultancy_metadata.json
new file mode 100644
index 0000000..ae315c4
--- /dev/null
+++ b/data/consultancy/consultancy_metadata.json
@@ -0,0 +1,419 @@
+{
+  "reports": [
+    {
+      "report_id": "CON-4001",
+      "location_id": 0,
+      "location_name": "All Locations (Corporate)",
+      "report_type": "Market Expansion Strategy",
+      "subtitle": "Identifying High-Value Growth Markets for Ghost Kitchen Operations",
+      "consulting_firm": "Oliver Wyman",
+      "report_date": "2023-07-15",
+      "executive_summary": "Casper's Kitchens has demonstrated strong unit economics across its 4 operating locations. This engagement analyzes 12 potential expansion markets across the United States, scoring each on population density, delivery app penetration, competitive intensity, and real estate costs. We recommend prioritizing Austin TX, Denver CO, and Seattle WA as Tier-1 expansion candidates for 2024\u20132025, with projected EBITDA breakeven at 14\u201318 months per location.",
+      "sections": [
+        [
+          "Market Sizing",
+          "The U.S. ghost kitchen market is projected to reach $71.4B by 2027 (CAGR 12.3%). Delivery-app adoption in target markets averages 38% of restaurant-goers. Casper's 16-brand portfolio gives a meaningful differentiation advantage vs. single-concept operators."
+        ],
+        [
+          "Competitive Landscape",
+          "Primary competitors include Kitchen United, CloudKitchens, and regional operators. Casper's AI-driven demand forecasting and multi-brand efficiency creates a 15\u201322% cost-per-order advantage in modeled scenarios."
+        ],
+        [
+          "Recommended Markets",
+          "Austin TX: Population 978K, delivery penetration 44%, real estate cost index 0.72. Denver CO: Population 2.1M metro, tech-worker density high, index 0.81. Seattle WA: High income per capita, strong DoorDash/UberEats market share, index 0.88."
+        ],
+        [
+          "Financial Projections",
+          "Modeled 3-year P&L: Year 1 revenue $2.1M\u2013$2.8M per location; Year 2 $3.4M\u2013$4.2M; Year 3 $4.8M\u2013$6.1M. Target Contribution Margin of 28% achievable with current brand mix and operational model."
+        ],
+        [
+          "Recommendations",
+          "Proceed with Austin TX as first expansion by Q3 2024. Secure dark kitchen facility lease (3,500\u20134,500 sq ft) at $18\u201322/sq ft NNN. Budget $420K\u2013$560K for fit-out, equipment, and pre-opening expenses."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4002",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "report_type": "Market Expansion Strategy",
+      "subtitle": "Identifying High-Value Growth Markets for Ghost Kitchen Operations",
+      "consulting_firm": "McKinsey & Company",
+      "report_date": "2023-07-26",
+      "executive_summary": "Casper's Kitchens has demonstrated strong unit economics across its 4 operating locations. This engagement analyzes 12 potential expansion markets across the United States, scoring each on population density, delivery app penetration, competitive intensity, and real estate costs. We recommend prioritizing Austin TX, Denver CO, and Seattle WA as Tier-1 expansion candidates for 2024\u20132025, with projected EBITDA breakeven at 14\u201318 months per location.",
+      "sections": [
+        [
+          "Market Sizing",
+          "The U.S. ghost kitchen market is projected to reach $71.4B by 2027 (CAGR 12.3%). Delivery-app adoption in target markets averages 38% of restaurant-goers. Casper's 16-brand portfolio gives a meaningful differentiation advantage vs. single-concept operators."
+        ],
+        [
+          "Competitive Landscape",
+          "Primary competitors include Kitchen United, CloudKitchens, and regional operators. Casper's AI-driven demand forecasting and multi-brand efficiency creates a 15\u201322% cost-per-order advantage in modeled scenarios."
+        ],
+        [
+          "Recommended Markets",
+          "Austin TX: Population 978K, delivery penetration 44%, real estate cost index 0.72. Denver CO: Population 2.1M metro, tech-worker density high, index 0.81. Seattle WA: High income per capita, strong DoorDash/UberEats market share, index 0.88."
+        ],
+        [
+          "Financial Projections",
+          "Modeled 3-year P&L: Year 1 revenue $2.1M\u2013$2.8M per location; Year 2 $3.4M\u2013$4.2M; Year 3 $4.8M\u2013$6.1M. Target Contribution Margin of 28% achievable with current brand mix and operational model."
+        ],
+        [
+          "Recommendations",
+          "Proceed with Austin TX as first expansion by Q3 2024. Secure dark kitchen facility lease (3,500\u20134,500 sq ft) at $18\u201322/sq ft NNN. Budget $420K\u2013$560K for fit-out, equipment, and pre-opening expenses."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4003",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "report_type": "Operations Efficiency Analysis",
+      "subtitle": "Reducing Cost-Per-Order and Improving Kitchen Throughput",
+      "consulting_firm": "Bain & Company",
+      "report_date": "2024-03-14",
+      "executive_summary": "An operational review of Casper's Kitchens ghost kitchen locations identified $1.2M\u2013$1.8M in annualized cost reduction opportunities through process optimization, scheduling improvements, and waste reduction. This report presents 14 specific initiatives ranked by ease-of-implementation and financial impact, with a 90-day implementation roadmap.",
+      "sections": [
+        [
+          "Current State Assessment",
+          "Average cost-per-order across locations: $8.40. Industry benchmark for comparable operations: $6.90\u2013$7.50. Labor accounts for 34% of total costs vs. 28% benchmark. Food waste running at 8.2% of food cost vs. 4\u20135% best-in-class."
+        ],
+        [
+          "Initiative 1 \u2014 Dynamic Labor Scheduling",
+          "Implementing AI-driven scheduling to match labor hours to predicted order volume. Estimated savings: $180K\u2013$240K annually. Payback period: 4 months. Risk: Low. Recommended tool: 7shifts or HotSchedules integration."
+        ],
+        [
+          "Initiative 2 \u2014 Menu Rationalization",
+          "Current 16-brand \u00d7 ~45 item average = 720 active SKUs across locations. Analysis shows 30% of items generate 8% of revenue. Reducing to top-performing 12 items per brand estimated to reduce prep time by 18% and food waste by 31%."
+        ],
+        [
+          "Initiative 3 \u2014 Batch Cooking Protocols",
+          "Standardizing batch cooking windows for high-volume items (proteins, sauces) reduces cook-to-order time by 23% during peak hours. Estimated throughput increase: +2.4 orders/hour/kitchen."
+        ],
+        [
+          "Initiative 4 \u2014 Supplier Consolidation",
+          "Consolidating from 18 to 9 primary suppliers enables volume discounts of 6\u201311% on produce and proteins. Estimated savings: $95K\u2013$140K annually. Also reduces receiving labor by 22%."
+        ],
+        [
+          "Implementation Roadmap",
+          "Days 1\u201330: Labor scheduling rollout, supplier consolidation RFP. Days 31\u201360: Menu rationalization pilot at San Francisco and Chicago. Days 61\u201390: Batch cooking SOP rollout, pilot measurement and scaling decision."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4004",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "report_type": "Operations Efficiency Analysis",
+      "subtitle": "Reducing Cost-Per-Order and Improving Kitchen Throughput",
+      "consulting_firm": "Boston Consulting Group",
+      "report_date": "2023-06-27",
+      "executive_summary": "An operational review of Casper's Kitchens ghost kitchen locations identified $1.2M\u2013$1.8M in annualized cost reduction opportunities through process optimization, scheduling improvements, and waste reduction. This report presents 14 specific initiatives ranked by ease-of-implementation and financial impact, with a 90-day implementation roadmap.",
+      "sections": [
+        [
+          "Current State Assessment",
+          "Average cost-per-order across locations: $8.40. Industry benchmark for comparable operations: $6.90\u2013$7.50. Labor accounts for 34% of total costs vs. 28% benchmark. Food waste running at 8.2% of food cost vs. 4\u20135% best-in-class."
+        ],
+        [
+          "Initiative 1 \u2014 Dynamic Labor Scheduling",
+          "Implementing AI-driven scheduling to match labor hours to predicted order volume. Estimated savings: $180K\u2013$240K annually. Payback period: 4 months. Risk: Low. Recommended tool: 7shifts or HotSchedules integration."
+        ],
+        [
+          "Initiative 2 \u2014 Menu Rationalization",
+          "Current 16-brand \u00d7 ~45 item average = 720 active SKUs across locations. Analysis shows 30% of items generate 8% of revenue. Reducing to top-performing 12 items per brand estimated to reduce prep time by 18% and food waste by 31%."
+        ],
+        [
+          "Initiative 3 \u2014 Batch Cooking Protocols",
+          "Standardizing batch cooking windows for high-volume items (proteins, sauces) reduces cook-to-order time by 23% during peak hours. Estimated throughput increase: +2.4 orders/hour/kitchen."
+        ],
+        [
+          "Initiative 4 \u2014 Supplier Consolidation",
+          "Consolidating from 18 to 9 primary suppliers enables volume discounts of 6\u201311% on produce and proteins. Estimated savings: $95K\u2013$140K annually. Also reduces receiving labor by 22%."
+        ],
+        [
+          "Implementation Roadmap",
+          "Days 1\u201330: Labor scheduling rollout, supplier consolidation RFP. Days 31\u201360: Menu rationalization pilot at San Francisco and Chicago. Days 61\u201390: Batch cooking SOP rollout, pilot measurement and scaling decision."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4005",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "report_type": "Operations Efficiency Analysis",
+      "subtitle": "Reducing Cost-Per-Order and Improving Kitchen Throughput",
+      "consulting_firm": "A.T. Kearney",
+      "report_date": "2023-11-20",
+      "executive_summary": "An operational review of Casper's Kitchens ghost kitchen locations identified $1.2M\u2013$1.8M in annualized cost reduction opportunities through process optimization, scheduling improvements, and waste reduction. This report presents 14 specific initiatives ranked by ease-of-implementation and financial impact, with a 90-day implementation roadmap.",
+      "sections": [
+        [
+          "Current State Assessment",
+          "Average cost-per-order across locations: $8.40. Industry benchmark for comparable operations: $6.90\u2013$7.50. Labor accounts for 34% of total costs vs. 28% benchmark. Food waste running at 8.2% of food cost vs. 4\u20135% best-in-class."
+        ],
+        [
+          "Initiative 1 \u2014 Dynamic Labor Scheduling",
+          "Implementing AI-driven scheduling to match labor hours to predicted order volume. Estimated savings: $180K\u2013$240K annually. Payback period: 4 months. Risk: Low. Recommended tool: 7shifts or HotSchedules integration."
+        ],
+        [
+          "Initiative 2 \u2014 Menu Rationalization",
+          "Current 16-brand \u00d7 ~45 item average = 720 active SKUs across locations. Analysis shows 30% of items generate 8% of revenue. Reducing to top-performing 12 items per brand estimated to reduce prep time by 18% and food waste by 31%."
+        ],
+        [
+          "Initiative 3 \u2014 Batch Cooking Protocols",
+          "Standardizing batch cooking windows for high-volume items (proteins, sauces) reduces cook-to-order time by 23% during peak hours. Estimated throughput increase: +2.4 orders/hour/kitchen."
+        ],
+        [
+          "Initiative 4 \u2014 Supplier Consolidation",
+          "Consolidating from 18 to 9 primary suppliers enables volume discounts of 6\u201311% on produce and proteins. Estimated savings: $95K\u2013$140K annually. Also reduces receiving labor by 22%."
+        ],
+        [
+          "Implementation Roadmap",
+          "Days 1\u201330: Labor scheduling rollout, supplier consolidation RFP. Days 31\u201360: Menu rationalization pilot at San Francisco and Chicago. Days 61\u201390: Batch cooking SOP rollout, pilot measurement and scaling decision."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4006",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "report_type": "AI & Digital Transformation Roadmap",
+      "subtitle": "Accelerating Value Creation Through Intelligent Automation",
+      "consulting_firm": "McKinsey & Company",
+      "report_date": "2023-08-23",
+      "executive_summary": "Casper's Kitchens is well-positioned to leverage artificial intelligence across demand forecasting, customer experience personalization, and operational intelligence. This report outlines a phased 18-month AI transformation roadmap with projected ROI of 3.2x\u20134.8x on technology investment. Priority use cases include predictive ordering, AI-driven refund resolution, and real-time kitchen performance analytics.",
+      "sections": [
+        [
+          "Current Technology Stack",
+          "Current capabilities: Basic POS integration, manual demand forecasting, reactive customer service. Gaps: No predictive analytics, limited automation in complaint resolution, no unified data platform across locations."
+        ],
+        [
+          "Phase 1 \u2014 Data Foundation (Months 1\u20134)",
+          "Deploy a unified data lakehouse architecture (Databricks recommended) ingesting POS, delivery platform, and supplier data. Estimated investment: $280K\u2013$340K. Output: Single source of truth for all operational metrics accessible within 24 hours."
+        ],
+        [
+          "Phase 2 \u2014 Predictive Intelligence (Months 5\u201310)",
+          "AI demand forecasting: Reduce food waste by 35\u201340% (estimated $220K\u2013$310K annual savings). AI refund agent: Automate 68% of refund decisions, reducing resolution time from 4.2 hours to 8 minutes. Customer propensity models to personalize promotions."
+        ],
+        [
+          "Phase 3 \u2014 Autonomous Operations (Months 11\u201318)",
+          "Kitchen orchestration AI to auto-route orders based on real-time capacity. Predictive maintenance for equipment (reduce downtime by 45%). AI-generated supply chain reordering. Estimated Year 2 incremental EBITDA contribution: $1.4M\u2013$2.1M."
+        ],
+        [
+          "Build vs. Buy Recommendation",
+          "Recommend a hybrid approach: Databricks platform (buy) + custom AI models (build on top). Avoid point-solution vendors in demand forecasting and refund automation \u2014 proprietary models trained on Casper's data will outperform generic SaaS by 30\u201350% within 6 months of training data accumulation."
+        ],
+        [
+          "Investment & ROI Summary",
+          "Total 18-month investment: $1.1M\u2013$1.5M. Year 1 savings + revenue uplift: $680K\u2013$890K. Year 2\u20133 annualized benefit: $2.2M\u2013$3.1M. Blended 3-year ROI: 320\u2013480%. Recommendation: PROCEED immediately with Phase 1 data foundation."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4007",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "report_type": "AI & Digital Transformation Roadmap",
+      "subtitle": "Accelerating Value Creation Through Intelligent Automation",
+      "consulting_firm": "A.T. Kearney",
+      "report_date": "2023-07-15",
+      "executive_summary": "Casper's Kitchens is well-positioned to leverage artificial intelligence across demand forecasting, customer experience personalization, and operational intelligence. This report outlines a phased 18-month AI transformation roadmap with projected ROI of 3.2x\u20134.8x on technology investment. Priority use cases include predictive ordering, AI-driven refund resolution, and real-time kitchen performance analytics.",
+      "sections": [
+        [
+          "Current Technology Stack",
+          "Current capabilities: Basic POS integration, manual demand forecasting, reactive customer service. Gaps: No predictive analytics, limited automation in complaint resolution, no unified data platform across locations."
+        ],
+        [
+          "Phase 1 \u2014 Data Foundation (Months 1\u20134)",
+          "Deploy a unified data lakehouse architecture (Databricks recommended) ingesting POS, delivery platform, and supplier data. Estimated investment: $280K\u2013$340K. Output: Single source of truth for all operational metrics accessible within 24 hours."
+        ],
+        [
+          "Phase 2 \u2014 Predictive Intelligence (Months 5\u201310)",
+          "AI demand forecasting: Reduce food waste by 35\u201340% (estimated $220K\u2013$310K annual savings). AI refund agent: Automate 68% of refund decisions, reducing resolution time from 4.2 hours to 8 minutes. Customer propensity models to personalize promotions."
+        ],
+        [
+          "Phase 3 \u2014 Autonomous Operations (Months 11\u201318)",
+          "Kitchen orchestration AI to auto-route orders based on real-time capacity. Predictive maintenance for equipment (reduce downtime by 45%). AI-generated supply chain reordering. Estimated Year 2 incremental EBITDA contribution: $1.4M\u2013$2.1M."
+        ],
+        [
+          "Build vs. Buy Recommendation",
+          "Recommend a hybrid approach: Databricks platform (buy) + custom AI models (build on top). Avoid point-solution vendors in demand forecasting and refund automation \u2014 proprietary models trained on Casper's data will outperform generic SaaS by 30\u201350% within 6 months of training data accumulation."
+        ],
+        [
+          "Investment & ROI Summary",
+          "Total 18-month investment: $1.1M\u2013$1.5M. Year 1 savings + revenue uplift: $680K\u2013$890K. Year 2\u20133 annualized benefit: $2.2M\u2013$3.1M. Blended 3-year ROI: 320\u2013480%. Recommendation: PROCEED immediately with Phase 1 data foundation."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4008",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "report_type": "AI & Digital Transformation Roadmap",
+      "subtitle": "Accelerating Value Creation Through Intelligent Automation",
+      "consulting_firm": "McKinsey & Company",
+      "report_date": "2023-07-06",
+      "executive_summary": "Casper's Kitchens is well-positioned to leverage artificial intelligence across demand forecasting, customer experience personalization, and operational intelligence. This report outlines a phased 18-month AI transformation roadmap with projected ROI of 3.2x\u20134.8x on technology investment. Priority use cases include predictive ordering, AI-driven refund resolution, and real-time kitchen performance analytics.",
+      "sections": [
+        [
+          "Current Technology Stack",
+          "Current capabilities: Basic POS integration, manual demand forecasting, reactive customer service. Gaps: No predictive analytics, limited automation in complaint resolution, no unified data platform across locations."
+        ],
+        [
+          "Phase 1 \u2014 Data Foundation (Months 1\u20134)",
+          "Deploy a unified data lakehouse architecture (Databricks recommended) ingesting POS, delivery platform, and supplier data. Estimated investment: $280K\u2013$340K. Output: Single source of truth for all operational metrics accessible within 24 hours."
+        ],
+        [
+          "Phase 2 \u2014 Predictive Intelligence (Months 5\u201310)",
+          "AI demand forecasting: Reduce food waste by 35\u201340% (estimated $220K\u2013$310K annual savings). AI refund agent: Automate 68% of refund decisions, reducing resolution time from 4.2 hours to 8 minutes. Customer propensity models to personalize promotions."
+        ],
+        [
+          "Phase 3 \u2014 Autonomous Operations (Months 11\u201318)",
+          "Kitchen orchestration AI to auto-route orders based on real-time capacity. Predictive maintenance for equipment (reduce downtime by 45%). AI-generated supply chain reordering. Estimated Year 2 incremental EBITDA contribution: $1.4M\u2013$2.1M."
+        ],
+        [
+          "Build vs. Buy Recommendation",
+          "Recommend a hybrid approach: Databricks platform (buy) + custom AI models (build on top). Avoid point-solution vendors in demand forecasting and refund automation \u2014 proprietary models trained on Casper's data will outperform generic SaaS by 30\u201350% within 6 months of training data accumulation."
+        ],
+        [
+          "Investment & ROI Summary",
+          "Total 18-month investment: $1.1M\u2013$1.5M. Year 1 savings + revenue uplift: $680K\u2013$890K. Year 2\u20133 annualized benefit: $2.2M\u2013$3.1M. Blended 3-year ROI: 320\u2013480%. Recommendation: PROCEED immediately with Phase 1 data foundation."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4009",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "report_type": "Workforce Management & Culture Report",
+      "subtitle": "Building a High-Performance Ghost Kitchen Workforce",
+      "consulting_firm": "McKinsey & Company",
+      "report_date": "2023-07-23",
+      "executive_summary": "Staff turnover across Casper's Kitchens locations averages 84% annually \u2014 significantly above the 72% food service industry average. This report identifies the root causes of attrition, benchmarks compensation and culture practices, and recommends a 12-month Workforce Transformation Program projected to reduce turnover to 55\u201360% and save $340K\u2013$480K annually in recruiting and training costs.",
+      "sections": [
+        [
+          "Turnover Analysis",
+          "Chicago location: 112% annual turnover (critical). San Francisco: 91%. Silicon Valley: 78%. Bellevue: 71% (best performer). Primary drivers: Scheduling unpredictability (cited by 61% of exit interviews), compensation gap vs. market (8\u201312% below), and limited advancement path."
+        ],
+        [
+          "Compensation Benchmarking",
+          "Current average kitchen staff hourly rate: $17.40. Market benchmark (Glassdoor, Indeed, LinkedIn data): $19.20\u2013$21.50. Closing 50% of the gap (+$0.90\u2013$1.80/hr) combined with performance bonuses estimated to reduce voluntary exits by 28%."
+        ],
+        [
+          "Culture & Engagement Initiatives",
+          "Recommended: Monthly all-hands per location (30 min, CEO video + local manager Q&A). Peer recognition program ('Kitchen MVP'). Transparent promotion pathways: Lead Cook \u2192 Kitchen Supervisor \u2192 Location Manager (3\u201318 months). Target: eNPS improvement from current -12 to +20 within 12 months."
+        ],
+        [
+          "Training & Development",
+          "Current: 8-hour onboarding. Recommended: 24-hour structured onboarding + 90-day buddy program. Cross-training across all 16 brands increases scheduling flexibility by 35% and reduces call-out impact. Annual training budget per FTE: increase from $180 to $420."
+        ],
+        [
+          "Hiring & Onboarding Optimization",
+          "Partner with local culinary schools in all 4 markets. Streamline application-to-offer timeline from 18 days to 7 days. Offer $500 signing bonus contingent on 90-day tenure. Pre-screen for tech-friendliness (order management systems)."
+        ],
+        [
+          "Financial Impact",
+          "Current annual turnover cost per employee (recruiting + training + productivity loss): $4,200. At 84% turnover on 120 FTE base: $423K/year. At 58% turnover post-program: $292K/year. Net saving: $131K/year. Combined with reduced training costs and productivity gains: $340K\u2013$480K total annual benefit."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4010",
+      "location_id": 0,
+      "location_name": "All Locations (Corporate)",
+      "report_type": "Workforce Management & Culture Report",
+      "subtitle": "Building a High-Performance Ghost Kitchen Workforce",
+      "consulting_firm": "Boston Consulting Group",
+      "report_date": "2023-08-12",
+      "executive_summary": "Staff turnover across Casper's Kitchens locations averages 84% annually \u2014 significantly above the 72% food service industry average. This report identifies the root causes of attrition, benchmarks compensation and culture practices, and recommends a 12-month Workforce Transformation Program projected to reduce turnover to 55\u201360% and save $340K\u2013$480K annually in recruiting and training costs.",
+      "sections": [
+        [
+          "Turnover Analysis",
+          "Chicago location: 112% annual turnover (critical). San Francisco: 91%. Silicon Valley: 78%. Bellevue: 71% (best performer). Primary drivers: Scheduling unpredictability (cited by 61% of exit interviews), compensation gap vs. market (8\u201312% below), and limited advancement path."
+        ],
+        [
+          "Compensation Benchmarking",
+          "Current average kitchen staff hourly rate: $17.40. Market benchmark (Glassdoor, Indeed, LinkedIn data): $19.20\u2013$21.50. Closing 50% of the gap (+$0.90\u2013$1.80/hr) combined with performance bonuses estimated to reduce voluntary exits by 28%."
+        ],
+        [
+          "Culture & Engagement Initiatives",
+          "Recommended: Monthly all-hands per location (30 min, CEO video + local manager Q&A). Peer recognition program ('Kitchen MVP'). Transparent promotion pathways: Lead Cook \u2192 Kitchen Supervisor \u2192 Location Manager (3\u201318 months). Target: eNPS improvement from current -12 to +20 within 12 months."
+        ],
+        [
+          "Training & Development",
+          "Current: 8-hour onboarding. Recommended: 24-hour structured onboarding + 90-day buddy program. Cross-training across all 16 brands increases scheduling flexibility by 35% and reduces call-out impact. Annual training budget per FTE: increase from $180 to $420."
+        ],
+        [
+          "Hiring & Onboarding Optimization",
+          "Partner with local culinary schools in all 4 markets. Streamline application-to-offer timeline from 18 days to 7 days. Offer $500 signing bonus contingent on 90-day tenure. Pre-screen for tech-friendliness (order management systems)."
+        ],
+        [
+          "Financial Impact",
+          "Current annual turnover cost per employee (recruiting + training + productivity loss): $4,200. At 84% turnover on 120 FTE base: $423K/year. At 58% turnover post-program: $292K/year. Net saving: $131K/year. Combined with reduced training costs and productivity gains: $340K\u2013$480K total annual benefit."
+        ]
+      ]
+    },
+    {
+      "report_id": "CON-4011",
+      "location_id": 0,
+      "location_name": "All Locations (Corporate)",
+      "report_type": "Workforce Management & Culture Report",
+      "subtitle": "Building a High-Performance Ghost Kitchen Workforce",
+      "consulting_firm": "Oliver Wyman",
+      "report_date": "2023-10-28",
+      "executive_summary": "Staff turnover across Casper's Kitchens locations averages 84% annually \u2014 significantly above the 72% food service industry average. This report identifies the root causes of attrition, benchmarks compensation and culture practices, and recommends a 12-month Workforce Transformation Program projected to reduce turnover to 55\u201360% and save $340K\u2013$480K annually in recruiting and training costs.",
+      "sections": [
+        [
+          "Turnover Analysis",
+          "Chicago location: 112% annual turnover (critical). San Francisco: 91%. Silicon Valley: 78%. Bellevue: 71% (best performer). Primary drivers: Scheduling unpredictability (cited by 61% of exit interviews), compensation gap vs. market (8\u201312% below), and limited advancement path."
+        ],
+        [
+          "Compensation Benchmarking",
+          "Current average kitchen staff hourly rate: $17.40. Market benchmark (Glassdoor, Indeed, LinkedIn data): $19.20\u2013$21.50. Closing 50% of the gap (+$0.90\u2013$1.80/hr) combined with performance bonuses estimated to reduce voluntary exits by 28%."
+        ],
+        [
+          "Culture & Engagement Initiatives",
+          "Recommended: Monthly all-hands per location (30 min, CEO video + local manager Q&A). Peer recognition program ('Kitchen MVP'). Transparent promotion pathways: Lead Cook \u2192 Kitchen Supervisor \u2192 Location Manager (3\u201318 months). Target: eNPS improvement from current -12 to +20 within 12 months."
+        ],
+        [
+          "Training & Development",
+          "Current: 8-hour onboarding. Recommended: 24-hour structured onboarding + 90-day buddy program. Cross-training across all 16 brands increases scheduling flexibility by 35% and reduces call-out impact. Annual training budget per FTE: increase from $180 to $420."
+        ],
+        [
+          "Hiring & Onboarding Optimization",
+          "Partner with local culinary schools in all 4 markets. Streamline application-to-offer timeline from 18 days to 7 days. Offer $500 signing bonus contingent on 90-day tenure. Pre-screen for tech-friendliness (order management systems)."
+        ],
+        [
+          "Financial Impact",
+          "Current annual turnover cost per employee (recruiting + training + productivity loss): $4,200. At 84% turnover on 120 FTE base: $423K/year. At 58% turnover post-program: $292K/year. Net saving: $131K/year. Combined with reduced training costs and productivity gains: $340K\u2013$480K total annual benefit."
+        ]
+      ]
+    }
+  ],
+  "locations": [
+    {
+      "location_id": 0,
+      "name": "All Locations (Corporate)",
+      "address": "Corporate HQ"
+    },
+    {
+      "location_id": 1,
+      "name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103"
+    },
+    {
+      "location_id": 2,
+      "name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051"
+    },
+    {
+      "location_id": 3,
+      "name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004"
+    },
+    {
+      "location_id": 4,
+      "name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/data/consultancy/generate_consultancy_reports.py b/data/consultancy/generate_consultancy_reports.py
new file mode 100644
index 0000000..de12796
--- /dev/null
+++ b/data/consultancy/generate_consultancy_reports.py
@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+"""
+Generate consultancy report PDFs for Casper's Kitchens.
+
+Produces realistic management consulting reports: market expansion strategies,
+operations efficiency analysis, AI transformation roadmaps, and workforce
+management optimization reports.
+
+Outputs:
+  - data/consultancy/pdfs/*.pdf
+  - data/consultancy/consultancy_metadata.json
+
+Requirements:
+  pip install fpdf2
+"""
+
+import json
+import random
+import textwrap
+from datetime import date, timedelta
+from pathlib import Path
+
+from fpdf import FPDF
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def _safe(text: str) -> str:
+    return (
+        str(text)
+        .replace("\u2014", "--")
+        .replace("\u2013", "-")
+        .replace("\u2018", "'")
+        .replace("\u2019", "'")
+        .replace("\u201c", '"')
+        .replace("\u201d", '"')
+        .replace("\u2026", "...")
+        .replace("\u2022", "-")
+        .replace("\u00d7", "x")
+        .replace("\u2192", "->")
+        .replace("\u2190", "<-")
+        .encode("latin-1", errors="replace")
+        .decode("latin-1")
+    )
+PDF_DIR = SCRIPT_DIR / "pdfs"
+METADATA_PATH = SCRIPT_DIR / "consultancy_metadata.json"
+
+random.seed(123)
+
+CONSULTING_FIRMS = [
+    "McKinsey & Company",
+    "Boston Consulting Group",
+    "Bain & Company",
+    "Oliver Wyman",
+    "A.T. Kearney",
+    "Accenture Strategy",
+]
+
+REPORT_TYPES = [
+    {
+        "type": "Market Expansion Strategy",
+        "subtitle": "Identifying High-Value Growth Markets for Ghost Kitchen Operations",
+        "executive_summary": (
+            "Casper's Kitchens has demonstrated strong unit economics across its 4 operating locations. "
+            "This engagement analyzes 12 potential expansion markets across the United States, scoring each "
+            "on population density, delivery app penetration, competitive intensity, and real estate costs. "
+            "We recommend prioritizing Austin TX, Denver CO, and Seattle WA as Tier-1 expansion candidates "
+            "for 2024–2025, with projected EBITDA breakeven at 14–18 months per location."
+        ),
+        "sections": [
+            ("Market Sizing", "The U.S. ghost kitchen market is projected to reach $71.4B by 2027 (CAGR 12.3%). Delivery-app adoption in target markets averages 38% of restaurant-goers. Casper's 16-brand portfolio gives a meaningful differentiation advantage vs. single-concept operators."),
+            ("Competitive Landscape", "Primary competitors include Kitchen United, CloudKitchens, and regional operators. Casper's AI-driven demand forecasting and multi-brand efficiency creates a 15–22% cost-per-order advantage in modeled scenarios."),
+            ("Recommended Markets", "Austin TX: Population 978K, delivery penetration 44%, real estate cost index 0.72. Denver CO: Population 2.1M metro, tech-worker density high, index 0.81. Seattle WA: High income per capita, strong DoorDash/UberEats market share, index 0.88."),
+            ("Financial Projections", "Modeled 3-year P&L: Year 1 revenue $2.1M–$2.8M per location; Year 2 $3.4M–$4.2M; Year 3 $4.8M–$6.1M. Target Contribution Margin of 28% achievable with current brand mix and operational model."),
+            ("Recommendations", "Proceed with Austin TX as first expansion by Q3 2024. Secure dark kitchen facility lease (3,500–4,500 sq ft) at $18–22/sq ft NNN. Budget $420K–$560K for fit-out, equipment, and pre-opening expenses."),
+        ],
+    },
+    {
+        "type": "Operations Efficiency Analysis",
+        "subtitle": "Reducing Cost-Per-Order and Improving Kitchen Throughput",
+        "executive_summary": (
+            "An operational review of Casper's Kitchens ghost kitchen locations identified $1.2M–$1.8M "
+            "in annualized cost reduction opportunities through process optimization, scheduling improvements, "
+            "and waste reduction. This report presents 14 specific initiatives ranked by ease-of-implementation "
+            "and financial impact, with a 90-day implementation roadmap."
+        ),
+        "sections": [
+            ("Current State Assessment", "Average cost-per-order across locations: $8.40. Industry benchmark for comparable operations: $6.90–$7.50. Labor accounts for 34% of total costs vs. 28% benchmark. Food waste running at 8.2% of food cost vs. 4–5% best-in-class."),
+            ("Initiative 1 — Dynamic Labor Scheduling", "Implementing AI-driven scheduling to match labor hours to predicted order volume. Estimated savings: $180K–$240K annually. Payback period: 4 months. Risk: Low. Recommended tool: 7shifts or HotSchedules integration."),
+            ("Initiative 2 — Menu Rationalization", "Current 16-brand × ~45 item average = 720 active SKUs across locations. Analysis shows 30% of items generate 8% of revenue. Reducing to top-performing 12 items per brand estimated to reduce prep time by 18% and food waste by 31%."),
+            ("Initiative 3 — Batch Cooking Protocols", "Standardizing batch cooking windows for high-volume items (proteins, sauces) reduces cook-to-order time by 23% during peak hours. Estimated throughput increase: +2.4 orders/hour/kitchen."),
+            ("Initiative 4 — Supplier Consolidation", "Consolidating from 18 to 9 primary suppliers enables volume discounts of 6–11% on produce and proteins. Estimated savings: $95K–$140K annually. Also reduces receiving labor by 22%."),
+            ("Implementation Roadmap", "Days 1–30: Labor scheduling rollout, supplier consolidation RFP. Days 31–60: Menu rationalization pilot at San Francisco and Chicago. Days 61–90: Batch cooking SOP rollout, pilot measurement and scaling decision."),
+        ],
+    },
+    {
+        "type": "AI & Digital Transformation Roadmap",
+        "subtitle": "Accelerating Value Creation Through Intelligent Automation",
+        "executive_summary": (
+            "Casper's Kitchens is well-positioned to leverage artificial intelligence across demand forecasting, "
+            "customer experience personalization, and operational intelligence. This report outlines a phased "
+            "18-month AI transformation roadmap with projected ROI of 3.2x–4.8x on technology investment. "
+            "Priority use cases include predictive ordering, AI-driven refund resolution, and real-time "
+            "kitchen performance analytics."
+        ),
+        "sections": [
+            ("Current Technology Stack", "Current capabilities: Basic POS integration, manual demand forecasting, reactive customer service. Gaps: No predictive analytics, limited automation in complaint resolution, no unified data platform across locations."),
+            ("Phase 1 — Data Foundation (Months 1–4)", "Deploy a unified data lakehouse architecture (Databricks recommended) ingesting POS, delivery platform, and supplier data. Estimated investment: $280K–$340K. Output: Single source of truth for all operational metrics accessible within 24 hours."),
+            ("Phase 2 — Predictive Intelligence (Months 5–10)", "AI demand forecasting: Reduce food waste by 35–40% (estimated $220K–$310K annual savings). AI refund agent: Automate 68% of refund decisions, reducing resolution time from 4.2 hours to 8 minutes. Customer propensity models to personalize promotions."),
+            ("Phase 3 — Autonomous Operations (Months 11–18)", "Kitchen orchestration AI to auto-route orders based on real-time capacity. Predictive maintenance for equipment (reduce downtime by 45%). AI-generated supply chain reordering. Estimated Year 2 incremental EBITDA contribution: $1.4M–$2.1M."),
+            ("Build vs. Buy Recommendation", "Recommend a hybrid approach: Databricks platform (buy) + custom AI models (build on top). Avoid point-solution vendors in demand forecasting and refund automation — proprietary models trained on Casper's data will outperform generic SaaS by 30–50% within 6 months of training data accumulation."),
+            ("Investment & ROI Summary", "Total 18-month investment: $1.1M–$1.5M. Year 1 savings + revenue uplift: $680K–$890K. Year 2–3 annualized benefit: $2.2M–$3.1M. Blended 3-year ROI: 320–480%. Recommendation: PROCEED immediately with Phase 1 data foundation."),
+        ],
+    },
+    {
+        "type": "Workforce Management & Culture Report",
+        "subtitle": "Building a High-Performance Ghost Kitchen Workforce",
+        "executive_summary": (
+            "Staff turnover across Casper's Kitchens locations averages 84% annually — significantly above "
+            "the 72% food service industry average. This report identifies the root causes of attrition, "
+            "benchmarks compensation and culture practices, and recommends a 12-month Workforce Transformation "
+            "Program projected to reduce turnover to 55–60% and save $340K–$480K annually in recruiting and "
+            "training costs."
+        ),
+        "sections": [
+            ("Turnover Analysis", "Chicago location: 112% annual turnover (critical). San Francisco: 91%. Silicon Valley: 78%. Bellevue: 71% (best performer). Primary drivers: Scheduling unpredictability (cited by 61% of exit interviews), compensation gap vs. market (8–12% below), and limited advancement path."),
+            ("Compensation Benchmarking", "Current average kitchen staff hourly rate: $17.40. Market benchmark (Glassdoor, Indeed, LinkedIn data): $19.20–$21.50. Closing 50% of the gap (+$0.90–$1.80/hr) combined with performance bonuses estimated to reduce voluntary exits by 28%."),
+            ("Culture & Engagement Initiatives", "Recommended: Monthly all-hands per location (30 min, CEO video + local manager Q&A). Peer recognition program ('Kitchen MVP'). Transparent promotion pathways: Lead Cook → Kitchen Supervisor → Location Manager (3–18 months). Target: eNPS improvement from current -12 to +20 within 12 months."),
+            ("Training & Development", "Current: 8-hour onboarding. Recommended: 24-hour structured onboarding + 90-day buddy program. Cross-training across all 16 brands increases scheduling flexibility by 35% and reduces call-out impact. Annual training budget per FTE: increase from $180 to $420."),
+            ("Hiring & Onboarding Optimization", "Partner with local culinary schools in all 4 markets. Streamline application-to-offer timeline from 18 days to 7 days. Offer $500 signing bonus contingent on 90-day tenure. Pre-screen for tech-friendliness (order management systems)."),
+            ("Financial Impact", "Current annual turnover cost per employee (recruiting + training + productivity loss): $4,200. At 84% turnover on 120 FTE base: $423K/year. At 58% turnover post-program: $292K/year. Net saving: $131K/year. Combined with reduced training costs and productivity gains: $340K–$480K total annual benefit."),
+        ],
+    },
+]
+
+
+def _random_date(start: date, end: date) -> date:
+    delta = (end - start).days
+    return start + timedelta(days=random.randint(0, delta))
+
+
+def generate_consultancy_data() -> list[dict]:
+    reports = []
+    report_counter = 4001
+    period_start = date(2023, 6, 1)
+    period_end = date(2024, 3, 15)
+
+    for report_type in REPORT_TYPES:
+        num_reports = random.randint(2, 3)
+        for _ in range(num_reports):
+            loc = random.choice(LOCATIONS if len(reports) > 0 else [{"location_id": 0, "name": "All Locations (Corporate)", "address": "Corporate HQ"}])
+            report_date = _random_date(period_start, period_end)
+            firm = random.choice(CONSULTING_FIRMS)
+
+            reports.append({
+                "report_id": f"CON-{report_counter}",
+                "location_id": loc["location_id"],
+                "location_name": loc["name"],
+                "report_type": report_type["type"],
+                "subtitle": report_type["subtitle"],
+                "consulting_firm": firm,
+                "report_date": report_date.isoformat(),
+                "executive_summary": report_type["executive_summary"],
+                "sections": report_type["sections"],
+            })
+            report_counter += 1
+
+    return reports
+
+
+LOCATIONS = [
+    {"location_id": 0, "name": "All Locations (Corporate)", "address": "Corporate HQ"},
+    {"location_id": 1, "name": "San Francisco", "address": "1847 Market Street, San Francisco, CA 94103"},
+    {"location_id": 2, "name": "Silicon Valley", "address": "2350 El Camino Real, Santa Clara, CA 95051"},
+    {"location_id": 3, "name": "Bellevue", "address": "10456 NE 8th Street, Bellevue, WA 98004"},
+    {"location_id": 4, "name": "Chicago", "address": "872 N. Milwaukee Avenue, Chicago, IL 60642"},
+    {"location_id": 5, "name": "London", "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK"},
+    {"location_id": 6, "name": "Munich", "address": "Leopoldstrasse 75, 80802 Munich, Germany"},
+    {"location_id": 7, "name": "Amsterdam", "address": "Damrak 66, 1012 LM Amsterdam, Netherlands"},
+    {"location_id": 8, "name": "Vianen", "address": "Voorstraat 78, 4131 LW Vianen, Netherlands"},
+]
+
+
+class ConsultancyPDF(FPDF):
+    def __init__(self, firm: str):
+        super().__init__()
+        self.firm = firm
+        self.set_auto_page_break(auto=True, margin=22)
+
+    def header(self):
+        self.set_font("Helvetica", "B", 14)
+        self.cell(0, 8, self.firm.upper(), new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "", 9)
+        self.cell(0, 5, "Prepared exclusively for Casper's Kitchens Inc. -- Strictly Confidential", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.ln(2)
+        self.set_line_width(0.5)
+        self.line(10, self.get_y(), 200, self.get_y())
+        self.ln(4)
+
+    def footer(self):
+        self.set_y(-15)
+        self.set_font("Helvetica", "I", 7)
+        self.cell(0, 4, _safe(f"(c) {self.firm} -- Strictly Confidential. Not for Distribution."), new_x="LMARGIN", new_y="NEXT", align="C")
+        self.cell(0, 4, f"Page {self.page_no()}", align="C")
+
+
+METHODOLOGIES = {
+    "Market Expansion Strategy": (
+        "This engagement followed a structured four-phase methodology: (1) Data Collection -- 6 weeks of primary research "
+        "including 24 management interviews, proprietary delivery platform data analysis, and real estate market scanning "
+        "across 12 candidate markets; (2) Market Scoring -- quantitative scoring model applied across 7 weighted dimensions "
+        "including population density, delivery adoption rate, competitive density, average order value, real estate cost, "
+        "regulatory complexity, and supply chain accessibility; (3) Financial Modeling -- 3-year P&L modeling for each "
+        "Tier-1 market using Casper's current unit economics as the baseline; (4) Validation -- peer review of all "
+        "quantitative models by a senior partner and independent validation of market sizing data against third-party sources."
+    ),
+    "Operations Efficiency Analysis": (
+        "The operations review was conducted over a 5-week engagement period using the following methodology: "
+        "(1) Process Mapping -- time-and-motion studies conducted across all 8 locations (US + EMEA) during peak and off-peak hours; "
+        "(2) Benchmarking -- current performance compared against a proprietary database of 340+ food service operations; "
+        "(3) Root Cause Analysis -- structured interviews with 38 kitchen staff, shift supervisors, and location managers; "
+        "(4) Financial Analysis -- cost decomposition performed for each location to isolate labor, food cost, and overhead "
+        "contribution to the identified efficiency gap; (5) Initiative Prioritization -- 2x2 ease-impact matrix applied "
+        "to 22 candidate initiatives to identify highest-value actions."
+    ),
+    "AI & Digital Transformation Roadmap": (
+        "This roadmap was developed through a 7-week engagement using the following approach: "
+        "(1) Technology Audit -- assessment of current systems, data infrastructure, and integration capability; "
+        "(2) Use Case Identification -- structured workshops with senior leadership to identify and score 18 potential "
+        "AI use cases against value, feasibility, and strategic alignment criteria; (3) Market Intelligence -- review "
+        "of AI deployments at 12 comparable food service operators and 6 adjacent industries; (4) Build/Buy Analysis -- "
+        "detailed vendor landscape review and technical feasibility assessment for top-priority use cases; "
+        "(5) ROI Modeling -- financial modeling using conservative, base, and optimistic assumptions for each Phase."
+    ),
+    "Workforce Management & Culture Report": (
+        "This workforce assessment was completed over 6 weeks using the following methodology: "
+        "(1) Data Analysis -- review of 18 months of HR data including hiring volumes, tenure distributions, and "
+        "exit interview responses; (2) Benchmarking -- comparison of compensation, turnover, and engagement metrics "
+        "against food service industry data from the National Restaurant Association and proprietary firm databases; "
+        "(3) Employee Research -- anonymous pulse survey administered to 87 employees across all 8 locations (62% "
+        "response rate); (4) Leadership Interviews -- 14 structured interviews with location managers and corporate HR; "
+        "(5) Initiative Design -- recommendations co-developed with HR leadership to ensure implementation feasibility."
+    ),
+}
+
+KPI_FRAMEWORKS = {
+    "Market Expansion Strategy": [
+        ("New Market Revenue (Y1)", "$2.1M-$2.8M per location", "Monthly", "Finance / GM"),
+        ("EBITDA Contribution (Y2)", "$480K-$650K per location", "Monthly", "Finance"),
+        ("Market Penetration Rate", ">2.1% of addressable delivery orders", "Quarterly", "Strategy"),
+        ("Customer Acquisition Cost", "<$6.50 per active customer", "Monthly", "Marketing"),
+        ("Delivery Platform Ranking", "Top 10 in category by Month 6", "Weekly", "Operations"),
+    ],
+    "Operations Efficiency Analysis": [
+        ("Cost-Per-Order", "Target: $6.90-$7.50 (from $8.40 baseline)", "Weekly", "Operations"),
+        ("Food Waste %", "Target: <5% of food cost (from 8.2%)", "Weekly", "Kitchen Mgr"),
+        ("Order Throughput", ">+2.4 orders/hr during peak", "Daily", "Kitchen Mgr"),
+        ("Labor Cost %", "Target: 28-30% of revenue (from 34%)", "Bi-weekly", "Finance"),
+        ("Supplier On-Time Delivery", ">92% on-time (temp-compliant)", "Weekly", "Procurement"),
+    ],
+    "AI & Digital Transformation Roadmap": [
+        ("Demand Forecast Accuracy", ">88% within 10% variance", "Weekly", "Data/Analytics"),
+        ("Refund Resolution Time", "<8 minutes avg (from 4.2 hours)", "Daily", "Customer Ops"),
+        ("Food Waste Reduction", ">35% reduction from baseline", "Monthly", "Operations"),
+        ("AI Automation Rate", ">68% of eligible decisions automated", "Monthly", "Technology"),
+        ("Technology ROI", ">3.2x on investment by Month 24", "Quarterly", "Finance"),
+    ],
+    "Workforce Management & Culture Report": [
+        ("Annual Turnover Rate", "Target: 55-60% (from 84% baseline)", "Quarterly", "HR"),
+        ("eNPS Score", "Target: +20 or above (from -12)", "Quarterly", "HR"),
+        ("Time-to-Fill (Vacancies)", "Target: <7 days (from 18 days)", "Monthly", "HR"),
+        ("Training Completion Rate", ">95% of required certifications", "Monthly", "HR"),
+        ("90-Day Retention Rate", ">80% of new hires (from 62%)", "Monthly", "HR"),
+    ],
+}
+
+RISK_FACTORS = [
+    ("Implementation Pace Risk", "MEDIUM", "Recommended initiatives require cross-functional coordination. Recommend dedicated project management resource (0.5 FTE) and bi-weekly steering committee."),
+    ("Data Quality Risk", "MEDIUM", "Financial projections are sensitive to quality of underlying operational data. Recommend data audit prior to technology implementation phases."),
+    ("Market Condition Risk", "LOW-MEDIUM", "Macroeconomic factors including consumer discretionary spending and delivery platform commission structures may impact financial projections by +/-15%."),
+    ("Change Management Risk", "MEDIUM-HIGH", "Successful implementation requires buy-in from frontline staff and location managers. Structured change management program recommended."),
+    ("Competitive Response Risk", "LOW", "Identified expansion markets have moderate competitive density. Risk of established competitor price response is mitigated by Casper's multi-brand model."),
+    ("Regulatory Risk", "LOW", "No material regulatory changes anticipated in target markets within 18-month implementation horizon based on current legislative pipeline review."),
+]
+
+NEXT_STEPS = [
+    ("Week 1-2", "Present findings to senior leadership; obtain executive endorsement for recommended approach"),
+    ("Week 2-4", "Establish project governance: appoint executive sponsor, working group, and PMO lead"),
+    ("Month 1", "Kick off Phase 1 initiatives; establish baseline metrics against KPI framework"),
+    ("Month 2", "First steering committee review; assess early indicators; make go/no-go decision on Phase 2"),
+    ("Month 3", "Phase 1 completion review; refine Phase 2 plan based on learnings"),
+    ("Month 6", "Mid-point review of all initiatives; financial impact assessment vs. projected targets"),
+    ("Month 12", "Formal program review; present Year 1 outcomes to Board; plan Year 2 roadmap"),
+]
+
+
+def generate_pdf(report: dict) -> str:
+    pdf = ConsultancyPDF(report["consulting_firm"])
+    pdf.add_page()
+
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.set_fill_color(228, 228, 248)
+        pdf.cell(0, 7, _safe(f"  {title}"), new_x="LMARGIN", new_y="NEXT", fill=True)
+        pdf.set_line_width(0.3)
+        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
+        pdf.ln(2)
+
+    def para(text: str):
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(text), width=100):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Cover Block ──────────────────────────────────────────────────────────
+    pdf.set_fill_color(225, 225, 248)
+    pdf.rect(10, pdf.get_y(), 190, 26, "F")
+    pdf.set_font("Helvetica", "B", 14)
+    pdf.cell(0, 9, _safe(report["report_type"].upper()), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "I", 10)
+    pdf.cell(0, 6, _safe(report["subtitle"]), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "", 9)
+    pdf.cell(0, 5, _safe(f"Prepared by: {report['consulting_firm']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.cell(0, 5, _safe(f"Client: Casper's Kitchens Inc.  |  Date: {report['report_date']}  |  Report ID: {report['report_id']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.ln(5)
+
+    # ── Section 1: Executive Summary ─────────────────────────────────────────
+    section("I. EXECUTIVE SUMMARY")
+    para(report["executive_summary"])
+    para(
+        f"This report has been prepared by {report['consulting_firm']} following a structured engagement with "
+        f"Casper's Kitchens leadership. All findings, projections, and recommendations contained herein are "
+        f"based on data and analysis current as of {report['report_date']}. This document should be read in "
+        f"conjunction with the supporting appendices and data models provided to the client separately."
+    )
+
+    # ── Section 2: Methodology ────────────────────────────────────────────────
+    section("II. METHODOLOGY & APPROACH")
+    method_text = METHODOLOGIES.get(report["report_type"], METHODOLOGIES["Operations Efficiency Analysis"])
+    para(method_text)
+
+    # ── Section 3: Detailed Findings ─────────────────────────────────────────
+    section("III. DETAILED FINDINGS & ANALYSIS")
+    for i, (sec_title, sec_content) in enumerate(report["sections"], 1):
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(0, 6, _safe(f"  {i}. {sec_title}"), new_x="LMARGIN", new_y="NEXT")
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(sec_content), width=100):
+            pdf.cell(0, 5, f"    {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(2)
+
+    # ── Section 4: KPI Framework ──────────────────────────────────────────────
+    section("IV. KEY PERFORMANCE INDICATORS & SUCCESS METRICS")
+    para("The following KPI framework should be adopted to track progress against the recommendations in this report. Baseline measurements should be established within 30 days of engagement start.")
+    kpis = KPI_FRAMEWORKS.get(report["report_type"], KPI_FRAMEWORKS["Operations Efficiency Analysis"])
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(228, 228, 248)
+    pdf.cell(50, 6, "KPI", fill=True, border=1)
+    pdf.cell(45, 6, "Target", fill=True, border=1)
+    pdf.cell(25, 6, "Frequency", fill=True, border=1)
+    pdf.cell(0, 6, "Owner", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for kpi in kpis:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(50, 5.5, _safe(kpi[0]), fill=True, border=1)
+        pdf.cell(45, 5.5, _safe(kpi[1]), fill=True, border=1)
+        pdf.cell(25, 5.5, _safe(kpi[2]), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(kpi[3]), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+
+    # ── Section 5: Risk Analysis ──────────────────────────────────────────────
+    section("V. RISK ANALYSIS & MITIGATIONS")
+    para("The following risks have been identified in relation to the implementation of recommendations contained in this report. Each risk should be actively monitored and managed by the designated owner.")
+    selected_risks = random.sample(RISK_FACTORS, 4)
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(228, 228, 248)
+    pdf.cell(55, 6, "Risk", fill=True, border=1)
+    pdf.cell(25, 6, "Level", fill=True, border=1)
+    pdf.cell(0, 6, "Mitigation", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for r_name, r_level, r_mit in selected_risks:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(55, 5.5, _safe(r_name), fill=True, border=1)
+        pdf.cell(25, 5.5, _safe(r_level), fill=True, border=1)
+        mits = textwrap.wrap(_safe(r_mit), width=60)
+        pdf.cell(0, 5.5, mits[0] if mits else "", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        for extra_line in mits[1:]:
+            pdf.cell(80, 5.5, "", fill=True, border=0)
+            pdf.cell(0, 5.5, extra_line, fill=True, border=0, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+
+    # ── Section 6: Next Steps ─────────────────────────────────────────────────
+    section("VI. RECOMMENDED NEXT STEPS & IMPLEMENTATION TIMELINE")
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(228, 228, 248)
+    pdf.cell(35, 6, "Timeframe", fill=True, border=1)
+    pdf.cell(0, 6, "Action", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for timeframe, action in NEXT_STEPS:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(35, 5.5, _safe(timeframe), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(action), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+
+    # ── Section 7: Data Sources & Limitations ────────────────────────────────
+    section("VII. DATA SOURCES & LIMITATIONS")
+    sources = [
+        f"Internal Casper's Kitchens operational data provided by management for the period covered",
+        "National Restaurant Association 2023 State of the Industry Report",
+        "Delivery platform public disclosures and industry analyst estimates (Bloomberg Second Measure, YipitData)",
+        f"{report['consulting_firm']} proprietary benchmark database ({random.randint(280, 420)} comparable food service operations)",
+        "U.S. Census Bureau demographic data and Bureau of Labor Statistics employment data",
+        "Real estate market data: CoStar Group and CBRE Research",
+        "Management interviews and workshops conducted during the engagement period",
+    ]
+    pdf.set_font("Helvetica", "", 9)
+    for src in sources:
+        pdf.cell(0, 5, _safe(f"  - {src}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(2)
+    para(
+        f"LIMITATIONS: Financial projections are forward-looking statements subject to material uncertainty. "
+        f"Actual results may differ from projections due to market conditions, competitive actions, operational "
+        f"factors, and other variables not within the scope of this analysis. {report['consulting_firm']} "
+        f"makes no warranty as to the accuracy of projections and recommends sensitivity analysis before "
+        f"making material capital allocation decisions."
+    )
+
+    # ── Section 8: Disclaimer ─────────────────────────────────────────────────
+    section("VIII. DISCLAIMER & CONFIDENTIALITY")
+    para(
+        f"This report has been prepared by {report['consulting_firm']} exclusively for Casper's Kitchens Inc. "
+        f"and is strictly confidential. It may not be reproduced, distributed, or disclosed to any third party "
+        f"without the prior written consent of both {report['consulting_firm']} and Casper's Kitchens Inc. "
+        f"The analysis is based on information available as of {report['report_date']}. "
+        f"{report['consulting_firm']} has relied upon information provided by Casper's Kitchens without "
+        f"independent verification. This report does not constitute legal, tax, accounting, or investment advice."
+    )
+
+    # ── Signature Block ───────────────────────────────────────────────────────
+    pdf.ln(8)
+    pdf.set_line_width(0.3)
+    pdf.line(10, pdf.get_y(), 100, pdf.get_y())
+    pdf.ln(3)
+    pdf.set_font("Helvetica", "", 9)
+    pdf.cell(0, 5, _safe(f"Managing Director, {report['consulting_firm']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(report["report_date"]), new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.cell(0, 5, _safe(f"(c) {report['consulting_firm']} -- Strictly Confidential. Not for Distribution."), new_x="LMARGIN", new_y="NEXT")
+
+    safe_id = report["report_id"].replace("-", "_").lower()
+    out_path = PDF_DIR / f"consultancy_{safe_id}.pdf"
+    pdf.output(str(out_path))
+    return str(out_path)
+
+
+def main():
+    PDF_DIR.mkdir(parents=True, exist_ok=True)
+    reports = generate_consultancy_data()
+
+    for r in reports:
+        path = generate_pdf(r)
+        print(f"  Generated: {path}")
+
+    with open(METADATA_PATH, "w") as f:
+        json.dump({"reports": reports, "locations": LOCATIONS}, f, indent=2)
+    print(f"  Metadata: {METADATA_PATH}")
+    print(f"\nDone! Generated {len(reports)} consultancy reports.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/data/consultancy/pdfs/consultancy_con_4001.pdf b/data/consultancy/pdfs/consultancy_con_4001.pdf
new file mode 100644
index 0000000..196a0d2
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4001.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4002.pdf b/data/consultancy/pdfs/consultancy_con_4002.pdf
new file mode 100644
index 0000000..6afbee1
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4002.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4003.pdf b/data/consultancy/pdfs/consultancy_con_4003.pdf
new file mode 100644
index 0000000..9a44cf9
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4003.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4004.pdf b/data/consultancy/pdfs/consultancy_con_4004.pdf
new file mode 100644
index 0000000..06d5ff2
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4004.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4005.pdf b/data/consultancy/pdfs/consultancy_con_4005.pdf
new file mode 100644
index 0000000..0722f2c
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4005.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4006.pdf b/data/consultancy/pdfs/consultancy_con_4006.pdf
new file mode 100644
index 0000000..0a20326
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4006.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4007.pdf b/data/consultancy/pdfs/consultancy_con_4007.pdf
new file mode 100644
index 0000000..24273db
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4007.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4008.pdf b/data/consultancy/pdfs/consultancy_con_4008.pdf
new file mode 100644
index 0000000..1356e68
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4008.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4009.pdf b/data/consultancy/pdfs/consultancy_con_4009.pdf
new file mode 100644
index 0000000..6e49398
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4009.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4010.pdf b/data/consultancy/pdfs/consultancy_con_4010.pdf
new file mode 100644
index 0000000..fd2f485
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4010.pdf differ
diff --git a/data/consultancy/pdfs/consultancy_con_4011.pdf b/data/consultancy/pdfs/consultancy_con_4011.pdf
new file mode 100644
index 0000000..f8cb408
Binary files /dev/null and b/data/consultancy/pdfs/consultancy_con_4011.pdf differ
diff --git a/data/dimensional/brands.parquet b/data/dimensional/brands.parquet
deleted file mode 100644
index 45e5972..0000000
Binary files a/data/dimensional/brands.parquet and /dev/null differ
diff --git a/data/dimensional/categories.parquet b/data/dimensional/categories.parquet
deleted file mode 100644
index a008d10..0000000
Binary files a/data/dimensional/categories.parquet and /dev/null differ
diff --git a/data/dimensional/items.parquet b/data/dimensional/items.parquet
deleted file mode 100644
index 1ccbcb4..0000000
Binary files a/data/dimensional/items.parquet and /dev/null differ
diff --git a/data/dimensional/menus.parquet b/data/dimensional/menus.parquet
deleted file mode 100644
index 060bb8c..0000000
Binary files a/data/dimensional/menus.parquet and /dev/null differ
diff --git a/data/generator/configs/README.md b/data/generator/configs/README.md
deleted file mode 100644
index b471e70..0000000
--- a/data/generator/configs/README.md
+++ /dev/null
@@ -1,240 +0,0 @@
-# Location Configuration Guide
-
-This directory contains JSON configuration files that define ghost kitchen locations for simulation. Each JSON file represents one location and its simulation parameters.
-
-## Quick Start
-
-**To add a new location:**
-1. Copy `sanfrancisco.json` as your template
-2. Update the location-specific parameters (see below)
-3. Save with a descriptive name (e.g., `chicago.json`, `nyc.json`)
-
-**To select which locations to run:**
-
-By default, only San Francisco runs when you execute the Casper's Initializer job. You can control which locations are generated using the `LOCATIONS` parameter in the job. Set this parameter in the **Casper's Initializer job UI** under Parameters when running the job.
-
-Examples:
-- `sanfrancisco.json` - Run only San Francisco (default)
-- `chicago.json` - Run only Chicago
-- `nyc.json` - Run only your custom NYC config
-- `sanfrancisco.json,chicago.json` - Run multiple locations (comma-separated)
-- `all` - Run all available location configs in this directory
-
-This works for any `.json` files you create in this directory - just specify the filename(s) in the `LOCATIONS` parameter.
-
-**Important:** All `.json` files in this directory are discovered automatically, but only those specified in the `LOCATIONS` parameter will run. Use a different extension (e.g., `.json.template`) if you want example configs that shouldn't be available for selection.
-
-## Configuration Parameters
-
-### Simulation Window
-
-Controls the time range and speed of data generation:
-
-- **`start_days_ago`** (integer): Number of days of historical data to generate
-  - Example: `3` starts the simulation 3 days in the past
-  - Historical data is generated in one batch at startup
-
-- **`end_days_ahead`** (integer): Number of days into the future to simulate
-  - Example: `362` runs for approximately 1 year
-  - Set to `0` for historical data only (no ongoing simulation)
-
-- **`speed_up`** (number): Time acceleration multiplier
-  - `1` = real-time (1 simulated hour = 1 real hour)
-  - `60` = 1 hour of orders generated per real minute
-  - `1000` = ~6 weeks compressed into 1 real hour
-  - Higher values = faster data generation, useful for creating static datasets quickly
-
-### Order Volume
-
-Controls how many orders are generated over time:
-
-- **`orders_day_1`** (number): Orders per day at the start of simulation
-  - This is the baseline - actual volume varies by day of week and noise
-
-- **`orders_last`** (number): Orders per day at the end of simulation
-  - Volume grows linearly from `orders_day_1` to `orders_last`
-  - Set equal to `orders_day_1` for constant volume
-
-- **`noise_pct`** (number): Random daily variation percentage
-  - Example: `10` adds ±10% random noise to daily order volume
-  - Applied via `random.uniform(1-noise, 1+noise)`
-
-**Day of week multipliers** (hardcoded in generator):
-- Monday: 1.0x, Tuesday: 1.05x, Wednesday: 1.08x, Thursday: 1.10x
-- Friday: 1.25x, Saturday: 1.35x, Sunday: 1.15x
-
-**Intraday patterns** (hardcoded):
-- Lunch peak: 11:00-13:30 (3x baseline)
-- Dinner peak: 17:00-20:00 (3.5x baseline)
-
-### Service Times
-
-The `svc` object defines timing for each stage of order fulfillment. Each stage is specified as `[mean, std_dev]` in minutes, using a Gaussian distribution (minimum 0.1 minutes):
-
-- **`cs`**: Customer order placed → Kitchen starts cooking
-  - Queue/prep time before cooking begins
-
-- **`sf`**: Kitchen starts → Kitchen finishes cooking
-  - Actual cooking time
-
-- **`fr`**: Kitchen finishes → Order ready for pickup
-  - Packaging and staging time
-
-- **`rp`**: Order ready → Driver picks up
-  - Time between ready and actual pickup (driver wait time)
-
-Example:
-```json
-"svc": {
-  "cs": [2, 1],   // 2 min average queue, 1 min std dev
-  "sf": [10, 3],  // 10 min cook time, 3 min variation
-  "fr": [2, 1],   // 2 min packaging
-  "rp": [6, 2]    // 6 min driver wait
-}
-```
-
-These times generate the following events per order:
-1. `order_created` (at t=0)
-2. `gk_started` (after cs delay)
-3. `gk_finished` (after sf delay)
-4. `gk_ready` (after fr delay)
-5. `driver_arrived` (sampled between order creation and pickup)
-6. `driver_picked_up` (after rp delay from ready)
-7. `driver_ping` events (during delivery, frequency controlled by `ping_sec`)
-8. `delivered` (after driving time based on route distance and `driver_mph`)
-
-### Driver Behavior
-
-Controls when drivers arrive and how they navigate:
-
-- **`driver_arrival`** (object): Timing of driver arrival relative to food being ready
-  - **`alpha`** and **`beta`**: Shape parameters for Beta distribution
-    - Default `[3, 3]` creates a symmetric bell curve
-  - **`after_ready_pct`**: Probability driver arrives after food is ready
-    - Example: `0.5` means 50% of drivers arrive after food is ready
-    - The other 50% arrive between order creation and ready time
-  - Driver arrival time is sampled from a Beta distribution within these windows
-
-- **`driver_mph`** (number): Average driver speed for route calculations
-  - Used to calculate delivery time from route distance
-  - Example: `25` means 25 miles per hour average speed
-
-### Brand Dynamics
-
-Controls how brand popularity changes over time:
-
-- **`brand_momentum`** (object): Distribution of brands across performance categories
-  - **`improving`**: Fraction of brands with growing sales
-  - **`flat`**: Fraction with stable sales
-  - **`declining`**: Fraction with declining sales
-  - Must sum to 1.0
-  - Example: `{"improving": 0.1, "flat": 0.2, "declining": 0.7}`
-    - 10% of brands improving, 20% flat, 70% declining
-
-- **`momentum_rates`** (object): Rate of change for non-flat brands
-  - **`growth`**: Daily compound growth rate for improving brands
-    - Example: `0.8` = 0.8% daily growth
-  - **`decline`**: Daily compound decline rate for declining brands
-    - Example: `0.2` = 0.2% daily decline
-  - Rates are compounded monthly: `(1 ± rate)^(day/30)`
-
-Brand momentum affects basket selection - improving brands are more likely to be chosen.
-
-### Location Details
-
-Defines the ghost kitchen's geographic location and service area:
-
-- **`gk_location`** (string): Full address or intersection for the ghost kitchen
-  - Used by OpenStreetMap/OSMnx to download real road network
-  - Examples:
-    - `"5th Avenue & 42nd Street, New York, NY"`
-    - `"1600 Amphitheatre Parkway, Mountain View, CA"`
-  - Must be geocodable by OSMnx (uses Nominatim)
-
-- **`location_name`** (string): Short identifier for this location
-  - Appears in the `location` field of all events
-  - Used for filtering/grouping in downstream analytics
-  - Example: `"san_francisco"`, `"chicago_loop"`
-
-- **`radius_mi`** (number): Delivery service area radius in miles
-  - Used to download road network around ghost kitchen
-  - Customers are sampled from nodes within this radius
-  - Converted to meters (× 1609.34) for OSMnx
-
-**Road network details:**
-- Graph is downloaded once at startup and cached
-- Only nodes in the same connected component as the ghost kitchen are used
-- Routing uses NetworkX shortest path with real road lengths
-- Customer addresses are matched to building footprints with real street addresses from OpenStreetMap
-
-### Technical Parameters
-
-Control batch writing and GPS tracking granularity:
-
-- **`batch_rows`** (integer): Number of events to accumulate before writing to volume
-  - Higher values = fewer, larger files
-  - Lower values = more frequent writes, more granular streaming
-
-- **`batch_seconds`** (number): Maximum seconds to wait before flushing batch
-  - Even if `batch_rows` isn't reached, batch is flushed after this time
-  - Prevents delays during low-volume periods
-
-- **`ping_sec`** (integer): Frequency of GPS pings during delivery (in seconds)
-  - Example: `60` = one GPS ping per minute during delivery
-  - Lower values = more granular driver tracking, more events
-  - Number of pings = `floor(delivery_time_minutes * 60 / ping_sec)`
-
-- **`random_seed`** (integer): Seed for random number generation
-  - Same seed + same config = identical simulation results
-  - Useful for reproducible demos or testing
-  - Seeds both Python's `random` and NumPy's `np.random`
-
-### Data Quality Issues
-
-Optional injection of data quality problems for testing:
-
-- **`dq`** (object): Dictionary mapping event types to field corruption rates
-  - Currently used by `maybe_corrupt()` function
-  - Each field can have a probability of being set to `null`
-  - Example: `{"order_created": {"customer_lat": 0.1}}` would null out latitude in 10% of order_created events
-  - Usually left as empty object: `{}`
-
-## Example: Creating a Chicago Location
-
-```json
-{
-  "start_days_ago": 1,
-  "end_days_ahead": 30,
-  "speed_up": 60,
-  "orders_day_1": 75,
-  "orders_last": 150,
-  "noise_pct": 12,
-  "svc": {
-    "cs": [3, 1.5],
-    "sf": [12, 4],
-    "fr": [2, 1],
-    "rp": [8, 3]
-  },
-  "driver_arrival": {"alpha": 3, "beta": 3, "after_ready_pct": 0.5},
-  "brand_momentum": {"improving": 0.15, "flat": 0.25, "declining": 0.6},
-  "momentum_rates": {"growth": 0.8, "decline": 0.2},
-  "dq": {},
-  "gk_location": "Michigan Avenue & Randolph Street, Chicago, IL",
-  "location_name": "chicago",
-  "radius_mi": 5,
-  "driver_mph": 22,
-  "batch_rows": 10,
-  "batch_seconds": 1,
-  "ping_sec": 60,
-  "random_seed": 42
-}
-```
-
-## Output Format
-
-Events are written as JSON files to the configured volume:
-- Location: `/Volumes/{CATALOG}/{SCHEMA}/{VOLUME}/`
-- Format: `YYYYMMDD-HHMMSS.ffffff-{event_id}.json` (for real-time events)
-- Format: `YYYYMMDD-HHMMSS.ffffff.json` (for batches)
-- Each event has: `event_id`, `event_type`, `ts`, `gk_id`, `location`, `order_id`, `sequence`, `body`
-- Body is JSON-encoded string with event-specific payload
diff --git a/data/generator/configs/chicago.json b/data/generator/configs/chicago.json
deleted file mode 100644
index 444f813..0000000
--- a/data/generator/configs/chicago.json
+++ /dev/null
@@ -1,49 +0,0 @@
-{
-    "start_days_ago": 3,
-    "end_days_ahead": 362,
-    "speed_up": 1,
-    "orders_day_1": 60,
-    "orders_last": 950,
-    "noise_pct": 10,
-    "svc": {
-        "cs": [
-            2,
-            1
-        ],
-        "sf": [
-            11,
-            3
-        ],
-        "fr": [
-            2,
-            1
-        ],
-        "rp": [
-            5,
-            2
-        ]
-    },
-    "driver_arrival": {
-        "alpha": 3,
-        "beta": 3,
-        "after_ready_pct": 0.5
-    },
-    "brand_momentum": {
-        "improving": 0.1,
-        "flat": 0.2,
-        "declining": 0.7
-    },
-    "momentum_rates": {
-        "growth": 0.8,
-        "decline": 0.2
-    },
-    "dq": {},
-    "gk_location": "311 W Monroe St, Chicago, IL 60606",
-    "location_name": "chicago",
-    "radius_mi": 3.5,
-    "driver_mph": 22,
-    "batch_rows": 10,
-    "batch_seconds": 1,
-    "ping_sec": 60,
-    "random_seed": 42
-}
diff --git a/data/generator/configs/sanfrancisco.json b/data/generator/configs/sanfrancisco.json
deleted file mode 100644
index ac2f3c3..0000000
--- a/data/generator/configs/sanfrancisco.json
+++ /dev/null
@@ -1,49 +0,0 @@
-{
-    "start_days_ago": 3,
-    "end_days_ahead": 362,
-    "speed_up": 1,
-    "orders_day_1": 50,
-    "orders_last": 1000,
-    "noise_pct": 10,
-    "svc": {
-        "cs": [
-            2,
-            1
-        ],
-        "sf": [
-            10,
-            3
-        ],
-        "fr": [
-            2,
-            1
-        ],
-        "rp": [
-            6,
-            2
-        ]
-    },
-    "driver_arrival": {
-        "alpha": 3,
-        "beta": 3,
-        "after_ready_pct": 0.5
-    },
-    "brand_momentum": {
-        "improving": 0.1,
-        "flat": 0.2,
-        "declining": 0.7
-    },
-    "momentum_rates": {
-        "growth": 0.8,
-        "decline": 0.2
-    },
-    "dq": {},
-    "gk_location": "160 Spear St, San Francisco, CA 94105",
-    "location_name": "sanfrancisco",
-    "radius_mi": 4,
-    "driver_mph": 25,
-    "batch_rows": 10,
-    "batch_seconds": 1,
-    "ping_sec": 60,
-    "random_seed": 72
-}
\ No newline at end of file
diff --git a/data/generator/generator.ipynb b/data/generator/generator.ipynb
deleted file mode 100644
index 8d55201..0000000
--- a/data/generator/generator.ipynb
+++ /dev/null
@@ -1,577 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "201d7b57-5c79-4436-905e-a4f350a032cf",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%pip install osmnx==1.7.1 networkx==3.2.1 geopy==2.4.1 shapely==2.0.3 databricks-sdk[openai]>=0.35.0"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "4b2fa429-b8bc-4fbc-9d7c-a258ae9b71e6",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "\n",
-    "SIM_CFG = json.loads(dbutils.widgets.get(\"SIM_CFG_JSON\"))\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "SCHEMA = dbutils.widgets.get(\"SCHEMA\")\n",
-    "VOLUME = dbutils.widgets.get(\"VOLUME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "256edeef-7673-4be4-ae1b-a59e5ca4df85",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "# ╔═══════════════════════════════════════════════════════════════════════╗\n",
-    "# ║  Ghost-Kitchen Event Simulator 2.1  →  Delta table                    ║\n",
-    "# ╚═══════════════════════════════════════════════════════════════════════╝\n",
-    "#\n",
-    "#  All tunables live in SIM_CFG  – supply as a JSON widget or edit below\n",
-    "# ------------------------------------------------------------------------\n",
-    "\n",
-    "import asyncio, datetime as dt, json, math, pickle, random, time, uuid\n",
-    "from pathlib import Path\n",
-    "from typing import Dict, List, Tuple\n",
-    "\n",
-    "import nest_asyncio, networkx as nx, numpy as np, osmnx as ox, pandas as pd\n",
-    "from pyspark.sql import SparkSession, functions as F\n",
-    "\n",
-    "from datetime import datetime\n",
-    "import json\n",
-    "\n",
-    "nest_asyncio.apply()\n",
-    "spark = SparkSession.builder.getOrCreate()\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 0.  CONFIGURATION                                                      │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "CFG = SIM_CFG; get = lambda k: CFG[k]\n",
-    "RAND = random.Random(get(\"random_seed\")); np.random.seed(get(\"random_seed\"))\n",
-    "\n",
-    "now = dt.datetime.utcnow()\n",
-    "START_TS = now - dt.timedelta(days=get(\"start_days_ago\"))\n",
-    "END_TS   = now + dt.timedelta(days=get(\"end_days_ahead\"))\n",
-    "SPEED_UP               = get(\"speed_up\")\n",
-    "GK_ADDRESS, GK_R_MI    = get(\"gk_location\"), get(\"radius_mi\")\n",
-    "LOC_NAME               = get(\"location_name\")\n",
-    "GK_DRIVER_MPH          = get(\"driver_mph\")\n",
-    "NOISE, SVC             = get(\"noise_pct\")/100, get(\"svc\")\n",
-    "BATCH_ROWS, BATCH_SEC  = get(\"batch_rows\"), get(\"batch_seconds\")\n",
-    "PING_SEC               = get(\"ping_sec\")\n",
-    "VOLUME_PATH = f\"/Volumes/{CATALOG}/{SCHEMA}/{VOLUME}/\"\n",
-    "VOLUME_DIR  = Path(VOLUME_PATH).expanduser()   \n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 1.  ROAD GRAPH + NODES                                     │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "\n",
-    "# ─── NEW imports (all come with osmnx’s deps) ────────────────────────────\n",
-    "import geopandas as gpd\n",
-    "from shapely.geometry import Point\n",
-    "\n",
-    "# ─── Bulk-address cache (lazy-loaded once per run) ───────────────────────\n",
-    "_BUILDINGS = None  # GeoDataFrame cache\n",
-    "\n",
-    "def load_buildings() -> gpd.GeoDataFrame:\n",
-    "    \"\"\"\n",
-    "    Grab all building polygons that already have addr:housenumber + addr:street\n",
-    "    tags inside the simulator’s radius.  No external HTTP calls after this.\n",
-    "    \"\"\"\n",
-    "    global _BUILDINGS\n",
-    "    if _BUILDINGS is not None:           # reuse if we already fetched\n",
-    "        return _BUILDINGS\n",
-    "\n",
-    "    center_pt = ox.geocoder.geocode(GK_ADDRESS)\n",
-    "    tags = {\"addr:housenumber\": True, \"addr:street\": True}\n",
-    "\n",
-    "    # One Overpass query → GeoDataFrame of footprints with address tags\n",
-    "    bldgs = ox.geometries_from_point(center_pt,\n",
-    "                                     dist=GK_R_MI * 1609.34,\n",
-    "                                     tags=tags)\n",
-    "\n",
-    "    # Keep only rows that really have both tags\n",
-    "    bldgs = bldgs.dropna(subset=[\"addr:housenumber\", \"addr:street\"])\n",
-    "    # footprints are Polygons; centroids are fine for nearest-search\n",
-    "    bldgs = bldgs.to_crs(\"EPSG:4326\")  # ensure same CRS as nodes\n",
-    "    _BUILDINGS = bldgs[[\"addr:housenumber\", \"addr:street\", \"geometry\"]]\n",
-    "    return _BUILDINGS\n",
-    "\n",
-    "# ─── Replacement for load_nodes() ───────────────────────────────────────\n",
-    "def load_nodes(g: nx.MultiDiGraph) -> pd.DataFrame:\n",
-    "    \"\"\"\n",
-    "    Return DataFrame with real lat/ lon and best available street address.\n",
-    "    Works offline after the initial Overpass pull inside load_buildings().\n",
-    "    \"\"\"\n",
-    "    # ---- 1. Nodes → GeoDataFrame ---------------------------------------\n",
-    "    node_rows = []\n",
-    "    for nid, data in g.nodes(data=True):\n",
-    "        lat, lon = data[\"y\"], data[\"x\"]\n",
-    "        node_rows.append({\"node_id\": nid,\n",
-    "                          \"lat\": lat,\n",
-    "                          \"lon\": lon,\n",
-    "                          \"geometry\": Point(lon, lat)})\n",
-    "    gdf_nodes = gpd.GeoDataFrame(node_rows, crs=\"EPSG:4326\")\n",
-    "\n",
-    "    # ---- 2. Spatial join: nearest addressed footprint ------------------\n",
-    "    bldgs = load_buildings()                       # cached after first call\n",
-    "    joined = gpd.sjoin_nearest(\n",
-    "        gdf_nodes, bldgs,\n",
-    "        how=\"left\",\n",
-    "        distance_col=\"addr_dist_m\"                 # keep for curiosity\n",
-    "    )\n",
-    "\n",
-    "    # ---- 3. Build final rows with fallback for empties -----------------\n",
-    "    rows = []\n",
-    "    for _, r in joined.iterrows():\n",
-    "        if pd.notna(r[\"addr:housenumber\"]) and pd.notna(r[\"addr:street\"]):\n",
-    "            label = f\"{r['addr:housenumber']} {r['addr:street']}\"\n",
-    "        else:\n",
-    "            label = f\"{RAND.randint(1, 9999)} Main St\"\n",
-    "        rows.append(dict(node_id=int(r[\"node_id\"]),\n",
-    "                         lat=r[\"lat\"],\n",
-    "                         lon=r[\"lon\"],\n",
-    "                         addr=label))\n",
-    "    return pd.DataFrame(rows)\n",
-    "\n",
-    "def load_graph() -> nx.MultiDiGraph:\n",
-    "    ox.settings.log_console = False\n",
-    "    g = ox.graph_from_point(ox.geocoder.geocode(GK_ADDRESS),\n",
-    "                            dist=GK_R_MI*1609.34, network_type=\"drive\")\n",
-    "    return g\n",
-    "\n",
-    "GRAPH = load_graph(); NODES = load_nodes(GRAPH)\n",
-    "GK_LAT, GK_LON = ox.geocoder.geocode(GK_ADDRESS)\n",
-    "GK_NODE = ox.distance.nearest_nodes(GRAPH, GK_LON, GK_LAT)\n",
-    "comp_map = {n:cid for cid,comp in enumerate(nx.connected_components(GRAPH.to_undirected())) for n in comp}\n",
-    "NODES = NODES[NODES.node_id.map(comp_map)==comp_map[GK_NODE]].reset_index(drop=True)\n",
-    "def rand_customer():\n",
-    "    r = NODES.sample(1, random_state=RAND.randrange(2**32)).iloc[0]  # ✔\n",
-    "    return int(r.node_id), r.lat, r.lon, r.addr\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 2.  MENU + BRAND MOMENTUM                                              │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "ITEMS_DF = spark.read.table(f\"{CATALOG}.{SCHEMA}.items\").toPandas()\n",
-    "ITEMS_BY_BRAND = {bid: grp.to_dict(\"records\") for bid, grp in ITEMS_DF.groupby(\"brand_id\")}\n",
-    "BRANDS = list(ITEMS_BY_BRAND); RAND.shuffle(BRANDS)\n",
-    "\n",
-    "bm = get(\"brand_momentum\"); cuts = np.cumsum([bm[\"improving\"], bm[\"flat\"]])*len(BRANDS)\n",
-    "IMPR, FLAT, DECL = BRANDS[:int(cuts[0])], BRANDS[int(cuts[0]):int(cuts[1])], BRANDS[int(cuts[1]):]\n",
-    "rates = get(\"momentum_rates\")\n",
-    "\n",
-    "def brand_weight(day, total, b):\n",
-    "    if b in IMPR:  f = (1+rates[\"growth\"])**(day/30)\n",
-    "    elif b in DECL: f = (1-rates[\"decline\"])**(day/30)\n",
-    "    else:          f = 1.0\n",
-    "    return f\n",
-    "\n",
-    "def rand_basket(day, total, p_single=0.7, max_brands=4, items_rng=(1,4)):\n",
-    "    w = np.array([brand_weight(day,total,b) for b in BRANDS]); w = w/w.sum()\n",
-    "    chosen = [RAND.choices(BRANDS, weights=w, k=1)[0]] if RAND.random()<p_single \\\n",
-    "             else RAND.choices(BRANDS, weights=w, k=RAND.randint(2,max_brands))\n",
-    "    items=[]\n",
-    "    for b in chosen:\n",
-    "        for itm in RAND.sample(ITEMS_BY_BRAND[b], RAND.randint(*items_rng)):\n",
-    "            rec = itm.copy(); rec[\"qty\"] = RAND.randint(1,3); items.append(rec)\n",
-    "    return items\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 3.  DEMAND SHAPE                                                       │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "def minute_weights():\n",
-    "    w = np.ones(1440)\n",
-    "    for s,e,m in [(\"11:00\",\"13:30\",3), (\"17:00\",\"20:00\",3.5)]:\n",
-    "        s_dt,e_dt = [dt.datetime.strptime(x,\"%H:%M\") for x in (s,e)]\n",
-    "        s_m,e_m = s_dt.hour*60+s_dt.minute, e_dt.hour*60+e_dt.minute; span=e_m-s_m\n",
-    "        for mi in range(s_m,e_m):\n",
-    "            x = (mi-s_m)/span; w[mi] += (m-1)*(math.sin(math.pi*x)**2)\n",
-    "    return w\n",
-    "MIN_W = minute_weights()\n",
-    "\n",
-    "def orders_today(d, total, date):\n",
-    "    base = CFG[\"orders_day_1\"]+(CFG[\"orders_last\"]-CFG[\"orders_day_1\"])*(d/total)\n",
-    "    wd = {\"mon\":1,\"tue\":1.05,\"wed\":1.08,\"thu\":1.10,\"fri\":1.25,\"sat\":1.35,\"sun\":1.15}[date.strftime(\"%a\").lower()]\n",
-    "    return base*wd*RAND.uniform(1-NOISE,1+NOISE)\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 4.  ROUTING                                                            │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "def shortest_route(lat,lon):\n",
-    "    cust = ox.distance.nearest_nodes(GRAPH, lon, lat)\n",
-    "    try:\n",
-    "        path = nx.shortest_path(GRAPH, GK_NODE, cust, weight=\"length\"); g = GRAPH\n",
-    "    except nx.NetworkXNoPath:\n",
-    "        g = GRAPH.to_undirected(); path = nx.shortest_path(g, GK_NODE, cust, weight=\"length\")\n",
-    "    coords = [(g.nodes[n][\"y\"], g.nodes[n][\"x\"]) for n in path]\n",
-    "    dist = sum(min(d[\"length\"] for d in g[u][v].values()) for u,v in zip(path[:-1],path[1:]))\n",
-    "    return coords, dist\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 5.  JSON WRITER (flat directory, no date partitions)\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "def write_event_json(row: Dict):\n",
-    "    \"\"\"\n",
-    "    Save each event in a single, flat directory:\n",
-    "        {json_dir}/<ts>-<event_id>.json\n",
-    "    \"\"\"\n",
-    "    ts = dt.datetime.strptime(row[\"ts\"], \"%Y-%m-%d %H:%M:%S.%f\")\n",
-    "    fname = f\"{ts:%Y%m%d-%H%M%S.%f}-{row['event_id']}.json\"\n",
-    "    (VOLUME_DIR / fname).write_text(json.dumps(row))\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 5.  DELTA WRITER + DATA-QUALITY                                        │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "EVENT_Q = asyncio.PriorityQueue(); CNT = 0\n",
-    "GK_ID = uuid.uuid4().hex; DQ = get(\"dq\")\n",
-    "\n",
-    "def maybe_corrupt(ev, payload):\n",
-    "    dq = DQ.get(ev, {}); return {k:(None if RAND.random()<dq.get(k,0) else v) for k,v in payload.items()}\n",
-    "\n",
-    "def enqueue(ts, ev, oid, seq, payload):\n",
-    "    global CNT; CNT += 1\n",
-    "    EVENT_Q.put_nowait((ts.timestamp(), CNT, {\n",
-    "        \"event_id\": uuid.uuid4().hex,\n",
-    "        \"event_type\": ev,\n",
-    "        \"ts\": ts.strftime(\"%Y-%m-%d %H:%M:%S.%f\"),\n",
-    "        \"gk_id\": GK_ID,\n",
-    "        \"location\": LOC_NAME,\n",
-    "        \"order_id\": oid,\n",
-    "        \"sequence\": seq,\n",
-    "        \"body\": json.dumps(maybe_corrupt(ev, payload))\n",
-    "    }))\n",
-    "\n",
-    "def flush(rows):\n",
-    "    if not rows: return\n",
-    "    ts = dt.datetime.now()                               \n",
-    "    fname = ts.strftime(\"%Y%m%d-%H%M%S.%f\") + \".json\"\n",
-    "    (VOLUME_DIR / fname).write_text(json.dumps(rows))\n",
-    "\n",
-    "async def consumer():\n",
-    "    buf,last=[],time.time()\n",
-    "    while True:\n",
-    "        _,_,row = await EVENT_Q.get(); buf.append(row)\n",
-    "        if len(buf)>=BATCH_ROWS or (time.time()-last)>=BATCH_SEC:\n",
-    "            flush(buf); buf.clear(); last=time.time()\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 6.  ORDER LIFECYCLE (real-time)                                        │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "MICRO = lambda n: dt.timedelta(microseconds=n)\n",
-    "def gauss(mu_sigma): return max(0.1, RAND.gauss(*mu_sigma))\n",
-    "\n",
-    "driver_cfg = get(\"driver_arrival\")\n",
-    "def driver_arrival_time(created_at, t_ready, t_pick):\n",
-    "    \"\"\"Return a dt between created_at and t_pick with prob mass after ready.\"\"\"\n",
-    "    if RAND.random() < driver_cfg[\"after_ready_pct\"]:\n",
-    "        base, span = t_ready, (t_pick - t_ready)\n",
-    "    else:\n",
-    "        base, span = created_at, (t_ready - created_at)\n",
-    "    frac = np.random.beta(driver_cfg[\"alpha\"], driver_cfg[\"beta\"])\n",
-    "    t_arr = base + span * frac\n",
-    "    if t_arr >= t_pick:  # safety: keep strict order\n",
-    "        t_arr = t_pick - MICRO(1)\n",
-    "    return t_arr\n",
-    "\n",
-    "async def play_order(created_at, day, total):\n",
-    "    oid=uuid.uuid4().hex; seq=0\n",
-    "    _,lat,lon,addr = rand_customer(); items = rand_basket(day,total)\n",
-    "    pts,dist = shortest_route(lat,lon); drive_min = dist/1609.34/GK_DRIVER_MPH*60\n",
-    "\n",
-    "    t_cs  = created_at + dt.timedelta(minutes=gauss(SVC[\"cs\"]))\n",
-    "    t_sf  = t_cs + dt.timedelta(minutes=gauss(SVC[\"sf\"]))\n",
-    "    t_fr  = t_sf + dt.timedelta(minutes=gauss(SVC[\"fr\"]))\n",
-    "    t_ready = t_fr\n",
-    "    t_pick  = t_ready + dt.timedelta(minutes=gauss(SVC[\"rp\"]))\n",
-    "    t_drop  = t_pick  + dt.timedelta(minutes=drive_min)\n",
-    "    t_arr   = driver_arrival_time(created_at, t_ready, t_pick)\n",
-    "\n",
-    "    enqueue(created_at+MICRO(seq),\"order_created\",oid,seq,\n",
-    "            dict(customer_lat=lat,customer_lon=lon,customer_addr=addr,items=items)); seq+=1\n",
-    "    enqueue(t_cs+MICRO(seq),\"gk_started\",oid,seq,{}); seq+=1\n",
-    "    enqueue(t_sf+MICRO(seq),\"gk_finished\",oid,seq,{}); seq+=1\n",
-    "    enqueue(t_ready+MICRO(seq),\"gk_ready\",oid,seq,{}); seq+=1\n",
-    "    enqueue(t_arr+MICRO(seq),\"driver_arrived\",oid,seq,{}); seq+=1\n",
-    "    enqueue(t_pick+MICRO(seq),\"driver_picked_up\",oid,seq,\n",
-    "            dict(route_points=pts, eta_mins=round(drive_min,1))); seq+=1\n",
-    "\n",
-    "    hops=max(1,int(drive_min*60//PING_SEC))\n",
-    "    for h in range(1,hops):\n",
-    "        p=h/hops; lat_i,lon_i=pts[int(p*(len(pts)-1))]\n",
-    "        enqueue(t_pick+dt.timedelta(seconds=h*PING_SEC)+MICRO(seq),\"driver_ping\",oid,seq,\n",
-    "                dict(progress_pct=round(p*100,1),loc_lat=lat_i,loc_lon=lon_i)); seq+=1\n",
-    "\n",
-    "    enqueue(t_drop+MICRO(seq),\"delivered\",oid,seq,\n",
-    "            dict(delivered_lat=lat,delivered_lon=lon))\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 7.  BACK-FILL (single write)                                           │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "def build_rows(ts, lat, lon, addr, items, pts, dist, svc, day, total):\n",
-    "    rows=[]; seq=0; oid=uuid.uuid4().hex\n",
-    "    drive=dist/1609.34/GK_DRIVER_MPH*60\n",
-    "    t_cs=ts+dt.timedelta(minutes=gauss(svc[\"cs\"]))\n",
-    "    t_sf=t_cs+dt.timedelta(minutes=gauss(svc[\"sf\"]))\n",
-    "    t_fr=t_sf+dt.timedelta(minutes=gauss(svc[\"fr\"]))\n",
-    "    t_ready=t_fr\n",
-    "    t_pick=t_ready+dt.timedelta(minutes=gauss(svc[\"rp\"]))\n",
-    "    t_drop=t_pick+dt.timedelta(minutes=drive)\n",
-    "    t_arr=driver_arrival_time(ts, t_ready, t_pick)\n",
-    "\n",
-    "    def add(t,ev,p):\n",
-    "        nonlocal seq\n",
-    "        rows.append({\n",
-    "            \"event_id\":uuid.uuid4().hex,\"event_type\":ev,\n",
-    "            \"ts\":t.strftime(\"%Y-%m-%d %H:%M:%S.%f\"),\"gk_id\":GK_ID,\n",
-    "            \"location\": LOC_NAME,\n",
-    "            \"order_id\":oid,\"sequence\":seq,\n",
-    "            \"body\":json.dumps(maybe_corrupt(ev,p))\n",
-    "        }); seq+=1\n",
-    "\n",
-    "    add(ts,\"order_created\",dict(customer_lat=lat,customer_lon=lon,customer_addr=addr,items=items))\n",
-    "    add(t_cs,\"gk_started\",{}); add(t_sf,\"gk_finished\",{}); add(t_ready,\"gk_ready\",{})\n",
-    "    add(t_arr,\"driver_arrived\",{}); add(t_pick,\"driver_picked_up\",dict(route_points=pts,eta_mins=round(drive,1)))\n",
-    "    hops=max(1,int(drive*60//PING_SEC))\n",
-    "    for h in range(1,hops):\n",
-    "        p=h/hops; lat_i,lon_i=pts[int(p*(len(pts)-1))]\n",
-    "        add(t_pick+dt.timedelta(seconds=h*PING_SEC),\"driver_ping\",\n",
-    "            dict(progress_pct=round(p*100,1),loc_lat=lat_i,loc_lon=lon_i))\n",
-    "    add(t_drop,\"delivered\",dict(delivered_lat=lat,delivered_lon=lon))\n",
-    "    return rows\n",
-    "\n",
-    "def gen_backfill(start, now, total_days):\n",
-    "    back=[]\n",
-    "    for d in range(total_days+1):\n",
-    "        date = start.date()+dt.timedelta(days=d)\n",
-    "        mean = orders_today(d,total_days,date)\n",
-    "        lam  = mean/MIN_W.sum()*MIN_W; midnight=dt.datetime.combine(date,dt.time.min)\n",
-    "        for m,v in enumerate(lam):\n",
-    "            for _ in range(np.random.poisson(v)):\n",
-    "                ts=midnight+dt.timedelta(minutes=m,seconds=RAND.randint(0,59))\n",
-    "                if ts>=now: continue\n",
-    "                _,lat,lon,addr = rand_customer(); items=rand_basket(d,total_days)\n",
-    "                pts,dist=shortest_route(lat,lon)\n",
-    "                back.extend(build_rows(ts,lat,lon,addr,items,pts,dist,SVC,d,total_days))\n",
-    "    return back\n",
-    "\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "# 8.  MAIN SCHEDULER                                                     │\n",
-    "# ─────────────────────────────────────────────────────────────────────────\n",
-    "async def schedule():\n",
-    "    now = dt.datetime.utcnow()\n",
-    "    total_days = (END_TS.date()-START_TS.date()).days\n",
-    "\n",
-    "    flush(gen_backfill(START_TS, now, total_days))   # back-fill\n",
-    "    asyncio.create_task(consumer())                  # live consumer\n",
-    "\n",
-    "    async def later(ts, d):\n",
-    "        await asyncio.sleep(max(0,(ts-now).total_seconds()/SPEED_UP))\n",
-    "        await play_order(ts, d, total_days)\n",
-    "\n",
-    "    futures=[]\n",
-    "    for d in range(total_days+1):\n",
-    "        date = START_TS.date()+dt.timedelta(days=d)\n",
-    "        mean = orders_today(d,total_days,date)\n",
-    "        lam  = mean/MIN_W.sum()*MIN_W; midnight = dt.datetime.combine(date,dt.time.min)\n",
-    "        for m,v in enumerate(lam):\n",
-    "            for _ in range(np.random.poisson(v)):\n",
-    "                ts=midnight+dt.timedelta(minutes=m,seconds=RAND.randint(0,59))\n",
-    "                if ts>=now:\n",
-    "                    futures.append(asyncio.create_task(later(ts,d)))\n",
-    "    if futures: await asyncio.gather(*futures)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "e9fa0de7-be2c-437c-8060-baf66d26dd71",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "print(f\"👻  GK-sim → {VOLUME_PATH}  (×{SPEED_UP})\")\n",
-    "print(f\"Running with config: {CFG}\")\n",
-    "await schedule()"
-   ]
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "generator",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "",
-     "nuid": "4af78a5a-4db1-4ef9-ba6a-7afacdfa1c0b",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "widgetDisplayType": "Text",
-       "validationRegex": null
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "widgetType": "text",
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "widgetType": "text",
-       "autoCreated": false,
-       "validationRegex": null
-      }
-     }
-    },
-    "SCHEMA": {
-     "currentValue": "",
-     "nuid": "4a6cb71c-b92c-47b8-9e14-ad0603238807",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "SCHEMA",
-      "options": {
-       "widgetDisplayType": "Text",
-       "validationRegex": null
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "widgetType": "text",
-      "defaultValue": "",
-      "label": "",
-      "name": "SCHEMA",
-      "options": {
-       "widgetType": "text",
-       "autoCreated": false,
-       "validationRegex": null
-      }
-     }
-    },
-    "SIM_CFG_JSON": {
-     "currentValue": "",
-     "nuid": "d08237a7-8750-475b-aa76-ddf4035a210b",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "SIM_CFG_JSON",
-      "options": {
-       "widgetDisplayType": "Text",
-       "validationRegex": null
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "widgetType": "text",
-      "defaultValue": "",
-      "label": "",
-      "name": "SIM_CFG_JSON",
-      "options": {
-       "widgetType": "text",
-       "autoCreated": false,
-       "validationRegex": null
-      }
-     }
-    },
-    "VOLUME": {
-     "currentValue": "",
-     "nuid": "a27650ef-5e5c-4b1e-8533-3880a4ef5b0f",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "VOLUME",
-      "options": {
-       "widgetDisplayType": "Text",
-       "validationRegex": null
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "widgetType": "text",
-      "defaultValue": "",
-      "label": "",
-      "name": "VOLUME",
-      "options": {
-       "widgetType": "text",
-       "autoCreated": false,
-       "validationRegex": null
-      }
-     }
-    }
-   }
-  },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
-}
diff --git a/data/inspections/generate_inspection_reports.py b/data/inspections/generate_inspection_reports.py
index fad6806..d9a271a 100644
--- a/data/inspections/generate_inspection_reports.py
+++ b/data/inspections/generate_inspection_reports.py
@@ -28,6 +28,26 @@
 
 random.seed(42)
 
+
+def _safe(text: str) -> str:
+    """Replace non-latin-1 characters so fpdf core fonts don't crash."""
+    return (
+        str(text)
+        .replace("\u2014", "--")
+        .replace("\u2013", "-")
+        .replace("\u2018", "'")
+        .replace("\u2019", "'")
+        .replace("\u201c", '"')
+        .replace("\u201d", '"')
+        .replace("\u2026", "...")
+        .replace("\u2022", "-")
+        .replace("\u00d7", "x")
+        .replace("\u2192", "->")
+        .replace("\u2190", "<-")
+        .encode("latin-1", errors="replace")
+        .decode("latin-1")
+    )
+
 # ---------------------------------------------------------------------------
 # Locations (matching canonical dataset)
 # ---------------------------------------------------------------------------
@@ -56,6 +76,30 @@
         "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
         "jurisdiction": "Chicago Department of Public Health",
     },
+    {
+        "location_id": 5,
+        "name": "London",
+        "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+        "jurisdiction": "London Borough of Hackney Environmental Health",
+    },
+    {
+        "location_id": 6,
+        "name": "Munich",
+        "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+        "jurisdiction": "Landeshauptstadt Munchen Veterinaramt",
+    },
+    {
+        "location_id": 7,
+        "name": "Amsterdam",
+        "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+        "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+    },
+    {
+        "location_id": 8,
+        "name": "Vianen",
+        "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+        "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+    },
 ]
 
 # ---------------------------------------------------------------------------
@@ -251,97 +295,285 @@ def _severity_label(severity: str) -> str:
     return {"critical": "CRITICAL", "major": "MAJOR", "minor": "Minor"}[severity]
 
 
+AREA_OBSERVATIONS = [
+    ("Receiving Area", "Delivery bay clean and free of debris. Temperature logs for incoming produce reviewed; 2 of 3 recent logs show compliant temperatures on arrival. Receiving thermometer calibrated and within tolerance. Cold chain documentation from primary produce vendor present for last 30 days."),
+    ("Walk-in Refrigerator (Main)", "Internal air temperature measured at 38°F (compliant). Shelving organized with raw proteins on lowest shelf. Date labels present on 94% of items inspected. Door gaskets in good condition with no visible mold or condensation buildup. Drain clear and unobstructed."),
+    ("Walk-in Freezer", "Temperature measured at -4°F (compliant). Contents organized and properly labeled. No evidence of ice accumulation on walls or product indicating freeze-thaw cycling. Door closes and seals properly. Thermometer mounted and legible."),
+    ("Hot Holding / Steam Table", "Items held at or above 140°F per measurements taken during inspection. Staff demonstrated correct use of food probe thermometer. HACCP temperature log entries current and complete for current shift. Proper sneeze guards in place."),
+    ("Food Preparation Stations", "Cutting boards color-coded per allergen management protocol. Prep surfaces cleaned between uses per direct observation. Hand sink adjacent to prep area accessible and stocked with soap and paper towels. Food handler gloves available and in use."),
+    ("Dishwashing / Warewashing Area", "High-temperature dishmachine measured at 165°F final rinse (compliant). Sanitizer test strips present. Chemical sanitizer dispensed at correct concentration per test. Clean dishes air-dried on rack -- no towel drying observed. Grease trap access cover in place."),
+    ("Dry Storage", "FIFO rotation observed. Shelving 6 inches off floor. All containers covered and labeled. No evidence of pest activity on visual inspection. Chemical cleaning products stored in designated separate area away from food items. Temperature 72°F (within acceptable range)."),
+    ("Employee Handwashing Stations", "All stations stocked with soap and single-use towels. Foot-pedal or sensor-activated fixtures at primary stations. 'Wash Hands' signage posted. Inspector observed 2 employees washing hands between tasks during inspection period. All sinks unobstructed and accessible."),
+    ("Restrooms (Staff)", "Stocked with soap, paper towels, and working hot water. Handwashing reminder sign posted. No issues noted. Restrooms cleaned per posted schedule which was current at time of inspection."),
+    ("Exhaust Hood & Ventilation", "Exhaust filters in place and show evidence of recent cleaning (grease accumulation within acceptable range). Ansul suppression system inspection tag current and within 6-month maintenance window. Makeup air balanced; no observable smoke accumulation during cooking."),
+]
+
+HACCP_CRITICAL_LIMITS = [
+    ("Receiving - Refrigerated Foods", "41°F or below", "Calibrated probe thermometer at delivery", "Reject delivery; return to vendor; notify supplier"),
+    ("Cold Storage - All Refrigerated Items", "41°F or below", "Digital thermometer; continuous monitoring", "Transfer to compliant unit; discard if > 4 hours out of range"),
+    ("Hot Holding", "135°F or above", "Food probe thermometer; every 2 hours", "Reheat to 165°F; if not feasible, discard"),
+    ("Cooking - Poultry", "165°F internal", "Food probe thermometer at thickest point", "Return to cooking; extend time; discard if unable to achieve"),
+    ("Cooking - Ground Meat", "155°F internal", "Food probe thermometer", "Return to cooking; extend time; discard if unable to achieve"),
+    ("Cooling", "135°F to 70°F within 2 hrs; 70°F to 41°F within 4 hrs", "Logged temperature checks", "Discard if time-temperature abused; document incident"),
+    ("Sanitizing - Chemical", "50-200 ppm chlorine or per manufacturer spec", "Chemical test strips at each use", "Adjust concentration; retest; replace sanitizer solution"),
+]
+
+
 def generate_pdf(inspection: dict) -> str:
-    """Generate a single inspection report PDF. Returns the output file path."""
+    """Generate a multi-page inspection report PDF. Returns the output file path."""
     pdf = InspectionPDF(inspection["jurisdiction"])
     pdf.add_page()
 
-    # Facility information
-    pdf.set_font("Helvetica", "B", 12)
-    pdf.cell(0, 7, "Facility Information", new_x="LMARGIN", new_y="NEXT")
-    pdf.set_font("Helvetica", "", 10)
-    pdf.cell(40, 6, "Facility Name:")
-    pdf.cell(0, 6, f"Casper's Kitchens - {inspection['location_name']}", new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(40, 6, "Address:")
-    pdf.cell(0, 6, inspection["address"], new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(40, 6, "Inspection Date:")
-    pdf.cell(0, 6, inspection["inspection_date"], new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(40, 6, "Inspector:")
-    pdf.cell(0, 6, inspection["inspector_name"], new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(40, 6, "Inspection ID:")
-    pdf.cell(0, 6, inspection["inspection_id"], new_x="LMARGIN", new_y="NEXT")
-    pdf.ln(4)
-
-    # Score and grade
-    pdf.set_draw_color(120, 120, 120)
-    pdf.set_line_width(0.3)
-    pdf.line(10, pdf.get_y(), 200, pdf.get_y())
-    pdf.ln(4)
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 11)
+        pdf.set_fill_color(242, 242, 250)
+        pdf.cell(0, 7, _safe(f"  {title}"), new_x="LMARGIN", new_y="NEXT", fill=True)
+        pdf.set_line_width(0.3)
+        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
+        pdf.ln(2)
+        pdf.set_font("Helvetica", "", 9)
 
-    pdf.set_font("Helvetica", "B", 14)
-    grade = inspection["grade"]
-    pdf.cell(0, 8, f"Overall Score: {inspection['score']} / 100    Grade: {grade}", new_x="LMARGIN", new_y="NEXT", align="C")
-    pdf.ln(2)
+    def kv(label: str, value: str, label_w: int = 50):
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(label_w, 5.5, _safe(label))
+        pdf.set_font("Helvetica", "", 9)
+        pdf.cell(0, 5.5, _safe(value), new_x="LMARGIN", new_y="NEXT")
 
-    pdf.set_font("Helvetica", "", 9)
-    pdf.cell(0, 5, "Scoring: A (90-100) Excellent  |  B (80-89) Good  |  C (Below 80) Needs Improvement", new_x="LMARGIN", new_y="NEXT", align="C")
-    pdf.ln(4)
+    def para(text: str):
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(text), width=100):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
 
-    # Summary
-    pdf.set_font("Helvetica", "B", 12)
-    pdf.cell(0, 7, "Inspection Summary", new_x="LMARGIN", new_y="NEXT")
-    pdf.set_font("Helvetica", "", 10)
-    pdf.cell(0, 6, f"Total Violations: {inspection['violation_count']}    "
-                    f"(Critical: {inspection['critical_count']}, "
-                    f"Major: {inspection['major_count']}, "
-                    f"Minor: {inspection['minor_count']})", new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(40, 6, "Follow-up:")
-    pdf.cell(0, 6, inspection["follow_up_status"], new_x="LMARGIN", new_y="NEXT")
+    # ── Cover Block ──────────────────────────────────────────────────────────
+    grade = inspection["grade"]
+    grade_color = (0, 140, 60) if grade == "A" else (180, 100, 0) if grade == "B" else (180, 30, 30)
+    pdf.set_fill_color(235, 245, 235)
+    pdf.rect(10, pdf.get_y(), 190, 24, "F")
+    pdf.set_font("Helvetica", "B", 15)
+    pdf.cell(0, 9, f"Casper's Kitchens -- {inspection['location_name']}", new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "B", 11)
+    pdf.cell(0, 7, _safe(f"FOOD SAFETY INSPECTION -- {inspection['inspection_date']}  |  ID: {inspection['inspection_id']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_text_color(*grade_color)
+    pdf.set_font("Helvetica", "B", 10)
+    pdf.cell(0, 6, _safe(f"Score: {inspection['score']}/100  |  Grade: {grade}  |  Violations: {inspection['violation_count']}  |  {inspection['follow_up_status']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_text_color(0, 0, 0)
     pdf.ln(4)
 
-    # Violations detail
+    # ── Section 1: Facility & Inspection Details ─────────────────────────────
+    section("I. FACILITY INFORMATION & INSPECTION DETAILS")
+    kv("Facility Name:", f"Casper's Kitchens -- {inspection['location_name']}")
+    kv("Address:", inspection["address"])
+    kv("Jurisdiction:", inspection["jurisdiction"])
+    kv("Inspection ID:", inspection["inspection_id"])
+    kv("Inspection Date:", inspection["inspection_date"])
+    kv("Inspector:", inspection["inspector_name"])
+    kv("Inspection Type:", "Routine Unannounced Inspection")
+    kv("Permit Status:", "Active -- Current")
+    kv("Operating Hours:", "10:00 AM -- 11:00 PM (Delivery Only)")
+    kv("Staff Present:", f"{random.randint(6, 14)} kitchen staff on duty at time of inspection")
+
+    # ── Section 2: Score Summary ─────────────────────────────────────────────
+    section("II. SCORING SUMMARY")
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(50, 6, "Category", fill=True, border=1)
+    pdf.cell(30, 6, "Violations Found", fill=True, border=1)
+    pdf.cell(30, 6, "Points Deducted", fill=True, border=1)
+    pdf.cell(0, 6, "Comments", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    critical_deduct = inspection["critical_count"] * 8
+    major_deduct = inspection["major_count"] * 4
+    minor_deduct = inspection["minor_count"] * 2
+    rows = [
+        ("Critical Violations", str(inspection["critical_count"]), f"-{critical_deduct}", "Immediate corrective action required"),
+        ("Major Violations", str(inspection["major_count"]), f"-{major_deduct}", "Corrective action required within 14 days"),
+        ("Minor Violations", str(inspection["minor_count"]), f"-{minor_deduct}", "Corrective action required within 30 days"),
+        ("Total Deductions", str(inspection["violation_count"]), f"-{critical_deduct + major_deduct + minor_deduct}", ""),
+        ("Final Score", "", str(inspection["score"]), f"Grade: {inspection['grade']} -- {'Excellent' if grade=='A' else 'Good' if grade=='B' else 'Needs Improvement'}"),
+    ]
+    fill = False
+    for row in rows:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(50, 5.5, _safe(row[0]), fill=True, border=1)
+        pdf.cell(30, 5.5, _safe(row[1]), fill=True, border=1)
+        pdf.cell(30, 5.5, _safe(row[2]), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(row[3]), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(3)
+
+    # ── Section 3: Violations Detail ─────────────────────────────────────────
+    section("III. VIOLATIONS DETAIL")
     if inspection["violations"]:
-        pdf.set_draw_color(120, 120, 120)
-        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
-        pdf.ln(4)
-
-        pdf.set_font("Helvetica", "B", 12)
-        pdf.cell(0, 7, "Violations Detail", new_x="LMARGIN", new_y="NEXT")
-        pdf.ln(2)
-
+        severity_colors = {"critical": (200, 40, 40), "major": (180, 90, 0), "minor": (40, 130, 40)}
         for idx, v in enumerate(inspection["violations"], 1):
-            severity_tag = _severity_label(v["severity"])
-
-            pdf.set_font("Helvetica", "B", 10)
-            pdf.cell(0, 6, f"{idx}. [{severity_tag}] {v['code']} - {v['category']}", new_x="LMARGIN", new_y="NEXT")
-
+            col = severity_colors.get(v["severity"], (80, 80, 80))
+            pdf.set_text_color(*col)
+            pdf.set_font("Helvetica", "B", 9)
+            pdf.cell(0, 6, _safe(f"  {idx}. [{_severity_label(v['severity'])}] {v['code']} -- {v['category']}"), new_x="LMARGIN", new_y="NEXT")
+            pdf.set_text_color(0, 0, 0)
             pdf.set_font("Helvetica", "", 9)
-            desc_lines = textwrap.wrap(f"Finding: {v['description']}", width=95)
-            for line in desc_lines:
-                pdf.cell(0, 5, f"   {line}", new_x="LMARGIN", new_y="NEXT")
+            for line in textwrap.wrap(f"     Finding: {v['description']}", width=97):
+                pdf.cell(0, 5, _safe(line), new_x="LMARGIN", new_y="NEXT")
+            for line in textwrap.wrap(f"     Required Action: {v['corrective_action']}", width=97):
+                pdf.cell(0, 5, _safe(line), new_x="LMARGIN", new_y="NEXT")
+            pdf.set_font("Helvetica", "I", 8)
+            pdf.cell(0, 5, _safe(f"     Compliance Deadline: {v['deadline_days']} days from inspection date.  Re-inspection: {'Yes' if v['severity']=='critical' else 'As needed'}"), new_x="LMARGIN", new_y="NEXT")
+            pdf.ln(2)
+    else:
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.cell(0, 8, "  No violations found. Facility is in full compliance.", new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(2)
 
-            action_lines = textwrap.wrap(f"Corrective Action: {v['corrective_action']}", width=95)
-            for line in action_lines:
-                pdf.cell(0, 5, f"   {line}", new_x="LMARGIN", new_y="NEXT")
+    # ── Section 4: Facility Walk-Through Narrative ────────────────────────────
+    section("IV. FACILITY WALK-THROUGH NARRATIVE")
+    para(
+        f"The following summarizes the inspector's observations during the walk-through of the {inspection['location_name']} "
+        f"facility on {inspection['inspection_date']}. The inspection covered all food preparation, storage, and service "
+        f"areas in accordance with {inspection['jurisdiction']} inspection protocol."
+    )
+    selected_areas = random.sample(AREA_OBSERVATIONS, 6)
+    for area_name, obs in selected_areas:
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(0, 6, _safe(f"  {area_name}"), new_x="LMARGIN", new_y="NEXT")
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(obs), width=98):
+            pdf.cell(0, 5, f"    {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Section 5: HACCP Assessment ──────────────────────────────────────────
+    section("V. HACCP PLAN ASSESSMENT")
+    para(
+        f"Casper's Kitchens -- {inspection['location_name']} maintains a HACCP (Hazard Analysis and Critical Control Points) "
+        f"plan as required under FSMA 21 CFR Part 117. The following critical control points (CCPs) were reviewed during "
+        f"this inspection. HACCP plan documentation, monitoring logs, and corrective action records were examined."
+    )
+    pdf.set_font("Helvetica", "B", 7)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(38, 6, "CCP", fill=True, border=1)
+    pdf.cell(28, 6, "Critical Limit", fill=True, border=1)
+    pdf.cell(38, 6, "Monitoring Method", fill=True, border=1)
+    pdf.cell(0, 6, "Corrective Action", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 7)
+    fill = False
+    for row in HACCP_CRITICAL_LIMITS:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(38, 5.5, _safe(row[0]), fill=True, border=1)
+        pdf.cell(28, 5.5, _safe(row[1]), fill=True, border=1)
+        pdf.cell(38, 5.5, _safe(row[2]), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(row[3]), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+    haccp_ok = inspection["score"] >= 85
+    para(
+        f"HACCP plan review result: {'SATISFACTORY' if haccp_ok else 'REQUIRES ATTENTION'}. "
+        f"{'All critical limits were documented and monitoring logs were current at the time of inspection. ' if haccp_ok else 'Gaps in HACCP log documentation were identified. See violations above. '}"
+        f"The facility's Food Safety Manager ({random.choice(['Alex Rivera', 'Jordan Kim', 'Morgan Patel', 'Casey Johnson'])}) "
+        f"was present and demonstrated satisfactory knowledge of HACCP principles and emergency procedures."
+    )
+
+    # ── Section 6: Staff Training Records ────────────────────────────────────
+    section("VI. STAFF TRAINING & CERTIFICATION REVIEW")
+    total_staff = random.randint(10, 18)
+    certified = random.randint(max(6, total_staff - 3), total_staff)
+    compliance_pct = int(certified / total_staff * 100)
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(70, 6, "Certification Type", fill=True, border=1)
+    pdf.cell(30, 6, "Required", fill=True, border=1)
+    pdf.cell(30, 6, "Current", fill=True, border=1)
+    pdf.cell(0, 6, "Status", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    training_rows = [
+        ("Food Handler Certificate (State)", str(total_staff), str(certified), f"{compliance_pct}% -- {'OK' if compliance_pct >= 95 else 'Action Needed'}"),
+        ("Certified Food Protection Manager", "1 minimum on premises", "1", "Compliant"),
+        ("Allergen Awareness Training", str(total_staff), str(max(certified - 1, certified)), f"{min(100, compliance_pct + 2)}% -- {'OK' if compliance_pct >= 90 else 'Action Needed'}"),
+        ("First Aid / CPR Certification", "2 minimum per shift", "2", "Compliant"),
+        ("HACCP Principles Training", "All supervisors", f"{random.randint(2, 3)} of 3", "{'Compliant' if random.random() > 0.3 else 'Action Needed'}"),
+    ]
+    fill = False
+    for row in training_rows:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(70, 5.5, _safe(row[0]), fill=True, border=1)
+        pdf.cell(30, 5.5, _safe(row[1]), fill=True, border=1)
+        pdf.cell(30, 5.5, _safe(row[2]), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(row[3]), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
 
-            pdf.set_font("Helvetica", "I", 9)
-            pdf.cell(0, 5, f"   Deadline: {v['deadline_days']} days from inspection date", new_x="LMARGIN", new_y="NEXT")
-            pdf.ln(2)
+    # ── Section 7: Required Actions & Timelines ───────────────────────────────
+    section("VII. REQUIRED CORRECTIVE ACTIONS & COMPLIANCE TIMELINE")
+    if inspection["violations"]:
+        para("The following corrective actions are required by the stated deadlines. Non-compliance may result in re-inspection, permit suspension, or financial penalties.")
+        pdf.set_font("Helvetica", "B", 8)
+        pdf.set_fill_color(235, 235, 245)
+        pdf.cell(18, 6, "Code", fill=True, border=1)
+        pdf.cell(20, 6, "Severity", fill=True, border=1)
+        pdf.cell(35, 6, "Deadline", fill=True, border=1)
+        pdf.cell(0, 6, "Action Required", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        from datetime import date as date_cls
+        insp_date = date_cls.fromisoformat(inspection["inspection_date"])
+        pdf.set_font("Helvetica", "", 8)
+        fill = False
+        for v in inspection["violations"]:
+            deadline = insp_date + timedelta(days=v["deadline_days"])
+            pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+            pdf.cell(18, 5.5, _safe(v["code"]), fill=True, border=1)
+            pdf.cell(20, 5.5, _safe(v["severity"].capitalize()), fill=True, border=1)
+            pdf.cell(35, 5.5, deadline.strftime("%b %d, %Y"), fill=True, border=1)
+            action_short = _safe(v["corrective_action"])[:80]
+            pdf.cell(0, 5.5, action_short, fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+            fill = not fill
+        pdf.ln(2)
     else:
-        pdf.set_font("Helvetica", "B", 11)
-        pdf.ln(4)
-        pdf.cell(0, 8, "No violations found. Facility in full compliance.", new_x="LMARGIN", new_y="NEXT", align="C")
-        pdf.ln(4)
+        para("No corrective actions required. Facility in full compliance. Next routine inspection in 90 days.")
+
+    # ── Section 8: Inspector's Summary ───────────────────────────────────────
+    section("VIII. INSPECTOR'S SUMMARY AND OBSERVATIONS")
+    overall = (
+        "excellent" if inspection["score"] >= 93 else
+        "good" if inspection["score"] >= 85 else
+        "satisfactory" if inspection["score"] >= 78 else
+        "below-standard"
+    )
+    para(
+        f"Overall, the {inspection['location_name']} facility demonstrated {overall} food safety practices at the time of "
+        f"this inspection. The inspector noted that staff were cooperative and knowledgeable during the inspection process. "
+        f"Management provided all requested documentation in a timely manner."
+    )
+    if inspection["critical_count"] > 0:
+        para(
+            f"CRITICAL FINDING NOTE: {inspection['critical_count']} critical violation(s) were identified during this inspection "
+            f"requiring immediate corrective action. A re-inspection will be scheduled within 10 business days to verify "
+            f"compliance. Failure to correct critical violations may result in permit suspension proceedings."
+        )
+    elif inspection["score"] < 85:
+        para(
+            f"While no critical violations were observed, the number of major violations ({inspection['major_count']}) "
+            f"indicates that systemic improvements to food safety management processes are warranted. Management is "
+            f"encouraged to conduct an internal food safety audit within the next 30 days and provide the department with "
+            f"a corrective action plan."
+        )
+    else:
+        para(
+            f"The facility's HACCP plan is functioning effectively, and observable food safety culture among staff is positive. "
+            f"Continued emphasis on temperature monitoring, date-labeling compliance, and handwashing practices will support "
+            f"maintaining the current performance level. Next routine inspection is scheduled in 90 days."
+        )
 
-    # Signature block
+    # ── Signature Block ───────────────────────────────────────────────────────
     pdf.ln(6)
     pdf.set_draw_color(120, 120, 120)
-    pdf.line(10, pdf.get_y(), 200, pdf.get_y())
-    pdf.ln(6)
-    pdf.set_font("Helvetica", "", 10)
-    pdf.cell(0, 6, f"Inspector: {inspection['inspector_name']}", new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(0, 6, f"Date: {inspection['inspection_date']}", new_x="LMARGIN", new_y="NEXT")
-    pdf.cell(0, 6, f"Agency: {inspection['jurisdiction']}", new_x="LMARGIN", new_y="NEXT")
+    pdf.line(10, pdf.get_y(), 110, pdf.get_y())
+    pdf.ln(4)
+    pdf.set_font("Helvetica", "", 9)
+    pdf.cell(0, 5, _safe(f"Inspector: {inspection['inspector_name']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(f"Agency: {inspection['jurisdiction']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(f"Date: {inspection['inspection_date']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(4)
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.cell(0, 5, "This report is a public record. The facility operator has the right to appeal findings within 10 business days.", new_x="LMARGIN", new_y="NEXT")
 
     safe_name = inspection["location_name"].lower().replace(" ", "_")
     out_path = PDF_DIR / f"inspection_{safe_name}_{inspection['inspection_date']}.pdf"
diff --git a/data/inspections/inspection_metadata.json b/data/inspections/inspection_metadata.json
index 0c51591..3e467e7 100644
--- a/data/inspections/inspection_metadata.json
+++ b/data/inspections/inspection_metadata.json
@@ -34,82 +34,6 @@
       "minor_count": 1,
       "follow_up_status": "Routine re-inspection in 90 days"
     },
-    {
-      "inspection_id": "INS-01-20240212",
-      "location_id": 1,
-      "location_name": "San Francisco",
-      "address": "1847 Market Street, San Francisco, CA 94103",
-      "jurisdiction": "San Francisco Department of Public Health",
-      "inspection_date": "2024-02-12",
-      "inspector_name": "Marcus Williams",
-      "score": 87,
-      "grade": "B",
-      "violations": [
-        {
-          "code": "V-305",
-          "severity": "minor",
-          "category": "Administrative",
-          "description": "Permit or latest inspection report not posted in public view",
-          "corrective_action": "Print and post current permit and latest inspection report in customer-visible area within 24 hours.",
-          "deadline_days": 30
-        },
-        {
-          "code": "V-306",
-          "severity": "minor",
-          "category": "Maintenance",
-          "description": "Ceiling vent above dishwashing station shows condensation buildup",
-          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
-          "deadline_days": 30
-        },
-        {
-          "code": "V-303",
-          "severity": "minor",
-          "category": "Personal Hygiene",
-          "description": "Employee personal items stored in food preparation area",
-          "corrective_action": "Issue verbal warning to staff member. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 3,
-      "critical_count": 0,
-      "major_count": 0,
-      "minor_count": 3,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
-    {
-      "inspection_id": "INS-01-20240318",
-      "location_id": 1,
-      "location_name": "San Francisco",
-      "address": "1847 Market Street, San Francisco, CA 94103",
-      "jurisdiction": "San Francisco Department of Public Health",
-      "inspection_date": "2024-03-18",
-      "inspector_name": "Dr. Sarah Chen",
-      "score": 96,
-      "grade": "A",
-      "violations": [
-        {
-          "code": "V-201",
-          "severity": "major",
-          "category": "Facilities",
-          "description": "Handwashing sink blocked by equipment, not accessible to staff",
-          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
-          "deadline_days": 14
-        },
-        {
-          "code": "V-307",
-          "severity": "minor",
-          "category": "Chemical Safety",
-          "description": "Chemical cleaning supplies stored without labels in utility closet",
-          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 2,
-      "critical_count": 0,
-      "major_count": 1,
-      "minor_count": 1,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
     {
       "inspection_id": "INS-02-20240115",
       "location_id": 2,
@@ -144,74 +68,6 @@
       "minor_count": 1,
       "follow_up_status": "Routine re-inspection in 90 days"
     },
-    {
-      "inspection_id": "INS-02-20240212",
-      "location_id": 2,
-      "location_name": "Silicon Valley",
-      "address": "2350 El Camino Real, Santa Clara, CA 95051",
-      "jurisdiction": "Santa Clara County Environmental Health",
-      "inspection_date": "2024-02-12",
-      "inspector_name": "Marcus Williams",
-      "score": 94,
-      "grade": "A",
-      "violations": [
-        {
-          "code": "V-301",
-          "severity": "minor",
-          "category": "Facilities",
-          "description": "Floor tiles cracked or missing in food preparation area",
-          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
-          "deadline_days": 30
-        },
-        {
-          "code": "V-204",
-          "severity": "major",
-          "category": "Food Labeling",
-          "description": "Date-marking missing on prepared foods held more than 24 hours",
-          "corrective_action": "Label all prepped items immediately. Implement date-label audit at start and end of each shift.",
-          "deadline_days": 14
-        },
-        {
-          "code": "V-302",
-          "severity": "minor",
-          "category": "Facilities",
-          "description": "Light fixture missing protective shield in food prep zone",
-          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 3,
-      "critical_count": 0,
-      "major_count": 1,
-      "minor_count": 2,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
-    {
-      "inspection_id": "INS-02-20240318",
-      "location_id": 2,
-      "location_name": "Silicon Valley",
-      "address": "2350 El Camino Real, Santa Clara, CA 95051",
-      "jurisdiction": "Santa Clara County Environmental Health",
-      "inspection_date": "2024-03-18",
-      "inspector_name": "Linda Ramirez",
-      "score": 90,
-      "grade": "A",
-      "violations": [
-        {
-          "code": "V-307",
-          "severity": "minor",
-          "category": "Chemical Safety",
-          "description": "Chemical cleaning supplies stored without labels in utility closet",
-          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 1,
-      "critical_count": 0,
-      "major_count": 0,
-      "minor_count": 1,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
     {
       "inspection_id": "INS-03-20240115",
       "location_id": 3,
@@ -262,66 +118,6 @@
       "minor_count": 0,
       "follow_up_status": "Follow-up inspection scheduled within 30 days"
     },
-    {
-      "inspection_id": "INS-03-20240212",
-      "location_id": 3,
-      "location_name": "Bellevue",
-      "address": "10456 NE 8th Street, Bellevue, WA 98004",
-      "jurisdiction": "King County Public Health",
-      "inspection_date": "2024-02-12",
-      "inspector_name": "Dr. Sarah Chen",
-      "score": 87,
-      "grade": "B",
-      "violations": [
-        {
-          "code": "V-206",
-          "severity": "major",
-          "category": "Pest Control",
-          "description": "Pest control log not up to date or pest evidence found in dry storage",
-          "corrective_action": "Contact licensed pest control service for treatment within 72 hours. Update pest control log.",
-          "deadline_days": 14
-        },
-        {
-          "code": "V-307",
-          "severity": "minor",
-          "category": "Chemical Safety",
-          "description": "Chemical cleaning supplies stored without labels in utility closet",
-          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 2,
-      "critical_count": 0,
-      "major_count": 1,
-      "minor_count": 1,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
-    {
-      "inspection_id": "INS-03-20240318",
-      "location_id": 3,
-      "location_name": "Bellevue",
-      "address": "10456 NE 8th Street, Bellevue, WA 98004",
-      "jurisdiction": "King County Public Health",
-      "inspection_date": "2024-03-18",
-      "inspector_name": "Linda Ramirez",
-      "score": 90,
-      "grade": "A",
-      "violations": [
-        {
-          "code": "V-306",
-          "severity": "minor",
-          "category": "Maintenance",
-          "description": "Ceiling vent above dishwashing station shows condensation buildup",
-          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
-          "deadline_days": 30
-        }
-      ],
-      "violation_count": 1,
-      "critical_count": 0,
-      "major_count": 0,
-      "minor_count": 1,
-      "follow_up_status": "Routine re-inspection in 90 days"
-    },
     {
       "inspection_id": "INS-04-20240115",
       "location_id": 4,
@@ -397,63 +193,1871 @@
       "follow_up_status": "Re-inspection required within 10 business days"
     },
     {
-      "inspection_id": "INS-04-20240212",
-      "location_id": 4,
-      "location_name": "Chicago",
-      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
-      "jurisdiction": "Chicago Department of Public Health",
-      "inspection_date": "2024-02-12",
-      "inspector_name": "Linda Ramirez",
-      "score": 79,
-      "grade": "C",
+      "inspection_id": "INS-05-20240115",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2024-01-15",
+      "inspector_name": "James Nakamura",
+      "score": 87,
+      "grade": "B",
       "violations": [
         {
-          "code": "V-102",
-          "severity": "critical",
-          "category": "Cross-Contamination",
-          "description": "Raw meat stored above ready-to-eat food in refrigeration unit",
-          "corrective_action": "Rearrange refrigeration to store raw proteins on lowest shelves. Retrain staff on proper storage hierarchy.",
-          "deadline_days": 3
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
         },
         {
           "code": "V-203",
           "severity": "major",
           "category": "Equipment",
           "description": "Thermometer not available or not calibrated in walk-in cooler",
-          "corrective_action": "Purchase and install calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
-          "deadline_days": 14
-        },
-        {
-          "code": "V-205",
-          "severity": "major",
-          "category": "Maintenance",
-          "description": "Grease buildup on exhaust hood and filters above cooking stations",
-          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
+          "corrective_action": "Purchase calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
           "deadline_days": 14
         }
       ],
-      "violation_count": 3,
-      "critical_count": 1,
-      "major_count": 2,
-      "minor_count": 0,
-      "follow_up_status": "Re-inspection required within 10 business days"
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
     },
     {
-      "inspection_id": "INS-04-20240318",
-      "location_id": 4,
-      "location_name": "Chicago",
-      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
-      "jurisdiction": "Chicago Department of Public Health",
-      "inspection_date": "2024-03-18",
+      "inspection_id": "INS-06-20240115",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2024-01-15",
       "inspector_name": "Dr. Sarah Chen",
-      "score": 91,
+      "score": 92,
       "grade": "A",
-      "violations": [],
-      "violation_count": 0,
-      "critical_count": 0,
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-302",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Light fixture missing protective shield in food prep zone",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 2,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20240115",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2024-01-15",
+      "inspector_name": "James Nakamura",
+      "score": 86,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log immediately.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 0,
+      "major_count": 2,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20240115",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2024-01-15",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 80,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-301",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Floor tiles cracked or missing in food preparation area",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-103",
+          "severity": "critical",
+          "category": "Personal Hygiene",
+          "description": "Employee handling food without gloves after touching face/hair",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 3
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 1,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Re-inspection required within 10 business days"
+    },
+    {
+      "inspection_id": "INS-01-20240212",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Marcus Williams",
+      "score": 87,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-305",
+          "severity": "minor",
+          "category": "Administrative",
+          "description": "Permit or latest inspection report not posted in public view",
+          "corrective_action": "Print and post current permit and latest inspection report in customer-visible area within 24 hours.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-306",
+          "severity": "minor",
+          "category": "Maintenance",
+          "description": "Ceiling vent above dishwashing station shows condensation buildup",
+          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning to staff member. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 3,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20240212",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Marcus Williams",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-301",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Floor tiles cracked or missing in food preparation area",
+          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-204",
+          "severity": "major",
+          "category": "Food Labeling",
+          "description": "Date-marking missing on prepared foods held more than 24 hours",
+          "corrective_action": "Label all prepped items immediately. Implement date-label audit at start and end of each shift.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-302",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Light fixture missing protective shield in food prep zone",
+          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 2,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20240212",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 87,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control service for treatment within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20240212",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Linda Ramirez",
+      "score": 79,
+      "grade": "C",
+      "violations": [
+        {
+          "code": "V-102",
+          "severity": "critical",
+          "category": "Cross-Contamination",
+          "description": "Raw meat stored above ready-to-eat food in refrigeration unit",
+          "corrective_action": "Rearrange refrigeration to store raw proteins on lowest shelves. Retrain staff on proper storage hierarchy.",
+          "deadline_days": 3
+        },
+        {
+          "code": "V-203",
+          "severity": "major",
+          "category": "Equipment",
+          "description": "Thermometer not available or not calibrated in walk-in cooler",
+          "corrective_action": "Purchase and install calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-205",
+          "severity": "major",
+          "category": "Maintenance",
+          "description": "Grease buildup on exhaust hood and filters above cooking stations",
+          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 1,
+      "major_count": 2,
+      "minor_count": 0,
+      "follow_up_status": "Re-inspection required within 10 business days"
+    },
+    {
+      "inspection_id": "INS-05-20240212",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Klaus Weber",
+      "score": 89,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all containers per EU REACH requirements within 24 hours. Relocate to designated storage area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20240212",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Klaus Weber",
+      "score": 90,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all containers per EU REACH requirements within 24 hours. Relocate to designated storage area.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log immediately.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20240212",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log immediately.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20240212",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2024-02-12",
+      "inspector_name": "James Nakamura",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-201",
+          "severity": "major",
+          "category": "Facilities",
+          "description": "Handwashing sink blocked by equipment, not accessible to staff",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20240318",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 96,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-201",
+          "severity": "major",
+          "category": "Facilities",
+          "description": "Handwashing sink blocked by equipment, not accessible to staff",
+          "corrective_action": "Submit maintenance request for repair within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20240318",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Linda Ramirez",
+      "score": 90,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated chemical storage area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20240318",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Linda Ramirez",
+      "score": 90,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-306",
+          "severity": "minor",
+          "category": "Maintenance",
+          "description": "Ceiling vent above dishwashing station shows condensation buildup",
+          "corrective_action": "Schedule professional deep-cleaning of exhaust system within 7 days. Add monthly cleaning to maintenance calendar.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20240318",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 91,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20240318",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Sophie Lambert",
+      "score": 97,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20240318",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "James Nakamura",
+      "score": 93,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20240318",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "James Nakamura",
+      "score": 95,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20240318",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2024-03-18",
+      "inspector_name": "Annika de Vries",
+      "score": 94,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20240716",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Klaus Weber",
+      "score": 95,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20240716",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Sophie Lambert",
+      "score": 91,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20240716",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Sophie Lambert",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20240716",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Marcus Williams",
+      "score": 89,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-201",
+          "severity": "major",
+          "category": "Facilities",
+          "description": "Handwashing sink blocked by equipment, not accessible to staff",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20240716",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-301",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Floor tiles cracked or missing in food preparation area",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20240716",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "Annika de Vries",
+      "score": 98,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20240716",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "James Nakamura",
+      "score": 96,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20240716",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2024-07-16",
+      "inspector_name": "James Nakamura",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-306",
+          "severity": "minor",
+          "category": "Maintenance",
+          "description": "Ceiling vent above dishwashing station shows condensation buildup",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20241112",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Dr. Sarah Chen",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20241112",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Annika de Vries",
+      "score": 96,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20241112",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "James Nakamura",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20241112",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20241112",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Klaus Weber",
+      "score": 98,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20241112",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 95,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20241112",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Klaus Weber",
+      "score": 96,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20241112",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2024-11-12",
+      "inspector_name": "Sophie Lambert",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20250318",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "David Kowalski",
+      "score": 96,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20250318",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "James Nakamura",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20250318",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "David Kowalski",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-203",
+          "severity": "major",
+          "category": "Equipment",
+          "description": "Thermometer not available or not calibrated in walk-in cooler",
+          "corrective_action": "Purchase calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-205",
+          "severity": "major",
+          "category": "Maintenance",
+          "description": "Grease buildup on exhaust hood and filters above cooking stations",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 2,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20250318",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 86,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20250318",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 97,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20250318",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "Annika de Vries",
+      "score": 95,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-306",
+          "severity": "minor",
+          "category": "Maintenance",
+          "description": "Ceiling vent above dishwashing station shows condensation buildup",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20250318",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "Annika de Vries",
+      "score": 97,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20250318",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2025-03-18",
+      "inspector_name": "James Nakamura",
+      "score": 95,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20250715",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "Sophie Lambert",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20250715",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "James Nakamura",
+      "score": 91,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-204",
+          "severity": "major",
+          "category": "Food Labeling",
+          "description": "Date-marking missing on prepared foods held more than 24 hours",
+          "corrective_action": "Label all prepped items immediately. Implement date-label audit each shift.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20250715",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "Klaus Weber",
+      "score": 91,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-305",
+          "severity": "minor",
+          "category": "Administrative",
+          "description": "Permit or latest inspection report not posted in public view",
+          "corrective_action": "Post current permit and latest inspection report in customer-visible area within 24 hours.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20250715",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "Marcus Williams",
+      "score": 80,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-103",
+          "severity": "critical",
+          "category": "Personal Hygiene",
+          "description": "Employee handling food without gloves after touching face/hair",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 3
+        },
+        {
+          "code": "V-205",
+          "severity": "major",
+          "category": "Maintenance",
+          "description": "Grease buildup on exhaust hood and filters above cooking stations",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-101",
+          "severity": "critical",
+          "category": "Temperature Control",
+          "description": "Food held at improper temperature (outside 41F-135F range)",
+          "corrective_action": "Immediately discard affected food. Recalibrate holding equipment. Retrain on HACCP temperature logs.",
+          "deadline_days": 3
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 2,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Re-inspection required within 10 business days"
+    },
+    {
+      "inspection_id": "INS-05-20250715",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 97,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-204",
+          "severity": "major",
+          "category": "Food Labeling",
+          "description": "Date-marking missing on prepared foods held more than 24 hours",
+          "corrective_action": "Label all prepped items immediately. Implement date-label audit each shift.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20250715",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "David Kowalski",
+      "score": 95,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20250715",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "David Kowalski",
+      "score": 97,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20250715",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2025-07-15",
+      "inspector_name": "James Nakamura",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-301",
+          "severity": "minor",
+          "category": "Facilities",
+          "description": "Floor tiles cracked or missing in food preparation area",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20251110",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 97,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20251110",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Sophie Lambert",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-204",
+          "severity": "major",
+          "category": "Food Labeling",
+          "description": "Date-marking missing on prepared foods held more than 24 hours",
+          "corrective_action": "Label all prepped items immediately. Implement date-label audit each shift.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20251110",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "David Kowalski",
+      "score": 91,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-201",
+          "severity": "major",
+          "category": "Facilities",
+          "description": "Handwashing sink blocked by equipment, not accessible to staff",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20251110",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Klaus Weber",
+      "score": 92,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-303",
+          "severity": "minor",
+          "category": "Personal Hygiene",
+          "description": "Employee personal items stored in food preparation area",
+          "corrective_action": "Issue verbal warning. Retrain all kitchen staff on glove-use and hand-hygiene SOP.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20251110",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 96,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-202",
+          "severity": "major",
+          "category": "Sanitation",
+          "description": "Food contact surfaces not cleaned and sanitized between uses",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20251110",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Sophie Lambert",
+      "score": 98,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20251110",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "David Kowalski",
+      "score": 97,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20251110",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2025-11-10",
+      "inspector_name": "Patricia Okonkwo",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-01-20260120",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "jurisdiction": "San Francisco Department of Public Health",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "James Nakamura",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-206",
+          "severity": "major",
+          "category": "Pest Control",
+          "description": "Pest control log not up to date or pest evidence found in dry storage",
+          "corrective_action": "Contact licensed pest control within 72 hours. Update pest control log.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-02-20260120",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "jurisdiction": "Santa Clara County Environmental Health",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Annika de Vries",
+      "score": 93,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-305",
+          "severity": "minor",
+          "category": "Administrative",
+          "description": "Permit or latest inspection report not posted in public view",
+          "corrective_action": "Post current permit and latest inspection report in customer-visible area within 24 hours.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-203",
+          "severity": "major",
+          "category": "Equipment",
+          "description": "Thermometer not available or not calibrated in walk-in cooler",
+          "corrective_action": "Purchase calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-03-20260120",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "jurisdiction": "King County Public Health",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Linda Ramirez",
+      "score": 90,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-203",
+          "severity": "major",
+          "category": "Equipment",
+          "description": "Thermometer not available or not calibrated in walk-in cooler",
+          "corrective_action": "Purchase calibrated thermometers within 48 hours. Add to weekly calibration checklist.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 0,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-04-20260120",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "jurisdiction": "Chicago Department of Public Health",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Marcus Williams",
+      "score": 87,
+      "grade": "B",
+      "violations": [
+        {
+          "code": "V-201",
+          "severity": "major",
+          "category": "Facilities",
+          "description": "Handwashing sink blocked by equipment, not accessible to staff",
+          "corrective_action": "Submit maintenance request within 14 days. Restrict use of affected area until repaired.",
+          "deadline_days": 14
+        },
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated area.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 3,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 2,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-05-20260120",
+      "location_id": 5,
+      "location_name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Linda Ramirez",
+      "score": 99,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-307",
+          "severity": "minor",
+          "category": "Chemical Safety",
+          "description": "Chemical cleaning supplies stored without labels in utility closet",
+          "corrective_action": "Label all chemical containers per OSHA requirements within 24 hours. Relocate to designated area.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-06-20260120",
+      "location_id": 6,
+      "location_name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Linda Ramirez",
+      "score": 96,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-304",
+          "severity": "minor",
+          "category": "Sanitation",
+          "description": "Waste receptacle lid not self-closing or missing",
+          "corrective_action": "Deep-clean and re-sanitize surfaces. Verify sanitizer concentration. Restock supplies.",
+          "deadline_days": 30
+        }
+      ],
+      "violation_count": 1,
+      "critical_count": 0,
+      "major_count": 0,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-07-20260120",
+      "location_id": 7,
+      "location_name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Sophie Lambert",
+      "score": 95,
+      "grade": "A",
+      "violations": [],
+      "violation_count": 0,
+      "critical_count": 0,
       "major_count": 0,
       "minor_count": 0,
       "follow_up_status": "Routine re-inspection in 90 days"
+    },
+    {
+      "inspection_id": "INS-08-20260120",
+      "location_id": 8,
+      "location_name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority",
+      "inspection_date": "2026-01-20",
+      "inspector_name": "Annika de Vries",
+      "score": 94,
+      "grade": "A",
+      "violations": [
+        {
+          "code": "V-306",
+          "severity": "minor",
+          "category": "Maintenance",
+          "description": "Ceiling vent above dishwashing station shows condensation buildup",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 30
+        },
+        {
+          "code": "V-205",
+          "severity": "major",
+          "category": "Maintenance",
+          "description": "Grease buildup on exhaust hood and filters above cooking stations",
+          "corrective_action": "Schedule professional deep-cleaning within 7 days. Add monthly cleaning to calendar.",
+          "deadline_days": 14
+        }
+      ],
+      "violation_count": 2,
+      "critical_count": 0,
+      "major_count": 1,
+      "minor_count": 1,
+      "follow_up_status": "Routine re-inspection in 90 days"
     }
   ],
   "locations": [
@@ -480,6 +2084,30 @@
       "name": "Chicago",
       "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
       "jurisdiction": "Chicago Department of Public Health"
+    },
+    {
+      "location_id": 5,
+      "name": "London",
+      "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+      "jurisdiction": "London Borough of Hackney Environmental Health"
+    },
+    {
+      "location_id": 6,
+      "name": "Munich",
+      "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+      "jurisdiction": "Landeshauptstadt Muenchen Veterinaramt"
+    },
+    {
+      "location_id": 7,
+      "name": "Amsterdam",
+      "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+      "jurisdiction": "Gemeente Amsterdam NVWA Food Safety Authority"
+    },
+    {
+      "location_id": 8,
+      "name": "Vianen",
+      "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+      "jurisdiction": "Gemeente Vijfheerenlanden NVWA Food Safety Authority"
     }
   ]
 }
\ No newline at end of file
diff --git a/data/inspections/pdfs/inspection_amsterdam_2024-01-15.pdf b/data/inspections/pdfs/inspection_amsterdam_2024-01-15.pdf
new file mode 100644
index 0000000..32b5b98
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2024-02-12.pdf b/data/inspections/pdfs/inspection_amsterdam_2024-02-12.pdf
new file mode 100644
index 0000000..4ed5d80
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2024-03-18.pdf b/data/inspections/pdfs/inspection_amsterdam_2024-03-18.pdf
new file mode 100644
index 0000000..3255833
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2024-07-16.pdf b/data/inspections/pdfs/inspection_amsterdam_2024-07-16.pdf
new file mode 100644
index 0000000..63b100f
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2024-11-12.pdf b/data/inspections/pdfs/inspection_amsterdam_2024-11-12.pdf
new file mode 100644
index 0000000..74ba161
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2025-03-18.pdf b/data/inspections/pdfs/inspection_amsterdam_2025-03-18.pdf
new file mode 100644
index 0000000..e5a482c
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2025-07-15.pdf b/data/inspections/pdfs/inspection_amsterdam_2025-07-15.pdf
new file mode 100644
index 0000000..66cd2b4
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2025-11-10.pdf b/data/inspections/pdfs/inspection_amsterdam_2025-11-10.pdf
new file mode 100644
index 0000000..4231467
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_amsterdam_2026-01-20.pdf b/data/inspections/pdfs/inspection_amsterdam_2026-01-20.pdf
new file mode 100644
index 0000000..1e48184
Binary files /dev/null and b/data/inspections/pdfs/inspection_amsterdam_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2024-01-15.pdf b/data/inspections/pdfs/inspection_bellevue_2024-01-15.pdf
index 11c4f54..68fc749 100644
Binary files a/data/inspections/pdfs/inspection_bellevue_2024-01-15.pdf and b/data/inspections/pdfs/inspection_bellevue_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2024-02-12.pdf b/data/inspections/pdfs/inspection_bellevue_2024-02-12.pdf
index 2eb56cc..8e4921d 100644
Binary files a/data/inspections/pdfs/inspection_bellevue_2024-02-12.pdf and b/data/inspections/pdfs/inspection_bellevue_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2024-03-18.pdf b/data/inspections/pdfs/inspection_bellevue_2024-03-18.pdf
index ad53b5b..f11f8d1 100644
Binary files a/data/inspections/pdfs/inspection_bellevue_2024-03-18.pdf and b/data/inspections/pdfs/inspection_bellevue_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2024-07-16.pdf b/data/inspections/pdfs/inspection_bellevue_2024-07-16.pdf
new file mode 100644
index 0000000..7f2fe7d
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2024-11-12.pdf b/data/inspections/pdfs/inspection_bellevue_2024-11-12.pdf
new file mode 100644
index 0000000..83d3338
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2025-03-18.pdf b/data/inspections/pdfs/inspection_bellevue_2025-03-18.pdf
new file mode 100644
index 0000000..0c8ad62
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2025-07-15.pdf b/data/inspections/pdfs/inspection_bellevue_2025-07-15.pdf
new file mode 100644
index 0000000..df84beb
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2025-11-10.pdf b/data/inspections/pdfs/inspection_bellevue_2025-11-10.pdf
new file mode 100644
index 0000000..65ab8aa
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_bellevue_2026-01-20.pdf b/data/inspections/pdfs/inspection_bellevue_2026-01-20.pdf
new file mode 100644
index 0000000..0d0d13f
Binary files /dev/null and b/data/inspections/pdfs/inspection_bellevue_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2024-01-15.pdf b/data/inspections/pdfs/inspection_chicago_2024-01-15.pdf
index eabea9b..b90ca2a 100644
Binary files a/data/inspections/pdfs/inspection_chicago_2024-01-15.pdf and b/data/inspections/pdfs/inspection_chicago_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2024-02-12.pdf b/data/inspections/pdfs/inspection_chicago_2024-02-12.pdf
index 97ef7a3..7ebe6de 100644
Binary files a/data/inspections/pdfs/inspection_chicago_2024-02-12.pdf and b/data/inspections/pdfs/inspection_chicago_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2024-03-18.pdf b/data/inspections/pdfs/inspection_chicago_2024-03-18.pdf
index e3fad0b..3203fe7 100644
Binary files a/data/inspections/pdfs/inspection_chicago_2024-03-18.pdf and b/data/inspections/pdfs/inspection_chicago_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2024-07-16.pdf b/data/inspections/pdfs/inspection_chicago_2024-07-16.pdf
new file mode 100644
index 0000000..e42d1af
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2024-11-12.pdf b/data/inspections/pdfs/inspection_chicago_2024-11-12.pdf
new file mode 100644
index 0000000..11f7087
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2025-03-18.pdf b/data/inspections/pdfs/inspection_chicago_2025-03-18.pdf
new file mode 100644
index 0000000..8ccf5a9
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2025-07-15.pdf b/data/inspections/pdfs/inspection_chicago_2025-07-15.pdf
new file mode 100644
index 0000000..88f8f4a
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2025-11-10.pdf b/data/inspections/pdfs/inspection_chicago_2025-11-10.pdf
new file mode 100644
index 0000000..ec277e7
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_chicago_2026-01-20.pdf b/data/inspections/pdfs/inspection_chicago_2026-01-20.pdf
new file mode 100644
index 0000000..a26e57a
Binary files /dev/null and b/data/inspections/pdfs/inspection_chicago_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2024-01-15.pdf b/data/inspections/pdfs/inspection_london_2024-01-15.pdf
new file mode 100644
index 0000000..50edfa3
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2024-02-12.pdf b/data/inspections/pdfs/inspection_london_2024-02-12.pdf
new file mode 100644
index 0000000..c9ec0e9
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2024-03-18.pdf b/data/inspections/pdfs/inspection_london_2024-03-18.pdf
new file mode 100644
index 0000000..0656c33
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2024-07-16.pdf b/data/inspections/pdfs/inspection_london_2024-07-16.pdf
new file mode 100644
index 0000000..fefdd54
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2024-11-12.pdf b/data/inspections/pdfs/inspection_london_2024-11-12.pdf
new file mode 100644
index 0000000..d2a7e6d
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2025-03-18.pdf b/data/inspections/pdfs/inspection_london_2025-03-18.pdf
new file mode 100644
index 0000000..62327b7
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2025-07-15.pdf b/data/inspections/pdfs/inspection_london_2025-07-15.pdf
new file mode 100644
index 0000000..d94d13a
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2025-11-10.pdf b/data/inspections/pdfs/inspection_london_2025-11-10.pdf
new file mode 100644
index 0000000..d5ce243
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_london_2026-01-20.pdf b/data/inspections/pdfs/inspection_london_2026-01-20.pdf
new file mode 100644
index 0000000..4caf171
Binary files /dev/null and b/data/inspections/pdfs/inspection_london_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2024-01-15.pdf b/data/inspections/pdfs/inspection_munich_2024-01-15.pdf
new file mode 100644
index 0000000..1b79435
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2024-02-12.pdf b/data/inspections/pdfs/inspection_munich_2024-02-12.pdf
new file mode 100644
index 0000000..d792990
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2024-03-18.pdf b/data/inspections/pdfs/inspection_munich_2024-03-18.pdf
new file mode 100644
index 0000000..8a882e3
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2024-07-16.pdf b/data/inspections/pdfs/inspection_munich_2024-07-16.pdf
new file mode 100644
index 0000000..18fea98
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2024-11-12.pdf b/data/inspections/pdfs/inspection_munich_2024-11-12.pdf
new file mode 100644
index 0000000..92af9fa
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2025-03-18.pdf b/data/inspections/pdfs/inspection_munich_2025-03-18.pdf
new file mode 100644
index 0000000..8c6f0f9
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2025-07-15.pdf b/data/inspections/pdfs/inspection_munich_2025-07-15.pdf
new file mode 100644
index 0000000..b487a14
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2025-11-10.pdf b/data/inspections/pdfs/inspection_munich_2025-11-10.pdf
new file mode 100644
index 0000000..5f86de4
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_munich_2026-01-20.pdf b/data/inspections/pdfs/inspection_munich_2026-01-20.pdf
new file mode 100644
index 0000000..eb74016
Binary files /dev/null and b/data/inspections/pdfs/inspection_munich_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2024-01-15.pdf b/data/inspections/pdfs/inspection_san_francisco_2024-01-15.pdf
index fad7381..8427d88 100644
Binary files a/data/inspections/pdfs/inspection_san_francisco_2024-01-15.pdf and b/data/inspections/pdfs/inspection_san_francisco_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2024-02-12.pdf b/data/inspections/pdfs/inspection_san_francisco_2024-02-12.pdf
index 7be59bc..3845951 100644
Binary files a/data/inspections/pdfs/inspection_san_francisco_2024-02-12.pdf and b/data/inspections/pdfs/inspection_san_francisco_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2024-03-18.pdf b/data/inspections/pdfs/inspection_san_francisco_2024-03-18.pdf
index 2b176dd..3be1e11 100644
Binary files a/data/inspections/pdfs/inspection_san_francisco_2024-03-18.pdf and b/data/inspections/pdfs/inspection_san_francisco_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2024-07-16.pdf b/data/inspections/pdfs/inspection_san_francisco_2024-07-16.pdf
new file mode 100644
index 0000000..01fd3ea
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2024-11-12.pdf b/data/inspections/pdfs/inspection_san_francisco_2024-11-12.pdf
new file mode 100644
index 0000000..5866dfa
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2025-03-18.pdf b/data/inspections/pdfs/inspection_san_francisco_2025-03-18.pdf
new file mode 100644
index 0000000..ed90df4
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2025-07-15.pdf b/data/inspections/pdfs/inspection_san_francisco_2025-07-15.pdf
new file mode 100644
index 0000000..93b6c18
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2025-11-10.pdf b/data/inspections/pdfs/inspection_san_francisco_2025-11-10.pdf
new file mode 100644
index 0000000..adf45df
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_san_francisco_2026-01-20.pdf b/data/inspections/pdfs/inspection_san_francisco_2026-01-20.pdf
new file mode 100644
index 0000000..ba59e76
Binary files /dev/null and b/data/inspections/pdfs/inspection_san_francisco_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2024-01-15.pdf b/data/inspections/pdfs/inspection_silicon_valley_2024-01-15.pdf
index ff2c528..236be3e 100644
Binary files a/data/inspections/pdfs/inspection_silicon_valley_2024-01-15.pdf and b/data/inspections/pdfs/inspection_silicon_valley_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2024-02-12.pdf b/data/inspections/pdfs/inspection_silicon_valley_2024-02-12.pdf
index 4d0f866..cd6f053 100644
Binary files a/data/inspections/pdfs/inspection_silicon_valley_2024-02-12.pdf and b/data/inspections/pdfs/inspection_silicon_valley_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2024-03-18.pdf b/data/inspections/pdfs/inspection_silicon_valley_2024-03-18.pdf
index 87e5d99..5646299 100644
Binary files a/data/inspections/pdfs/inspection_silicon_valley_2024-03-18.pdf and b/data/inspections/pdfs/inspection_silicon_valley_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2024-07-16.pdf b/data/inspections/pdfs/inspection_silicon_valley_2024-07-16.pdf
new file mode 100644
index 0000000..fa3efbb
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2024-11-12.pdf b/data/inspections/pdfs/inspection_silicon_valley_2024-11-12.pdf
new file mode 100644
index 0000000..7f1d7b7
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2025-03-18.pdf b/data/inspections/pdfs/inspection_silicon_valley_2025-03-18.pdf
new file mode 100644
index 0000000..fd9b9bf
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2025-07-15.pdf b/data/inspections/pdfs/inspection_silicon_valley_2025-07-15.pdf
new file mode 100644
index 0000000..e214f81
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2025-11-10.pdf b/data/inspections/pdfs/inspection_silicon_valley_2025-11-10.pdf
new file mode 100644
index 0000000..b93f3b6
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_silicon_valley_2026-01-20.pdf b/data/inspections/pdfs/inspection_silicon_valley_2026-01-20.pdf
new file mode 100644
index 0000000..f1b6a44
Binary files /dev/null and b/data/inspections/pdfs/inspection_silicon_valley_2026-01-20.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2024-01-15.pdf b/data/inspections/pdfs/inspection_vianen_2024-01-15.pdf
new file mode 100644
index 0000000..803fd49
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2024-01-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2024-02-12.pdf b/data/inspections/pdfs/inspection_vianen_2024-02-12.pdf
new file mode 100644
index 0000000..b746cbe
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2024-02-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2024-03-18.pdf b/data/inspections/pdfs/inspection_vianen_2024-03-18.pdf
new file mode 100644
index 0000000..8ff2199
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2024-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2024-07-16.pdf b/data/inspections/pdfs/inspection_vianen_2024-07-16.pdf
new file mode 100644
index 0000000..ddc1349
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2024-07-16.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2024-11-12.pdf b/data/inspections/pdfs/inspection_vianen_2024-11-12.pdf
new file mode 100644
index 0000000..cc4b5a1
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2024-11-12.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2025-03-18.pdf b/data/inspections/pdfs/inspection_vianen_2025-03-18.pdf
new file mode 100644
index 0000000..ec2af76
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2025-03-18.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2025-07-15.pdf b/data/inspections/pdfs/inspection_vianen_2025-07-15.pdf
new file mode 100644
index 0000000..1948c2e
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2025-07-15.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2025-11-10.pdf b/data/inspections/pdfs/inspection_vianen_2025-11-10.pdf
new file mode 100644
index 0000000..d4a60e4
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2025-11-10.pdf differ
diff --git a/data/inspections/pdfs/inspection_vianen_2026-01-20.pdf b/data/inspections/pdfs/inspection_vianen_2026-01-20.pdf
new file mode 100644
index 0000000..15a54d7
Binary files /dev/null and b/data/inspections/pdfs/inspection_vianen_2026-01-20.pdf differ
diff --git a/data/legal_complaints/generate_legal_complaints.py b/data/legal_complaints/generate_legal_complaints.py
new file mode 100644
index 0000000..3fb00fe
--- /dev/null
+++ b/data/legal_complaints/generate_legal_complaints.py
@@ -0,0 +1,721 @@
+#!/usr/bin/env python3
+"""
+Generate legal complaint PDFs for Casper's Kitchens locations.
+
+Produces realistic legal documents covering employment disputes, customer injury
+claims, vendor/contract disputes, and regulatory compliance challenges across all
+8 ghost kitchen locations (US + EMEA).
+
+Outputs:
+  - data/legal_complaints/pdfs/*.pdf   (one per complaint)
+  - data/legal_complaints/legal_metadata.json
+
+Requirements:
+  pip install fpdf2
+"""
+
+import json
+import random
+import textwrap
+from datetime import date, timedelta
+from pathlib import Path
+
+from fpdf import FPDF
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def _safe(text: str) -> str:
+    """Replace non-latin-1 characters so fpdf core fonts don't crash."""
+    return (
+        str(text)
+        .replace("\u2014", "--")   # em dash
+        .replace("\u2013", "-")    # en dash
+        .replace("\u2018", "'")    # left single quote
+        .replace("\u2019", "'")    # right single quote
+        .replace("\u201c", '"')    # left double quote
+        .replace("\u201d", '"')    # right double quote
+        .replace("\u2026", "...")  # ellipsis
+        .replace("\u2022", "-")    # bullet
+        .replace("\u00d7", "x")    # multiplication sign
+        .replace("\u2192", "->")   # right arrow
+        .replace("\u2190", "<-")   # left arrow
+        .encode("latin-1", errors="replace")
+        .decode("latin-1")
+    )
+PDF_DIR = SCRIPT_DIR / "pdfs"
+METADATA_PATH = SCRIPT_DIR / "legal_metadata.json"
+
+random.seed(77)
+
+LOCATIONS = [
+    {"location_id": 1, "name": "San Francisco", "address": "1847 Market Street, San Francisco, CA 94103", "state": "CA"},
+    {"location_id": 2, "name": "Silicon Valley", "address": "2350 El Camino Real, Santa Clara, CA 95051", "state": "CA"},
+    {"location_id": 3, "name": "Bellevue", "address": "10456 NE 8th Street, Bellevue, WA 98004", "state": "WA"},
+    {"location_id": 4, "name": "Chicago", "address": "872 N. Milwaukee Avenue, Chicago, IL 60642", "state": "IL"},
+    {"location_id": 5, "name": "London", "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK", "state": "England"},
+    {"location_id": 6, "name": "Munich", "address": "Leopoldstrasse 75, 80802 Munich, Germany", "state": "Bavaria"},
+    {"location_id": 7, "name": "Amsterdam", "address": "Damrak 66, 1012 LM Amsterdam, Netherlands", "state": "North Holland"},
+    {"location_id": 8, "name": "Vianen", "address": "Voorstraat 78, 4131 LW Vianen, Netherlands", "state": "Utrecht"},
+]
+
+COMPLAINT_TYPES = [
+    {
+        "type": "Employment Discrimination",
+        "category": "Employment",
+        "basis": ["Age Discrimination", "Racial Discrimination", "Gender Discrimination", "Disability Discrimination"],
+        "statutes": {"CA": "FEHA § 12940", "WA": "RCW 49.60.180", "IL": "775 ILCS 5/2-102"},
+        "federal_statute": "Title VII, 42 U.S.C. § 2000e",
+        "relief_sought": ["Back pay", "Reinstatement", "Compensatory damages", "Punitive damages", "Attorney fees"],
+    },
+    {
+        "type": "Wrongful Termination",
+        "category": "Employment",
+        "basis": ["Retaliation for whistleblowing", "Termination in violation of public policy", "Breach of implied contract"],
+        "statutes": {"CA": "Lab. Code § 1102.5", "WA": "RCW 49.60.210", "IL": "740 ILCS 174/"},
+        "federal_statute": "NLRA § 7, 29 U.S.C. § 157",
+        "relief_sought": ["Lost wages", "Emotional distress damages", "Punitive damages", "Reinstatement"],
+    },
+    {
+        "type": "Customer Personal Injury",
+        "category": "Liability",
+        "basis": ["Slip and fall on premises", "Food-borne illness", "Allergic reaction from undisclosed ingredients", "Burn injury from defective packaging"],
+        "statutes": {"CA": "Civil Code § 1714", "WA": "RCW 4.22.005", "IL": "740 ILCS 100/"},
+        "federal_statute": "N/A (state tort law)",
+        "relief_sought": ["Medical expenses", "Lost income", "Pain and suffering", "Punitive damages"],
+    },
+    {
+        "type": "Wage and Hour Violation",
+        "category": "Employment",
+        "basis": ["Unpaid overtime", "Minimum wage violation", "Failure to provide meal/rest breaks", "Misclassification of employees"],
+        "statutes": {"CA": "Lab. Code § 510, IWC Wage Orders", "WA": "RCW 49.46.130", "IL": "820 ILCS 105/"},
+        "federal_statute": "FLSA, 29 U.S.C. § 207",
+        "relief_sought": ["Unpaid wages", "Liquidated damages", "Civil penalties", "Attorney fees"],
+    },
+    {
+        "type": "Vendor Contract Dispute",
+        "category": "Commercial",
+        "basis": ["Breach of supply agreement", "Non-payment of invoices", "Quality non-conformance", "Exclusivity violation"],
+        "statutes": {"CA": "Cal. UCC § 2201", "WA": "RCW 62A.2-201", "IL": "810 ILCS 5/2-201"},
+        "federal_statute": "N/A (state contract law)",
+        "relief_sought": ["Contract value", "Lost profits", "Consequential damages", "Specific performance"],
+    },
+]
+
+PLAINTIFF_FIRMS = [
+    "Morrison & Foerster LLP",
+    "Littler Mendelson P.C.",
+    "Ogletree, Deakins, Nash, Smoak & Stewart",
+    "Jackson Lewis P.C.",
+    "Seyfarth Shaw LLP",
+    "Reed Smith LLP",
+]
+
+DEFENSE_FIRMS = [
+    "Wilson Sonsini Goodrich & Rosati",
+    "Cooley LLP",
+    "Fenwick & West LLP",
+    "DLA Piper LLP",
+    "Perkins Coie LLP",
+    "Baker McKenzie LLP",
+]
+
+CASE_STATUS = [
+    ("Active – Discovery Phase", "Parties exchanging documents and depositions are ongoing."),
+    ("Active – Mediation Scheduled", "Mediation scheduled with JAMS; parties exploring settlement."),
+    ("Settled – Confidential Terms", "Case resolved via confidential settlement agreement. No admission of liability."),
+    ("Dismissed Without Prejudice", "Plaintiff voluntarily dismissed; statute of limitations tolled."),
+    ("Pending – Motion to Dismiss", "Defendant's motion to dismiss under review by the court."),
+    ("Judgment – Defendant Prevailed", "Court granted summary judgment in favor of Casper's Kitchens."),
+]
+
+
+def _random_date(start: date, end: date) -> date:
+    delta = (end - start).days
+    return start + timedelta(days=random.randint(0, delta))
+
+
+def generate_complaint_data() -> list[dict]:
+    complaints = []
+    period_start = date(2023, 7, 1)
+    period_end = date(2024, 3, 30)
+    case_counter = 1001
+
+    for loc in LOCATIONS:
+        num_complaints = random.randint(3, 5)
+        chosen_types = random.choices(COMPLAINT_TYPES, k=num_complaints)
+        for ct in chosen_types:
+            filed_date = _random_date(period_start, period_end)
+            basis = random.choice(ct["basis"])
+            status_label, status_detail = random.choice(CASE_STATUS)
+            state = loc["state"]
+            state_statute = ct["statutes"].get(state, ct["statutes"].get("CA", "State law applicable"))
+            amount = random.randint(25_000, 850_000)
+
+            complaints.append({
+                "case_number": f"CK-{loc['location_id']:02d}-{case_counter}",
+                "location_id": loc["location_id"],
+                "location_name": loc["name"],
+                "address": loc["address"],
+                "state": state,
+                "complaint_type": ct["type"],
+                "category": ct["category"],
+                "basis": basis,
+                "filed_date": filed_date.isoformat(),
+                "plaintiff_firm": random.choice(PLAINTIFF_FIRMS),
+                "defense_firm": random.choice(DEFENSE_FIRMS),
+                "amount_sought_usd": amount,
+                "state_statute": state_statute,
+                "federal_statute": ct["federal_statute"],
+                "relief_sought": ct["relief_sought"],
+                "status": status_label,
+                "status_detail": status_detail,
+            })
+            case_counter += 1
+
+    return complaints
+
+
+class LegalPDF(FPDF):
+    def header(self):
+        self.set_font("Helvetica", "B", 14)
+        self.cell(0, 8, "CASPER'S KITCHENS -- LEGAL AFFAIRS OFFICE", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "B", 11)
+        self.cell(0, 6, "LEGAL COMPLAINT SUMMARY & CASE FILE", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "I", 8)
+        self.cell(0, 5, "CONFIDENTIAL -- ATTORNEY-CLIENT PRIVILEGE / ATTORNEY WORK PRODUCT", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.ln(2)
+        self.set_line_width(0.5)
+        self.line(10, self.get_y(), 200, self.get_y())
+        self.ln(4)
+
+    def footer(self):
+        self.set_y(-18)
+        self.set_font("Helvetica", "I", 7)
+        self.cell(0, 4, "PRIVILEGED AND CONFIDENTIAL -- For Internal Legal Use Only -- Do Not Distribute", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.cell(0, 4, f"Page {self.page_no()}", align="C")
+
+
+FACTUAL_BACKGROUNDS = {
+    "Employment Discrimination": [
+        "The complainant, a long-tenured employee at the {loc} location, alleges that they were subjected to a pattern of discriminatory treatment based on {basis}. The alleged conduct began approximately six months prior to the formal complaint filing and included differential treatment in scheduling, exclusion from management communications, and denial of a promotion opportunity for which the complainant was qualified.",
+        "Witnesses corroborate that the complainant raised concerns internally through the HR reporting channel on two separate occasions prior to filing the external complaint. Documentation produced during discovery indicates that supervisors at the {loc} location were aware of the complainant's concerns but failed to escalate the matter to corporate Human Resources in accordance with the company's EEO policy.",
+        "The complainant's personnel file, produced during discovery, reflects satisfactory or above-average performance reviews in the four quarters preceding the adverse employment action. Defense counsel notes that a legitimate, non-discriminatory business reason was documented at the time of the adverse action; however, plaintiff's counsel argues that this rationale was pretextual given the temporal proximity to the protected activity.",
+        "Casper's Kitchens has a comprehensive Equal Employment Opportunity policy and a zero-tolerance discrimination standard. The company has cooperated fully with the investigation and provided all requested employment records. The matter is being actively defended by {defense} under a reservation of rights.",
+    ],
+    "Wrongful Termination": [
+        "The plaintiff alleges that their termination from the {loc} location constituted wrongful discharge in violation of {basis}. The plaintiff had been employed for approximately 22 months at the time of termination and had recently raised concerns about operational practices that the plaintiff characterizes as violating applicable law.",
+        "According to the complaint, the plaintiff made an internal report to a supervisor approximately 14 days prior to receiving notice of termination. The plaintiff contends that the timing establishes a causal connection between the protected activity and the adverse employment action, which the company disputes.",
+        "The company's position, as articulated by defense counsel {defense}, is that the termination was made in accordance with documented performance improvement procedures and was not connected to the plaintiff's internal report. The termination documentation, including written warnings and a performance improvement plan, was produced to plaintiff's counsel during initial discovery.",
+        "The economic damages claimed include approximately 18 months of lost wages calculated at the plaintiff's last hourly rate, plus benefits continuation costs, and alleged emotional distress. The plaintiff has not yet obtained new comparable employment, which plaintiff's counsel cites as evidence of the harm caused by the termination.",
+    ],
+    "Customer Personal Injury": [
+        "The plaintiff alleges personal injury arising from an incident at the {loc} location. The basis of the claim is {basis}. The plaintiff asserts that Casper's Kitchens owed a duty of care as a business operator and that this duty was breached through negligent acts or omissions that directly caused the plaintiff's alleged injuries.",
+        "The incident is documented in the location's internal incident report, which was filed by the on-duty manager within one hour of the event. The incident report describes the circumstances in general terms but does not constitute an admission of liability. Photographs of the scene were taken by management and preserved as part of the company's standard incident documentation protocol.",
+        "Plaintiff's medical records, obtained through a signed medical authorization, indicate treatment for injuries consistent with the alleged mechanism of harm. The treating physician has been identified as a potential witness. Defense counsel {defense} has retained an independent medical expert to review the records and assess the causal relationship between the incident and the alleged injuries.",
+        "The {loc} location's premises liability insurer has been notified and is participating in the defense of this matter. The company's safety inspection logs for the 30 days preceding the incident have been produced and show no prior documented issues at the specific location within the facility where the incident occurred.",
+    ],
+    "Wage and Hour Violation": [
+        "The plaintiff, a former kitchen staff member at the {loc} location, brings this action alleging systematic violations of applicable wage and hour laws, including {basis}. The plaintiff seeks to certify this matter as a class action on behalf of all similarly-situated employees who worked at Casper's Kitchens locations in the relevant state during the applicable limitations period.",
+        "The complaint alleges that the company's timekeeping system automatically deducted 30-minute meal periods regardless of whether employees actually received an uninterrupted meal break, in violation of applicable state meal break requirements. The plaintiff claims this practice affected all hourly employees across the relevant time period and seeks recovery of all wage deductions plus applicable statutory penalties.",
+        "Defense counsel {defense} has engaged a wage and hour specialist to audit timekeeping records and employee schedules. Preliminary analysis indicates that the automatic deduction policy was implemented by a third-party payroll provider and that manual overrides were available but may not have been consistently utilized by location managers. The company is in the process of reviewing its timekeeping policies and procedures company-wide.",
+        "The potential class size is estimated at 85-110 current and former employees. At the claimed average unpaid wage of $14.20 per week per employee over the 36-month limitations period, the base wage claim totals approximately {amount_est_str}. With applicable waiting time penalties under state law, the total exposure could reach {total_claim_str} as claimed.",
+    ],
+    "Vendor Contract Dispute": [
+        "This matter arises from a commercial dispute between Casper's Kitchens and a vendor counterparty relating to obligations under their supply agreement. The dispute centers on {basis} under the contract governing supply of goods and services to the {loc} location. The contract at issue was executed in the ordinary course of business and governed by applicable state commercial law.",
+        "The vendor filed this action after Casper's Kitchens exercised its right to dispute certain invoices that the company contends did not conform to the contractual specifications for quality, quantity, and delivery timeline. Internal correspondence produced during discovery establishes that Casper's Kitchens sent written notices of non-conformance to the vendor on three separate occasions prior to withholding payment.",
+        "The vendor contends that the goods delivered conformed to industry standards and that Casper's Kitchens' rejection of conforming goods constitutes a breach of its payment obligations. The vendor further alleges that the company's actions violated an exclusivity provision in the agreement by sourcing competing goods from an alternative supplier during the period in dispute.",
+        "Defense counsel {defense} has retained a supply chain and quality control expert to assess whether the delivered goods met the contractual specifications. Initial expert review suggests that at least two of the three disputed deliveries fell outside the temperature range specified in the contract's Schedule A, supporting the company's position that rejection was commercially reasonable under applicable UCC provisions.",
+    ],
+}
+
+TIMELINE_EVENTS = {
+    "Employment Discrimination": [
+        ("Alleged conduct begins", -180),
+        ("First internal HR report filed", -90),
+        ("Second internal HR report filed", -60),
+        ("Adverse employment action taken", -30),
+        ("EEOC charge filed", 15),
+        ("EEOC right-to-sue notice issued", 120),
+        ("Complaint filed in court", 145),
+        ("Initial case management conference", 195),
+    ],
+    "Wrongful Termination": [
+        ("Protected activity / internal report", -14),
+        ("Termination notice issued", 0),
+        ("NLRB / agency charge filed", 30),
+        ("Employer response submitted", 60),
+        ("Complaint filed in court", 90),
+        ("Discovery commences", 150),
+    ],
+    "Customer Personal Injury": [
+        ("Incident occurs at facility", 0),
+        ("Incident report filed internally", 0),
+        ("Plaintiff seeks medical treatment", 2),
+        ("Demand letter received", 45),
+        ("Insurer notified", 47),
+        ("Complaint filed in court", 120),
+        ("Answer filed by defense", 150),
+        ("Expert disclosures due", 240),
+    ],
+    "Wage and Hour Violation": [
+        ("Alleged violations begin (class period start)", -1095),
+        ("Individual plaintiff separates from employment", -90),
+        ("PAGA notice filed (CA only)", -30),
+        ("Complaint filed; class action alleged", 0),
+        ("Motion for class certification due", 180),
+        ("Class certification hearing", 240),
+    ],
+    "Vendor Contract Dispute": [
+        ("Contract executed", -365),
+        ("First non-conforming delivery", -120),
+        ("Written notice of non-conformance #1", -118),
+        ("Second disputed delivery", -90),
+        ("Payment withheld by Casper's Kitchens", -60),
+        ("Vendor demand letter received", -30),
+        ("Complaint filed in court", 0),
+        ("Arbitration demand filed (if applicable)", 15),
+    ],
+}
+
+EXPERT_WITNESSES = [
+    ("Dr. Michael Torres, Ph.D.", "Organizational Psychology", "Retained by plaintiff to opine on workplace culture and discriminatory practices."),
+    ("Sandra Whitfield, CPA", "Forensic Accounting", "Retained by defense to analyze claimed economic damages and lost wage calculations."),
+    ("James Park, Esq.", "Employment Law Expert", "Retained by plaintiff as industry practice expert on HR policies and procedures."),
+    ("Dr. Anita Sharma, M.D.", "Occupational Medicine", "Retained by defense to review medical records and assess injury causation."),
+    ("Prof. Robert Chen", "Labor Economics", "Retained by defense to analyze wage and hour claims and class-wide damages methodology."),
+    ("Karen Oduya, CPCU", "Risk Management", "Retained by defense to opine on industry-standard premises safety practices."),
+]
+
+
+def generate_pdf(complaint: dict) -> str:
+    pdf = LegalPDF()
+    pdf.set_auto_page_break(auto=True, margin=22)
+    pdf.add_page()
+
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 11)
+        pdf.set_fill_color(245, 245, 245)
+        pdf.cell(0, 7, _safe(f"  {title}"), new_x="LMARGIN", new_y="NEXT", fill=True)
+        pdf.set_line_width(0.3)
+        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
+        pdf.ln(2)
+        pdf.set_font("Helvetica", "", 9)
+
+    def kv(label: str, value: str, label_w: int = 58):
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(label_w, 5.5, _safe(label))
+        pdf.set_font("Helvetica", "", 9)
+        pdf.cell(0, 5.5, _safe(value), new_x="LMARGIN", new_y="NEXT")
+
+    def para(text: str, indent: int = 2):
+        pdf.set_font("Helvetica", "", 9)
+        prefix = " " * indent
+        for line in textwrap.wrap(_safe(text), width=100):
+            pdf.cell(0, 5, f"{prefix}{line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    def bullet(items: list):
+        pdf.set_font("Helvetica", "", 9)
+        for item in items:
+            for j, line in enumerate(textwrap.wrap(_safe(item), width=96)):
+                prefix = "  - " if j == 0 else "    "
+                pdf.cell(0, 5, f"{prefix}{line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Cover Block ──────────────────────────────────────────────────────────
+    pdf.set_fill_color(230, 230, 240)
+    pdf.rect(10, pdf.get_y(), 190, 20, "F")
+    pdf.set_font("Helvetica", "B", 14)
+    pdf.cell(0, 9, _safe(f"Case No. {complaint['case_number']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "B", 10)
+    pdf.cell(0, 7, _safe(f"{complaint['complaint_type'].upper()} -- {complaint['location_name']} Location"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.ln(2)
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.cell(0, 5, _safe(f"Filed: {complaint['filed_date']}  |  Amount Sought: ${complaint['amount_sought_usd']:,.0f}  |  Status: {complaint['status']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.ln(5)
+
+    # ── Section 1: Case Identification ───────────────────────────────────────
+    section("I. CASE IDENTIFICATION")
+    col1_w = 95
+    pdf.set_font("Helvetica", "B", 9)
+    pdf.cell(col1_w, 5.5, _safe("Case Number:"))
+    pdf.cell(0, 5.5, _safe(complaint["case_number"]), new_x="LMARGIN", new_y="NEXT")
+    kv("Complaint Type:", complaint["complaint_type"])
+    kv("Legal Basis:", complaint["basis"])
+    kv("Category:", complaint["category"])
+    kv("Date Filed:", complaint["filed_date"])
+    kv("Amount Sought:", f"${complaint['amount_sought_usd']:,.0f}")
+    kv("Current Status:", complaint["status"])
+    kv("Plaintiff Counsel:", complaint["plaintiff_firm"])
+    kv("Defense Counsel:", complaint["defense_firm"])
+    kv("State Statute:", complaint["state_statute"])
+    kv("Federal Statute:", complaint["federal_statute"])
+
+    # ── Section 2: Statement of Facts ────────────────────────────────────────
+    section("II. STATEMENT OF FACTS AND FACTUAL BACKGROUND")
+    ctype = complaint["complaint_type"]
+    backgrounds = FACTUAL_BACKGROUNDS.get(ctype, FACTUAL_BACKGROUNDS["Employment Discrimination"])
+    amount_est = complaint["amount_sought_usd"] * 0.6
+    for bg_text in backgrounds:
+        filled = bg_text.format(
+            loc=complaint["location_name"],
+            basis=complaint["basis"],
+            defense=complaint["defense_firm"],
+            amount_est=amount_est,
+            amount_est_str=f"${amount_est:,.0f}",
+            total_claim_str=f"${complaint['amount_sought_usd']:,.0f}",
+        )
+        para(filled)
+
+    # ── Section 3: Causes of Action ──────────────────────────────────────────
+    section("III. CAUSES OF ACTION")
+    para(
+        f"Plaintiff brings the following causes of action against Casper's Kitchens Inc. and, where applicable, "
+        f"individual named defendants at the {complaint['location_name']} location:"
+    )
+    causes = [
+        f"COUNT I -- {complaint['complaint_type']}: Plaintiff alleges that Casper's Kitchens violated "
+        f"{complaint['state_statute']} through the conduct described in Section II above. Elements of this claim "
+        f"include: (1) membership in a protected class or engagement in protected activity; (2) an adverse action "
+        f"by the employer; (3) a causal connection between the two; and (4) resulting damages.",
+        f"COUNT II -- Federal Claims Under {complaint['federal_statute']}: To the extent applicable, Plaintiff "
+        f"brings parallel federal claims under {complaint['federal_statute']}, which provides an independent basis "
+        f"for recovery and may allow for additional remedies including potential fee-shifting provisions.",
+        f"COUNT III -- Negligent Supervision and Retention: Plaintiff alleges that Casper's Kitchens knew or "
+        f"should have known of the conduct giving rise to this complaint and failed to take adequate remedial action, "
+        f"constituting negligent supervision and retention of the responsible personnel.",
+    ]
+    for c in causes:
+        para(c)
+
+    # ── Section 4: Relief Sought ──────────────────────────────────────────────
+    section("IV. RELIEF SOUGHT")
+    para(
+        f"Plaintiff seeks the following relief totaling up to ${complaint['amount_sought_usd']:,.0f} as follows:"
+    )
+    bullet(complaint["relief_sought"])
+    para(
+        f"Plaintiff further seeks pre-judgment and post-judgment interest at the applicable statutory rate, "
+        f"reasonable attorney's fees and costs under applicable fee-shifting provisions, and such other and "
+        f"further relief as the Court deems just and proper."
+    )
+
+    # ── Section 5: Timeline of Key Events ────────────────────────────────────
+    section("V. TIMELINE OF KEY EVENTS")
+    from datetime import date as date_cls
+    filed = date_cls.fromisoformat(complaint["filed_date"])
+    timeline = TIMELINE_EVENTS.get(ctype, TIMELINE_EVENTS["Employment Discrimination"])
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(38, 6, "Date (Approximate)", fill=True, border=1)
+    pdf.cell(0, 6, "Event", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for label, day_offset in timeline:
+        event_date = filed + timedelta(days=day_offset)
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(38, 5.5, event_date.strftime("%b %d, %Y"), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(label), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+
+    # ── Section 6: Evidence Inventory ────────────────────────────────────────
+    section("VI. EVIDENCE INVENTORY & DISCOVERY STATUS")
+    evidence_items = [
+        "Employment records (personnel file, performance reviews, disciplinary history) -- Produced",
+        "Timekeeping and payroll records for the relevant period -- Produced",
+        "Internal communications (emails, HR tickets, Slack/Teams messages) -- Partially produced; privilege review ongoing",
+        "Witness statements from 4 current and 2 former employees -- Scheduled",
+        "Incident reports and safety logs (where applicable) -- Produced",
+        "Applicable company policies (EEO, Code of Conduct, HR handbook) -- Produced",
+        "Plaintiff's medical records (where applicable) -- Obtained via HIPAA authorization",
+        "Third-party vendor or customer records (where applicable) -- Subpoena issued",
+    ]
+    bullet(evidence_items)
+    para(
+        "Discovery is ongoing. The parties have agreed to a rolling production schedule. Privilege log to be "
+        "exchanged by the date specified in the case management order. Depositions of key witnesses are expected "
+        "to occur within the next 60-90 days."
+    )
+
+    # ── Section 7: Expert Witness Summary ────────────────────────────────────
+    section("VII. EXPERT WITNESS SUMMARY")
+    selected_experts = random.sample(EXPERT_WITNESSES, 3)
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(52, 6, "Expert Name", fill=True, border=1)
+    pdf.cell(40, 6, "Specialty", fill=True, border=1)
+    pdf.cell(0, 6, "Retained By / Role", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for name, specialty, role in selected_experts:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(52, 5.5, _safe(name), fill=True, border=1)
+        pdf.cell(40, 5.5, _safe(specialty), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(role), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+
+    # ── Section 8: Financial Exposure Analysis ────────────────────────────────
+    section("VIII. FINANCIAL EXPOSURE ANALYSIS")
+    risk_level = "HIGH" if complaint["amount_sought_usd"] > 500_000 else "MEDIUM" if complaint["amount_sought_usd"] > 150_000 else "LOW"
+    low_est = int(complaint["amount_sought_usd"] * 0.15)
+    mid_est = int(complaint["amount_sought_usd"] * 0.40)
+    high_est = int(complaint["amount_sought_usd"] * 0.75)
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(235, 235, 245)
+    pdf.cell(60, 6, "Scenario", fill=True, border=1)
+    pdf.cell(40, 6, "Estimated Exposure", fill=True, border=1)
+    pdf.cell(0, 6, "Notes", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    rows = [
+        ("Early Settlement", f"${low_est:,}", "Before discovery completion; high probability of confidential terms"),
+        ("Mediated Resolution", f"${mid_est:,}", "Post-discovery mediation; moderate probability of resolution"),
+        ("Trial Verdict (Adverse)", f"${high_est:,}", "Worst-case outcome at trial; excludes attorney fee award"),
+        ("Full Claimed Amount", f"${complaint['amount_sought_usd']:,}", "Plaintiff's stated demand; includes punitive element"),
+    ]
+    fill = False
+    for row in rows:
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(60, 5.5, _safe(row[0]), fill=True, border=1)
+        pdf.cell(40, 5.5, _safe(row[1]), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(row[2]), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(2)
+    para(
+        f"Defense counsel {complaint['defense_firm']} has assessed the overall litigation risk as {risk_level}. "
+        f"Legal reserve of ${mid_est:,.0f} has been established per company policy. Insurance coverage under the "
+        f"applicable Employment Practices Liability (EPLI) policy has been confirmed, subject to deductible and "
+        f"coverage limits. Finance has been notified for reserve tracking purposes."
+    )
+
+    # ── Section 9: Settlement History ────────────────────────────────────────
+    section("IX. SETTLEMENT NEGOTIATION HISTORY")
+    settle_map = {
+        "Active – Discovery Phase": "No settlement discussions have occurred to date. The case is in active discovery. Defense counsel recommends evaluating settlement posture following completion of key depositions.",
+        "Active – Mediation Scheduled": "Parties have agreed to private mediation before JAMS. A mediator has been selected by mutual agreement. A mediation brief will be submitted by defense counsel 10 days prior to the session. The company's settlement authority is under review by the executive team and General Counsel.",
+        "Settled – Confidential Terms": "This matter has been resolved via a confidential settlement agreement executed by all parties. The settlement includes no admission of liability by Casper's Kitchens. Settlement payment has been processed and all claims have been dismissed with prejudice. A mutual non-disparagement agreement is in effect.",
+        "Dismissed Without Prejudice": "Plaintiff's counsel filed a voluntary dismissal without prejudice. The statute of limitations has been tolled by agreement. Monitor file for potential refiling. Defense counsel recommends retaining file materials for a minimum of 3 years.",
+        "Pending – Motion to Dismiss": "Defense counsel filed a motion to dismiss for failure to state a claim. Plaintiff's opposition is due within 21 days per court rules. Oral argument has been requested. If the motion is granted, plaintiff may seek leave to amend. Defense counsel assesses a 55-65% probability of partial dismissal.",
+        "Judgment – Defendant Prevailed": "The court granted summary judgment in favor of Casper's Kitchens. Plaintiff has filed a notice of appeal. Defense counsel expects the appellate court to affirm the lower court's ruling based on the strength of the undisputed factual record. Appellate briefing schedule has been established.",
+    }
+    para(settle_map.get(complaint["status"], complaint["status_detail"]))
+
+    # ── Section 10: Legal Strategy & Recommendations ─────────────────────────
+    section("X. LEGAL STRATEGY & RECOMMENDATIONS")
+    strategies = [
+        f"Continue active defense under the direction of {complaint['defense_firm']}. Maintain all relevant documents and communications under legal hold.",
+        f"Coordinate closely with HR and Operations leadership at the {complaint['location_name']} location to ensure no further actions are taken that could be characterized as retaliatory or prejudicial to the defense.",
+        f"Complete discovery within the agreed schedule. Prioritize deposition of key decision-makers and any identified witnesses.",
+        f"Evaluate settlement posture at the conclusion of fact discovery based on deposition testimony and expert assessments. Reserve authority of ${mid_est:,.0f} approved for initial negotiation phase.",
+        f"Conduct a proactive audit of {complaint['complaint_type'].lower()}-related policies and practices at all locations to identify and remediate any systemic issues that could give rise to additional claims.",
+        f"Ensure all communications regarding this matter are directed through legal counsel to preserve attorney-client privilege.",
+    ]
+    bullet(strategies)
+
+    # ── Signature Block ───────────────────────────────────────────────────────
+    pdf.ln(8)
+    pdf.set_line_width(0.3)
+    pdf.line(10, pdf.get_y(), 100, pdf.get_y())
+    pdf.ln(3)
+    pdf.set_font("Helvetica", "", 9)
+    pdf.cell(0, 5, "General Counsel, Casper's Kitchens Inc.", new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(f"Report Prepared: {complaint['filed_date']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, "PRIVILEGED AND CONFIDENTIAL -- ATTORNEY-CLIENT COMMUNICATION", new_x="LMARGIN", new_y="NEXT")
+
+    out_path = PDF_DIR / f"legal_{complaint['case_number'].replace('-', '_').lower()}.pdf"
+    pdf.output(str(out_path))
+    return str(out_path)
+
+
+def generate_summary_pdf(complaints: list[dict]) -> str:
+    """Generate a master Legal Risk Executive Summary PDF across all locations."""
+    from collections import defaultdict
+
+    # Aggregate counts by location
+    by_loc: dict[str, dict] = defaultdict(lambda: {
+        "total": 0, "active": 0, "pending": 0, "settled": 0,
+        "dismissed": 0, "judgment": 0, "total_exposure": 0,
+        "cases": [],
+    })
+    for c in complaints:
+        loc = c["location_name"]
+        stats = by_loc[loc]
+        stats["total"] += 1
+        stats["total_exposure"] += c["amount_sought_usd"]
+        stats["cases"].append(c)
+        status = c["status"]
+        if "Active" in status:
+            stats["active"] += 1
+        elif "Pending" in status:
+            stats["pending"] += 1
+        elif "Settled" in status:
+            stats["settled"] += 1
+        elif "Dismissed" in status:
+            stats["dismissed"] += 1
+        elif "Judgment" in status:
+            stats["judgment"] += 1
+
+    sorted_locs = sorted(by_loc.items(), key=lambda x: x[1]["active"], reverse=True)
+
+    pdf = LegalPDF()
+    pdf.add_page()
+    pdf.set_margins(10, 10, 10)
+    pdf.set_auto_page_break(auto=True, margin=18)
+
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 11)
+        pdf.set_fill_color(30, 30, 80)
+        pdf.set_text_color(255, 255, 255)
+        pdf.cell(0, 7, _safe(f"  {title}"), fill=True, new_x="LMARGIN", new_y="NEXT")
+        pdf.set_text_color(0, 0, 0)
+        pdf.ln(2)
+
+    # Available width = page width (210mm) minus left+right margins (10+10) = 190mm.
+    # Keep tables within 185mm so there is always space for multi_cell.
+    PAGE_W = 185
+
+    def para(text: str):
+        pdf.set_font("Helvetica", "", 9)
+        pdf.set_x(pdf.l_margin)          # always reset to left margin before multi_cell
+        pdf.multi_cell(PAGE_W, 5, _safe(text))
+        pdf.ln(1)
+
+    # ── Title block ──────────────────────────────────────────────────────────
+    pdf.set_font("Helvetica", "B", 14)
+    pdf.cell(0, 8, "CASPER'S KITCHENS -- LEGAL AFFAIRS OFFICE", new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "B", 12)
+    pdf.cell(0, 7, "LEGAL RISK EXECUTIVE SUMMARY -- ALL LOCATIONS", new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.cell(0, 5, "CONFIDENTIAL -- ATTORNEY-CLIENT PRIVILEGE / ATTORNEY WORK PRODUCT", new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.ln(4)
+
+    total_cases = len(complaints)
+    total_active = sum(s["active"] for _, s in by_loc.items())
+    total_exposure = sum(s["total_exposure"] for _, s in by_loc.items())
+
+    para(
+        f"This executive summary provides a consolidated view of all legal cases filed against "
+        f"Casper's Kitchens locations. As of the reporting date, there are {total_cases} total cases "
+        f"across all locations, with {total_active} currently active cases and total aggregate financial "
+        f"exposure of ${total_exposure:,.0f}."
+    )
+
+    # ── Location ranking by active cases ─────────────────────────────────────
+    # Columns must sum to <= PAGE_W (185mm): 48+16+16+16+16+16+43 = 171mm
+    section("I. ACTIVE CASE COUNT BY LOCATION (RANKED)")
+
+    pdf.set_font("Helvetica", "B", 9)
+    pdf.set_fill_color(220, 220, 240)
+    cols = [48, 16, 16, 16, 28, 18, 43]   # total = 185mm
+    headers = ["Location", "Total", "Active", "Pending", "Settled/Closed", "Dismissed", "Exposure ($)"]
+    pdf.set_x(pdf.l_margin)
+    for w, h in zip(cols, headers):
+        pdf.cell(w, 6, _safe(h), border=1, fill=True)
+    pdf.ln()
+
+    fill = False
+    for loc_name, stats in sorted_locs:
+        pdf.set_font("Helvetica", "", 9)
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        closed = stats["settled"] + stats["dismissed"] + stats["judgment"]
+        pdf.set_x(pdf.l_margin)
+        pdf.cell(48, 5.5, _safe(loc_name), border=1, fill=fill)
+        pdf.cell(16, 5.5, str(stats["total"]), border=1, fill=fill, align="C")
+        pdf.cell(16, 5.5, str(stats["active"]), border=1, fill=fill, align="C")
+        pdf.cell(16, 5.5, str(stats["pending"]), border=1, fill=fill, align="C")
+        pdf.cell(28, 5.5, str(closed), border=1, fill=fill, align="C")
+        pdf.cell(18, 5.5, str(stats["dismissed"]), border=1, fill=fill, align="C")
+        pdf.cell(43, 5.5, f"${stats['total_exposure']:,.0f}", border=1, fill=fill, align="R")
+        pdf.ln()
+        fill = not fill
+
+    pdf.ln(3)
+    most_active_loc, most_active_stats = sorted_locs[0]
+    para(
+        f"FINDING: {most_active_loc} has the highest number of active legal cases "
+        f"({most_active_stats['active']} active out of {most_active_stats['total']} total cases), "
+        f"with total financial exposure of ${most_active_stats['total_exposure']:,.0f}. "
+        f"All {total_active} active cases across the portfolio require immediate executive attention "
+        f"and ongoing resource allocation for legal defense."
+    )
+
+    # ── Case-by-case detail table ─────────────────────────────────────────────
+    # Columns: 24+38+33+35+25+30 = 185mm
+    section("II. COMPLETE CASE REGISTER -- ALL LOCATIONS")
+
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(220, 220, 240)
+    hdr_cols  = [24, 38, 33, 35, 25, 30]   # total = 185mm
+    hdr_labels = ["Case No.", "Location", "Type", "Basis", "Status", "Amount ($)"]
+    pdf.set_x(pdf.l_margin)
+    for w, h in zip(hdr_cols, hdr_labels):
+        pdf.cell(w, 6, _safe(h), border=1, fill=True)
+    pdf.ln()
+
+    fill = False
+    for c in sorted(complaints, key=lambda x: (x["location_name"], x["case_number"])):
+        pdf.set_font("Helvetica", "", 7.5)
+        pdf.set_fill_color(248, 248, 252) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.set_x(pdf.l_margin)
+        pdf.cell(24, 5, _safe(c["case_number"]), border=1, fill=fill)
+        pdf.cell(38, 5, _safe(c["location_name"]), border=1, fill=fill)
+        pdf.cell(33, 5, _safe(c["complaint_type"][:24]), border=1, fill=fill)
+        pdf.cell(35, 5, _safe(c["basis"][:26]), border=1, fill=fill)
+        pdf.cell(25, 5, _safe(c["status"][:20]), border=1, fill=fill)
+        pdf.cell(30, 5, f"${c['amount_sought_usd']:,.0f}", border=1, fill=fill, align="R")
+        pdf.ln()
+        fill = not fill
+
+    # ── Risk analysis ─────────────────────────────────────────────────────────
+    section("III. EXECUTIVE RISK ASSESSMENT")
+
+    pdf.set_font("Helvetica", "B", 9)
+    pdf.set_x(pdf.l_margin)
+    pdf.cell(0, 5, "Location Risk Rankings:", new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(1)
+    for rank, (loc_name, stats) in enumerate(sorted_locs, 1):
+        active = stats["active"]
+        exposure = stats["total_exposure"]
+        risk = "HIGH" if active >= 3 else ("MEDIUM" if active >= 2 else "LOW")
+        pdf.set_font("Helvetica", "", 9)
+        pdf.set_x(pdf.l_margin)           # reset X before every multi_cell
+        pdf.multi_cell(
+            PAGE_W, 5,
+            _safe(f"  {rank}. {loc_name}: {active} active cases | ${exposure:,.0f} total exposure | Risk: {risk}"),
+        )
+    pdf.ln(2)
+    para(
+        "The locations ranked above reflect active litigation risk as of the current reporting period. "
+        "Locations with 2 or more active cases are classified as HIGH or MEDIUM risk and should be "
+        "prioritized for executive oversight, proactive HR and operations audits, and enhanced legal "
+        "resource allocation. General Counsel recommends quarterly risk review meetings for all HIGH "
+        "risk locations."
+    )
+
+    out_path = PDF_DIR / "legal_risk_executive_summary.pdf"
+    pdf.output(str(out_path))
+    return str(out_path)
+
+
+def main():
+    PDF_DIR.mkdir(parents=True, exist_ok=True)
+    complaints = generate_complaint_data()
+
+    for c in complaints:
+        path = generate_pdf(c)
+        print(f"  Generated: {path}")
+
+    summary_path = generate_summary_pdf(complaints)
+    print(f"  Generated summary: {summary_path}")
+
+    with open(METADATA_PATH, "w") as f:
+        json.dump({"complaints": complaints, "locations": LOCATIONS}, f, indent=2)
+    print(f"  Metadata: {METADATA_PATH}")
+    print(f"\nDone! Generated {len(complaints)} legal complaint documents + 1 executive summary.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/data/legal_complaints/legal_metadata.json b/data/legal_complaints/legal_metadata.json
new file mode 100644
index 0000000..1598bfb
--- /dev/null
+++ b/data/legal_complaints/legal_metadata.json
@@ -0,0 +1,371 @@
+{
+  "complaints": [
+    {
+      "case_number": "CK-01-1001",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA",
+      "complaint_type": "Wrongful Termination",
+      "category": "Employment",
+      "basis": "Breach of implied contract",
+      "filed_date": "2024-02-29",
+      "plaintiff_firm": "Littler Mendelson P.C.",
+      "defense_firm": "Perkins Coie LLP",
+      "amount_sought_usd": 274362,
+      "state_statute": "Lab. Code \u00a7 1102.5",
+      "federal_statute": "NLRA \u00a7 7, 29 U.S.C. \u00a7 157",
+      "relief_sought": [
+        "Lost wages",
+        "Emotional distress damages",
+        "Punitive damages",
+        "Reinstatement"
+      ],
+      "status": "Pending \u2013 Motion to Dismiss",
+      "status_detail": "Defendant's motion to dismiss under review by the court."
+    },
+    {
+      "case_number": "CK-01-1002",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA",
+      "complaint_type": "Wrongful Termination",
+      "category": "Employment",
+      "basis": "Retaliation for whistleblowing",
+      "filed_date": "2024-03-13",
+      "plaintiff_firm": "Jackson Lewis P.C.",
+      "defense_firm": "Cooley LLP",
+      "amount_sought_usd": 54728,
+      "state_statute": "Lab. Code \u00a7 1102.5",
+      "federal_statute": "NLRA \u00a7 7, 29 U.S.C. \u00a7 157",
+      "relief_sought": [
+        "Lost wages",
+        "Emotional distress damages",
+        "Punitive damages",
+        "Reinstatement"
+      ],
+      "status": "Settled \u2013 Confidential Terms",
+      "status_detail": "Case resolved via confidential settlement agreement. No admission of liability."
+    },
+    {
+      "case_number": "CK-01-1003",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA",
+      "complaint_type": "Vendor Contract Dispute",
+      "category": "Commercial",
+      "basis": "Exclusivity violation",
+      "filed_date": "2023-10-06",
+      "plaintiff_firm": "Ogletree, Deakins, Nash, Smoak & Stewart",
+      "defense_firm": "Wilson Sonsini Goodrich & Rosati",
+      "amount_sought_usd": 372591,
+      "state_statute": "Cal. UCC \u00a7 2201",
+      "federal_statute": "N/A (state contract law)",
+      "relief_sought": [
+        "Contract value",
+        "Lost profits",
+        "Consequential damages",
+        "Specific performance"
+      ],
+      "status": "Active \u2013 Mediation Scheduled",
+      "status_detail": "Mediation scheduled with JAMS; parties exploring settlement."
+    },
+    {
+      "case_number": "CK-01-1004",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA",
+      "complaint_type": "Employment Discrimination",
+      "category": "Employment",
+      "basis": "Gender Discrimination",
+      "filed_date": "2023-08-14",
+      "plaintiff_firm": "Littler Mendelson P.C.",
+      "defense_firm": "Cooley LLP",
+      "amount_sought_usd": 517478,
+      "state_statute": "FEHA \u00a7 12940",
+      "federal_statute": "Title VII, 42 U.S.C. \u00a7 2000e",
+      "relief_sought": [
+        "Back pay",
+        "Reinstatement",
+        "Compensatory damages",
+        "Punitive damages",
+        "Attorney fees"
+      ],
+      "status": "Pending \u2013 Motion to Dismiss",
+      "status_detail": "Defendant's motion to dismiss under review by the court."
+    },
+    {
+      "case_number": "CK-02-1005",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "state": "CA",
+      "complaint_type": "Employment Discrimination",
+      "category": "Employment",
+      "basis": "Age Discrimination",
+      "filed_date": "2024-02-10",
+      "plaintiff_firm": "Reed Smith LLP",
+      "defense_firm": "Cooley LLP",
+      "amount_sought_usd": 766757,
+      "state_statute": "FEHA \u00a7 12940",
+      "federal_statute": "Title VII, 42 U.S.C. \u00a7 2000e",
+      "relief_sought": [
+        "Back pay",
+        "Reinstatement",
+        "Compensatory damages",
+        "Punitive damages",
+        "Attorney fees"
+      ],
+      "status": "Active \u2013 Discovery Phase",
+      "status_detail": "Parties exchanging documents and depositions are ongoing."
+    },
+    {
+      "case_number": "CK-02-1006",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "state": "CA",
+      "complaint_type": "Vendor Contract Dispute",
+      "category": "Commercial",
+      "basis": "Breach of supply agreement",
+      "filed_date": "2023-12-16",
+      "plaintiff_firm": "Jackson Lewis P.C.",
+      "defense_firm": "Wilson Sonsini Goodrich & Rosati",
+      "amount_sought_usd": 629912,
+      "state_statute": "Cal. UCC \u00a7 2201",
+      "federal_statute": "N/A (state contract law)",
+      "relief_sought": [
+        "Contract value",
+        "Lost profits",
+        "Consequential damages",
+        "Specific performance"
+      ],
+      "status": "Active \u2013 Discovery Phase",
+      "status_detail": "Parties exchanging documents and depositions are ongoing."
+    },
+    {
+      "case_number": "CK-02-1007",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "state": "CA",
+      "complaint_type": "Wage and Hour Violation",
+      "category": "Employment",
+      "basis": "Failure to provide meal/rest breaks",
+      "filed_date": "2023-08-24",
+      "plaintiff_firm": "Seyfarth Shaw LLP",
+      "defense_firm": "Wilson Sonsini Goodrich & Rosati",
+      "amount_sought_usd": 682529,
+      "state_statute": "Lab. Code \u00a7 510, IWC Wage Orders",
+      "federal_statute": "FLSA, 29 U.S.C. \u00a7 207",
+      "relief_sought": [
+        "Unpaid wages",
+        "Liquidated damages",
+        "Civil penalties",
+        "Attorney fees"
+      ],
+      "status": "Dismissed Without Prejudice",
+      "status_detail": "Plaintiff voluntarily dismissed; statute of limitations tolled."
+    },
+    {
+      "case_number": "CK-03-1008",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA",
+      "complaint_type": "Vendor Contract Dispute",
+      "category": "Commercial",
+      "basis": "Non-payment of invoices",
+      "filed_date": "2024-03-28",
+      "plaintiff_firm": "Jackson Lewis P.C.",
+      "defense_firm": "DLA Piper LLP",
+      "amount_sought_usd": 625481,
+      "state_statute": "RCW 62A.2-201",
+      "federal_statute": "N/A (state contract law)",
+      "relief_sought": [
+        "Contract value",
+        "Lost profits",
+        "Consequential damages",
+        "Specific performance"
+      ],
+      "status": "Active \u2013 Mediation Scheduled",
+      "status_detail": "Mediation scheduled with JAMS; parties exploring settlement."
+    },
+    {
+      "case_number": "CK-03-1009",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA",
+      "complaint_type": "Employment Discrimination",
+      "category": "Employment",
+      "basis": "Disability Discrimination",
+      "filed_date": "2023-09-09",
+      "plaintiff_firm": "Morrison & Foerster LLP",
+      "defense_firm": "DLA Piper LLP",
+      "amount_sought_usd": 61801,
+      "state_statute": "RCW 49.60.180",
+      "federal_statute": "Title VII, 42 U.S.C. \u00a7 2000e",
+      "relief_sought": [
+        "Back pay",
+        "Reinstatement",
+        "Compensatory damages",
+        "Punitive damages",
+        "Attorney fees"
+      ],
+      "status": "Active \u2013 Discovery Phase",
+      "status_detail": "Parties exchanging documents and depositions are ongoing."
+    },
+    {
+      "case_number": "CK-03-1010",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA",
+      "complaint_type": "Vendor Contract Dispute",
+      "category": "Commercial",
+      "basis": "Quality non-conformance",
+      "filed_date": "2023-07-21",
+      "plaintiff_firm": "Ogletree, Deakins, Nash, Smoak & Stewart",
+      "defense_firm": "Perkins Coie LLP",
+      "amount_sought_usd": 148624,
+      "state_statute": "RCW 62A.2-201",
+      "federal_statute": "N/A (state contract law)",
+      "relief_sought": [
+        "Contract value",
+        "Lost profits",
+        "Consequential damages",
+        "Specific performance"
+      ],
+      "status": "Dismissed Without Prejudice",
+      "status_detail": "Plaintiff voluntarily dismissed; statute of limitations tolled."
+    },
+    {
+      "case_number": "CK-03-1011",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA",
+      "complaint_type": "Vendor Contract Dispute",
+      "category": "Commercial",
+      "basis": "Breach of supply agreement",
+      "filed_date": "2024-03-07",
+      "plaintiff_firm": "Reed Smith LLP",
+      "defense_firm": "Baker McKenzie LLP",
+      "amount_sought_usd": 519421,
+      "state_statute": "RCW 62A.2-201",
+      "federal_statute": "N/A (state contract law)",
+      "relief_sought": [
+        "Contract value",
+        "Lost profits",
+        "Consequential damages",
+        "Specific performance"
+      ],
+      "status": "Judgment \u2013 Defendant Prevailed",
+      "status_detail": "Court granted summary judgment in favor of Casper's Kitchens."
+    },
+    {
+      "case_number": "CK-04-1012",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "state": "IL",
+      "complaint_type": "Employment Discrimination",
+      "category": "Employment",
+      "basis": "Gender Discrimination",
+      "filed_date": "2024-03-05",
+      "plaintiff_firm": "Morrison & Foerster LLP",
+      "defense_firm": "Wilson Sonsini Goodrich & Rosati",
+      "amount_sought_usd": 628542,
+      "state_statute": "775 ILCS 5/2-102",
+      "federal_statute": "Title VII, 42 U.S.C. \u00a7 2000e",
+      "relief_sought": [
+        "Back pay",
+        "Reinstatement",
+        "Compensatory damages",
+        "Punitive damages",
+        "Attorney fees"
+      ],
+      "status": "Dismissed Without Prejudice",
+      "status_detail": "Plaintiff voluntarily dismissed; statute of limitations tolled."
+    },
+    {
+      "case_number": "CK-04-1013",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "state": "IL",
+      "complaint_type": "Customer Personal Injury",
+      "category": "Liability",
+      "basis": "Food-borne illness",
+      "filed_date": "2024-03-03",
+      "plaintiff_firm": "Morrison & Foerster LLP",
+      "defense_firm": "Cooley LLP",
+      "amount_sought_usd": 760051,
+      "state_statute": "740 ILCS 100/",
+      "federal_statute": "N/A (state tort law)",
+      "relief_sought": [
+        "Medical expenses",
+        "Lost income",
+        "Pain and suffering",
+        "Punitive damages"
+      ],
+      "status": "Active \u2013 Discovery Phase",
+      "status_detail": "Parties exchanging documents and depositions are ongoing."
+    },
+    {
+      "case_number": "CK-04-1014",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "state": "IL",
+      "complaint_type": "Employment Discrimination",
+      "category": "Employment",
+      "basis": "Disability Discrimination",
+      "filed_date": "2023-08-15",
+      "plaintiff_firm": "Jackson Lewis P.C.",
+      "defense_firm": "Wilson Sonsini Goodrich & Rosati",
+      "amount_sought_usd": 434215,
+      "state_statute": "775 ILCS 5/2-102",
+      "federal_statute": "Title VII, 42 U.S.C. \u00a7 2000e",
+      "relief_sought": [
+        "Back pay",
+        "Reinstatement",
+        "Compensatory damages",
+        "Punitive damages",
+        "Attorney fees"
+      ],
+      "status": "Active \u2013 Discovery Phase",
+      "status_detail": "Parties exchanging documents and depositions are ongoing."
+    }
+  ],
+  "locations": [
+    {
+      "location_id": 1,
+      "name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA"
+    },
+    {
+      "location_id": 2,
+      "name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "state": "CA"
+    },
+    {
+      "location_id": 3,
+      "name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA"
+    },
+    {
+      "location_id": 4,
+      "name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "state": "IL"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/data/legal_complaints/pdfs/legal_ck_01_1001.pdf b/data/legal_complaints/pdfs/legal_ck_01_1001.pdf
new file mode 100644
index 0000000..e325167
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_01_1001.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_01_1002.pdf b/data/legal_complaints/pdfs/legal_ck_01_1002.pdf
new file mode 100644
index 0000000..e58f9c9
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_01_1002.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_01_1003.pdf b/data/legal_complaints/pdfs/legal_ck_01_1003.pdf
new file mode 100644
index 0000000..38c8fb7
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_01_1003.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_01_1004.pdf b/data/legal_complaints/pdfs/legal_ck_01_1004.pdf
new file mode 100644
index 0000000..b07ed36
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_01_1004.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_02_1005.pdf b/data/legal_complaints/pdfs/legal_ck_02_1005.pdf
new file mode 100644
index 0000000..b836dcd
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_02_1005.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_02_1006.pdf b/data/legal_complaints/pdfs/legal_ck_02_1006.pdf
new file mode 100644
index 0000000..cb3a097
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_02_1006.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_02_1007.pdf b/data/legal_complaints/pdfs/legal_ck_02_1007.pdf
new file mode 100644
index 0000000..38f8818
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_02_1007.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_03_1008.pdf b/data/legal_complaints/pdfs/legal_ck_03_1008.pdf
new file mode 100644
index 0000000..908397d
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_03_1008.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_03_1009.pdf b/data/legal_complaints/pdfs/legal_ck_03_1009.pdf
new file mode 100644
index 0000000..6ff58bb
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_03_1009.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_03_1010.pdf b/data/legal_complaints/pdfs/legal_ck_03_1010.pdf
new file mode 100644
index 0000000..aa6fc2e
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_03_1010.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_03_1011.pdf b/data/legal_complaints/pdfs/legal_ck_03_1011.pdf
new file mode 100644
index 0000000..528a110
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_03_1011.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_04_1012.pdf b/data/legal_complaints/pdfs/legal_ck_04_1012.pdf
new file mode 100644
index 0000000..871dc95
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_04_1012.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_04_1013.pdf b/data/legal_complaints/pdfs/legal_ck_04_1013.pdf
new file mode 100644
index 0000000..eac3412
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_04_1013.pdf differ
diff --git a/data/legal_complaints/pdfs/legal_ck_04_1014.pdf b/data/legal_complaints/pdfs/legal_ck_04_1014.pdf
new file mode 100644
index 0000000..1acce31
Binary files /dev/null and b/data/legal_complaints/pdfs/legal_ck_04_1014.pdf differ
diff --git a/data/regulatory/generate_regulatory_docs.py b/data/regulatory/generate_regulatory_docs.py
new file mode 100644
index 0000000..14d3f23
--- /dev/null
+++ b/data/regulatory/generate_regulatory_docs.py
@@ -0,0 +1,503 @@
+#!/usr/bin/env python3
+"""
+Generate regulatory document PDFs for Casper's Kitchens locations.
+
+Produces realistic regulatory correspondence: health permits, fire safety
+certificates, zoning compliance letters, FDA food facility registrations,
+and liquor/food handler licensing documents.
+
+Outputs:
+  - data/regulatory/pdfs/*.pdf
+  - data/regulatory/regulatory_metadata.json
+
+Requirements:
+  pip install fpdf2
+"""
+
+import json
+import random
+import textwrap
+from datetime import date, timedelta
+from pathlib import Path
+
+from fpdf import FPDF
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def _safe(text: str) -> str:
+    return (
+        str(text)
+        .replace("\u2014", "--")
+        .replace("\u2013", "-")
+        .replace("\u2018", "'")
+        .replace("\u2019", "'")
+        .replace("\u201c", '"')
+        .replace("\u201d", '"')
+        .replace("\u2026", "...")
+        .replace("\u2022", "-")
+        .replace("\u00d7", "x")
+        .replace("\u2192", "->")
+        .replace("\u2190", "<-")
+        .encode("latin-1", errors="replace")
+        .decode("latin-1")
+    )
+PDF_DIR = SCRIPT_DIR / "pdfs"
+METADATA_PATH = SCRIPT_DIR / "regulatory_metadata.json"
+
+random.seed(55)
+
+LOCATIONS = [
+    {
+        "location_id": 1, "name": "San Francisco", "address": "1847 Market Street, San Francisco, CA 94103",
+        "state": "CA", "city": "San Francisco",
+        "health_dept": "San Francisco Department of Public Health",
+        "fire_dept": "San Francisco Fire Department",
+        "zoning_office": "SF Planning Department",
+    },
+    {
+        "location_id": 2, "name": "Silicon Valley", "address": "2350 El Camino Real, Santa Clara, CA 95051",
+        "state": "CA", "city": "Santa Clara",
+        "health_dept": "Santa Clara County Environmental Health",
+        "fire_dept": "Santa Clara Fire Department",
+        "zoning_office": "Santa Clara Planning & Inspection",
+    },
+    {
+        "location_id": 3, "name": "Bellevue", "address": "10456 NE 8th Street, Bellevue, WA 98004",
+        "state": "WA", "city": "Bellevue",
+        "health_dept": "King County Public Health",
+        "fire_dept": "Bellevue Fire Department",
+        "zoning_office": "City of Bellevue Development Services",
+    },
+    {
+        "location_id": 4, "name": "Chicago", "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+        "state": "IL", "city": "Chicago",
+        "health_dept": "Chicago Department of Public Health",
+        "fire_dept": "Chicago Fire Department",
+        "zoning_office": "Chicago Department of Buildings",
+    },
+    {
+        "location_id": 5, "name": "London", "address": "14 Curtain Road, Shoreditch, London EC2A 3NH, UK",
+        "state": "England", "city": "London",
+        "health_dept": "London Borough of Hackney Environmental Health",
+        "fire_dept": "London Fire Brigade",
+        "zoning_office": "Hackney Planning Department",
+    },
+    {
+        "location_id": 6, "name": "Munich", "address": "Leopoldstrasse 75, 80802 Munich, Germany",
+        "state": "Bavaria", "city": "Munich",
+        "health_dept": "Landeshauptstadt Munchen Veterinaramt",
+        "fire_dept": "Feuerwehr Munchen",
+        "zoning_office": "Munchen Referat fur Stadtplanung",
+    },
+    {
+        "location_id": 7, "name": "Amsterdam", "address": "Damrak 66, 1012 LM Amsterdam, Netherlands",
+        "state": "North Holland", "city": "Amsterdam",
+        "health_dept": "Gemeente Amsterdam NVWA",
+        "fire_dept": "Brandweer Amsterdam-Amstelland",
+        "zoning_office": "Gemeente Amsterdam Ruimte en Duurzaamheid",
+    },
+    {
+        "location_id": 8, "name": "Vianen", "address": "Voorstraat 78, 4131 LW Vianen, Netherlands",
+        "state": "Utrecht", "city": "Vianen",
+        "health_dept": "Gemeente Vijfheerenlanden NVWA",
+        "fire_dept": "Brandweer Utrecht",
+        "zoning_office": "Gemeente Vijfheerenlanden Ruimtelijke Ordening",
+    },
+]
+
+DOC_TEMPLATES = [
+    {
+        "doc_type": "Food Service Establishment Permit",
+        "issuer_key": "health_dept",
+        "status_options": ["APPROVED – Active", "APPROVED – Active (Conditional)", "RENEWAL PENDING"],
+        "conditions": [
+            "Facility must maintain compliance with all applicable food safety regulations.",
+            "Any change to menu, ownership, or facility layout requires prior approval.",
+            "Permit must be posted in a conspicuous location visible to the public.",
+            "Annual renewal required by permit expiration date.",
+        ],
+    },
+    {
+        "doc_type": "Fire Safety & Occupancy Certificate",
+        "issuer_key": "fire_dept",
+        "status_options": ["ISSUED", "ISSUED – Conditional", "ISSUED – Pending Sprinkler Inspection"],
+        "conditions": [
+            "Maximum occupancy of 45 persons including staff at all times.",
+            "Monthly testing of fire suppression system required.",
+            "Annual fire safety training mandatory for all kitchen staff.",
+            "Exit routes must remain unobstructed at all times.",
+        ],
+    },
+    {
+        "doc_type": "Zoning Compliance Letter",
+        "issuer_key": "zoning_office",
+        "status_options": ["COMPLIANT", "COMPLIANT – Variance Granted", "UNDER REVIEW"],
+        "conditions": [
+            "Use limited to food service and preparation (ghost kitchen operations).",
+            "Delivery vehicle access restricted to rear alley between 6AM–10PM.",
+            "Exterior signage must comply with Municipal Code § 136.3.",
+            "On-site dining is not permitted under ghost kitchen classification.",
+        ],
+    },
+    {
+        "doc_type": "FDA Food Facility Registration",
+        "issuer_key": "health_dept",
+        "status_options": ["REGISTERED", "REGISTERED – Biennial Renewal Due"],
+        "conditions": [
+            "Registration under 21 CFR Part 1, Subpart H — Food Facilities.",
+            "Facility must allow FDA inspection upon request with no prior notice.",
+            "Any changes to facility, processes, or products must be reported within 60 days.",
+            "FSMA Preventive Controls Rule compliance required.",
+        ],
+    },
+    {
+        "doc_type": "Food Handler Certification — Corporate Compliance",
+        "issuer_key": "health_dept",
+        "status_options": ["IN COMPLIANCE", "PARTIAL COMPLIANCE – 2 Staff Pending Renewal"],
+        "conditions": [
+            "All food handlers must hold a current food handler certificate.",
+            "Certified Food Manager must be present during all operating hours.",
+            "Certificates expire every 3 years; renewal training required.",
+            "Records of all certifications must be maintained on-site.",
+        ],
+    },
+]
+
+INSPECTORS = [
+    "Regional Compliance Officer",
+    "Deputy Director of Environmental Health",
+    "Fire Marshal, District 7",
+    "Senior Zoning Administrator",
+    "FDA District Inspector",
+]
+
+
+def _random_date(start: date, end: date) -> date:
+    delta = (end - start).days
+    return start + timedelta(days=random.randint(0, delta))
+
+
+def generate_regulatory_data() -> list[dict]:
+    docs = []
+    doc_counter = 2001
+    period_start = date(2023, 9, 1)
+    period_end = date(2024, 3, 30)
+
+    for loc in LOCATIONS:
+        for template in DOC_TEMPLATES:
+            issue_date = _random_date(period_start, date(2024, 1, 15))
+            expiry_date = issue_date + timedelta(days=random.choice([180, 365, 730]))
+            status = random.choice(template["status_options"])
+
+            docs.append({
+                "doc_id": f"REG-{loc['location_id']:02d}-{doc_counter}",
+                "location_id": loc["location_id"],
+                "location_name": loc["name"],
+                "address": loc["address"],
+                "city": loc["city"],
+                "state": loc["state"],
+                "doc_type": template["doc_type"],
+                "issuing_authority": loc[template["issuer_key"]],
+                "issue_date": issue_date.isoformat(),
+                "expiry_date": expiry_date.isoformat(),
+                "status": status,
+                "conditions": template["conditions"],
+                "inspector": random.choice(INSPECTORS),
+            })
+            doc_counter += 1
+
+    return docs
+
+
+class RegPDF(FPDF):
+    def __init__(self, issuer: str):
+        super().__init__()
+        self.issuer = issuer
+        self.set_auto_page_break(auto=True, margin=22)
+
+    def header(self):
+        self.set_font("Helvetica", "B", 14)
+        self.cell(0, 8, self.issuer.upper(), new_x="LMARGIN", new_y="NEXT", align="C")
+        self.set_font("Helvetica", "", 10)
+        self.cell(0, 5, "REGULATORY COMPLIANCE DOCUMENT", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.ln(2)
+        self.set_line_width(0.5)
+        self.line(10, self.get_y(), 200, self.get_y())
+        self.ln(4)
+
+    def footer(self):
+        self.set_y(-15)
+        self.set_font("Helvetica", "I", 7)
+        self.cell(0, 4, "This is an official regulatory document. Alterations render this document void.", new_x="LMARGIN", new_y="NEXT", align="C")
+        self.cell(0, 4, f"Page {self.page_no()}", align="C")
+
+
+REG_LEGAL_BACKGROUND = {
+    "Food Service Establishment Permit": (
+        "Food service establishments operating within the jurisdiction are subject to the provisions of the California "
+        "Retail Food Code (Cal. Health & Safety Code § 113700 et seq.), Washington Administrative Code (WAC) Chapter "
+        "246-215, or the Illinois Food Service Sanitation Code (77 Ill. Adm. Code 750), as applicable. These statutes "
+        "require that all food service operations be conducted under a valid, current permit issued by the local "
+        "environmental health authority. Permits are non-transferable and are issued to the named operator at the "
+        "specified address only. Any change of ownership, concept, or significant facility modification requires "
+        "submission of a new permit application and may require a pre-operational inspection."
+    ),
+    "Fire Safety & Occupancy Certificate": (
+        "Commercial kitchen operations are subject to the International Fire Code (IFC) as locally adopted, NFPA 96 "
+        "(Standard for Ventilation Control and Fire Protection of Commercial Cooking Operations), and applicable local "
+        "fire prevention ordinances. Ghost kitchen facilities must maintain operational fire suppression systems, "
+        "compliant egress routes, and current fire safety training records for all staff. The Certificate of Occupancy "
+        "establishes the maximum permitted occupant load as determined by the Fire Marshal based on egress capacity "
+        "calculations in accordance with IFC Section 1004. Non-compliance with fire safety requirements may result in "
+        "immediate closure by the fire authority having jurisdiction (AHJ)."
+    ),
+    "Zoning Compliance Letter": (
+        "Ghost kitchen operations are subject to land use and zoning regulations as codified in the applicable "
+        "municipal code. The designated use classification for ghost kitchen (delivery-only food preparation) "
+        "is typically permitted in commercial or light industrial zones, subject to specific use conditions. "
+        "Zoning compliance requires that all operations conform to approved use parameters, including hours of "
+        "operation, delivery access restrictions, signage limitations, and prohibition on on-premises dining. "
+        "Any proposed change to operational scope, hours, or physical footprint requires advance approval from "
+        "the Planning Department and may require a new conditional use permit application."
+    ),
+    "FDA Food Facility Registration": (
+        "Food facilities that manufacture, process, pack, or hold food for consumption in the United States are "
+        "required to register with the U.S. Food and Drug Administration (FDA) pursuant to Section 415 of the "
+        "Federal Food, Drug, and Cosmetic Act (FD&C Act), as amended by the Bioterrorism Act of 2002 and the "
+        "Food Safety Modernization Act of 2011 (FSMA). Registration must be renewed biennially during the period "
+        "October 1 through December 31 of each even-numbered year. Registered facilities are subject to FDA "
+        "inspection under 21 U.S.C. § 374. The facility must also comply with applicable Preventive Controls "
+        "requirements under 21 CFR Part 117."
+    ),
+    "Food Handler Certification — Corporate Compliance": (
+        "State and local food safety laws require that all persons who handle food in a commercial setting hold "
+        "a current, valid food handler certificate from an accredited certification program. Additionally, at least "
+        "one Certified Food Protection Manager (CFPM) holding ANSI-accredited certification (such as ServSafe, "
+        "Prometric, or equivalent) must be present at the facility during all hours of operation. Certification "
+        "records must be maintained on-site and made available for inspection upon request. Failure to maintain "
+        "required certifications constitutes a violation subject to administrative penalty."
+    ),
+}
+
+INSPECTION_HISTORY_POOL = [
+    ("Prior Routine Inspection", -365, "Compliant", "No violations; Grade A issued"),
+    ("Follow-up Inspection", -280, "Compliant", "All prior items resolved; permit renewed"),
+    ("Routine Inspection", -180, "Conditional", "2 minor violations; corrective actions completed"),
+    ("Complaint-Triggered Inspection", -120, "Compliant", "No basis for complaint found; facility in compliance"),
+    ("Pre-Permit Inspection", -90, "Approved", "Facility approved for operation at this address"),
+    ("Annual Review", -60, "Compliant", "Annual permit review completed; documentation current"),
+]
+
+REQUIRED_POSTINGS = [
+    "Current permit/certificate (this document) must be posted in a conspicuous location",
+    "Most recent inspection report (public record) must be posted in public-facing area",
+    "Food allergy awareness notice (where required by jurisdiction)",
+    "No smoking signage at all entrances and throughout facility",
+    "Hand washing instructions at each hand sink",
+    "Emergency contact information for management on-call",
+    "Workers' compensation notice (as required by state law)",
+    "Anti-discrimination and equal opportunity employment poster (EEOC)",
+]
+
+
+def generate_pdf(doc: dict) -> str:
+    pdf = RegPDF(doc["issuing_authority"])
+    pdf.add_page()
+
+    def kv(label: str, value: str, label_w: int = 60):
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.cell(label_w, 5.5, _safe(label))
+        pdf.set_font("Helvetica", "", 9)
+        pdf.cell(0, 5.5, _safe(value), new_x="LMARGIN", new_y="NEXT")
+
+    def section(title: str):
+        pdf.ln(4)
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.set_fill_color(230, 245, 230)
+        pdf.cell(0, 7, _safe(f"  {title}"), new_x="LMARGIN", new_y="NEXT", fill=True)
+        pdf.set_line_width(0.3)
+        pdf.line(10, pdf.get_y(), 200, pdf.get_y())
+        pdf.ln(2)
+
+    def para(text: str):
+        pdf.set_font("Helvetica", "", 9)
+        for line in textwrap.wrap(_safe(text), width=100):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Cover Block ──────────────────────────────────────────────────────────
+    status_ok = "PENDING" not in doc["status"] and "REVIEW" not in doc["status"]
+    bg_color = (215, 240, 215) if status_ok else (245, 230, 210)
+    pdf.set_fill_color(*bg_color)
+    pdf.rect(10, pdf.get_y(), 190, 20, "F")
+    pdf.set_font("Helvetica", "B", 13)
+    pdf.cell(0, 8, _safe(doc["doc_type"].upper()), new_x="LMARGIN", new_y="NEXT", align="C")
+    status_color = (0, 130, 50) if status_ok else (160, 80, 0)
+    pdf.set_text_color(*status_color)
+    pdf.set_font("Helvetica", "B", 10)
+    pdf.cell(0, 6, _safe(f"STATUS: {doc['status']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.set_text_color(0, 0, 0)
+    pdf.set_font("Helvetica", "", 8)
+    pdf.cell(0, 5, _safe(f"Document ID: {doc['doc_id']}  |  Issued: {doc['issue_date']}  |  Expires: {doc['expiry_date']}"), new_x="LMARGIN", new_y="NEXT", align="C")
+    pdf.ln(4)
+
+    # ── Section 1: Document & Facility Details ────────────────────────────────
+    section("I. DOCUMENT & FACILITY DETAILS")
+    kv("Document ID:", doc["doc_id"])
+    kv("Document Type:", doc["doc_type"])
+    kv("Issuing Authority:", doc["issuing_authority"])
+    kv("Issue Date:", doc["issue_date"])
+    kv("Expiry / Renewal Date:", doc["expiry_date"])
+    kv("Authorized By:", doc["inspector"])
+    kv("Current Status:", doc["status"])
+    pdf.ln(2)
+    kv("Facility Name:", f"Casper's Kitchens -- {doc['location_name']}")
+    kv("Location:", doc["location_name"])
+    kv("Address:", doc["address"])
+    kv("City / State:", f"{doc['city']}, {doc['state']}")
+    kv("Facility Type:", "Ghost Kitchen / Food Delivery Operation (No On-Premises Dining)")
+    kv("Brands Operated:", "16 virtual restaurant brands")
+
+    # ── Section 2: Legal Background ──────────────────────────────────────────
+    section("II. REGULATORY BACKGROUND & APPLICABLE LAW")
+    legal_text = REG_LEGAL_BACKGROUND.get(doc["doc_type"], REG_LEGAL_BACKGROUND["Food Service Establishment Permit"])
+    para(legal_text)
+    para(
+        f"This document has been issued to Casper's Kitchens for the {doc['location_name']} facility located at "
+        f"{doc['address']}. The operator is responsible for maintaining compliance with all applicable statutes, "
+        f"regulations, and conditions of this authorization throughout the validity period."
+    )
+
+    # ── Section 3: Conditions & Requirements ─────────────────────────────────
+    section("III. CONDITIONS, OBLIGATIONS & REQUIREMENTS")
+    para("The following conditions are binding upon the operator as a condition of this authorization. Failure to comply with any condition may result in suspension, revocation, or non-renewal of this document.")
+    pdf.set_font("Helvetica", "", 9)
+    for i, cond in enumerate(doc["conditions"], 1):
+        for j, line in enumerate(textwrap.wrap(_safe(f"{i}. {cond}"), width=98)):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+    pdf.ln(1)
+    # Additional general conditions
+    general_conditions = [
+        f"The operator must notify {doc['issuing_authority']} within 5 business days of any change in ownership, management, or facility address.",
+        "All required inspections must be scheduled and completed within the timeframes specified by the issuing authority.",
+        "This authorization is subject to revocation at any time if the facility fails to maintain compliance with applicable laws.",
+        "The operator must maintain all required records and make them available for inspection upon request with no prior notice.",
+    ]
+    pdf.set_font("Helvetica", "B", 9)
+    pdf.cell(0, 5, "  General Conditions Applicable to All Authorizations:", new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 9)
+    for i, cond in enumerate(general_conditions, len(doc["conditions"]) + 1):
+        for j, line in enumerate(textwrap.wrap(_safe(f"{i}. {cond}"), width=98)):
+            pdf.cell(0, 5, f"  {line}", new_x="LMARGIN", new_y="NEXT")
+        pdf.ln(1)
+
+    # ── Section 4: Inspection History ────────────────────────────────────────
+    section("IV. COMPLIANCE & INSPECTION HISTORY")
+    from datetime import date as date_cls
+    issue_dt = date_cls.fromisoformat(doc["issue_date"])
+    history = random.sample(INSPECTION_HISTORY_POOL, 4)
+    history.sort(key=lambda x: x[1])
+    pdf.set_font("Helvetica", "B", 8)
+    pdf.set_fill_color(230, 245, 230)
+    pdf.cell(35, 6, "Date", fill=True, border=1)
+    pdf.cell(55, 6, "Inspection Type", fill=True, border=1)
+    pdf.cell(30, 6, "Outcome", fill=True, border=1)
+    pdf.cell(0, 6, "Notes", fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "", 8)
+    fill = False
+    for h_type, h_days, h_outcome, h_notes in history:
+        h_date = issue_dt + timedelta(days=h_days)
+        pdf.set_fill_color(248, 250, 248) if fill else pdf.set_fill_color(255, 255, 255)
+        pdf.cell(35, 5.5, h_date.strftime("%b %d, %Y"), fill=True, border=1)
+        pdf.cell(55, 5.5, _safe(h_type), fill=True, border=1)
+        pdf.cell(30, 5.5, _safe(h_outcome), fill=True, border=1)
+        pdf.cell(0, 5.5, _safe(h_notes), fill=True, border=1, new_x="LMARGIN", new_y="NEXT")
+        fill = not fill
+    pdf.ln(3)
+
+    # ── Section 5: Required Postings ──────────────────────────────────────────
+    section("V. REQUIRED POSTINGS & RECORDKEEPING")
+    para("The following items must be posted or maintained at the facility in accordance with applicable law:")
+    pdf.set_font("Helvetica", "", 9)
+    for item in REQUIRED_POSTINGS:
+        pdf.cell(0, 5, _safe(f"  - {item}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(2)
+
+    # ── Section 6: Renewal Information ───────────────────────────────────────
+    section("VI. RENEWAL & EXPIRATION INFORMATION")
+    expiry_dt = date_cls.fromisoformat(doc["expiry_date"])
+    days_remaining = (expiry_dt - issue_dt).days
+    renewal_notice = max(30, days_remaining // 4)
+    para(
+        f"This authorization expires on {doc['expiry_date']}. To ensure uninterrupted operation, a renewal "
+        f"application must be submitted to {doc['issuing_authority']} no later than {renewal_notice} days prior "
+        f"to the expiration date. Renewal may require a pre-renewal inspection. Operating without a valid, "
+        f"current authorization is a violation subject to administrative penalty and/or immediate closure."
+    )
+    para(
+        f"Renewal fees are subject to the current fee schedule published by {doc['issuing_authority']}. The "
+        f"operator should contact the issuing authority to confirm the applicable fee and required documentation "
+        f"for the renewal application at least {renewal_notice + 15} days prior to expiration."
+    )
+
+    # ── Section 7: Appeal Rights ──────────────────────────────────────────────
+    section("VII. APPEAL RIGHTS & ENFORCEMENT")
+    para(
+        f"The operator has the right to appeal any conditions, restrictions, or adverse actions taken with respect "
+        f"to this authorization. Appeals must be submitted in writing to the administrative appeals division of "
+        f"{doc['issuing_authority']} within 10 business days of the date of this document or any notice of "
+        f"adverse action. The appeal must state the specific grounds for appeal and include supporting documentation."
+    )
+    para(
+        f"Violations of the conditions of this authorization or applicable regulations may result in: (1) written "
+        f"notice of violation and opportunity to cure; (2) administrative fine up to $5,000 per violation per day; "
+        f"(3) suspension of this authorization pending corrective action; or (4) revocation of this authorization "
+        f"and prohibition on reapplication for a period not to exceed two years."
+    )
+
+    # ── Section 8: Compliance Statement ──────────────────────────────────────
+    section("VIII. OFFICIAL COMPLIANCE STATEMENT")
+    para(
+        f"Casper's Kitchens -- {doc['location_name']}, located at {doc['address']}, has been reviewed by "
+        f"authorized representatives of {doc['issuing_authority']} and found to be in compliance with all "
+        f"applicable requirements as of the issue date stated herein. This document constitutes official "
+        f"authorization to operate in accordance with the terms and conditions specified above until the "
+        f"expiry date, provided that the operator maintains continuous compliance."
+    )
+
+    # ── Signature Block ───────────────────────────────────────────────────────
+    pdf.ln(8)
+    pdf.set_line_width(0.3)
+    pdf.line(10, pdf.get_y(), 100, pdf.get_y())
+    pdf.set_font("Helvetica", "", 9)
+    pdf.ln(2)
+    pdf.cell(0, 5, _safe(doc["inspector"]), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(doc["issuing_authority"]), new_x="LMARGIN", new_y="NEXT")
+    pdf.cell(0, 5, _safe(f"Date Issued: {doc['issue_date']}"), new_x="LMARGIN", new_y="NEXT")
+    pdf.set_font("Helvetica", "I", 8)
+    pdf.ln(2)
+    pdf.cell(0, 5, "This is an official regulatory document. Any alteration, forgery, or unauthorized reproduction renders this document void.", new_x="LMARGIN", new_y="NEXT")
+
+    out_path = PDF_DIR / f"regulatory_{doc['doc_id'].replace('-', '_').lower()}.pdf"
+    pdf.output(str(out_path))
+    return str(out_path)
+
+
+def main():
+    PDF_DIR.mkdir(parents=True, exist_ok=True)
+    docs = generate_regulatory_data()
+
+    for doc in docs:
+        path = generate_pdf(doc)
+        print(f"  Generated: {path}")
+
+    with open(METADATA_PATH, "w") as f:
+        json.dump({"regulatory_docs": docs, "locations": LOCATIONS}, f, indent=2)
+    print(f"  Metadata: {METADATA_PATH}")
+    print(f"\nDone! Generated {len(docs)} regulatory documents.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/data/regulatory/pdfs/regulatory_reg_01_2001.pdf b/data/regulatory/pdfs/regulatory_reg_01_2001.pdf
new file mode 100644
index 0000000..e3ccb9b
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_01_2001.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_01_2002.pdf b/data/regulatory/pdfs/regulatory_reg_01_2002.pdf
new file mode 100644
index 0000000..eefb768
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_01_2002.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_01_2003.pdf b/data/regulatory/pdfs/regulatory_reg_01_2003.pdf
new file mode 100644
index 0000000..4429f83
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_01_2003.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_01_2004.pdf b/data/regulatory/pdfs/regulatory_reg_01_2004.pdf
new file mode 100644
index 0000000..d4b724f
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_01_2004.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_01_2005.pdf b/data/regulatory/pdfs/regulatory_reg_01_2005.pdf
new file mode 100644
index 0000000..0a870ac
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_01_2005.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_02_2006.pdf b/data/regulatory/pdfs/regulatory_reg_02_2006.pdf
new file mode 100644
index 0000000..2cff340
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_02_2006.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_02_2007.pdf b/data/regulatory/pdfs/regulatory_reg_02_2007.pdf
new file mode 100644
index 0000000..1761069
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_02_2007.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_02_2008.pdf b/data/regulatory/pdfs/regulatory_reg_02_2008.pdf
new file mode 100644
index 0000000..4344fe7
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_02_2008.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_02_2009.pdf b/data/regulatory/pdfs/regulatory_reg_02_2009.pdf
new file mode 100644
index 0000000..78c9cb8
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_02_2009.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_02_2010.pdf b/data/regulatory/pdfs/regulatory_reg_02_2010.pdf
new file mode 100644
index 0000000..cccfca8
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_02_2010.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_03_2011.pdf b/data/regulatory/pdfs/regulatory_reg_03_2011.pdf
new file mode 100644
index 0000000..c30f82f
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_03_2011.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_03_2012.pdf b/data/regulatory/pdfs/regulatory_reg_03_2012.pdf
new file mode 100644
index 0000000..cd60e84
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_03_2012.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_03_2013.pdf b/data/regulatory/pdfs/regulatory_reg_03_2013.pdf
new file mode 100644
index 0000000..e3f3136
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_03_2013.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_03_2014.pdf b/data/regulatory/pdfs/regulatory_reg_03_2014.pdf
new file mode 100644
index 0000000..9f609c6
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_03_2014.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_03_2015.pdf b/data/regulatory/pdfs/regulatory_reg_03_2015.pdf
new file mode 100644
index 0000000..2146deb
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_03_2015.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_04_2016.pdf b/data/regulatory/pdfs/regulatory_reg_04_2016.pdf
new file mode 100644
index 0000000..5bbf075
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_04_2016.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_04_2017.pdf b/data/regulatory/pdfs/regulatory_reg_04_2017.pdf
new file mode 100644
index 0000000..7ebbfd1
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_04_2017.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_04_2018.pdf b/data/regulatory/pdfs/regulatory_reg_04_2018.pdf
new file mode 100644
index 0000000..e209baf
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_04_2018.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_04_2019.pdf b/data/regulatory/pdfs/regulatory_reg_04_2019.pdf
new file mode 100644
index 0000000..15497e6
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_04_2019.pdf differ
diff --git a/data/regulatory/pdfs/regulatory_reg_04_2020.pdf b/data/regulatory/pdfs/regulatory_reg_04_2020.pdf
new file mode 100644
index 0000000..3061860
Binary files /dev/null and b/data/regulatory/pdfs/regulatory_reg_04_2020.pdf differ
diff --git a/data/regulatory/regulatory_metadata.json b/data/regulatory/regulatory_metadata.json
new file mode 100644
index 0000000..63bbe87
--- /dev/null
+++ b/data/regulatory/regulatory_metadata.json
@@ -0,0 +1,446 @@
+{
+  "regulatory_docs": [
+    {
+      "doc_id": "REG-01-2001",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "city": "San Francisco",
+      "state": "CA",
+      "doc_type": "Food Service Establishment Permit",
+      "issuing_authority": "San Francisco Department of Public Health",
+      "issue_date": "2023-09-24",
+      "expiry_date": "2024-03-22",
+      "status": "APPROVED \u2013 Active",
+      "conditions": [
+        "Facility must maintain compliance with all applicable food safety regulations.",
+        "Any change to menu, ownership, or facility layout requires prior approval.",
+        "Permit must be posted in a conspicuous location visible to the public.",
+        "Annual renewal required by permit expiration date."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-01-2002",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "city": "San Francisco",
+      "state": "CA",
+      "doc_type": "Fire Safety & Occupancy Certificate",
+      "issuing_authority": "San Francisco Fire Department",
+      "issue_date": "2023-09-21",
+      "expiry_date": "2025-09-20",
+      "status": "ISSUED",
+      "conditions": [
+        "Maximum occupancy of 45 persons including staff at all times.",
+        "Monthly testing of fire suppression system required.",
+        "Annual fire safety training mandatory for all kitchen staff.",
+        "Exit routes must remain unobstructed at all times."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-01-2003",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "city": "San Francisco",
+      "state": "CA",
+      "doc_type": "Zoning Compliance Letter",
+      "issuing_authority": "SF Planning Department",
+      "issue_date": "2023-09-23",
+      "expiry_date": "2024-09-22",
+      "status": "UNDER REVIEW",
+      "conditions": [
+        "Use limited to food service and preparation (ghost kitchen operations).",
+        "Delivery vehicle access restricted to rear alley between 6AM\u201310PM.",
+        "Exterior signage must comply with Municipal Code \u00a7 136.3.",
+        "On-site dining is not permitted under ghost kitchen classification."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-01-2004",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "city": "San Francisco",
+      "state": "CA",
+      "doc_type": "FDA Food Facility Registration",
+      "issuing_authority": "San Francisco Department of Public Health",
+      "issue_date": "2023-12-08",
+      "expiry_date": "2024-12-07",
+      "status": "REGISTERED \u2013 Biennial Renewal Due",
+      "conditions": [
+        "Registration under 21 CFR Part 1, Subpart H \u2014 Food Facilities.",
+        "Facility must allow FDA inspection upon request with no prior notice.",
+        "Any changes to facility, processes, or products must be reported within 60 days.",
+        "FSMA Preventive Controls Rule compliance required."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-01-2005",
+      "location_id": 1,
+      "location_name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "city": "San Francisco",
+      "state": "CA",
+      "doc_type": "Food Handler Certification \u2014 Corporate Compliance",
+      "issuing_authority": "San Francisco Department of Public Health",
+      "issue_date": "2023-12-19",
+      "expiry_date": "2025-12-18",
+      "status": "IN COMPLIANCE",
+      "conditions": [
+        "All food handlers must hold a current food handler certificate.",
+        "Certified Food Manager must be present during all operating hours.",
+        "Certificates expire every 3 years; renewal training required.",
+        "Records of all certifications must be maintained on-site."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-02-2006",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "city": "Santa Clara",
+      "state": "CA",
+      "doc_type": "Food Service Establishment Permit",
+      "issuing_authority": "Santa Clara County Environmental Health",
+      "issue_date": "2023-09-11",
+      "expiry_date": "2024-03-09",
+      "status": "RENEWAL PENDING",
+      "conditions": [
+        "Facility must maintain compliance with all applicable food safety regulations.",
+        "Any change to menu, ownership, or facility layout requires prior approval.",
+        "Permit must be posted in a conspicuous location visible to the public.",
+        "Annual renewal required by permit expiration date."
+      ],
+      "inspector": "Regional Compliance Officer"
+    },
+    {
+      "doc_id": "REG-02-2007",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "city": "Santa Clara",
+      "state": "CA",
+      "doc_type": "Fire Safety & Occupancy Certificate",
+      "issuing_authority": "Santa Clara Fire Department",
+      "issue_date": "2023-12-28",
+      "expiry_date": "2024-06-25",
+      "status": "ISSUED",
+      "conditions": [
+        "Maximum occupancy of 45 persons including staff at all times.",
+        "Monthly testing of fire suppression system required.",
+        "Annual fire safety training mandatory for all kitchen staff.",
+        "Exit routes must remain unobstructed at all times."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-02-2008",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "city": "Santa Clara",
+      "state": "CA",
+      "doc_type": "Zoning Compliance Letter",
+      "issuing_authority": "Santa Clara Planning & Inspection",
+      "issue_date": "2023-10-30",
+      "expiry_date": "2024-04-27",
+      "status": "UNDER REVIEW",
+      "conditions": [
+        "Use limited to food service and preparation (ghost kitchen operations).",
+        "Delivery vehicle access restricted to rear alley between 6AM\u201310PM.",
+        "Exterior signage must comply with Municipal Code \u00a7 136.3.",
+        "On-site dining is not permitted under ghost kitchen classification."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-02-2009",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "city": "Santa Clara",
+      "state": "CA",
+      "doc_type": "FDA Food Facility Registration",
+      "issuing_authority": "Santa Clara County Environmental Health",
+      "issue_date": "2023-10-20",
+      "expiry_date": "2024-04-17",
+      "status": "REGISTERED",
+      "conditions": [
+        "Registration under 21 CFR Part 1, Subpart H \u2014 Food Facilities.",
+        "Facility must allow FDA inspection upon request with no prior notice.",
+        "Any changes to facility, processes, or products must be reported within 60 days.",
+        "FSMA Preventive Controls Rule compliance required."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-02-2010",
+      "location_id": 2,
+      "location_name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "city": "Santa Clara",
+      "state": "CA",
+      "doc_type": "Food Handler Certification \u2014 Corporate Compliance",
+      "issuing_authority": "Santa Clara County Environmental Health",
+      "issue_date": "2023-10-14",
+      "expiry_date": "2024-10-13",
+      "status": "PARTIAL COMPLIANCE \u2013 2 Staff Pending Renewal",
+      "conditions": [
+        "All food handlers must hold a current food handler certificate.",
+        "Certified Food Manager must be present during all operating hours.",
+        "Certificates expire every 3 years; renewal training required.",
+        "Records of all certifications must be maintained on-site."
+      ],
+      "inspector": "Regional Compliance Officer"
+    },
+    {
+      "doc_id": "REG-03-2011",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "city": "Bellevue",
+      "state": "WA",
+      "doc_type": "Food Service Establishment Permit",
+      "issuing_authority": "King County Public Health",
+      "issue_date": "2023-09-28",
+      "expiry_date": "2024-09-27",
+      "status": "APPROVED \u2013 Active (Conditional)",
+      "conditions": [
+        "Facility must maintain compliance with all applicable food safety regulations.",
+        "Any change to menu, ownership, or facility layout requires prior approval.",
+        "Permit must be posted in a conspicuous location visible to the public.",
+        "Annual renewal required by permit expiration date."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-03-2012",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "city": "Bellevue",
+      "state": "WA",
+      "doc_type": "Fire Safety & Occupancy Certificate",
+      "issuing_authority": "Bellevue Fire Department",
+      "issue_date": "2023-12-02",
+      "expiry_date": "2025-12-01",
+      "status": "ISSUED",
+      "conditions": [
+        "Maximum occupancy of 45 persons including staff at all times.",
+        "Monthly testing of fire suppression system required.",
+        "Annual fire safety training mandatory for all kitchen staff.",
+        "Exit routes must remain unobstructed at all times."
+      ],
+      "inspector": "Deputy Director of Environmental Health"
+    },
+    {
+      "doc_id": "REG-03-2013",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "city": "Bellevue",
+      "state": "WA",
+      "doc_type": "Zoning Compliance Letter",
+      "issuing_authority": "City of Bellevue Development Services",
+      "issue_date": "2023-12-29",
+      "expiry_date": "2024-06-26",
+      "status": "COMPLIANT",
+      "conditions": [
+        "Use limited to food service and preparation (ghost kitchen operations).",
+        "Delivery vehicle access restricted to rear alley between 6AM\u201310PM.",
+        "Exterior signage must comply with Municipal Code \u00a7 136.3.",
+        "On-site dining is not permitted under ghost kitchen classification."
+      ],
+      "inspector": "Deputy Director of Environmental Health"
+    },
+    {
+      "doc_id": "REG-03-2014",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "city": "Bellevue",
+      "state": "WA",
+      "doc_type": "FDA Food Facility Registration",
+      "issuing_authority": "King County Public Health",
+      "issue_date": "2023-11-19",
+      "expiry_date": "2025-11-18",
+      "status": "REGISTERED",
+      "conditions": [
+        "Registration under 21 CFR Part 1, Subpart H \u2014 Food Facilities.",
+        "Facility must allow FDA inspection upon request with no prior notice.",
+        "Any changes to facility, processes, or products must be reported within 60 days.",
+        "FSMA Preventive Controls Rule compliance required."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-03-2015",
+      "location_id": 3,
+      "location_name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "city": "Bellevue",
+      "state": "WA",
+      "doc_type": "Food Handler Certification \u2014 Corporate Compliance",
+      "issuing_authority": "King County Public Health",
+      "issue_date": "2023-10-24",
+      "expiry_date": "2024-10-23",
+      "status": "IN COMPLIANCE",
+      "conditions": [
+        "All food handlers must hold a current food handler certificate.",
+        "Certified Food Manager must be present during all operating hours.",
+        "Certificates expire every 3 years; renewal training required.",
+        "Records of all certifications must be maintained on-site."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    },
+    {
+      "doc_id": "REG-04-2016",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "city": "Chicago",
+      "state": "IL",
+      "doc_type": "Food Service Establishment Permit",
+      "issuing_authority": "Chicago Department of Public Health",
+      "issue_date": "2023-12-30",
+      "expiry_date": "2025-12-29",
+      "status": "RENEWAL PENDING",
+      "conditions": [
+        "Facility must maintain compliance with all applicable food safety regulations.",
+        "Any change to menu, ownership, or facility layout requires prior approval.",
+        "Permit must be posted in a conspicuous location visible to the public.",
+        "Annual renewal required by permit expiration date."
+      ],
+      "inspector": "Regional Compliance Officer"
+    },
+    {
+      "doc_id": "REG-04-2017",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "city": "Chicago",
+      "state": "IL",
+      "doc_type": "Fire Safety & Occupancy Certificate",
+      "issuing_authority": "Chicago Fire Department",
+      "issue_date": "2023-12-12",
+      "expiry_date": "2025-12-11",
+      "status": "ISSUED",
+      "conditions": [
+        "Maximum occupancy of 45 persons including staff at all times.",
+        "Monthly testing of fire suppression system required.",
+        "Annual fire safety training mandatory for all kitchen staff.",
+        "Exit routes must remain unobstructed at all times."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-04-2018",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "city": "Chicago",
+      "state": "IL",
+      "doc_type": "Zoning Compliance Letter",
+      "issuing_authority": "Chicago Department of Buildings",
+      "issue_date": "2023-09-15",
+      "expiry_date": "2025-09-14",
+      "status": "UNDER REVIEW",
+      "conditions": [
+        "Use limited to food service and preparation (ghost kitchen operations).",
+        "Delivery vehicle access restricted to rear alley between 6AM\u201310PM.",
+        "Exterior signage must comply with Municipal Code \u00a7 136.3.",
+        "On-site dining is not permitted under ghost kitchen classification."
+      ],
+      "inspector": "Fire Marshal, District 7"
+    },
+    {
+      "doc_id": "REG-04-2019",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "city": "Chicago",
+      "state": "IL",
+      "doc_type": "FDA Food Facility Registration",
+      "issuing_authority": "Chicago Department of Public Health",
+      "issue_date": "2023-11-16",
+      "expiry_date": "2024-11-15",
+      "status": "REGISTERED \u2013 Biennial Renewal Due",
+      "conditions": [
+        "Registration under 21 CFR Part 1, Subpart H \u2014 Food Facilities.",
+        "Facility must allow FDA inspection upon request with no prior notice.",
+        "Any changes to facility, processes, or products must be reported within 60 days.",
+        "FSMA Preventive Controls Rule compliance required."
+      ],
+      "inspector": "Deputy Director of Environmental Health"
+    },
+    {
+      "doc_id": "REG-04-2020",
+      "location_id": 4,
+      "location_name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "city": "Chicago",
+      "state": "IL",
+      "doc_type": "Food Handler Certification \u2014 Corporate Compliance",
+      "issuing_authority": "Chicago Department of Public Health",
+      "issue_date": "2023-09-22",
+      "expiry_date": "2025-09-21",
+      "status": "PARTIAL COMPLIANCE \u2013 2 Staff Pending Renewal",
+      "conditions": [
+        "All food handlers must hold a current food handler certificate.",
+        "Certified Food Manager must be present during all operating hours.",
+        "Certificates expire every 3 years; renewal training required.",
+        "Records of all certifications must be maintained on-site."
+      ],
+      "inspector": "Senior Zoning Administrator"
+    }
+  ],
+  "locations": [
+    {
+      "location_id": 1,
+      "name": "San Francisco",
+      "address": "1847 Market Street, San Francisco, CA 94103",
+      "state": "CA",
+      "city": "San Francisco",
+      "health_dept": "San Francisco Department of Public Health",
+      "fire_dept": "San Francisco Fire Department",
+      "zoning_office": "SF Planning Department"
+    },
+    {
+      "location_id": 2,
+      "name": "Silicon Valley",
+      "address": "2350 El Camino Real, Santa Clara, CA 95051",
+      "state": "CA",
+      "city": "Santa Clara",
+      "health_dept": "Santa Clara County Environmental Health",
+      "fire_dept": "Santa Clara Fire Department",
+      "zoning_office": "Santa Clara Planning & Inspection"
+    },
+    {
+      "location_id": 3,
+      "name": "Bellevue",
+      "address": "10456 NE 8th Street, Bellevue, WA 98004",
+      "state": "WA",
+      "city": "Bellevue",
+      "health_dept": "King County Public Health",
+      "fire_dept": "Bellevue Fire Department",
+      "zoning_office": "City of Bellevue Development Services"
+    },
+    {
+      "location_id": 4,
+      "name": "Chicago",
+      "address": "872 N. Milwaukee Avenue, Chicago, IL 60642",
+      "state": "IL",
+      "city": "Chicago",
+      "health_dept": "Chicago Department of Public Health",
+      "fire_dept": "Chicago Fire Department",
+      "zoning_office": "Chicago Department of Buildings"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/databricks.yml b/databricks.yml
index 57573ab..73ce2b8 100644
--- a/databricks.yml
+++ b/databricks.yml
@@ -17,48 +17,72 @@ sync:
   include:
     - ./*
   exclude:
+    # Repo / tooling
     - .git/**
     - .DS_Store
     - .claude/**
     - .databricks/**
     - .venv/**
     - .bundle/**
-    - ./data/universe/**
     - __pycache__/**
     - "*.pyc"
+    # Repo content we never want shipped
     - images/**
     - docs/**
-    - apps/caspersai-terminal/node_modules/**
+    # Per-app build artifacts (anywhere under apps/)
+    - apps/**/.databricks/**
+    - apps/**/node_modules/**
+    - apps/**/dist/**
+    # App-specific files
+    - apps/caspers-ops-dashboard/app.yaml
     - apps/caspersai-terminal/logs/**
     - apps/caspersai-terminal/test/**
-    - apps/supportconsolek/**/.databricks/**
-    - apps/supportconsolek/**/node_modules/**
-    - apps/supportconsolek/**/dist/**
 
 scripts:
   cleanup:
+    # Cleanup is a bundle SCRIPT (not a job task), so it accepts bundle
+    # variable overrides — NOT job task `--params`.  Supported ways to
+    # specify the catalog to clean:
+    #
+    #   BUNDLE_VAR_catalog=mycatalog databricks bundle run cleanup -t <target>
+    #
+    # Note: `--var catalog=X` on `bundle run cleanup` does NOT propagate into
+    # this shell script (the CLI does not export BUNDLE_VAR_* to script
+    # subprocesses).  Use the inline BUNDLE_VAR_catalog= form above, or the
+    # nested `bundle validate` below falls back to the last deploy-time catalog
+    # or the default `caspersdev`.
+    #
+    # The `--params "CATALOG=..."` syntax (used for `bundle run caspers`)
+    # is silently ignored by this script — the CLI only forwards `--params`
+    # to job tasks, never to scripts.  If you omit BUNDLE_VAR_catalog, the
+    # script falls back to the catalog from the last `bundle deploy --var`
+    # deploy (or to `var.catalog`'s default), which may not be what you
+    # want.  The "Cleaning up catalog: <name>" line below is your last
+    # chance to confirm before resources are deleted.
     content: |
       set -eo pipefail
 
       # Detect the target passed to `databricks bundle run cleanup -t <target>`
       TARGET_FLAG=""
-      if env | grep -q '^DATABRICKS_BUNDLE_TARGET='; then
+      if [ -n "$DATABRICKS_BUNDLE_TARGET" ]; then
         TARGET_FLAG="-t $DATABRICKS_BUNDLE_TARGET"
       fi
 
-      # Get fully-resolved bundle config (includes target overrides)
-      RESOLVED_JSON="$(databricks bundle validate $TARGET_FLAG --output json)"
+      # Forward BUNDLE_VAR_catalog into nested validate.  (`bundle run --var`
+      # does not set BUNDLE_VAR_* in the script env — use
+      # `BUNDLE_VAR_catalog=X bundle run cleanup` on the command line.)
+      VAR_FLAG=""
+      if [ -n "$BUNDLE_VAR_catalog" ]; then
+        VAR_FLAG="--var catalog=$BUNDLE_VAR_catalog"
+      fi
 
-      # Pull values we need (requires jq)
-      FILE_PATH="$(printf '%s' "$RESOLVED_JSON" | jq -r '.workspace.file_path // (.workspace.root_path + "/src")')"
+      RESOLVED_JSON="$(databricks bundle validate $TARGET_FLAG $VAR_FLAG --output json)"
 
+      FILE_PATH="$(printf '%s' "$RESOLVED_JSON" | jq -r '.workspace.file_path // (.workspace.root_path + "/src")')"
       CATALOG="$(printf '%s' "$RESOLVED_JSON" | jq -r '.variables.catalog.value // .variables.catalog.default')"
-      ENV_CATALOG="$(printenv BUNDLE_VAR_catalog 2>/dev/null || true)"
-      if [ -n "$ENV_CATALOG" ]; then
-        CATALOG="$ENV_CATALOG"
-      fi
 
       echo "Cleaning up catalog: $CATALOG"
+      echo "  (override with: BUNDLE_VAR_catalog=<name> databricks bundle run cleanup -t <target>)"
 
       mkdir -p .bundle
       cat > .bundle/submit.json <<JSON
@@ -81,6 +105,9 @@ scripts:
 
 
 targets:
+  # ─────────────────────────────────────────────────────────────────────────────
+  # default — focused refund demo (refund recommender + reverse-ETL + manager app)
+  # ─────────────────────────────────────────────────────────────────────────────
   default:
     default: true
 
@@ -97,8 +124,29 @@ targets:
               default: ${var.catalog}
             - name: EVENTS_VOLUME
               default: events
+            # Switched off `databricks-meta-llama-3-3-70b-instruct` because it is
+            # the most heavily contended shared FMAPI endpoint in every workspace
+            # — agent eval + DSPy CoT bursts + the two `ai_gen()` generator
+            # crons + everyone else on the workspace consistently push the
+            # shared QPS bucket over its ceiling, surfacing as
+            # REQUEST_LIMIT_EXCEEDED (429) during the Refund/Complaint agent
+            # tasks even with eval concurrency pinned to 1.  Claude Sonnet 4.5
+            # has a separate per-endpoint QPS bucket, equivalent or better
+            # tool-use / structured-output quality, and is OpenAI-compatible
+            # so DSPy / `ai_gen()` / OpenAI client UDFs all keep working
+            # without code changes.  Override at run time with
+            # `--params "LLM_MODEL=..."` if you need a specific model.
             - name: LLM_MODEL
-              default: databricks-meta-llama-3-3-70b-instruct
+              default: databricks-claude-sonnet-4-5
+            # Eval is opt-in: it's a quality-measurement burst of ~30-50 LM
+            # calls in tight succession and was the dominant 429 source even
+            # with eval concurrency pinned to 1.  Deploy / register / endpoint
+            # readiness checks only burn ~1-2 calls and run fine.  Flip to
+            # "false" when you specifically want to measure agent quality:
+            #   databricks bundle run caspers -t all \
+            #     --params "CATALOG=oleksandra,SKIP_EVAL=false"
+            - name: SKIP_EVAL
+              default: "true"
             - name: REFUND_AGENT_ENDPOINT_NAME
               default: ${var.catalog}_refund_agent
             - name: SIMULATOR_SCHEMA
@@ -117,6 +165,16 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/canonical_data
 
+            # Shared Lakebase Autoscaling project.  Runs early in parallel with
+            # the data pipeline so the synced-table create downstream has its
+            # destination project ready when needed.  All Lakebase-consuming
+            # tasks depend on this stage; per-component logical databases
+            # (caspers_refund, caspers_complaint, caspers_ops) are created by
+            # their own stages inside this single project.
+            - task_key: Lakebase_Project
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/lakebase_project
+
             - task_key: Spark_Declarative_Pipeline
               depends_on:
                 - task_key: Canonical_Data
@@ -129,15 +187,46 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/refunder_agent
 
+            # Refund_Setup builds the curated eval dataset and registers it in
+            # UC at {CATALOG}.evaluations.refund_agent_eval_dataset.  Always
+            # runs (not gated by SKIP_EVAL) so the dataset is visible in
+            # Catalog Explorer after every deploy, even when Refund_Evaluation
+            # is skipped.  Built inline by the demo notebook, eval is run by Refund_Evaluation / Complaint_Evaluation.
+            - task_key: Refund_Setup
+              max_retries: 0
+              depends_on:
+                - task_key: Refund_Recommender_Agent
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/refund_setup
+
+            # Refund_Evaluation runs the deployed agent against the UC-managed
+            # eval dataset registered by Refund_Setup.  Gated by SKIP_EVAL=true
+            # (default), so this task shows up as "skipped" in the DAG unless a
+            # user opts in via --params "SKIP_EVAL=false".  See stages/refund_evaluation.
+            - task_key: Refund_Evaluation
+              max_retries: 0
+              depends_on:
+                - task_key: Refund_Setup
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/refund_evaluation
+
+            # Refund_Recommender_Stream calls w.jobs.run_now() on the
+            # streaming inference job whose UDF queries the Refund agent
+            # serving endpoint.  The endpoint must exist and be READY before
+            # the stream's first batch fires — without the explicit
+            # Refund_Recommender_Agent edge the two tasks race and the
+            # stream can hit a missing endpoint.
             - task_key: Refund_Recommender_Stream
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
+                - task_key: Refund_Recommender_Agent
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/refunder_stream
 
             - task_key: Lakebase_Reverse_ETL
               depends_on:
                 - task_key: Refund_Recommender_Stream
+                - task_key: Lakebase_Project
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/lakebase
 
@@ -147,6 +236,9 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/apps
 
+  # ─────────────────────────────────────────────────────────────────────────────
+  # complaints — focused complaints demo
+  # ─────────────────────────────────────────────────────────────────────────────
   complaints:
     resources:
       jobs:
@@ -161,8 +253,29 @@ targets:
               default: ${var.catalog}
             - name: EVENTS_VOLUME
               default: events
+            # Switched off `databricks-meta-llama-3-3-70b-instruct` because it is
+            # the most heavily contended shared FMAPI endpoint in every workspace
+            # — agent eval + DSPy CoT bursts + the two `ai_gen()` generator
+            # crons + everyone else on the workspace consistently push the
+            # shared QPS bucket over its ceiling, surfacing as
+            # REQUEST_LIMIT_EXCEEDED (429) during the Refund/Complaint agent
+            # tasks even with eval concurrency pinned to 1.  Claude Sonnet 4.5
+            # has a separate per-endpoint QPS bucket, equivalent or better
+            # tool-use / structured-output quality, and is OpenAI-compatible
+            # so DSPy / `ai_gen()` / OpenAI client UDFs all keep working
+            # without code changes.  Override at run time with
+            # `--params "LLM_MODEL=..."` if you need a specific model.
             - name: LLM_MODEL
-              default: databricks-meta-llama-3-3-70b-instruct
+              default: databricks-claude-sonnet-4-5
+            # Eval is opt-in: it's a quality-measurement burst of ~30-50 LM
+            # calls in tight succession and was the dominant 429 source even
+            # with eval concurrency pinned to 1.  Deploy / register / endpoint
+            # readiness checks only burn ~1-2 calls and run fine.  Flip to
+            # "false" when you specifically want to measure agent quality:
+            #   databricks bundle run caspers -t all \
+            #     --params "CATALOG=oleksandra,SKIP_EVAL=false"
+            - name: SKIP_EVAL
+              default: "true"
             - name: COMPLAINT_AGENT_ENDPOINT_NAME
               default: ${var.catalog}_complaint_agent
             - name: COMPLAINT_RATE
@@ -183,6 +296,11 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/canonical_data
 
+            # Shared Lakebase Autoscaling project (see comment under default).
+            - task_key: Lakebase_Project
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/lakebase_project
+
             - task_key: Spark_Declarative_Pipeline
               depends_on:
                 - task_key: Canonical_Data
@@ -195,6 +313,29 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/complaint_agent
 
+            # Complaint_Setup builds the curated eval dataset and registers it
+            # in UC at {CATALOG}.evaluations.complaint_agent_eval_dataset.
+            # Always runs (not gated by SKIP_EVAL) so the dataset is visible in
+            # Catalog Explorer after every deploy, even when Complaint_Evaluation
+            # is skipped.  Built inline by the demo notebook, eval is run by Refund_Evaluation / Complaint_Evaluation.
+            - task_key: Complaint_Setup
+              max_retries: 0
+              depends_on:
+                - task_key: Complaint_Agent
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/complaint_setup
+
+            # Complaint_Evaluation runs the deployed agent against the UC-managed
+            # eval dataset registered by Complaint_Setup.  Gated by SKIP_EVAL=true
+            # (default), so this task shows up as "skipped" in the DAG unless a
+            # user opts in via --params "SKIP_EVAL=false".  See stages/complaint_evaluation.
+            - task_key: Complaint_Evaluation
+              max_retries: 0
+              depends_on:
+                - task_key: Complaint_Setup
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/complaint_evaluation
+
             - task_key: Complaint_Generator_Stream
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
@@ -211,9 +352,13 @@ targets:
             - task_key: Complaint_Lakebase
               depends_on:
                 - task_key: Complaint_Agent_Stream
+                - task_key: Lakebase_Project
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/complaint_lakebase
 
+  # ─────────────────────────────────────────────────────────────────────────────
+  # free — minimal demo (canonical data + Spark Declarative Pipeline only)
+  # ─────────────────────────────────────────────────────────────────────────────
   free:
     resources:
       jobs:
@@ -250,98 +395,9 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/lakeflow
 
-  menus:
-    resources:
-      jobs:
-        caspers:
-          name: "Casper's Initializer"
-          queue:
-            enabled: true
-          performance_target: PERFORMANCE_OPTIMIZED
-
-          parameters:
-            - name: CATALOG
-              default: ${var.catalog}
-            - name: EVENTS_VOLUME
-              default: events
-            - name: LLM_MODEL
-              default: databricks-meta-llama-3-3-70b-instruct
-            - name: REFUND_AGENT_ENDPOINT_NAME
-              default: ${var.catalog}_refund_agent
-            - name: MENU_KNOWLEDGE_ENDPOINT_NAME
-              default: ${var.catalog}_menu_knowledge
-            - name: INSPECTION_KNOWLEDGE_ENDPOINT_NAME
-              default: ${var.catalog}_inspection_knowledge
-            - name: MENU_SUPERVISOR_ENDPOINT_NAME
-              default: ${var.catalog}_menu_supervisor
-            - name: SIMULATOR_SCHEMA
-              default: simulator
-            - name: START_DAY
-              default: "70"
-            - name: SPEED_MULTIPLIER
-              default: "60.0"
-            - name: SCHEDULE_MINUTES
-              default: "3"
-            - name: PIPELINE_SCHEDULE_MINUTES
-              default: "0"
-
-          tasks:
-            - task_key: Canonical_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/canonical_data
-
-            - task_key: Menu_Data
-              max_retries: 0
-              depends_on:
-                - task_key: Canonical_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_data
-
-            - task_key: Inspection_Data
-              max_retries: 0
-              depends_on:
-                - task_key: Canonical_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/inspection_data
-
-            - task_key: Menu_Pipeline
-              max_retries: 0
-              depends_on:
-                - task_key: Menu_Data
-                - task_key: Inspection_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_pipeline
-
-            - task_key: Menu_Genie
-              max_retries: 0
-              depends_on:
-                - task_key: Menu_Pipeline
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_genie
-
-            - task_key: Menu_Knowledge_Agent
-              max_retries: 0
-              depends_on:
-                - task_key: Menu_Pipeline
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_knowledge_agent
-
-            - task_key: Inspection_Knowledge_Agent
-              max_retries: 0
-              depends_on:
-                - task_key: Inspection_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/inspection_knowledge_agent
-
-            - task_key: Menu_Supervisor
-              max_retries: 0
-              depends_on:
-                - task_key: Menu_Genie
-                - task_key: Menu_Knowledge_Agent
-                - task_key: Inspection_Knowledge_Agent
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_supervisor
-
+  # ─────────────────────────────────────────────────────────────────────────────
+  # support — focused customer support agent demo
+  # ─────────────────────────────────────────────────────────────────────────────
   support:
     resources:
       jobs:
@@ -356,8 +412,29 @@ targets:
               default: ${var.catalog}
             - name: EVENTS_VOLUME
               default: events
+            # Switched off `databricks-meta-llama-3-3-70b-instruct` because it is
+            # the most heavily contended shared FMAPI endpoint in every workspace
+            # — agent eval + DSPy CoT bursts + the two `ai_gen()` generator
+            # crons + everyone else on the workspace consistently push the
+            # shared QPS bucket over its ceiling, surfacing as
+            # REQUEST_LIMIT_EXCEEDED (429) during the Refund/Complaint agent
+            # tasks even with eval concurrency pinned to 1.  Claude Sonnet 4.5
+            # has a separate per-endpoint QPS bucket, equivalent or better
+            # tool-use / structured-output quality, and is OpenAI-compatible
+            # so DSPy / `ai_gen()` / OpenAI client UDFs all keep working
+            # without code changes.  Override at run time with
+            # `--params "LLM_MODEL=..."` if you need a specific model.
             - name: LLM_MODEL
-              default: databricks-meta-llama-3-3-70b-instruct
+              default: databricks-claude-sonnet-4-5
+            # Eval is opt-in: it's a quality-measurement burst of ~30-50 LM
+            # calls in tight succession and was the dominant 429 source even
+            # with eval concurrency pinned to 1.  Deploy / register / endpoint
+            # readiness checks only burn ~1-2 calls and run fine.  Flip to
+            # "false" when you specifically want to measure agent quality:
+            #   databricks bundle run caspers -t all \
+            #     --params "CATALOG=oleksandra,SKIP_EVAL=false"
+            - name: SKIP_EVAL
+              default: "true"
             - name: SUPPORT_AGENT_ENDPOINT_NAME
               default: ${var.catalog}_support_agent
             - name: SUPPORT_RATE
@@ -396,9 +473,14 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/support_request_agent
 
+            # Support_Request_Agent_Stream's UDF calls the Support agent
+            # serving endpoint, so the endpoint must exist and be READY
+            # before the stream's first batch fires.  Mirrors the
+            # Refund_Recommender_Stream and Complaint_Agent_Stream patterns.
             - task_key: Support_Request_Agent_Stream
               depends_on:
                 - task_key: Support_Request_Generator_Stream
+                - task_key: Support_Request_Agent
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/support_request_agent_stream
 
@@ -408,8 +490,67 @@ targets:
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/support_lakebase
 
+  # ─────────────────────────────────────────────────────────────────────────────
+  # all — comprehensive DAIS demo: refund + complaints + Operational Dashboard
+  # ─────────────────────────────────────────────────────────────────────────────
   all:
     resources:
+      # Ops SQL warehouse.  DABs is the sole owner of this warehouse so that
+      # `bundle deploy -t all` has a stable warehouse id available for the
+      # dashboard at deploy time (no chicken-and-egg with task-run-time
+      # warehouse creation).  Config matches what `stages/operational_app.ipynb`
+      # used to create; the stage was refactored to find-only and uses this
+      # warehouse via name lookup.
+      sql_warehouses:
+        caspers_ops_warehouse:
+          name: ${var.catalog}-ops-warehouse
+          cluster_size: 2X-Small
+          min_num_clusters: 1
+          max_num_clusters: 1
+          # 60 min keeps the warehouse hot through a typical demo session.
+          # At 10 min, the ops dashboard incurred a 30-60s cold-start every
+          # time the presenter stepped away — much worse UX than the small
+          # incremental cost of an idle 2X-Small serverless warehouse.
+          auto_stop_mins: 60
+          enable_serverless_compute: true
+          warehouse_type: PRO
+      # AI/BI dashboards.  Scoped to `all` only because they query schemas
+      # that other targets do not build (complaints, food_safety, recommender,
+      # lakeflow, ai).  Datasets in each JSON are unqualified (`schema.table`)
+      # and `dataset_catalog` injects ${var.catalog} at runtime so the same
+      # JSON works in any catalog.  Both dashboards share the ops warehouse.
+      dashboards:
+        # The Operations dashboard is published in TWO variants — light and
+        # dark — because Databricks embedded dashboards always render in
+        # "light" mode (the `?theme=` URL param is ignored).  The dark
+        # variant bakes dark-palette tokens into the `light` theme slot so
+        # the iframe renders with dark colors.  The frontend swaps the
+        # iframe src when the user toggles the app theme.
+        caspers_ops:
+          display_name: "Casper's Kitchen - Operations (${var.catalog})"
+          file_path: ./resources/dashboards/caspers_kitchen_operations.lvdash.json
+          warehouse_id: ${resources.sql_warehouses.caspers_ops_warehouse.id}
+          dataset_catalog: ${var.catalog}
+        caspers_ops_dark:
+          display_name: "Casper's Kitchen - Operations - Dark (${var.catalog})"
+          file_path: ./resources/dashboards/caspers_kitchen_operations_dark.lvdash.json
+          warehouse_id: ${resources.sql_warehouses.caspers_ops_warehouse.id}
+          dataset_catalog: ${var.catalog}
+        caspers_delivery:
+          display_name: "Casper's Kitchen - Delivery Performance & SLA (${var.catalog})"
+          file_path: ./resources/dashboards/caspers_kitchen_delivery_performance.lvdash.json
+          warehouse_id: ${resources.sql_warehouses.caspers_ops_warehouse.id}
+          dataset_catalog: ${var.catalog}
+        caspers_ai_agent_performance:
+          display_name: "Casper's Kitchen - AI Agent Performance (${var.catalog})"
+          file_path: ./resources/dashboards/caspers_kitchen_ai_agent_performance.lvdash.json
+          warehouse_id: ${resources.sql_warehouses.caspers_ops_warehouse.id}
+          dataset_catalog: ${var.catalog}
+        caspers_menu_intelligence:
+          display_name: "Casper's Kitchen - Menu Intelligence & Nutrition (${var.catalog})"
+          file_path: ./resources/dashboards/caspers_kitchen_menu_intelligence.lvdash.json
+          warehouse_id: ${resources.sql_warehouses.caspers_ops_warehouse.id}
+          dataset_catalog: ${var.catalog}
       jobs:
         caspers:
           name: "Casper's Initializer"
@@ -422,20 +563,29 @@ targets:
               default: ${var.catalog}
             - name: EVENTS_VOLUME
               default: events
+            # Switched off `databricks-meta-llama-3-3-70b-instruct` because it is
+            # the most heavily contended shared FMAPI endpoint in every workspace
+            # — agent eval + DSPy CoT bursts + the two `ai_gen()` generator
+            # crons + everyone else on the workspace consistently push the
+            # shared QPS bucket over its ceiling, surfacing as
+            # REQUEST_LIMIT_EXCEEDED (429) during the Refund/Complaint agent
+            # tasks even with eval concurrency pinned to 1.  Claude Sonnet 4.5
+            # has a separate per-endpoint QPS bucket, equivalent or better
+            # tool-use / structured-output quality, and is OpenAI-compatible
+            # so DSPy / `ai_gen()` / OpenAI client UDFs all keep working
+            # without code changes.  Override at run time with
+            # `--params "LLM_MODEL=..."` if you need a specific model.
             - name: LLM_MODEL
-              default: databricks-meta-llama-3-3-70b-instruct
-            - name: REFUND_AGENT_ENDPOINT_NAME
-              default: ${var.catalog}_refund_agent
-            - name: COMPLAINT_AGENT_ENDPOINT_NAME
-              default: ${var.catalog}_complaint_agent
-            - name: COMPLAINT_RATE
-              default: "0.15"
-            - name: MENU_KNOWLEDGE_ENDPOINT_NAME
-              default: ${var.catalog}_menu_knowledge
-            - name: INSPECTION_KNOWLEDGE_ENDPOINT_NAME
-              default: ${var.catalog}_inspection_knowledge
-            - name: MENU_SUPERVISOR_ENDPOINT_NAME
-              default: ${var.catalog}_menu_supervisor
+              default: databricks-claude-sonnet-4-5
+            # Eval is opt-in: it's a quality-measurement burst of ~30-50 LM
+            # calls in tight succession and was the dominant 429 source even
+            # with eval concurrency pinned to 1.  Deploy / register / endpoint
+            # readiness checks only burn ~1-2 calls and run fine.  Flip to
+            # "false" when you specifically want to measure agent quality:
+            #   databricks bundle run caspers -t all \
+            #     --params "CATALOG=oleksandra,SKIP_EVAL=false"
+            - name: SKIP_EVAL
+              default: "true"
             - name: SIMULATOR_SCHEMA
               default: simulator
             - name: START_DAY
@@ -446,36 +596,188 @@ targets:
               default: "3"
             - name: PIPELINE_SCHEDULE_MINUTES
               default: "0"
+            # Refund + complaints
+            - name: REFUND_AGENT_ENDPOINT_NAME
+              default: ${var.catalog}_refund_agent
+            - name: COMPLAINT_AGENT_ENDPOINT_NAME
+              default: ${var.catalog}_complaint_agent
+            - name: COMPLAINT_RATE
+              default: "0.15"
+            # Unity AI Gateway (v2 Beta) endpoint name.  When set, the
+            # Refund + Complaint agents route their internal LLM calls
+            # through this gateway instead of the foundation-model
+            # endpoint named by LLM_MODEL — so every agent LLM call
+            # gets PII guardrails, inference-table audit, usage
+            # tracking and rate limits applied centrally.
+            #
+            # This parameter is only declared on the `all` target —
+            # `default` and `complaints` keep using direct foundation-
+            # model endpoints (no gateway routing).
+            #
+            # The endpoint must be created and configured manually in
+            # the Databricks UI before deploy: AI Gateway → Create
+            # Unity AI Gateway Endpoint → enable Guardrails (PII =
+            # Block, Safety, Jailbreak) + Inference Tables + Usage
+            # Tracking + Rate Limits.  See the "Unity AI Gateway"
+            # section of demos/dais2026-runbooks/SETUP.ipynb for the
+            # full step-by-step.
+            #
+            # Leave empty to keep the agents on direct foundation-model
+            # endpoints (legacy behaviour).
+            - name: AI_GATEWAY_ENDPOINT_NAME
+              default: ""
+            # Operational Dashboard — Knowledge Assistant endpoints are auto-generated
+            # by the KA v2.1 API and resolved from uc_state by downstream stages.
+            # Operational Dashboard — Multi-Agent Supervisor endpoint (user-supplied)
+            - name: SUPERVISOR_ENDPOINT_NAME
+              default: ${var.catalog}_operational_supervisor
+            # Ops warehouse name.  Resolved from `${var.catalog}` at DEPLOY
+            # time and baked into the job-parameter default, so the run-time
+            # value carries the deploy-time catalog even if `--params CATALOG`
+            # disagrees with `--var catalog`.  This is the same pattern used
+            # by REFUND_AGENT_ENDPOINT_NAME / COMPLAINT_AGENT_ENDPOINT_NAME
+            # above (see the rationale comment in stages/operational_app.ipynb
+            # cell 8) and exists for the same reason: the warehouse is owned
+            # by DABs (resources.sql_warehouses.caspers_ops_warehouse above)
+            # so its name is frozen at deploy time, and reconstructing it
+            # from the run-time CATALOG widget would fail whenever the two
+            # dials disagree.
+            - name: OPS_WAREHOUSE_NAME
+              default: ${var.catalog}-ops-warehouse
 
           tasks:
+            # ─── Data foundation ──────────────────────────────────────────────
             - task_key: Canonical_Data
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/canonical_data
 
+            # Shared Lakebase Autoscaling project.  All Lakebase-consuming tasks
+            # (Lakebase_Reverse_ETL, Complaint_Lakebase, Operational_Lakebase)
+            # depend on this.  Per-component logical databases (caspers_refund,
+            # caspers_complaint, caspers_ops) are created by their own stages
+            # inside this single project.
+            - task_key: Lakebase_Project
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/lakebase_project
+
+            # Small post-ingestion environment-population helpers (seed lookup
+            # tables, register helper UDFs, run AI SQL demos on uploaded PDFs,
+            # grant demo-user perms, ABAC tags/UDFs/policies, data-quality
+            # monitors, etc.).  Depends on Canonical_Data for the catalog/
+            # schemas, Document_Data for the food_safety PDF volume that the
+            # AI SQL cells parse, and Spark_Declarative_Pipeline so the
+            # ABAC cells can tag columns on the lakeflow.silver_*/gold_*
+            # tables that the pipeline materialises.  Add new helpers inside
+            # stages/environment_helpers.ipynb; keep each idempotent.
+            - task_key: Environment_Helpers
+              depends_on:
+                - task_key: Canonical_Data
+                - task_key: Document_Data
+                - task_key: Spark_Declarative_Pipeline
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/environment_helpers
+
             - task_key: Spark_Declarative_Pipeline
               depends_on:
                 - task_key: Canonical_Data
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/lakeflow
 
+            # ─── Refund recommender ───────────────────────────────────────────
             - task_key: Refund_Recommender_Agent
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/refunder_agent
 
+            # Refund_Setup builds the curated eval dataset and registers it in
+            # UC at {CATALOG}.evaluations.refund_agent_eval_dataset.  Always
+            # runs (not gated by SKIP_EVAL) so the dataset is visible in
+            # Catalog Explorer after every deploy, even when Refund_Evaluation
+            # is skipped.  Built inline by the demo notebook, eval is run by Refund_Evaluation / Complaint_Evaluation.
+            - task_key: Refund_Setup
+              max_retries: 0
+              depends_on:
+                - task_key: Refund_Recommender_Agent
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/refund_setup
+
+            # Refund_Evaluation runs the deployed agent against the UC-managed
+            # eval dataset registered by Refund_Setup.  Gated by SKIP_EVAL=true
+            # (default), so this task shows up as "skipped" in the DAG unless a
+            # user opts in via --params "SKIP_EVAL=false".  See stages/refund_evaluation.
+            - task_key: Refund_Evaluation
+              max_retries: 0
+              depends_on:
+                - task_key: Refund_Setup
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/refund_evaluation
+
+            # Refund_Recommender_Stream calls w.jobs.run_now() on the
+            # streaming inference job whose UDF queries the Refund agent
+            # serving endpoint.  The endpoint must exist and be READY before
+            # the stream's first batch fires — without the explicit
+            # Refund_Recommender_Agent edge the two tasks race and the
+            # stream can hit a missing endpoint.
             - task_key: Refund_Recommender_Stream
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
+                - task_key: Refund_Recommender_Agent
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/refunder_stream
 
+            - task_key: Lakebase_Reverse_ETL
+              depends_on:
+                - task_key: Refund_Recommender_Stream
+                - task_key: Lakebase_Project
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/lakebase
+
+            - task_key: Databricks_App_Refund_Manager
+              depends_on:
+                - task_key: Lakebase_Reverse_ETL
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/apps
+
+            # ─── Complaints stream ────────────────────────────────────────────
             - task_key: Complaint_Agent
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
+                # Serialized AFTER Refund_Recommender_Agent so the two agents do
+                # not race on the workspace QPS limit for the shared pay-per-token
+                # endpoint `databricks-meta-llama-3-3-70b-instruct` during their
+                # MLflow eval steps.  Under the previous parallel layout, the
+                # combined in-flight request rate consistently triggered
+                # REQUEST_LIMIT_EXCEEDED (429) and the auto-retry hit the same
+                # ceiling, failing the whole `all` run.  Adds ~10 min wall-clock
+                # but eliminates the rate-limit flake.  See review item P1-9.
+                - task_key: Refund_Recommender_Agent
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/complaint_agent
 
+            # Complaint_Setup builds the curated eval dataset and registers it
+            # in UC at {CATALOG}.evaluations.complaint_agent_eval_dataset.
+            # Always runs (not gated by SKIP_EVAL) so the dataset is visible in
+            # Catalog Explorer after every deploy, even when Complaint_Evaluation
+            # is skipped.  Built inline by the demo notebook, eval is run by Refund_Evaluation / Complaint_Evaluation.
+            - task_key: Complaint_Setup
+              max_retries: 0
+              depends_on:
+                - task_key: Complaint_Agent
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/complaint_setup
+
+            # Complaint_Evaluation runs the deployed agent against the UC-managed
+            # eval dataset registered by Complaint_Setup.  Gated by SKIP_EVAL=true
+            # (default), so this task shows up as "skipped" in the DAG unless a
+            # user opts in via --params "SKIP_EVAL=false".  See stages/complaint_evaluation.
+            - task_key: Complaint_Evaluation
+              max_retries: 0
+              depends_on:
+                - task_key: Complaint_Setup
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/complaint_evaluation
+
             - task_key: Complaint_Generator_Stream
               depends_on:
                 - task_key: Spark_Declarative_Pipeline
@@ -492,62 +794,88 @@ targets:
             - task_key: Complaint_Lakebase
               depends_on:
                 - task_key: Complaint_Agent_Stream
+                - task_key: Lakebase_Project
               notebook_task:
                 notebook_path: ${workspace.root_path}/stages/complaint_lakebase
 
-            - task_key: Lakebase_Reverse_ETL
+            # ─── Operational Dashboard: documents → menu pipeline → genie / KA / MAS / app ───
+            - task_key: Document_Data
+              max_retries: 0
               depends_on:
-                - task_key: Refund_Recommender_Stream
+                - task_key: Canonical_Data
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/lakebase
+                notebook_path: ${workspace.root_path}/stages/document_data
 
-            - task_key: Databricks_App_Refund_Manager
+            - task_key: Menu_Pipeline
+              max_retries: 0
               depends_on:
-                - task_key: Lakebase_Reverse_ETL
+                - task_key: Document_Data
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/apps
+                notebook_path: ${workspace.root_path}/stages/menu_pipeline
 
-            - task_key: Menu_Data
+            - task_key: Genie_Spaces
+              max_retries: 0
               depends_on:
-                - task_key: Canonical_Data
+                - task_key: Spark_Declarative_Pipeline
+                - task_key: Menu_Pipeline
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_data
+                notebook_path: ${workspace.root_path}/stages/genie_spaces
 
-            - task_key: Inspection_Data
+            - task_key: Knowledge_Agents
+              max_retries: 0
               depends_on:
-                - task_key: Canonical_Data
+                - task_key: Document_Data
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/inspection_data
+                notebook_path: ${workspace.root_path}/stages/knowledge_agents
 
-            - task_key: Menu_Pipeline
+            - task_key: Operational_Lakebase
+              max_retries: 0
               depends_on:
-                - task_key: Menu_Data
-                - task_key: Inspection_Data
+                - task_key: Canonical_Data
+                - task_key: Lakebase_Project
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_pipeline
+                notebook_path: ${workspace.root_path}/stages/operational_lakebase
 
-            - task_key: Menu_Genie
+            - task_key: Operational_Supervisor
+              max_retries: 0
               depends_on:
-                - task_key: Menu_Pipeline
+                - task_key: Genie_Spaces
+                - task_key: Knowledge_Agents
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_genie
+                notebook_path: ${workspace.root_path}/stages/operational_supervisor
 
-            - task_key: Menu_Knowledge_Agent
+            - task_key: Operational_App
+              max_retries: 0
               depends_on:
-                - task_key: Menu_Pipeline
+                - task_key: Operational_Supervisor
+                - task_key: Operational_Lakebase
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_knowledge_agent
+                notebook_path: ${workspace.root_path}/stages/operational_app
 
-            - task_key: Inspection_Knowledge_Agent
+            - task_key: Readiness_Check
+              max_retries: 0
               depends_on:
-                - task_key: Inspection_Data
-              notebook_task:
-                notebook_path: ${workspace.root_path}/stages/inspection_knowledge_agent
-
-            - task_key: Menu_Supervisor
+                - task_key: Operational_App
+              notebook_task:
+                notebook_path: ${workspace.root_path}/stages/operational_readiness_check
+
+            # Single consolidated evaluation task for managed Agent Bricks
+            # (Supervisor + 6 KAs).  operational_evaluation.ipynb does:
+            #   1. Build the UC-managed supervisor eval dataset inline
+            #   2. Run mlflow.genai.evaluate() against the supervisor
+            #   3. Register production scorers (Scorer.register + .start) on
+            #      /Serving/{SUPERVISOR_ENDPOINT}
+            #   4. Loop over KAs from uc_state, warmup each one, and register
+            #      production scorers on /Serving/{ka_endpoint}
+            # Everything lands in the managed /Serving/{endpoint} experiments
+            # Databricks creates per endpoint — no /Shared/_dev or _prod split.
+            # Refund + Complaint custom agents have their own stage evaluation
+            # notebooks; they're not managed services, so they keep the
+            # /Shared/{cat}_{refund,complaint}_agent_{dev,prod} convention.
+            - task_key: Evaluation
+              max_retries: 0
               depends_on:
-                - task_key: Menu_Genie
-                - task_key: Menu_Knowledge_Agent
-                - task_key: Inspection_Knowledge_Agent
+                - task_key: Readiness_Check
+                - task_key: Knowledge_Agents
               notebook_task:
-                notebook_path: ${workspace.root_path}/stages/menu_supervisor
+                notebook_path: ${workspace.root_path}/stages/operational_evaluation
diff --git a/demos/dais2026-runbooks/AgentBricks.ipynb b/demos/dais2026-runbooks/AgentBricks.ipynb
new file mode 100644
index 0000000..ab84062
--- /dev/null
+++ b/demos/dais2026-runbooks/AgentBricks.ipynb
@@ -0,0 +1,287 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "ab000000-0000-0000-0000-000000000001",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Agent Bricks — DAIS 2026 Runbook\n",
+        "\n",
+        "Story: Casper's Kitchens has hundreds of documents — inspection reports, legal complaints, regulatory filings, menus, audit reports. Unstructured, un-queryable, scattered. Agent Bricks turns them into a conversational intelligence layer on top of the operational data estate.\n",
+        "\n",
+        "**Message:** Parse documents with SQL, make them conversational with Knowledge Assistants, route everything with a Supervisor — one platform, all governed by Unity Catalog."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "ab000000-0000-0000-0000-000000000003",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Pre-flight: print fresh URLs for the demo.\n",
+        "# Re-run any time IDs go stale (e.g. after redeploy).\n",
+        "\n",
+        "def _autodetect_caspers_catalog():\n",
+        "    \"\"\"Find the most recently-deployed Casper's catalog via its uc_state table.\n",
+        "\n",
+        "    Every Casper's deployment creates `<catalog>._internal_state.resources`,\n",
+        "    so the catalog with the most recently altered such table is the freshest\n",
+        "    deployment in this workspace.  Falls back to `caspersdev` if the system\n",
+        "    tables aren't queryable or no Casper's deployment is found.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        rows = spark.sql(\"\"\"\n",
+        "            SELECT table_catalog FROM system.information_schema.tables\n",
+        "            WHERE table_schema = '_internal_state' AND table_name = 'resources'\n",
+        "            ORDER BY last_altered DESC LIMIT 1\n",
+        "        \"\"\").collect()\n",
+        "        return rows[0].table_catalog if rows else \"caspersdev\"\n",
+        "    except Exception:\n",
+        "        return \"caspersdev\"\n",
+        "\n",
+        "try:\n",
+        "    _detected = _autodetect_caspers_catalog()\n",
+        "    # Recreate the widget so the displayed default always reflects the freshest\n",
+        "    # deployment — `dbutils.widgets.text` does not reliably update the displayed\n",
+        "    # value when the widget already exists from a previous run.\n",
+        "    try:\n",
+        "        dbutils.widgets.remove(\"CATALOG\")\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    dbutils.widgets.text(\"CATALOG\", _detected, \"UC Catalog\")\n",
+        "    CATALOG = dbutils.widgets.get(\"CATALOG\") or _detected\n",
+        "except Exception:\n",
+        "    CATALOG = \"caspersdev\"\n",
+        "\n",
+        "import json\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "host = w.config.host.rstrip(\"/\")\n",
+        "\n",
+        "print(f\"Catalog: {CATALOG}\")\n",
+        "print(f\"Host:    {host}\\n\")\n",
+        "\n",
+        "# Knowledge Assistants\n",
+        "print(\"Knowledge Assistants\")\n",
+        "print(\"-\" * 80)\n",
+        "try:\n",
+        "    df = spark.sql(f\"SELECT resource_data FROM {CATALOG}._internal_state.resources WHERE resource_type = 'knowledge_assistants' ORDER BY created_at ASC\")\n",
+        "    # Defensive dedupe by KA tile_id — uc_state.add() doesn't enforce uniqueness,\n",
+        "    # so re-runs of the Knowledge_Agents stage can leave multiple rows per KA.\n",
+        "    seen_ids = set()\n",
+        "    for row in df.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        tile_id = info.get(\"tile_id\") or info.get(\"id\") or info.get(\"endpoint_name\")\n",
+        "        if tile_id and tile_id in seen_ids:\n",
+        "            continue\n",
+        "        seen_ids.add(tile_id)\n",
+        "        name = info.get(\"display_name\") or info.get(\"name\", \"?\")\n",
+        "        ep   = info.get(\"endpoint_name\", \"?\")\n",
+        "        print(f\"  {name}\")\n",
+        "        print(f\"    {host}/ml/endpoints/{ep}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  Could not read KAs from uc_state: {e}\")\n",
+        "\n",
+        "# Supervisor\n",
+        "print(\"\\nMulti-Agent Supervisor\")\n",
+        "print(\"-\" * 80)\n",
+        "try:\n",
+        "    df2 = spark.sql(f\"SELECT resource_data FROM {CATALOG}._internal_state.resources WHERE resource_type = 'multi_agent_supervisors' ORDER BY created_at DESC LIMIT 1\")\n",
+        "    for row in df2.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        ep = info.get(\"endpoint_name\") or info.get(\"name\", \"?\")\n",
+        "        print(f\"  {ep}\")\n",
+        "        print(f\"  {host}/ml/endpoints/{ep}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  Could not read supervisor from uc_state: {e}\")\n",
+        "\n",
+        "# AI SQL tables\n",
+        "print(\"\\nAI SQL tables\")\n",
+        "print(\"-\" * 80)\n",
+        "for tbl in [\"ai_parsed_inspections\", \"ai_classified_inspections\",\n",
+        "            \"ai_extracted_inspections\", \"ai_summarized_inspections\"]:\n",
+        "    try:\n",
+        "        cnt = spark.sql(f\"SELECT COUNT(*) AS n FROM {CATALOG}.food_safety.{tbl}\").collect()[0].n\n",
+        "        print(f\"  {CATALOG}.food_safety.{tbl}  ({cnt} rows)\")\n",
+        "    except Exception:\n",
+        "        print(f\"  {CATALOG}.food_safety.{tbl}  (not found)\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "ab000000-0000-0000-0000-000000000004",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### IPD: documents become data\n",
+        "\n",
+        "![Programmable Document Pipelines — ai_parse_document, ai_query, ai_extract, ai_translate](assets/idp_demo.png)\n",
+        "\n",
+        "| Function | What you get |\n",
+        "|---|---|\n",
+        "| `ai_parse_document` | Full text + structured VARIANT per PDF → `food_safety.ai_parsed_inspections` |\n",
+        "| `ai_classify` | Overall risk bucket + dominant violation category → `food_safety.ai_classified_inspections` |\n",
+        "| `ai_extract` | Structured fields (date, location, score, grade) → `food_safety.ai_extracted_inspections` |\n",
+        "| `ai_summarize` | 60-word plain-English summary → `food_safety.ai_summarized_inspections` |\n",
+        "\n",
+        "\n",
+        "\n",
+        "In DBSQL or notebook: \n",
+        "\n",
+        "```sql\n",
+        "SELECT pdf_name, summary FROM <catalog>.food_safety.ai_summarized_inspections\n",
+        "```\n",
+        "\n",
+        "`ai_classify` live:\n",
+        "\n",
+        "```sql\n",
+        "SELECT pdf_name,\n",
+        "       ai_classify(summary, ARRAY('low', 'medium', 'high', 'critical')) AS risk\n",
+        "FROM <catalog>.food_safety.ai_summarized_inspections\n",
+        "WHERE pdf_name IS NOT NULL AND summary IS NOT NULL\n",
+        "LIMIT 5\n",
+        "```\n",
+        "\n",
+        "The message: no pipeline, no custom model, no ETL framework. The AI is a SQL function. Any analyst who can write SQL can do this.\n",
+        "Code in `Environment_Helpers` task"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### Knowledge Assistants — ask the documents\n",
+        "\n",
+        "**Inspection KA:**\n",
+        "\n",
+        "- **What were the critical violations at the worst-scoring location in the last inspection?**\n",
+        "- **Which location has the most repeat violations across all inspections?**\n",
+        "- **What corrective actions are overdue based on the latest reports?**\n",
+        "\n",
+        "**Legal KA:**\n",
+        "\n",
+        "- **Summarize the open vendor dispute complaints**\n",
+        "- **Are there any employment complaints that mention wage violations?**\n",
+        "\n",
+        "**Regulatory KA:**\n",
+        "\n",
+        "- **Which locations have permits expiring in the next 90 days?**\n",
+        "- **Are there any outstanding fire safety compliance items?**\n",
+        "\n",
+        "The message: same chat experience as Genie, same UC governance — but the source is a PDF in a Volume, not a table."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Supervisor Agent — route everything\n",
+        "\n",
+        "\n",
+        "![Supervisor Agent Architecture](assets/SA_architecture.png)\n",
+        "\n",
+        "Open the supervisor endpoint. It routes across all 3 Genie spaces (structured data) and all 6 KAs (documents) automatically.\n",
+        "\n",
+        "- **Give me the executive briefing on the state of the business.**\n",
+        "\n",
+        "Show the routing — which sub-agents it called, in what order. Genie for revenue/ops metrics, KAs for inspection and compliance context.\n",
+        "\n",
+        "- **Which location is the highest combined legal and operational risk right now?**\n",
+        "\n",
+        "Needs both KA (legal complaints, inspection reports) and Genie (revenue trend, cancellation rate). Supervisor picks the right agents.\n",
+        "\n",
+        "- **What are the top 3 things the CEO should know before the board call tomorrow?**\n",
+        "- **Is there anything in our regulatory filings that conflicts with how we're currently operating?**\n",
+        "\n",
+        "Pure document reasoning — supervisor routes to Regulatory and Legal KAs.\n",
+        "\n",
+        "Follow-up (same conversation):\n",
+        "- **Draft a 3-bullet action plan for the riskiest location.**"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### MLflow experiment & evaluation\n",
+        "\n",
+        "Every agent call is traced in MLflow — open the experiment from the Experiments sidebar. Each trace shows the full reasoning chain: which sub-agents were called, what they returned, latency per hop.\n",
+        "\n",
+        "The `Evaluation` task ran a set of benchmark questions against the supervisor and scored the answers. Open the experiment → find the eval run → see pass rates and per-question results. This is how you know the agent is actually good before you put it in front of a customer.\n",
+        "\n",
+        "Show `mas_XXX` experiment in MLflow"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### What else Agent Bricks can do\n",
+        "\n",
+        "- **Custom tools** — register any UC Function as a tool; the supervisor calls it when needed\n",
+        "- **Governed** — every sub-agent call runs under the caller's UC identity; all data access is audited"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "ab000000-0000-0000-0000-000000000005",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "Source of truth: `stages/knowledge_agents.ipynb`, `stages/operational_supervisor.ipynb`, `stages/environment_helpers.ipynb`."
+      ]
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "dashboards": [],
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "AgentBricks",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": ".venv",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.14.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/demos/dais2026-runbooks/DAIS 2026 demo.pdf b/demos/dais2026-runbooks/DAIS 2026 demo.pdf
new file mode 100644
index 0000000..6a9d254
Binary files /dev/null and b/demos/dais2026-runbooks/DAIS 2026 demo.pdf differ
diff --git a/demos/dais2026-runbooks/Genie.ipynb b/demos/dais2026-runbooks/Genie.ipynb
new file mode 100644
index 0000000..9844b99
--- /dev/null
+++ b/demos/dais2026-runbooks/Genie.ipynb
@@ -0,0 +1,293 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000001",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Genie — DAIS 2026 Runbook\n",
+        "\n",
+        "Story: ops manager needs answers before a board call. No SQL, no analyst.\n",
+        "\n",
+        "**Message:** One governed chat surface across your entire data estate — desktop and mobile.\n",
+        "\n",
+        "> [The next generation of Databricks Genie](https://www.databricks.com/blog/next-generation-databricks-genie)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000002",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### Pre-flight\n",
+        "\n",
+        "- `<catalog>-genie-warehouse` running (warm with one sample question click)\n",
+        "- 3 Discover Domains exist (Operations, Revenue & Customers, Compliance & Safety) — Beta, manual UI setup, see `SETUP.ipynb`\n",
+        "- Genie iOS/Android app installed and logged in\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000003",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Pre-flight: print fresh URLs for the demo.\n",
+        "# Re-run any time IDs go stale (e.g. after redeploy).\n",
+        "\n",
+        "def _autodetect_caspers_catalog():\n",
+        "    \"\"\"Find the most recently-deployed Casper's catalog via its uc_state table.\n",
+        "\n",
+        "    Every Casper's deployment creates `<catalog>._internal_state.resources`,\n",
+        "    so the catalog with the most recently altered such table is the freshest\n",
+        "    deployment in this workspace.  Falls back to `caspersdev` if the system\n",
+        "    tables aren't queryable or no Casper's deployment is found.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        rows = spark.sql(\"\"\"\n",
+        "            SELECT table_catalog FROM system.information_schema.tables\n",
+        "            WHERE table_schema = '_internal_state' AND table_name = 'resources'\n",
+        "            ORDER BY last_altered DESC LIMIT 1\n",
+        "        \"\"\").collect()\n",
+        "        return rows[0].table_catalog if rows else \"caspersdev\"\n",
+        "    except Exception:\n",
+        "        return \"caspersdev\"\n",
+        "\n",
+        "try:\n",
+        "    _detected = _autodetect_caspers_catalog()\n",
+        "    # Recreate the widget so the displayed default always reflects the freshest\n",
+        "    # deployment — `dbutils.widgets.text` does not reliably update the displayed\n",
+        "    # value when the widget already exists from a previous run.\n",
+        "    try:\n",
+        "        dbutils.widgets.remove(\"CATALOG\")\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    dbutils.widgets.text(\"CATALOG\", _detected, \"UC Catalog\")\n",
+        "    CATALOG = dbutils.widgets.get(\"CATALOG\") or _detected\n",
+        "except Exception:\n",
+        "    CATALOG = \"caspersdev\"\n",
+        "\n",
+        "import json\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "host = w.config.host.rstrip(\"/\")\n",
+        "\n",
+        "print(f\"Catalog: {CATALOG}\")\n",
+        "print(f\"Host:    {host}\")\n",
+        "print(f\"Genie app (next-gen, replaces Databricks One): {host}/one\\n\")\n",
+        "\n",
+        "# 3 Genie Spaces (resolved from uc_state)\n",
+        "TITLES = {\n",
+        "    f\"Revenue & Orders Intelligence ({CATALOG})\",\n",
+        "    f\"Operations Intelligence ({CATALOG})\",\n",
+        "    f\"Menu & Safety Intelligence ({CATALOG})\",\n",
+        "}\n",
+        "print(\"Genie Spaces\")\n",
+        "print(\"-\" * 80)\n",
+        "seen = set()\n",
+        "df = spark.sql(f\"\"\"\n",
+        "    SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "    WHERE resource_type = 'genie_spaces' ORDER BY created_at DESC\n",
+        "\"\"\")\n",
+        "for row in df.collect():\n",
+        "    info = json.loads(row.resource_data)\n",
+        "    title = info.get(\"title\")\n",
+        "    if title in seen or title not in TITLES:\n",
+        "        continue\n",
+        "    seen.add(title)\n",
+        "    print(f\"  {title}\\n    {host}/genie/rooms/{info['space_id']}\")\n",
+        "\n",
+        "# Shared SQL warehouse\n",
+        "print(\"\\nWarehouse\")\n",
+        "print(\"-\" * 80)\n",
+        "wh_name = f\"{CATALOG}-genie-warehouse\"\n",
+        "for wh in w.warehouses.list():\n",
+        "    if wh.name == wh_name:\n",
+        "        print(f\"  {wh.name}  [{wh.state}]  {host}/sql/warehouses/{wh.id}\")\n",
+        "        break"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000004",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### Genie\n",
+        "\n",
+        "Open **Revenue & Orders Intelligence**. \n",
+        "\n",
+        "- **What is total revenue by location this month?**\n",
+        "\n",
+        "Show **View SQL** — auditable, gold table, runs as the asker's UC identity.\n",
+        "\n",
+        "- **Which location is trending down the most compared to last month?**\n",
+        "\n",
+        "Context carries — Genie knows \"location\" from the previous answer. This is conversational BI, not one-shot SQL.\n",
+        "\n",
+        "More questions for this space:\n",
+        "\n",
+        "- **Show me the top 5 brands by order volume today.**\n",
+        "- **What's the average order value across all locations this week?**\n",
+        "\n",
+        "\n",
+        "Switch to **Operations Intelligence**.\n",
+        "\n",
+        "- **Which locations have a food safety score below 80?**\n",
+        "- **Which location has the highest order cancellation rate this month?**\n",
+        "- **What are the most common violation categories across all locations?**\n",
+        "\n",
+        "Switch to **Menu & Safety Intelligence**. \n",
+        "\n",
+        "- **What are our highest-protein items under $15?**\n",
+        "- **Which brands have the most allergen-free options?**\n",
+        "- **Show me all critical violations from the last 60 days.**"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### Switch to **`/one`**.\n",
+        "\n",
+        "![Genie](assets/GenieOneChatv2.gif)\n",
+        "\n",
+        "Home screen: every space, dashboard, and app the user is entitled to — across workspaces, the whole account.\n",
+        "\n",
+        "- **Which Casper's location has the worst combination of declining revenue and low food safety score this month?**\n",
+        "\n",
+        "Expand the response — point at the spaces Genie consulted. Revenue and food safety live in separate spaces; the user never had to know that.\n",
+        "\n",
+        "- **Give me a full health check on that location — revenue trend, cancellation rate, and latest food safety violations.**\n",
+        "- **Which brand should we consider dropping based on low order volume and high complaint rate?**"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Discover Domains: business-aligned grouping (Beta)\n",
+        "\n",
+        "Catalog → **Discover** → **Domains**. Three domains pre-curated for Casper's:\n",
+        "\n",
+        "- **Operations** — orders, deliveries, locations, inspections; Ops dashboards; Operations Intelligence Genie; Ops Dashboard app\n",
+        "- **Revenue & Customers** — revenue/brands/customers tables; Revenue & Orders Genie; AI Agent Performance dashboard\n",
+        "- **Compliance & Safety** — food-safety reports + ai_parsed tables; Menu & Safety Genie; Legal / Regulatory / Audit / Inspection KAs"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Mobile App\n",
+        "\n",
+        "![Mobile App Genie](assets/Genie-Mobile3.gif)\n",
+        "\n",
+        "Pull out your phone. Open the Genie app. Show Genie"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Benchmarks: validate the space\n",
+        "\n",
+        "Some spaces contain benchmarks, run those. If the space doesn't contain benchmarks, use Genie Code to generate benchmarks. Use the following prompt:\n",
+        "\n",
+        "```\n",
+        "Generate 5 benchmark questions for evaluating this space. Cover:\n",
+        "1. A simple aggregation (e.g. total revenue, count of orders)\n",
+        "2. A top-N filter (e.g. top locations by a metric)\n",
+        "3. A time comparison (e.g. this week vs last week)\n",
+        "4. A JOIN across two tables returning human-readable names\n",
+        "5. A derived metric (e.g. cancellation rate, average order value, pass rate)\n",
+        "\n",
+        "Rules:\n",
+        "- Questions must be natural business language, no SQL jargon\n",
+        "- Always JOIN dimension tables (locations, brands) to return names not IDs\n",
+        "```"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### What else Genie can do\n",
+        "\n",
+        "- **Scheduled digests** — daily/weekly summaries pushed to email or Slack\n",
+        "- **MCP server** — external AI agents can query your Genie spaces as a tool\n",
+        "- **Document connectors** — attach Google Drive, SharePoint\n",
+        "- **Embed in apps** — Genie spaces are an API; route questions to them from any Databricks App or external surface\n",
+        "- **Account-level** — spans workspaces; one surface for the whole data estate\n",
+        "- **Governance throughout** — every query runs as the asker's UC identity, RLS/CLS apply\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000007",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "Source of truth for the spaces: `stages/genie_spaces.ipynb`."
+      ]
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "dashboards": [],
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "Genie",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/demos/dais2026-runbooks/LakebaseApps.ipynb b/demos/dais2026-runbooks/LakebaseApps.ipynb
new file mode 100644
index 0000000..20788a3
--- /dev/null
+++ b/demos/dais2026-runbooks/LakebaseApps.ipynb
@@ -0,0 +1,333 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "la000000-0000-0000-0000-000000000001",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Lakebase & Apps — DAIS 2026 Runbook\n",
+        "\n",
+        "Story: the ops manager doesn't just want to chat once. They want a live app, persistent history, and real-time data — all inside Databricks, no external services. And when they see a problem, they want to act on it immediately, right there.\n",
+        "\n",
+        "**Message:** Lakebase is PostgreSQL, serverless, built into the platform. Databricks Apps are full-stack. Together they close the loop from data to production application — and from AI decision to operational action — deployed from a single `databricks.yml`.\n",
+        "\n",
+        "> Docs: [Databricks Apps](https://docs.databricks.com/en/dev-tools/databricks-apps/index.html) · [Lakebase](https://docs.databricks.com/en/database/lakebase/index.html) · [Asset Bundles](https://docs.databricks.com/en/dev-tools/bundles/index.html) · [DevHub](https://developer.databricks.com)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Lakebase Autoscaling lives under `w.postgres`, which requires\n",
+        "# databricks-sdk >= 0.81.  The default runtime image often pins an\n",
+        "# older SDK; if so, upgrade in place and restart Python.  Run this\n",
+        "# cell first — it's a no-op once the workspace already has a recent SDK.\n",
+        "%pip install --quiet --upgrade \"databricks-sdk>=0.81.0\"\n",
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "la000000-0000-0000-0000-000000000003",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# Pre-flight: print fresh URLs for the demo.\n",
+        "\n",
+        "def _autodetect_caspers_catalog():\n",
+        "    \"\"\"Find the most recently-deployed Casper's catalog via its uc_state table.\n",
+        "\n",
+        "    Every Casper's deployment creates `<catalog>._internal_state.resources`,\n",
+        "    so the catalog with the most recently altered such table is the freshest\n",
+        "    deployment in this workspace.  Falls back to `caspersdev` if the system\n",
+        "    tables aren't queryable or no Casper's deployment is found.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        rows = spark.sql(\"\"\"\n",
+        "            SELECT table_catalog FROM system.information_schema.tables\n",
+        "            WHERE table_schema = '_internal_state' AND table_name = 'resources'\n",
+        "            ORDER BY last_altered DESC LIMIT 1\n",
+        "        \"\"\").collect()\n",
+        "        return rows[0].table_catalog if rows else \"caspersdev\"\n",
+        "    except Exception:\n",
+        "        return \"caspersdev\"\n",
+        "\n",
+        "try:\n",
+        "    _detected = _autodetect_caspers_catalog()\n",
+        "    # Recreate the widget so the displayed default always reflects the freshest\n",
+        "    # deployment — `dbutils.widgets.text` does not reliably update the displayed\n",
+        "    # value when the widget already exists from a previous run.\n",
+        "    try:\n",
+        "        dbutils.widgets.remove(\"CATALOG\")\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    dbutils.widgets.text(\"CATALOG\", _detected, \"UC Catalog\")\n",
+        "    CATALOG = dbutils.widgets.get(\"CATALOG\") or _detected\n",
+        "except Exception:\n",
+        "    CATALOG = \"caspersdev\"\n",
+        "\n",
+        "import json, re\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "host = w.config.host.rstrip(\"/\")\n",
+        "\n",
+        "print(f\"Catalog: {CATALOG}\")\n",
+        "print(f\"Host:    {host}\\n\")\n",
+        "\n",
+        "# Ops Dashboard app\n",
+        "print(\"Databricks Apps\")\n",
+        "print(\"-\" * 80)\n",
+        "try:\n",
+        "    df = spark.sql(f\"SELECT resource_data FROM {CATALOG}._internal_state.resources WHERE resource_type = 'apps' ORDER BY created_at DESC\")\n",
+        "    seen = set()\n",
+        "    for row in df.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        name = info.get(\"name\") or info.get(\"app_name\", \"\")\n",
+        "        url  = info.get(\"url\") or info.get(\"app_url\", \"\")\n",
+        "        if name and name not in seen:\n",
+        "            seen.add(name)\n",
+        "            print(f\"  {name}: {url}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  Could not read apps from uc_state: {e}\")\n",
+        "\n",
+        "# Refund Manager app\n",
+        "print()\n",
+        "# Name must match stages/apps.ipynb: APP_NAME = f\"refundmanager-{CATALOG}\" (no hyphen\n",
+        "# between \"refund\" and \"manager\") — Databricks Apps slug is capped at 30 chars and\n",
+        "# stages/apps.ipynb dropped the hyphen to leave room for longer catalog names.\n",
+        "refund_app_name = re.sub(r'-+', '-', re.sub(r'[^a-z0-9-]', '-', f'refundmanager-{CATALOG}'.lower())).strip('-')[:30]\n",
+        "try:\n",
+        "    ep = w.apps.get(refund_app_name)\n",
+        "    url = getattr(ep, 'url', None) or f\"(deploy {refund_app_name} first)\"\n",
+        "    print(f\"Refund Manager app: {url}\")\n",
+        "except Exception:\n",
+        "    print(f\"Refund Manager app: not found — deploy apps/refund-manager with target=all\")\n",
+        "\n",
+        "# Lakebase project\n",
+        "print(\"\\nLakebase\")\n",
+        "print(\"-\" * 80)\n",
+        "if not hasattr(w, \"postgres\"):\n",
+        "    print(\"  databricks-sdk on this cluster is too old (needs >= 0.81 for w.postgres).\")\n",
+        "    print(\"  Re-run the previous cell to upgrade, or attach a fresher runtime.\")\n",
+        "else:\n",
+        "    try:\n",
+        "        project_id = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "        ep = w.postgres.get_endpoint(name=f\"projects/{project_id}/branches/production/endpoints/primary\")\n",
+        "        host_pg = ep.status.hosts.host if ep.status and ep.status.hosts else \"?\"\n",
+        "        state = str(ep.status.current_state) if ep.status else \"?\"\n",
+        "        print(f\"  project:   {project_id}\")\n",
+        "        print(f\"  endpoint:  {host_pg}  [{state}]\")\n",
+        "        print(f\"  databases: caspers_ops  caspers_refund  caspers_complaint\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"  Could not read Lakebase project: {e}\")\n",
+        "\n",
+        "# Complaint decisions sanity check\n",
+        "print()\n",
+        "try:\n",
+        "    count = spark.sql(f\"SELECT COUNT(*) AS n FROM {CATALOG}.complaints.complaint_responses\").collect()[0]['n']\n",
+        "    print(f\"complaint_responses rows: {count} {'✅' if count > 0 else '⚠️  run complaint stream first'}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"complaint_responses: {e}\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "la000000-0000-0000-0000-000000000004",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### Casper's Ops Dashboard App\n",
+        "\n",
+        "Open the app URL from the pre-flight cell.\n",
+        "\n",
+        "It's a full-stack app: FastAPI backend, single-page frontend, deployed as a Databricks App — no external hosting, no separate infra. The app runs inside the workspace, inherits the caller's identity, and has direct access to the data.\n",
+        "\n",
+        "**Shortcut buttons** sit above the chat input — one click sends a real Supervisor prompt (no canned answers, full MLflow tracing):\n",
+        "\n",
+        "- 📊 **Executive briefing** — *\"Give me the executive briefing on the state of the business.\"*\n",
+        "- ⚠️ **Highest combined risk** — *\"Which location is the highest combined legal and operational risk right now?\"*\n",
+        "- 🎯 **Top 3 for the board** — *\"What are the top 3 things to know before the board call tomorrow?\"*\n",
+        "- 📬 **Review Complaints** — pulls the latest decisions from `{catalog}.complaints.complaint_responses`\n",
+        "\n",
+        "Click one to open. Or type your own:\n",
+        "\n",
+        "- **Which location needs the most attention right now?**\n",
+        "\n",
+        "The chat streams from the Supervisor Agent (same one from the Agent Bricks flow). Close the tab and reopen it — the conversation is still there. Chat history is persisted in **Lakebase**, not in browser storage.\n",
+        "\n",
+        "Point at the sidebar: previous sessions are listed. Each session is a row in a Postgres table. Any team member with app access sees the same history.\n",
+        "\n",
+        "- **What were the top complaints last week at that location?**\n",
+        "- **Summarize what we know about the regulatory risk across all locations.**"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### Lakebase: PostgreSQL, serverless, built in\n",
+        "\n",
+        "![Lakebase](assets/lakebase.png)\n",
+        "\n",
+        "In Lakebase SQL tab:\n",
+        "\n",
+        "```sql\n",
+        "SELECT session_id, created_at, title FROM caspers_ops.public.sessions ORDER BY created_at DESC LIMIT 10\n",
+        "```\n",
+        "```sql\n",
+        "SELECT role, LEFT(content, 120) AS preview FROM caspers_ops.public.messages WHERE session_id = '<id>' ORDER BY created_at\n",
+        "```\n",
+        "\n",
+        "Message: one project, three logical databases (`caspers_ops`, `caspers_refund`, `caspers_complaint`), one endpoint, serverless. You don't provision it; you don't patch it; you don't think about it.\n",
+        "\n",
+        "Show Lakebase features:\n",
+        "- Point in time recovery\n",
+        "- Branching\n",
+        "- Scale to Zero  "
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![Lakebase Usecases](assets/lakebase_usecases.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### How this was built: DABs + AppKit + DevHub + GitHub\n",
+        "\n",
+        "The whole stack — app, job, warehouse, dashboards, Lakebase project — is declared in a single [`databricks.yml`](https://github.com/databricks-solutions/caspers-kitchens/blob/main/databricks.yml).\n",
+        "\n",
+        "```bash\n",
+        "databricks bundle deploy -t all\n",
+        "databricks bundle run caspers\n",
+        "```\n",
+        "\n",
+        "**How the app was scaffolded:** [AppKit](https://developer.databricks.com) gives you a FastAPI + React starter wired to Databricks auth, UC, and the Apps runtime — the same scaffold Casper's Ops Dashboard started from. Start there, add your routes and components, drop it in `apps/` and reference it from `databricks.yml`.\n",
+        "\n",
+        "**Where to start:** [DevHub](https://developer.databricks.com) — tutorials, templates, and reference apps for building on Databricks. The Casper's Kitchens source is on [GitHub](https://github.com/databricks-solutions/caspers-kitchens) — fork it, strip it down, or use it as a reference.\n",
+        "\n",
+        "Key links:\n",
+        "- [Databricks Apps docs](https://docs.databricks.com/en/dev-tools/databricks-apps/index.html)\n",
+        "- [Asset Bundles docs](https://docs.databricks.com/en/dev-tools/bundles/index.html)\n",
+        "- [Lakebase docs](https://docs.databricks.com/en/database/lakebase/index.html)\n",
+        "- [DevHub](https://developer.databricks.com)\n",
+        "- [AppKit](https://developer.databricks.com/app-kit)\n",
+        "- [Casper's Kitchens on GitHub](https://github.com/databricks-solutions/caspers-kitchens)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![DevHub](assets/Devhub.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "la000000-0000-0000-0000-000000000005",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### Complaint Decisions - build in Agent\n",
+        "\n",
+        "Click **📬 Review Complaints** button. The app fetches the latest decisions from `{catalog}.complaints.complaint_responses` — the output table of the complaint agent streaming worker — and renders them as a list:\n",
+        "\n",
+        "- Each row shows: **category** · **rationale preview** · **decision badge** (🔴 Escalate / 🟢 Credit) · **credit amount**\n",
+        "- Click any row to expand it: full rationale, customer response message, order ID, and timestamp\n",
+        "\n",
+        "This is AI-generated triage running continuously in the background — the ops manager sees the output without having to trigger anything."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### From Complaint to Refund\n",
+        "\n",
+        "For rows where the agent recommended a credit, the expanded detail shows a gold **💳 Process Refund for $X.XX** button.\n",
+        "\n",
+        "Click it. The Refund Manager modal opens with the **order ID pre-filled** from the complaint record.\n",
+        "\n",
+        "Click **Evaluate** — the Refund Agent runs against the order, pulls live order data via UC functions, and returns a structured decision: refund class (none / partial / full), amount, and reasoning. The result appears inline as a card in the chat.\n",
+        "\n",
+        "After the refund is evaluated, the complaint list **silently refreshes** — no page reload, no second click. The ops manager sees the updated triage inline.\n",
+        "\n",
+        "**Story:** the complaint agent already did the triage. The ops manager reviews, confirms, and the refund agent closes the loop — all from one screen, no context switching.\n",
+        "\n",
+        "For high-volume refund processing, point to the standalone **Refund Manager** app (left menu in the app). It's purpose-built for working through a queue of orders, with the same refund agent under the hood."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "la000000-0000-0000-0000-000000000006",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "**Source of truth:** `stages/operational_app.ipynb`, `stages/lakebase_project.ipynb`, `stages/operational_lakebase.ipynb`, `stages/complaint_agent_stream.ipynb`."
+      ]
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "dashboards": [],
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "LakebaseApps",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/demos/dais2026-runbooks/MLflow.ipynb b/demos/dais2026-runbooks/MLflow.ipynb
new file mode 100644
index 0000000..a7f974b
--- /dev/null
+++ b/demos/dais2026-runbooks/MLflow.ipynb
@@ -0,0 +1,390 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# MLflow — DAIS 2026 Runbook\n",
+        "\n",
+        "Story: Three agents in production: **Refund**, **Complaint**, **Operational Supervisor** (fans out to 6 KAs + 3 Genie spaces).\n",
+        "\n",
+        "**Message**: One system, governed by UC. No extra services.\n",
+        "\n",
+        "> Docs: [MLflow GenAI](https://mlflow.org/docs/latest/llms/genai/index.html) · [Tracing](https://mlflow.org/docs/latest/llms/tracing/index.html) · [Evaluation](https://mlflow.org/docs/latest/llms/genai-evaluation/index.html) · [Prompt Registry](https://mlflow.org/docs/latest/llms/prompt-engineering/index.html)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Pre-flight\n",
+        "\n",
+        "- Send one message through the Operational Dashboard (so the **Sessions** tab has at least one entry to point at)\n",
+        "- Run the next cell for fresh URLs."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Pre-flight: print fresh URLs for the demo.\n",
+        "# Re-run any time IDs go stale (e.g. after redeploy).\n",
+        "\n",
+        "def _autodetect_caspers_catalog():\n",
+        "    \"\"\"Find the most recently-deployed Casper's catalog via its uc_state table.\n",
+        "\n",
+        "    Every Casper's deployment creates `<catalog>._internal_state.resources`,\n",
+        "    so the catalog with the most recently altered such table is the freshest\n",
+        "    deployment in this workspace.  Falls back to `caspersdev` if the system\n",
+        "    tables aren't queryable or no Casper's deployment is found.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        rows = spark.sql(\"\"\"\n",
+        "            SELECT table_catalog FROM system.information_schema.tables\n",
+        "            WHERE table_schema = '_internal_state' AND table_name = 'resources'\n",
+        "            ORDER BY last_altered DESC LIMIT 1\n",
+        "        \"\"\").collect()\n",
+        "        return rows[0].table_catalog if rows else \"caspersdev\"\n",
+        "    except Exception:\n",
+        "        return \"caspersdev\"\n",
+        "\n",
+        "try:\n",
+        "    _detected = _autodetect_caspers_catalog()\n",
+        "    # Recreate the widget so the displayed default always reflects the freshest\n",
+        "    # deployment — `dbutils.widgets.text` does not reliably update the displayed\n",
+        "    # value when the widget already exists from a previous run.\n",
+        "    try:\n",
+        "        dbutils.widgets.remove(\"CATALOG\")\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    dbutils.widgets.text(\"CATALOG\", _detected, \"UC Catalog\")\n",
+        "    CATALOG = dbutils.widgets.get(\"CATALOG\") or _detected\n",
+        "except Exception:\n",
+        "    CATALOG = \"caspersdev\"\n",
+        "\n",
+        "import json\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "host = w.config.host.rstrip(\"/\")\n",
+        "me = spark.sql(\"SELECT current_user()\").collect()[0][0]\n",
+        "\n",
+        "print(f\"Catalog: {CATALOG}\")\n",
+        "print(f\"Host:    {host}\")\n",
+        "print(f\"User:    {me}\\n\")\n",
+        "\n",
+        "\n",
+        "def _exp_url(name: str) -> str:\n",
+        "    \"\"\"Resolve an experiment by name and return a clickable URL, or '(not created yet)'.\n",
+        "\n",
+        "    Uses the Databricks SDK's experiments API rather than mlflow, so this\n",
+        "    works on serverless runtimes that don't ship mlflow by default.  The\n",
+        "    only mlflow-only section in this runbook is the prompt registry listing\n",
+        "    below, which imports mlflow lazily and degrades gracefully if missing.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        resp = w.experiments.get_by_name(name)\n",
+        "        exp = getattr(resp, \"experiment\", None) or resp\n",
+        "        eid = getattr(exp, \"experiment_id\", None)\n",
+        "        if eid:\n",
+        "            return f\"{host}/ml/experiments/{eid}\"\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    return \"(not created yet — fire one request to the endpoint or run the eval task)\"\n",
+        "\n",
+        "\n",
+        "def _endpoint_url(name: str) -> str:\n",
+        "    try:\n",
+        "        ep = w.serving_endpoints.get(name)\n",
+        "        state = getattr(getattr(ep, \"state\", None), \"ready\", \"?\")\n",
+        "        return f\"{host}/ml/endpoints/{name}  [{state}]\"\n",
+        "    except Exception:\n",
+        "        return f\"{name}  (not deployed in this target)\"\n",
+        "\n",
+        "\n",
+        "# ── Agent serving endpoints ──────────────────────────────────────────────────\n",
+        "print(\"Agent endpoints\")\n",
+        "print(\"=\" * 80)\n",
+        "print(f\"  Refund Agent:        {_endpoint_url(f'{CATALOG}_refund_agent')}\")\n",
+        "print(f\"  Complaint Agent:     {_endpoint_url(f'{CATALOG}_complaint_agent')}\")\n",
+        "\n",
+        "# Operational Supervisor endpoint name is dynamic — read it from uc_state.\n",
+        "supervisor_endpoint = \"\"\n",
+        "try:\n",
+        "    df = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'multi_agent_supervisors'\n",
+        "        ORDER BY created_at DESC LIMIT 1\n",
+        "    \"\"\")\n",
+        "    rows = df.collect()\n",
+        "    if rows:\n",
+        "        supervisor_endpoint = json.loads(rows[0].resource_data).get(\"endpoint_name\", \"\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  Could not read supervisor endpoint from uc_state: {e}\")\n",
+        "print(f\"  Operational Sup'r:   {_endpoint_url(supervisor_endpoint) if supervisor_endpoint else '(not deployed)'}\")\n",
+        "\n",
+        "# ── Per-agent dev/prod experiments ───────────────────────────────────────────\n",
+        "print(\"\\nDevelopment experiments (where evaluation runs land)\")\n",
+        "print(\"=\" * 80)\n",
+        "print(f\"  Refund dev:    {_exp_url(f'/Shared/{CATALOG}_refund_agent_dev')}\")\n",
+        "print(f\"  Refund prod:   {_exp_url(f'/Shared/{CATALOG}_refund_agent_prod')}\")\n",
+        "print(f\"  Complaint dev: {_exp_url(f'/Shared/{CATALOG}_complaint_agent_dev')}\")\n",
+        "print(f\"  Complaint prod:{_exp_url(f'/Shared/{CATALOG}_complaint_agent_prod')}\")\n",
+        "if supervisor_endpoint:\n",
+        "    mas_id = supervisor_endpoint.replace(\"-endpoint\", \"\")\n",
+        "    print(f\"  Supervisor:    {_exp_url(f'/Users/{me}/{mas_id}-dev-experiment')}\")\n",
+        "\n",
+        "# ── Production / serving experiments (where live traces land) ────────────────\n",
+        "print(\"\\nProduction experiments (auto-created by Model Serving — every live request lands here)\")\n",
+        "print(\"=\" * 80)\n",
+        "for label, ep in [\n",
+        "    (\"Refund\",     f\"{CATALOG}_refund_agent\"),\n",
+        "    (\"Complaint\",  f\"{CATALOG}_complaint_agent\"),\n",
+        "    (\"Supervisor\", supervisor_endpoint),\n",
+        "]:\n",
+        "    if ep:\n",
+        "        print(f\"  {label:<11} {_exp_url(f'/Serving/{ep}')}\")\n",
+        "\n",
+        "# ── UC-managed evaluation datasets ───────────────────────────────────────────\n",
+        "print(\"\\nUC-managed evaluation datasets (one per agent)\")\n",
+        "print(\"=\" * 80)\n",
+        "_uc_datasets = [\n",
+        "    (\"Supervisor\", \"operational_supervisor_eval_dataset\", \"Evaluation task\"),\n",
+        "    (\"Refund\",     \"refund_agent_eval_dataset\",          \"Refund_Setup task\"),\n",
+        "    (\"Complaint\",  \"complaint_agent_eval_dataset\",       \"Complaint_Setup task\"),\n",
+        "]\n",
+        "for _label, _table, _origin in _uc_datasets:\n",
+        "    _full = f\"{CATALOG}.evaluations.{_table}\"\n",
+        "    try:\n",
+        "        _n = spark.sql(f\"SELECT COUNT(*) AS n FROM {_full}\").collect()[0].n\n",
+        "        print(f\"  {_label:<11} {_full}  ({_n} rows)\")\n",
+        "        print(f\"              {host}/explore/data/{CATALOG}/evaluations/{_table}\")\n",
+        "    except Exception:\n",
+        "        print(f\"  {_label:<11} {_full}  (not created — run {_origin})\")\n",
+        "\n",
+        "# ── Prompt registry ──────────────────────────────────────────────────────────\n",
+        "# Prompts are stored in UC under <catalog>.prompts. They are NOT browsable\n",
+        "# as tables in Catalog Explorer (they're a different UC entity type — `SHOW\n",
+        "# TABLES IN prompts` returns zero).  The way to inspect prompt versions in\n",
+        "# the workspace UI is via the **Prompts tab on each Experiment that loaded\n",
+        "# the prompt** — those URLs are already printed above:\n",
+        "#   Refund dev/prod        → loads `refund_system`         (Prompts tab)\n",
+        "#   Complaint dev/prod     → loads `complaint_system`      (Prompts tab)\n",
+        "#   Supervisor experiment  → loads `supervisor_instructions` (Prompts tab)\n",
+        "print(\"\\nPrompt registry\")\n",
+        "print(\"=\" * 80)\n",
+        "try:\n",
+        "    import mlflow\n",
+        "    # Without databricks-uc registry, search_prompts hits workspace MLflow\n",
+        "    # and the catalog/schema filter returns nothing even if prompts exist in UC.\n",
+        "    mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "    prompts = mlflow.genai.search_prompts(\n",
+        "        filter_string=f\"catalog = '{CATALOG}' AND schema = 'prompts'\"\n",
+        "    )\n",
+        "    if not prompts:\n",
+        "        print(f\"  No prompts under {CATALOG}.prompts — has the `all` target been deployed?\")\n",
+        "    else:\n",
+        "        for p in sorted(prompts, key=lambda x: x.name):\n",
+        "            print(f\"  {p.name}\")\n",
+        "        print(f\"\\n  To see versions + tags + diffs:\")\n",
+        "        print(f\"    Open any of the experiment URLs printed above → click the 'Prompts' tab.\")\n",
+        "        print(f\"    Each experiment's Prompts tab lists the prompts loaded by that endpoint\")\n",
+        "        print(f\"    (via mlflow.genai.load_prompt) and their version history.\")\n",
+        "except ImportError:\n",
+        "    print(f\"  mlflow not installed in this runtime — install it to list prompts:\")\n",
+        "    print(f\"    %pip install -qq 'mlflow-skinny[databricks]'   # then restart kernel and re-run\")\n",
+        "    print(f\"  (You can still browse them via the Prompts tab on any experiment URL above.)\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  Could not list prompts under {CATALOG}.prompts: {type(e).__name__}: {e}\")\n",
+        "    print(f\"  (You can still browse them via the Prompts tab on any experiment URL above.)\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![MLflow Architecture](assets/mlflow_gen_arch.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Tracing\n",
+        "\n",
+        "**Show:**\n",
+        "- `Experiments`→ `mas_xxx experiment` → recent trace → waterfall (Genie SQL 10–30 s · KA 2–8 s · supervisor synth 3–6 s — bottleneck visible without instrumentation)\n",
+        "- `Experiments`→ `{catalog}_refund_agent_prod` → recent trace → LangGraph nodes + every tool call + every LLM call as separate spans\n",
+        "\n",
+        "**Message:** every agent traced by default — MAS by Agent Bricks, refund + complaint via `mlflow.langchain.autolog()`\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### Prompts\n",
+        "\n",
+        "**Show:**\n",
+        "- MLflow experiment -> prompts\n",
+        "\n",
+        "**Message:** prompts are governed UC artifacts; updates flow without rebuilding models. Refund agent loads at request-time; supervisor at construction-time; complaint is baked into the DSPy Signature at model-log time (registry entry is audit-only — re-baking requires a redeploy). KAs intentionally don't register prompts — their `instructions` are short literals managed in the stage notebook directly.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "### Evaluation\n",
+        "\n",
+        "**Show:**\n",
+        "- `/Users/{me}/{mas_id}-dev-experiment` → latest `ceo-supervisor-full-eval` run\n",
+        "- 10 questions × 4 scorers: `ExpectationsGuidelines`, `Safety`, `routing_accuracy` (custom `@scorer`), `cites_specific_data` (custom `@scorer`)\n",
+        "- Same shape on `{cat}-refund-agent-eval` and `{cat}-complaint-agent-eval`\n",
+        "\n",
+        "**Three UC-managed datasets, one per agent:**\n",
+        "\n",
+        "| Agent | UC table | Built by |\n",
+        "|---|---|---|\n",
+        "| Supervisor | `{CATALOG}.evaluations.operational_supervisor_eval_dataset` | `Evaluation` |\n",
+        "| Refund | `{CATALOG}.evaluations.refund_agent_eval_dataset` | `Refund_Setup` |\n",
+        "| Complaint | `{CATALOG}.evaluations.complaint_agent_eval_dataset` | `Complaint_Setup` |\n",
+        "\n",
+        "\n",
+        "**Message:** behavioral guidelines (not factual)\n",
+        "\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Production monitoring\n",
+        "\n",
+        "**Show:** prod experiment for any agent → **Assessments** column → sort by `safety < 1` or `operational_quality = 0` to surface caught failures.\n",
+        "\n",
+        "**Scorers (100% sampling, registered as last step of each stage):**\n",
+        "- All three: `safety`, `relevance_to_query`, `operational_quality`\n",
+        "- Refund: `refund_policy_compliance`\n",
+        "- Complaint: `decision_quality`, `refund_reason`\n",
+        "- Supervisor: `routing_accuracy`, `cites_specific_data`\n",
+        "\n",
+        "**Message:** same judges that gate dev eval keep running on every live request.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Unity AI Gateway\n",
+        "\n",
+        "Both Refund and Complaint route their internal LLM calls through a single\n",
+        "gateway endpoint (`dais2026-ai-gateway`) so guardrails / inference table /\n",
+        "usage tracking / rate limits apply to every agent LLM call centrally.\n",
+        "Refund uses `langchain_openai.ChatOpenAI` against the gateway URL,\n",
+        "Complaint uses `dspy.LM('openai/...')` — both extract a fresh OAuth\n",
+        "bearer at agent construction via `WorkspaceClient().config.authenticate()`.\n",
+        "\n",
+        "**Show:**\n",
+        "- `AI Gateway` → `dais2026-ai-gateway` → **Permissions** tab → `account\n",
+        "  users` has CAN_QUERY (so the deployed agent SPs can call it)\n",
+        "- `AI Gateway` → `dais2026-ai-gateway` → **Inference Tables** /\n",
+        "  **Guardrails** / **Usage Tracking** / **Rate Limits** all enabled\n",
+        "- Refund prod experiment → recent trace → the `ChatOpenAI` LLM span has\n",
+        "  `endpoint = <host>/ai-gateway/mlflow/v1` (vs the old foundation-model\n",
+        "  serving URL)\n",
+        "- Complaint prod experiment → recent trace → DSPy LM span has the same\n",
+        "  gateway URL\n",
+        "\n",
+        "**Inference table — one row per agent LLM call:**\n",
+        "\n",
+        "```sql\n",
+        "-- Replace the catalog/schema with whatever you pointed inference tables at\n",
+        "-- in step 5 of SETUP.ipynb (default suggestion: <CATALOG>.ai_gateway).\n",
+        "SELECT\n",
+        "  event_time,\n",
+        "  request_id,\n",
+        "  status_code,                  -- 200 = served, 400 = blocked by guardrail\n",
+        "  requester,                    -- the agent endpoint's SP — attribute usage by agent\n",
+        "  latency_ms,\n",
+        "  CAST(request AS STRING)  AS request_preview,\n",
+        "  CAST(response AS STRING) AS response_preview\n",
+        "FROM `<catalog>`.`ai_gateway`.`dais2026-ai-gateway_payload`\n",
+        "ORDER BY event_time DESC\n",
+        "LIMIT 20\n",
+        "```\n",
+        "\n",
+        "**Usage tracking — per-endpoint token spend (account-admin only):**\n",
+        "\n",
+        "```sql\n",
+        "SELECT\n",
+        "  endpoint_name,\n",
+        "  DATE_TRUNC('hour', usage_time) AS hour,\n",
+        "  SUM(input_tokens)  AS input_tokens,\n",
+        "  SUM(output_tokens) AS output_tokens,\n",
+        "  SUM(input_tokens + output_tokens) AS total_tokens\n",
+        "FROM system.ai_gateway.usage\n",
+        "WHERE endpoint_name = 'dais2026-ai-gateway'\n",
+        "  AND usage_time >= CURRENT_TIMESTAMP - INTERVAL 1 HOUR\n",
+        "GROUP BY endpoint_name, hour\n",
+        "ORDER BY hour DESC\n",
+        "```\n",
+        "\n",
+        "**Guardrails in action — fire a PII complaint and watch it block:**\n",
+        "\n",
+        "```python\n",
+        "# Run in any notebook attached to a cluster.  PII detection is set to\n",
+        "# BLOCK in the gateway config, so the request never reaches the LLM —\n",
+        "# the row in the inference table will show status_code = 400 and the\n",
+        "# guardrail label.\n",
+        "import requests\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "resp = requests.post(\n",
+        "    f\"{w.config.host.rstrip('/')}/ai-gateway/mlflow/v1/chat/completions\",\n",
+        "    headers=w.config.authenticate(),\n",
+        "    json={\n",
+        "        \"model\": \"dais2026-ai-gateway\",\n",
+        "        \"messages\": [{\"role\": \"user\", \"content\":\n",
+        "            \"My order ORD-123 was late! My SSN is 123-45-6789, refund please.\"\n",
+        "        }],\n",
+        "        \"max_tokens\": 64,\n",
+        "    },\n",
+        "    timeout=30,\n",
+        ")\n",
+        "print(resp.status_code, resp.text[:200])\n",
+        "```\n",
+        "\n",
+        "**Message:** one gateway, two agents, every LLM call governed — guardrails\n",
+        "stop PII before the model sees it, every request audited in UC, usage\n",
+        "attributable per agent SP via the `requester` column."
+      ]
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "dashboards": [],
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "MLflow",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/demos/dais2026-runbooks/Omnigent.ipynb b/demos/dais2026-runbooks/Omnigent.ipynb
new file mode 100644
index 0000000..2e81a1e
--- /dev/null
+++ b/demos/dais2026-runbooks/Omnigent.ipynb
@@ -0,0 +1,26 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "32a59292",
+   "metadata": {},
+   "source": [
+    "# Omnigent — DAIS 2026 Runbook\n",
+    "\n",
+    "(placeholder)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/demos/dais2026-runbooks/SETUP.ipynb b/demos/dais2026-runbooks/SETUP.ipynb
new file mode 100644
index 0000000..68a4b21
--- /dev/null
+++ b/demos/dais2026-runbooks/SETUP.ipynb
@@ -0,0 +1,261 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000001",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "# DAIS 2026 — Deployment & Setup\n",
+        "\n",
+        "Short checklist to get a workspace ready for the DAIS 2026 runbooks\n",
+        "(`Genie.ipynb`, `AgentBricks.ipynb`, `LakebaseApps.ipynb`, `MLflow.ipynb`).\n",
+        "All four run against a single `all`-target deployment."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000005",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### 1. Create Domains\n",
+        "\n",
+        "In **Catalog → Discover → Domains → New domain**, create three domains and select the matching existing governed tag for each:\n",
+        "\n",
+        "| Domain | Governed tag (select existing) |\n",
+        "|---|---|\n",
+        "| **Operations** | `caspers_domain_operations = true` |\n",
+        "| **Revenue & Customers** | `caspers_domain_revenue = true` |\n",
+        "| **Compliance & Safety** | `caspers_domain_compliance = true` |"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000006",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### 2. Enable Data quality monitor.\n",
+        "Enable schema-level anomaly detection on `${CATALOG}.food_safety`"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### 3. Add prompts schema to the experiments in MAS and others\n",
+        "Schema Catalog.prompts"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### 4. Fix agent endpoint UC perms\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# EDIT THIS to match the catalog you passed to `bundle deploy --var catalog=...`\n",
+        "# (bundle default is `caspersdev`; this workspace uses something else if you\n",
+        "#  deployed with `--var catalog=<other>`).\n",
+        "CATALOG = \"\"  # e.g. \"caspersdev\"\n",
+        "\n",
+        "assert CATALOG, \"Set CATALOG above to the catalog name from your last bundle deploy.\"\n",
+        "\n",
+        "result = dbutils.notebook.run(\n",
+        "    \"../../utils/fix_agent_perms\",\n",
+        "    1800,\n",
+        "    {\n",
+        "        \"CATALOG\": CATALOG,\n",
+        "        # Leave ENDPOINT_NAMES empty to use the default\n",
+        "        # f\"{CATALOG}_{refund,complaint,support}_agent\" pattern.\n",
+        "        \"ENDPOINT_NAMES\": \"\",\n",
+        "        \"MAX_WAIT_SECONDS\": \"300\",\n",
+        "    },\n",
+        ")\n",
+        "print(result)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### 5. Set up the Unity AI Gateway endpoint (`all` target only)\n",
+        "\n",
+        "Both the Refund agent (LangGraph + `langchain_openai.ChatOpenAI`) and the\n",
+        "Complaint agent (DSPy + `dspy.LM('openai/...')`) on the `all` target route\n",
+        "their internal LLM calls through a single Unity AI Gateway (v2 Beta)\n",
+        "endpoint, so every agent LLM call gets PII guardrails, inference-table\n",
+        "audit, usage tracking, and rate limits applied centrally — and you can\n",
+        "attribute usage to either agent via the `requester` column on the\n",
+        "inference table.\n",
+        "\n",
+        "The v2 Beta gateway is **UI-configured only** — there is no public REST /\n",
+        "SDK API for creating or modifying it (per\n",
+        "[Configure Unity AI Gateway endpoints](https://docs.databricks.com/aws/en/ai-gateway/configure-endpoints-beta)).\n",
+        "Do this manually in the workspace UI, **before** deploying the `all` target:\n",
+        "\n",
+        "1. **Enable the preview**\n",
+        "\n",
+        "   Account console → **Previews** → toggle **Unity AI Gateway** on. (Account\n",
+        "   admin only; skip if already enabled.)\n",
+        "\n",
+        "2. **Create the endpoint**\n",
+        "\n",
+        "   Workspace sidebar → **AI Gateway** → **Create Unity AI Gateway Endpoint**.\n",
+        "\n",
+        "   - **Name**: `dais2026-ai-gateway` (or pick another name — pass it via\n",
+        "     `--params \"AI_GATEWAY_ENDPOINT_NAME=<name>\"` at deploy time).\n",
+        "   - **Primary model**: a foundation model whose tool-use is good. We use\n",
+        "     `databricks-claude-sonnet-4-5` to match the agents' default `LLM_MODEL`.\n",
+        "   - Click **Create**.\n",
+        "\n",
+        "3. **Enable Inference Tables**\n",
+        "\n",
+        "   Endpoint detail page → **Inference Tables** → **Edit** → enable.\n",
+        "   Point it at a UC schema you control (e.g. `<your-catalog>.ai_gateway`).\n",
+        "   This populates `<catalog>.ai_gateway.<endpoint>_payload` with one row\n",
+        "   per request — both allowed and blocked.\n",
+        "\n",
+        "4. **Enable Usage Tracking**\n",
+        "\n",
+        "   Endpoint detail page → **Usage Tracking** → **Edit** → enable. Per-request\n",
+        "   token counts land in `system.ai_gateway.usage` (account admins only —\n",
+        "   if your user can't query that table, ask an account admin to grant\n",
+        "   `SELECT ON SCHEMA system.ai_gateway` to your group).\n",
+        "\n",
+        "5. **Configure Guardrails**\n",
+        "\n",
+        "   Endpoint detail page → **Guardrails** → **Edit**. Enable:\n",
+        "   - **PII Detection** = **Block** (rejects requests containing SSNs, credit\n",
+        "     cards, etc — returns HTTP 400 before the LLM sees them).\n",
+        "   - **Jailbreak and Prompt Injection** = on.\n",
+        "   - **Unsafe Content** = on.\n",
+        "\n",
+        "6. **Configure Rate Limits** (optional)\n",
+        "\n",
+        "   Endpoint detail page → **Rate Limits** → **Edit**. Set a per-user QPM /\n",
+        "   TPM limit if you want to demo the burst-test in `MLflow.ipynb` →\n",
+        "   \"Unity AI Gateway\" section. Skip otherwise.\n",
+        "\n",
+        "7. **Grant CAN_QUERY to `account users`**\n",
+        "\n",
+        "   Endpoint detail page → **Permissions** → **Add user / group** →\n",
+        "   `account users` → **CAN_QUERY**.\n",
+        "\n",
+        "   Why this is required and not auto-granted: v2 Beta gateway endpoints\n",
+        "   live on a separate API surface from regular serving endpoints, so the\n",
+        "   `mlflow.models.resources.DatabricksServingEndpoint(...)` resource\n",
+        "   listing that `agents.deploy()` uses to auto-grant CAN_QUERY does NOT\n",
+        "   work for them — it crashes with\n",
+        "   `NOT_FOUND: Dependent serving endpoint <gateway> does not exist`.\n",
+        "   Both the Refund and Complaint agent stages therefore **omit** the\n",
+        "   gateway from their `resources=[...]` lists and rely on you having\n",
+        "   granted CAN_QUERY manually here, so each deployed agent's runtime\n",
+        "   SP (a member of `account users`) can call the gateway at request\n",
+        "   time.\n",
+        "\n",
+        "   If you'd rather scope the grant tighter than `account users`, after\n",
+        "   the first successful deploy grant CAN_QUERY explicitly to each\n",
+        "   service principal that owns the agent endpoints\n",
+        "   (`<catalog>_refund_agent`, `<catalog>_complaint_agent`) — Serving →\n",
+        "   endpoint → Permissions → check the creator.\n",
+        "\n",
+        "8. **Deploy the `all` target with the gateway wired in**\n",
+        "\n",
+        "   ```bash\n",
+        "   databricks bundle deploy -t all\n",
+        "   databricks bundle run caspers -t all \\\n",
+        "     --params \"CATALOG=<your-catalog>,AI_GATEWAY_ENDPOINT_NAME=dais2026-ai-gateway\"\n",
+        "   ```\n",
+        "\n",
+        "   When `AI_GATEWAY_ENDPOINT_NAME` is non-empty:\n",
+        "   - The Refund agent's `agent.py` builds a LangChain `ChatOpenAI`\n",
+        "     pointed at `<host>/ai-gateway/mlflow/v1`.\n",
+        "   - The Complaint agent's `agent.py` configures DSPy with\n",
+        "     `dspy.LM('openai/<gateway>', api_base=<host>/ai-gateway/mlflow/v1, ...)`.\n",
+        "\n",
+        "   Both extract a fresh OAuth bearer from the runtime SP via\n",
+        "   `WorkspaceClient().config.authenticate()` at agent construction time\n",
+        "   (the SDK's `config.token` returns `None` in OAuth M2M mode, which is\n",
+        "   what `agents.deploy()` containers run under).\n",
+        "\n",
+        "   When empty (the `default` and `complaints` targets, or the `all`\n",
+        "   target without that param), each agent falls back to its previous\n",
+        "   direct foundation-model endpoint plumbing — `ChatDatabricks` for\n",
+        "   Refund, `dspy.LM('databricks/<model>')` for Complaint.\n",
+        "\n",
+        "> **Verify:** after deploy, send one request to each agent endpoint\n",
+        "> (`<catalog>_refund_agent`, `<catalog>_complaint_agent`) and check\n",
+        "> that two rows appear in `<catalog>.ai_gateway.<endpoint>_payload`.\n",
+        "> Both should show HTTP 200 with non-zero token counts."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "00000000-0000-0000-0000-000000000007",
+          "showTitle": false,
+          "title": ""
+        }
+      },
+      "source": [
+        "### Pre-show warm-up\n",
+        "\n",
+        "1. Open each runbook in the workspace and run its **pre-flight** cell\n",
+        "2. Click each app URL once (Ops Dashboard, Refund Manager) to dodge cold-start.\n",
+        "3. Click one sample question in each Genie space to warm `<catalog>-ops-warehouse` and `<catalog>-genie-warehouse`.\n",
+        "4. Open one Knowledge Assistant endpoint and the Supervisor endpoint to warm Model Serving.\n",
+        "5. Open all dashaboards\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "dashboards": [],
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "SETUP",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/demos/dais2026-runbooks/assets/Devhub.png b/demos/dais2026-runbooks/assets/Devhub.png
new file mode 100644
index 0000000..035e909
Binary files /dev/null and b/demos/dais2026-runbooks/assets/Devhub.png differ
diff --git a/demos/dais2026-runbooks/assets/Genie-Mobile3.gif b/demos/dais2026-runbooks/assets/Genie-Mobile3.gif
new file mode 100644
index 0000000..ab84411
Binary files /dev/null and b/demos/dais2026-runbooks/assets/Genie-Mobile3.gif differ
diff --git a/demos/dais2026-runbooks/assets/GenieOneChatv2.gif b/demos/dais2026-runbooks/assets/GenieOneChatv2.gif
new file mode 100644
index 0000000..fc9f1fe
Binary files /dev/null and b/demos/dais2026-runbooks/assets/GenieOneChatv2.gif differ
diff --git a/demos/dais2026-runbooks/assets/SA_architecture.png b/demos/dais2026-runbooks/assets/SA_architecture.png
new file mode 100644
index 0000000..758f4c0
Binary files /dev/null and b/demos/dais2026-runbooks/assets/SA_architecture.png differ
diff --git a/demos/dais2026-runbooks/assets/idp_demo.png b/demos/dais2026-runbooks/assets/idp_demo.png
new file mode 100644
index 0000000..035b903
Binary files /dev/null and b/demos/dais2026-runbooks/assets/idp_demo.png differ
diff --git a/demos/dais2026-runbooks/assets/lakebase.png b/demos/dais2026-runbooks/assets/lakebase.png
new file mode 100644
index 0000000..cf4cea3
Binary files /dev/null and b/demos/dais2026-runbooks/assets/lakebase.png differ
diff --git a/demos/dais2026-runbooks/assets/lakebase_usecases.png b/demos/dais2026-runbooks/assets/lakebase_usecases.png
new file mode 100644
index 0000000..e50c502
Binary files /dev/null and b/demos/dais2026-runbooks/assets/lakebase_usecases.png differ
diff --git a/demos/dais2026-runbooks/assets/mlflow_gen_arch.png b/demos/dais2026-runbooks/assets/mlflow_gen_arch.png
new file mode 100644
index 0000000..a02b182
Binary files /dev/null and b/demos/dais2026-runbooks/assets/mlflow_gen_arch.png differ
diff --git a/demos/multi-agent-supervisor/README.md b/demos/multi-agent-supervisor/README.md
deleted file mode 100644
index 216a119..0000000
--- a/demos/multi-agent-supervisor/README.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# Multi-Agent Supervisor Demo Flow
-
-The supervisor coordinates three sub-agents:
-
-- **Genie space** (`menu-safety-analytics`) -- structured SQL queries over silver and gold Delta tables
-- **Menu Knowledge Assistant** (`menu-document-search`) -- PDF document Q&A over 16 restaurant menu PDFs
-- **Inspection Knowledge Assistant** (`inspection-report-search`) -- PDF document Q&A over food safety inspection report PDFs
-
-The demo tells a story: start by exploring the menu portfolio, dig into specific dishes, pivot to food safety compliance, surface a serious problem in Chicago, and finish with the kind of cross-domain executive question that only a multi-agent system can answer.
-
----
-
-## Act 1: Menu Exploration
-
-*Routes to Genie (structured data)*
-
-Start casual, like a customer or ops manager browsing the data.
-
-**1. "What brands do we operate and what cuisines do they cover?"**
-
-Shows the 16 brands across Asian, Mexican, Italian, American, Vegan, etc.
-
-**2. "Which menu items are under $10 and allergen-free?"**
-
-Demonstrates the derived `price_tier` and `is_allergen_free` columns from the silver layer.
-
-**3. "Compare the average calories and protein across all our brands -- which is the healthiest?"**
-
-Hits the `brand_nutrition_summary` gold table. Shows aggregation and the `high_protein_items` / `low_calorie_items` / `allergen_free_items` counts. NootroNourish and Grain & Glory should stand out.
-
----
-
-## Act 2: Deep Dive into Documents
-
-*Routes to Menu Knowledge Assistant (PDF search)*
-
-Shift to questions that need actual PDF content, not structured data.
-
-**4. "Tell me about the Kung Pao Chicken from Wok This Way -- how is it prepared and what should I warn a customer about?"**
-
-Returns the description, allergen warnings (soy, peanut), and preparation details from the actual menu PDF with citations.
-
-**5. "What desserts does Pasta La Vista offer? Describe them."**
-
-Shows document retrieval with citations from the PDF. The structured tables only have item names; the PDFs have full prose descriptions.
-
----
-
-## Act 3: Safety Concerns
-
-*Routes to Inspection Knowledge Assistant (PDF search)*
-
-Pivot to compliance -- this is where the demo gets serious.
-
-**6. "What happened during the Chicago inspection in January? Were there any critical violations?"**
-
-Chicago's January 2024 inspection scored **69 (failing, grade F)** with a critical violation: *"Employee handling food without gloves after touching face/hair"* (code V-103, 3-day deadline). The PDF has full inspector notes and corrective action details.
-
-**7. "What corrective actions were required for the cross-contamination violation in Chicago?"**
-
-The February 2024 Chicago inspection (score 79, grade C) had a critical violation: *"Raw meat stored above ready-to-eat food in refrigeration unit"* (code V-102, 3-day deadline). Corrective action: rearrange refrigeration, retrain staff on storage hierarchy.
-
----
-
-## Act 4: Analytics + Safety Combined
-
-*Routes to Genie (structured data)*
-
-Use structured data to get the big picture on compliance.
-
-**8. "What is the pass rate and average severity index for each of our locations?"**
-
-Hits `location_compliance_summary`. Chicago will stand out as the worst performer. San Francisco shows a turnaround arc (82 -> 87 -> 96).
-
-**9. "Show me all violations that need immediate action -- deadline 7 days or less."**
-
-Filters `violation_analysis` on `needs_immediate_action = true`. Surfaces the critical violations in Chicago with 3-day deadlines.
-
----
-
-## Act 5: Cross-Domain Questions
-
-*Tests supervisor routing intelligence -- questions that blend domains*
-
-**10. "We have a customer with a peanut allergy ordering from Wok This Way. What should they avoid, and is that location safe to eat from?"**
-
-The supervisor should route the allergen part to Genie or Menu KA, and the safety part to Inspection KA or Genie. Demonstrates multi-agent coordination.
-
-**11. "I need a summary for our board meeting: how many brands do we run, what is our average menu price, and are there any outstanding critical food safety issues?"**
-
-Supervisor needs Genie for brand count + pricing, and Inspection KA or Genie for critical safety issues. Classic executive summary question.
-
-**12. "Which location would you recommend we expand first based on both menu variety and food safety record?"**
-
-Open-ended reasoning question. The supervisor should pull compliance data from Genie and menu data to form a recommendation.
-
----
-
-## Key Data Points
-
-### Locations and inspection scores
-
-| Location | Jan 2024 | Feb 2024 | Mar 2024 | Story |
-|---|---|---|---|---|
-| San Francisco | 82 (B) | 87 (B) | 96 (A) | Turnaround story |
-| Silicon Valley | 85 (B) | 94 (A) | 90 (A) | Consistently good |
-| Bellevue | 88 (B) | 87 (B) | 90 (A) | Steady improvement |
-| Chicago | 69 (F) | 79 (C) | 91 (A) | Problem location that recovered |
-
-### Brands (16 total)
-
-Wok This Way, Pho Real, Thai One On, Taco 'Bout It, Burrito Bandits, Five Gals Burgers, Cluck Yeah, Wing Commander, Grain & Glory, NootroNourish, Green Machine, Pasta La Vista, Pizza My Heart, Seoul Food, Curry Up, Mediterranean Nights
-
-### Notable data for the demo
-
-- **Chicago critical violations**: Employee handling food without gloves (Jan), raw meat above ready-to-eat food (Feb) -- both with 3-day corrective deadlines
-- **Allergen-rich items**: Shrimp Lo Mein (wheat, soy, shellfish, egg), many Asian dishes with soy + peanut
-- **Health brands**: NootroNourish and Grain & Glory have the highest protein ratios and most low-calorie items
-- **Price range**: Budget tier (under $10) through premium tier (over $18)
-
----
-
-## Architecture
-
-The supervisor routes based on question intent:
-
-```
-User Question
-     |
-     v
-Multi-Agent Supervisor
-     |
-     +---> [Genie space] -- numbers, counts, comparisons, filtering, aggregations
-     |
-     +---> [Menu Knowledge Assistant] -- dish descriptions, preparation details, ingredient info
-     |
-     +---> [Inspection Knowledge Assistant] -- violation details, inspector findings, corrective actions
-```
-
-### What each agent sees
-
-- **Genie**: 10 Delta tables (3 silver + 7 gold) with structured, queryable data
-- **Menu KA**: 16 PDF menu files in `/Volumes/{CATALOG}/menu_documents/menus/`
-- **Inspection KA**: 12 PDF inspection reports in `/Volumes/{CATALOG}/food_safety/reports/`
diff --git a/destroy.ipynb b/destroy.ipynb
index 22ed050..47f106a 100644
--- a/destroy.ipynb
+++ b/destroy.ipynb
@@ -1,191 +1,288 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "444a0b62-da37-41a8-b72e-7af7addf266f",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "### Casper's Ghost Kitchen Destroyer\n",
-    "\n",
-    "Select `Run All` to destroy Casper's Databricks environment"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "afc359c7-cc4d-4cf3-91ba-9fbabfbf160d",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%pip install databricks-sdk --upgrade"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "8b3d2fd6-9fbf-4103-9aca-d6f1e887e5d0",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%restart_python"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import sys\n",
-    "sys.path.append('./utils')\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "print(f\"Destroying resources for catalog: {CATALOG}\")\n",
-    "\n",
-    "state = None\n",
-    "try:\n",
-    "    from uc_state import create_state_manager\n",
-    "    state = create_state_manager(CATALOG)\n",
-    "    print(f\"State manager initialized for {CATALOG}\")\n",
-    "except Exception as e:\n",
-    "    print(f\"⚠️ Could not initialize state manager: {e}\")\n",
-    "    print(\"This usually means the catalog or state table doesn't exist. Skipping resource cleanup.\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "if state:\n",
-    "    try:\n",
-    "        results = state.clear_all()\n",
-    "        for rtype, info in results.items():\n",
-    "            if info[\"successful\"]:\n",
-    "                print(f\"✅ {rtype}: deleted {len(info['successful'])} resources\")\n",
-    "            if info[\"failed\"]:\n",
-    "                print(f\"⚠️ {rtype}: {len(info['failed'])} failures\")\n",
-    "                for f in info[\"failed\"]:\n",
-    "                    print(f\"   - {f['name']}: {f['reason']}\")\n",
-    "    except Exception as e:\n",
-    "        print(f\"⚠️ clear_all() failed: {e}\")\n",
-    "        print(\"Continuing with catalog drop...\")\n",
-    "else:\n",
-    "    print(\"No state manager available. Skipping resource cleanup, proceeding to catalog drop.\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "implicitDf": true,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "f4149da3-178c-4a26-bd52-3185e45ece03",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "DROP CATALOG IF EXISTS IDENTIFIER(:CATALOG) CASCADE;"
-   ]
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "mostRecentlyExecutedCommandWithImplicitDF": {
-     "commandId": 5241498588669022,
-     "dataframes": [
-      "_sqldf"
-     ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {
+            "byteLimit": 2048000,
+            "rowLimit": 10000
+          },
+          "inputWidgets": {},
+          "nuid": "444a0b62-da37-41a8-b72e-7af7addf266f",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "\n",
+        "### Casper's Ghost Kitchen Destroyer\n",
+        "\n",
+        "Select `Run All` to destroy Casper's Databricks environment"
+      ]
     },
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "destroy",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "caspers",
-     "nuid": "6bec1649-a0df-4b8c-acef-aeb2251e2d57",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {
+            "byteLimit": 2048000,
+            "rowLimit": 10000
+          },
+          "inputWidgets": {},
+          "nuid": "afc359c7-cc4d-4cf3-91ba-9fbabfbf160d",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
       },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
+      "source": [
+        "%pip install databricks-sdk --upgrade"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {
+            "byteLimit": 2048000,
+            "rowLimit": 10000
+          },
+          "inputWidgets": {},
+          "nuid": "8b3d2fd6-9fbf-4103-9aca-d6f1e887e5d0",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "%restart_python"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import sys\n",
+        "sys.path.append('./utils')\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "print(f\"Destroying resources for catalog: {CATALOG}\")\n",
+        "\n",
+        "state = None\n",
+        "try:\n",
+        "    from uc_state import create_state_manager\n",
+        "    state = create_state_manager(CATALOG)\n",
+        "    print(f\"State manager initialized for {CATALOG}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"⚠️ Could not initialize state manager: {e}\")\n",
+        "    print(\"This usually means the catalog or state table doesn't exist. Skipping resource cleanup.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "if state:\n",
+        "    try:\n",
+        "        results = state.clear_all()\n",
+        "        for rtype, info in results.items():\n",
+        "            if info[\"successful\"]:\n",
+        "                print(f\"✅ {rtype}: deleted {len(info['successful'])} resources\")\n",
+        "            if info[\"failed\"]:\n",
+        "                print(f\"⚠️ {rtype}: {len(info['failed'])} failures\")\n",
+        "                for f in info[\"failed\"]:\n",
+        "                    print(f\"   - {f['name']}: {f['reason']}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️ clear_all() failed: {e}\")\n",
+        "        print(\"Continuing with catalog drop...\")\n",
+        "else:\n",
+        "    print(\"No state manager available. Skipping resource cleanup, proceeding to catalog drop.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Belt-and-suspenders sweep BEFORE the catalog drop below.\n",
+        "#\n",
+        "# Why this exists:\n",
+        "#   `state.clear_all()` above only deletes resources tracked in\n",
+        "#   `<CATALOG>._caspers_state.resources`.  The state table itself lives inside\n",
+        "#   <CATALOG>, so any prior `destroy` that half-succeeded — `clear_all()`\n",
+        "#   errored or skipped rows, then the catalog drop wiped the table anyway —\n",
+        "#   leaves orphans with no row anywhere to drive future cleanups.\n",
+        "#\n",
+        "#   Agent serving endpoints, Knowledge Assistants, and Multi-Agent Supervisors\n",
+        "#   all live OUTSIDE Unity Catalog, so they survive `DROP CATALOG CASCADE`\n",
+        "#   indefinitely.  We observed this in practice: after a destroy+redeploy\n",
+        "#   cycle the state table came back empty while 4 serving endpoints and 7\n",
+        "#   KAs/MAS in the `<CATALOG>` namespace were still alive.  The reuse path in\n",
+        "#   `stages/refunder_agent` and `stages/complaint_agent` explicitly skips\n",
+        "#   `add(...)` when an endpoint is reused, so they would never be re-tracked.\n",
+        "#\n",
+        "# What it does:\n",
+        "#   For every serving endpoint whose name starts with `<CATALOG>_` and every\n",
+        "#   tile (KA / MAS) whose name starts with `<CATALOG>-`, attempt deletion.\n",
+        "#   Best-effort: 'already-gone' and any other error is logged but does not\n",
+        "#   block the catalog drop downstream.\n",
+        "#\n",
+        "# Naming conventions assumed (current in this repo):\n",
+        "#   - serving endpoints:  `<CATALOG>_<purpose>_agent`  e.g. `oleksandra_refund_agent`\n",
+        "#   - KA / MAS tiles:     `<CATALOG>-<purpose>`        e.g. `oleksandra-legal`\n",
+        "# If those conventions change, update the prefix tests below.\n",
+        "\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "_w = WorkspaceClient()\n",
+        "_CAT_LOWER = CATALOG.lower()\n",
+        "\n",
+        "\n",
+        "def _is_not_found(e):\n",
+        "    if type(e).__name__ in {\"NotFound\", \"ResourceDoesNotExist\"}:\n",
+        "        return True\n",
+        "    m = str(e).lower()\n",
+        "    return \"does not exist\" in m or \"not found\" in m or \"no such\" in m or \"404\" in m\n",
+        "\n",
+        "\n",
+        "print(f\"\\n🔎 Sweep: serving endpoints matching '{_CAT_LOWER}_*'\")\n",
+        "for ep in _w.serving_endpoints.list():\n",
+        "    name = (ep.name or \"\")\n",
+        "    if not name.lower().startswith(f\"{_CAT_LOWER}_\"):\n",
+        "        continue\n",
+        "    try:\n",
+        "        _w.serving_endpoints.delete(name=name)\n",
+        "        print(f\"  ✅ deleted endpoint {name}\")\n",
+        "    except Exception as e:\n",
+        "        if _is_not_found(e):\n",
+        "            print(f\"  ↪︎ already gone     {name}\")\n",
+        "        else:\n",
+        "            print(f\"  ⚠️  {name}: {type(e).__name__}: {e}\")\n",
+        "\n",
+        "print(f\"\\n🔎 Sweep: tiles (KA / MAS) matching '{_CAT_LOWER}-*'\")\n",
+        "try:\n",
+        "    _tiles_res = _w.api_client.do(\"GET\", \"/api/2.0/tiles\")\n",
+        "    _tiles = _tiles_res.get(\"tiles\", []) if isinstance(_tiles_res, dict) else []\n",
+        "except Exception as e:\n",
+        "    print(f\"  ⚠️  tiles.list failed: {type(e).__name__}: {e}\")\n",
+        "    _tiles = []\n",
+        "\n",
+        "for _t in _tiles:\n",
+        "    _name = (_t.get(\"name\") or \"\")\n",
+        "    if not _name.lower().startswith(f\"{_CAT_LOWER}-\"):\n",
+        "        continue\n",
+        "    _tile_id = _t.get(\"id\") or _t.get(\"tile_id\")\n",
+        "    _kind = (_t.get(\"tile_type\") or _t.get(\"type\") or \"\").upper()\n",
+        "    # Same path precedence uc_state.clear_all() uses: typed APIs first, then\n",
+        "    # Tiles API as the legacy fallback.\n",
+        "    _paths = (\n",
+        "        [\"/api/2.1/knowledge-assistants\", \"/api/2.0/knowledge-assistants\", \"/api/2.0/tiles\"]\n",
+        "        if _kind == \"KA\" else\n",
+        "        [\"/api/2.0/multi-agent-supervisors\", \"/api/2.0/tiles\"]\n",
+        "    )\n",
+        "    _deleted = False\n",
+        "    _last_err = None\n",
+        "    for _p in _paths:\n",
+        "        try:\n",
+        "            _w.api_client.do(\"DELETE\", f\"{_p}/{_tile_id}\")\n",
+        "            print(f\"  ✅ deleted {_kind or '???':3} {_name!r} via {_p}\")\n",
+        "            _deleted = True\n",
+        "            break\n",
+        "        except Exception as e:\n",
+        "            _last_err = e\n",
+        "    if not _deleted:\n",
+        "        print(f\"  ⚠️  {_name!r}: tried all paths, last err: {type(_last_err).__name__}: {_last_err}\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {
+            "byteLimit": 2048000,
+            "implicitDf": true,
+            "rowLimit": 10000
+          },
+          "inputWidgets": {},
+          "nuid": "f4149da3-178c-4a26-bd52-3185e45ece03",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "%sql\n",
+        "DROP CATALOG IF EXISTS IDENTIFIER(:CATALOG) CASCADE;"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
       },
-      "widgetType": "text"
-     }
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "mostRecentlyExecutedCommandWithImplicitDF": {
+          "commandId": 5241498588669022,
+          "dataframes": [
+            "_sqldf"
+          ]
+        },
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "destroy",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "caspers",
+          "nuid": "6bec1649-a0df-4b8c-acef-aeb2251e2d57",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
     }
-   }
   },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
+  "nbformat": 4,
+  "nbformat_minor": 0
 }
\ No newline at end of file
diff --git a/init.ipynb b/init.ipynb
deleted file mode 100644
index f1ffced..0000000
--- a/init.ipynb
+++ /dev/null
@@ -1,165 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "ddd5b0fd-469c-4eb8-b467-64c128596d15",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": "### Casper's Ghost Kitchen Initializer\n\nSelect `Run All` to create the job `Casper's Initializer`. Once this notebook has been run you can initialize the Casper's environment using the job, which also allows you to selectively create only parts of the demo (broken into tasks within the job).\n\n**After running this notebook:**\n- Navigate to Jobs & Pipelines in the left sidebar of your Databricks workspace\n- Find and run the `Casper's Initializer` job\n- You can pick a subset of tasks to run if you want. The `Raw_Data` and `Lakeflow_Declarative_Pipeline` tasks are required, but downstream tasks are demo-specific and you can run whichever ones you need.\n\n**Important Note on Catalog Name:**\nThe default catalog name is `caspers`. If you're working in a metastore that spans multiple workspaces and another workspace has already used this catalog name, you'll need to specify a different name using the `CATALOG` parameter. Catalog names must be unique within a metastore."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "45bf8d75-b68f-4025-95df-41b9909f2361",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "19fe1502-c847-4132-9149-46635a242995",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "1d1d1f12-be67-4d2f-bee4-59a9cc79313c",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "0639bcef-fd51-4ba2-8f2f-8cea09272e9a",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": "from databricks.sdk.service.jobs import JobSettings as Job\nimport os\n\nCasper_s_Initializer = Job.from_dict(\n    {\n        \"name\": \"Casper's Initializer\",\n        \"tasks\": [\n            {\n                \"task_key\": \"Raw_Data\",\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/raw_data\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Lakeflow_Declarative_Pipeline\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Raw_Data\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/lakeflow\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Refund_Recommender_Agent\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Lakeflow_Declarative_Pipeline\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/refunder_agent\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Refund_Recommender_Stream\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Lakeflow_Declarative_Pipeline\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/refunder_stream\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Complaint_Agent\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Lakeflow_Declarative_Pipeline\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/complaint_agent\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Complaint_Generator_Stream\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Lakeflow_Declarative_Pipeline\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/complaint_generator_stream\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Complaint_Agent_Stream\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Complaint_Agent\",\n                    },\n                    {\n                        \"task_key\": \"Complaint_Generator_Stream\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/complaint_agent_stream\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Complaint_Lakebase\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Complaint_Agent_Stream\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/complaint_lakebase\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Lakebase_Reverse_ETL\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Refund_Recommender_Stream\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/lakebase\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n            {\n                \"task_key\": \"Databricks_App_Refund_Manager\",\n                \"depends_on\": [\n                    {\n                        \"task_key\": \"Lakebase_Reverse_ETL\",\n                    },\n                ],\n                \"notebook_task\": {\n                    \"notebook_path\": os.path.abspath(\"./stages/apps\"),\n                    \"source\": \"WORKSPACE\",\n                },\n            },\n        ],\n        \"queue\": {\n            \"enabled\": True,\n        },\n        \"parameters\": [\n            {\n                \"name\": \"CATALOG\",\n                \"default\": f\"{CATALOG}\",\n            },\n            {\n                \"name\": \"EVENTS_VOLUME\",\n                \"default\": \"events\",\n            },\n            {\n                \"name\": \"LLM_MODEL\",\n                \"default\": \"databricks-meta-llama-3-3-70b-instruct\",\n            },\n            {\n                \"name\": \"REFUND_AGENT_ENDPOINT_NAME\",\n                \"default\": \"caspers_refund_agent\",\n            },\n            {\n                \"name\": \"COMPLAINT_AGENT_ENDPOINT_NAME\",\n                \"default\": \"caspers_complaint_agent\",\n            },\n            {\n                \"name\": \"COMPLAINT_RATE\",\n                \"default\": \"0.15\",\n            },\n            {\n                \"name\": \"SIMULATOR_SCHEMA\",\n                \"default\": \"simulator\",\n            },\n            {\n                \"name\": \"LOCATIONS\",\n                \"default\": \"sanfrancisco.json\",\n            },\n        ],\n        \"performance_target\": \"PERFORMANCE_OPTIMIZED\",\n    }\n)\n\nfrom databricks.sdk import WorkspaceClient\n\nw = WorkspaceClient()\nw.jobs.create(**Casper_s_Initializer.as_shallow_dict())"
-  },
-  {
-   "cell_type": "code",
-   "source": "print(f\"✅ Job created! Go to Jobs & Pipelines → 'Casper's Initializer' to run it\")",
-   "metadata": {},
-   "execution_count": null,
-   "outputs": []
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "mostRecentlyExecutedCommandWithImplicitDF": {
-     "commandId": 8588875451726566,
-     "dataframes": [
-      "_sqldf"
-     ]
-    },
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "init",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "caspers",
-     "nuid": "11cbec7a-980d-492b-af6d-47c909c273ce",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "caspers",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "caspers",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
-      },
-      "widgetType": "text"
-     }
-    }
-   }
-  },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
-}
\ No newline at end of file
diff --git a/jobs/complaint_agent_stream.ipynb b/jobs/complaint_agent_stream.ipynb
index 4c2a816..398bc73 100644
--- a/jobs/complaint_agent_stream.ipynb
+++ b/jobs/complaint_agent_stream.ipynb
@@ -1,112 +1,404 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Complaint Agent Stream\n",
-    "\n",
-    "This notebook streams complaints through the complaint agent for processing"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Complaint Agent Stream\n",
+        "\n",
+        "This notebook streams complaints through the complaint agent for processing"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
+        "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "COMPLAINT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install openai"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "import os\n",
+        "import random\n",
+        "\n",
+        "from pyspark.sql import functions as F\n",
+        "from pyspark.sql.types import StringType\n",
+        "from pyspark.sql.functions import udf\n",
+        "from pyspark.sql.window import Window\n",
+        "\n",
+        "from openai import OpenAI\n",
+        "\n",
+        "# Per-call timeout in seconds.  Without this, a stalled / scale-to-zero /\n",
+        "# deleted complaint-agent endpoint causes the underlying HTTP socket to hang\n",
+        "# indefinitely (we observed a single stream run hung for 3h47m on a previous\n",
+        "# test session, blocking the cron queue).  30s is generous for a healthy agent\n",
+        "# call (typical latency is 2-5s) but bounds the worst case.\n",
+        "_CALL_TIMEOUT_S = 30\n",
+        "\n",
+        "# Per-batch inference cap and checkpoint path.\n",
+        "# Why this exists: previously this stream had no cap — `availableNow=True` would\n",
+        "# drain the entire `raw_complaints` backlog through the agent UDF in one go,\n",
+        "# and a few hundred rows of backlog times 5-30s per call easily blew through\n",
+        "# the 10-min `timeout_seconds` task budget. The cron then dropped subsequent\n",
+        "# ticks (queue.enabled=False) and the backlog kept growing forever.\n",
+        "#\n",
+        "# Sizing the cap (10) against measured endpoint latency:\n",
+        "#   - Observed warm latency on this complaint-agent endpoint is 16-21s/call,\n",
+        "#     not the 2-5s the prior comment assumed.  With the previous cap of 20\n",
+        "#     and a 3-attempt retry loop, a single timed-out call cost up to 90s,\n",
+        "#     and we consistently blew the 600s budget at ~615s (every cron tick).\n",
+        "#   - With MAX=10 and no retries (see process_complaint below):\n",
+        "#       worst case   10 × 30s        = 300s  (~5min slack)\n",
+        "#       typical      10 × 18s        = 180s  (~7min slack)\n",
+        "#   - Refund + support streams use 50 because their endpoints are faster;\n",
+        "#     do not blindly copy that cap here without re-measuring.\n",
+        "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/complaints/checkpoints/complaint_agent_stream\"\n",
+        "# Sized for the 600s task timeout.  The complaint agent (DSPy ReAct) measured\n",
+        "# at ~38s per call — markedly slower than the refunder (~12s) because it does\n",
+        "# more tool-call iterations per complaint.  5 × 38 ≈ 190s leaves room for\n",
+        "# cold-start jitter, Delta write, and is_first_run() probes; 10 × 38 = 380s\n",
+        "# + ~250s overhead was tipping over the 600s wall once the endpoint was\n",
+        "# fully healthy.\n",
+        "MAX_INFERENCES_PER_BATCH = 5\n",
+        "\n",
+        "\n",
+        "def is_first_run():\n",
+        "    \"\"\"True when no micro-batch has been committed yet — drives the\n",
+        "    fake-it-till-up backfill path on cold start.\n",
+        "\n",
+        "    Looks at the `commits/` subdirectory specifically.  Spark Structured\n",
+        "    Streaming creates `offsets/`, `commits/`, `metadata`, `sources/` *before*\n",
+        "    the first call to `process_batch`, so the older heuristic of\n",
+        "    `os.listdir(CHECKPOINT_PATH) == 0` always returned False on the very first\n",
+        "    batch — silently disabling the fast path and forcing the entire historical\n",
+        "    backlog through the real-inference codepath in a single micro-batch (which\n",
+        "    is what kept blowing past the 10-min task timeout).  A non-hidden file\n",
+        "    under `commits/` is the unambiguous signal that this is not the first run.\n",
+        "    \"\"\"\n",
+        "    commits_dir = os.path.join(CHECKPOINT_PATH, \"commits\")\n",
+        "    if not os.path.exists(commits_dir):\n",
+        "        return True\n",
+        "    return not any(\n",
+        "        not f.startswith(\".\") and not f.startswith(\"_\")\n",
+        "        for f in os.listdir(commits_dir)\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "# ── Deterministic fallback responses ──────────────────────────────────────────\n",
+        "# Used both during initial backfill (when the checkpoint is empty, so we want\n",
+        "# to drain the entire historical source instantly) and as the per-batch\n",
+        "# overflow path beyond MAX_INFERENCES_PER_BATCH.  Schema matches the real\n",
+        "# agent response shape; values are realistic decision/credit pairs.\n",
+        "\n",
+        "fake_responses = [\n",
+        "    {\n",
+        "        \"complaint_category\": \"late_delivery\",\n",
+        "        \"decision\": \"credit\",\n",
+        "        \"credit_amount\": 5.0,\n",
+        "        \"rationale\": \"Order delivered after P75 threshold for the location.\",\n",
+        "        \"customer_response\": \"Sorry about the late delivery — we've issued a $5.00 credit to your account.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"complaint_category\": \"missing_item\",\n",
+        "        \"decision\": \"credit\",\n",
+        "        \"credit_amount\": 7.5,\n",
+        "        \"rationale\": \"Missing-item complaints are auto-credited at item value when verified by order line.\",\n",
+        "        \"customer_response\": \"We're sorry an item was missing from your order — we've added a $7.50 credit.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"complaint_category\": \"food_quality\",\n",
+        "        \"decision\": \"escalate\",\n",
+        "        \"credit_amount\": 0.0,\n",
+        "        \"rationale\": \"Food-quality complaints route to a human reviewer with kitchen photos.\",\n",
+        "        \"customer_response\": \"Thanks for the report — our quality team will follow up within 24 hours.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"complaint_category\": \"wrong_order\",\n",
+        "        \"decision\": \"credit\",\n",
+        "        \"credit_amount\": 10.0,\n",
+        "        \"rationale\": \"Wrong-order complaints trigger a same-day credit equal to subtotal cap.\",\n",
+        "        \"customer_response\": \"Apologies for the mixup — a $10.00 credit has been applied to your account.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"complaint_category\": \"other\",\n",
+        "        \"decision\": \"no_action\",\n",
+        "        \"credit_amount\": 0.0,\n",
+        "        \"rationale\": \"Insufficient signal for automated remediation; no credit.\",\n",
+        "        \"customer_response\": \"Thanks for reaching out — we'll look into this and follow up if needed.\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "\n",
+        "def get_fake_response(order_id: str) -> str:\n",
+        "    \"\"\"Return a deterministic fake response with the order_id filled in.\n",
+        "    Fast path for backfill and overflow rows.\"\"\"\n",
+        "    resp = random.choice(fake_responses).copy()\n",
+        "    resp[\"order_id\"] = order_id\n",
+        "    return json.dumps(resp)\n",
+        "\n",
+        "\n",
+        "def process_complaint(complaint_text: str, order_id: str) -> str:\n",
+        "    \"\"\"Process a complaint through the agent endpoint.\n",
+        "\n",
+        "    Returns a JSON-encoded response.  On any failure returns a default\n",
+        "    \"escalate\" response so the streaming write can still progress \\u2014 we'd rather mark the complaint as needing human\n",
+        "    review than hang the batch.\n",
+        "    \"\"\"\n",
+        "    client = OpenAI(\n",
+        "        api_key=DATABRICKS_TOKEN,\n",
+        "        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n",
+        "        timeout=_CALL_TIMEOUT_S,\n",
+        "    )\n",
+        "\n",
+        "    default_response = json.dumps({\n",
+        "        \"order_id\": order_id,\n",
+        "        \"complaint_category\": \"other\",\n",
+        "        \"decision\": \"escalate\",\n",
+        "        \"credit_amount\": 0.0,\n",
+        "        \"rationale\": \"agent did not return valid JSON\",\n",
+        "        \"customer_response\": \"We're reviewing your complaint and will get back to you shortly.\"\n",
+        "    })\n",
+        "\n",
+        "    # No retry: the dominant failure mode here is HTTP timeout, and each\n",
+        "    # retry costs the full _CALL_TIMEOUT_S of wall time.  Previous versions\n",
+        "    # did 3 blind retries, making the worst-case per-row cost 90s and\n",
+        "    # consistently blowing the 600s task budget (we observed ~615s every\n",
+        "    # cron tick).  For an availableNow catch-up stream the next tick will\n",
+        "    # re-process anything we escalate here, so fail-fast keeps each batch\n",
+        "    # bounded; the backlog drains on the next tick instead of stalling now.\n",
+        "    try:\n",
+        "        response_obj = client.responses.create(\n",
+        "            model=f\"{COMPLAINT_AGENT_ENDPOINT_NAME}\",\n",
+        "            input=[{\n",
+        "                \"role\": \"user\",\n",
+        "                \"content\": f\"{complaint_text} (Order ID: {order_id})\"\n",
+        "            }],\n",
+        "            timeout=_CALL_TIMEOUT_S,\n",
+        "        )\n",
+        "        response = response_obj.output[-1].content[0].text\n",
+        "        json.loads(response)\n",
+        "        return response\n",
+        "    except Exception:\n",
+        "        return default_response\n",
+        "\n",
+        "\n",
+        "process_complaint_udf = udf(process_complaint, StringType())\n",
+        "get_fake_response_udf = udf(get_fake_response, StringType())"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Stream processing.  Wrapped in a builder so the retry path can pass\n",
+        "# startingVersion=\"latest\" and skip a historical backfill after a table recreate.\n",
+        "# Note: unlike the previous version, we deliberately keep the raw columns here\n",
+        "# and run the agent UDF inside the foreachBatch handler so we can cap the\n",
+        "# number of real inferences per micro-batch (see process_batch).\n",
+        "def _build_complaint_source(starting_version=None):\n",
+        "    reader = spark.readStream\n",
+        "    if starting_version is not None:\n",
+        "        reader = reader.option(\"startingVersion\", str(starting_version))\n",
+        "    return reader.table(f\"{CATALOG}.complaints.raw_complaints\").select(\n",
+        "        F.col(\"complaint_id\"),\n",
+        "        F.col(\"order_id\"),\n",
+        "        F.col(\"complaint_text\"),\n",
+        "        F.col(\"ts\").alias(\"source_ts\"),\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "complaint_source = _build_complaint_source()\n",
+        "\n",
+        "\n",
+        "def process_batch(batch_df, batch_id):\n",
+        "    \"\"\"Process each micro-batch with inference capping.\n",
+        "\n",
+        "    - First run (no checkpoint): ALL rows get fake responses (fast backfill).\n",
+        "    - Subsequent runs: first MAX_INFERENCES_PER_BATCH rows get real agent\n",
+        "      inference, rest get deterministic fakes.  This bounds per-run wall time\n",
+        "      to roughly MAX_INFERENCES_PER_BATCH * worst_case_latency, so a backlog\n",
+        "      cannot blow the 10-min task timeout.\n",
+        "    \"\"\"\n",
+        "    if batch_df.isEmpty():\n",
+        "        return\n",
+        "\n",
+        "    first_run = is_first_run()\n",
+        "    row_count = batch_df.count()\n",
+        "\n",
+        "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
+        "\n",
+        "    if first_run:\n",
+        "        # Drain the historical backlog with fakes — fast path.\n",
+        "        print(f\"  -> First run detected, using fake responses for all {row_count} rows\")\n",
+        "        result_df = batch_df.select(\n",
+        "            F.col(\"complaint_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\"),\n",
+        "        )\n",
+        "    else:\n",
+        "        # Stable order so the cap is deterministic and resumable.\n",
+        "        windowed = batch_df.withColumn(\n",
+        "            \"row_num\",\n",
+        "            F.row_number().over(Window.orderBy(F.col(\"source_ts\"), F.col(\"complaint_id\"))),\n",
+        "        )\n",
+        "\n",
+        "        real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
+        "        fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
+        "        print(f\"  -> Real inference: {real_count} rows, fake: {fake_count} rows\")\n",
+        "\n",
+        "        real_inference_df = windowed.filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\").select(\n",
+        "            F.col(\"complaint_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            process_complaint_udf(F.col(\"complaint_text\"), F.col(\"order_id\")).alias(\"agent_response\"),\n",
+        "        )\n",
+        "\n",
+        "        fake_response_df = windowed.filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\").select(\n",
+        "            F.col(\"complaint_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\"),\n",
+        "        )\n",
+        "\n",
+        "        result_df = real_inference_df.union(fake_response_df)\n",
+        "\n",
+        "    result_df.write.mode(\"append\").saveAsTable(f\"{CATALOG}.complaints.complaint_responses\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.complaints;\n",
+        "CREATE VOLUME IF NOT EXISTS ${CATALOG}.complaints.checkpoints;"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE TABLE IF NOT EXISTS ${CATALOG}.complaints.complaint_responses (\n",
+        "  complaint_id STRING,\n",
+        "  order_id STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  agent_response STRING\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Enable Change Data Feed for Lakebase sync — idempotent so we don't churn\n",
+        "# the Delta table history with a SET TBLPROPERTIES commit on every cron tick\n",
+        "# (we observed 4+ no-op SET TBLPROPERTIES versions accumulating from this).\n",
+        "table_name = f\"{CATALOG}.complaints.complaint_responses\"\n",
+        "\n",
+        "try:\n",
+        "    props = spark.sql(f\"SHOW TBLPROPERTIES {table_name}\").collect()\n",
+        "    cdc_enabled = any(row.key == \"delta.enableChangeDataFeed\" and row.value == \"true\" for row in props)\n",
+        "except Exception:\n",
+        "    cdc_enabled = False\n",
+        "\n",
+        "if not cdc_enabled:\n",
+        "    print(f\"Enabling CDC on {table_name}\")\n",
+        "    spark.sql(f\"ALTER TABLE {table_name} SET TBLPROPERTIES (delta.enableChangeDataFeed = true)\")\n",
+        "else:\n",
+        "    print(f\"CDC already enabled on {table_name}, skipping\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Process with foreachBatch so process_batch can apply the per-batch inference\n",
+        "# cap (see cell defining MAX_INFERENCES_PER_BATCH).\n",
+        "def _run_stream(stream_df):\n",
+        "    q = (\n",
+        "        stream_df.writeStream\n",
+        "        .foreachBatch(process_batch)\n",
+        "        .option(\"checkpointLocation\", CHECKPOINT_PATH)\n",
+        "        .trigger(availableNow=True)\n",
+        "        .start()\n",
+        "    )\n",
+        "    q.awaitTermination()\n",
+        "\n",
+        "\n",
+        "# Recoverable errors that all warrant clearing the checkpoint and restarting\n",
+        "# from the LATEST version of the source:\n",
+        "#   - DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE: source table was recreated.\n",
+        "#   - STREAMING_CHECKPOINT_METADATA_ERROR / MISSING_METADATA_FILE: checkpoint\n",
+        "#     directory was partially wiped (e.g. by `bundle run cleanup`) leaving\n",
+        "#     offsets/commits without the metadata file, which Spark refuses to start on.\n",
+        "_RECOVERABLE_MARKERS = (\n",
+        "    \"DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE\",\n",
+        "    \"STREAMING_CHECKPOINT_METADATA_ERROR\",\n",
+        "    \"MISSING_METADATA_FILE\",\n",
+        ")\n",
+        "\n",
+        "try:\n",
+        "    _run_stream(complaint_source)\n",
+        "except Exception as e:\n",
+        "    msg = str(e)\n",
+        "    if any(marker in msg for marker in _RECOVERABLE_MARKERS):\n",
+        "        first_line = msg.splitlines()[0] if msg else \"\"\n",
+        "        print(\n",
+        "            f\"⚠️ Streaming state unrecoverable ({first_line}). \"\n",
+        "            f\"Clearing stale checkpoint at {CHECKPOINT_PATH} and restarting \"\n",
+        "            f\"from the LATEST version of the source (historical backfill skipped).\"\n",
+        "        )\n",
+        "        dbutils.fs.rm(CHECKPOINT_PATH, recurse=True)\n",
+        "        print(f\"✅ Cleared {CHECKPOINT_PATH}\")\n",
+        "        _run_stream(_build_complaint_source(starting_version=\"latest\"))\n",
+        "    else:\n",
+        "        raise"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9.0"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
-    "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "COMPLAINT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install openai"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from pyspark.sql import functions as F\nfrom pyspark.sql.types import StringType\nfrom pyspark.sql.functions import udf\nimport json\n\nfrom openai import OpenAI\n\ndef process_complaint(complaint_text: str, order_id: str) -> str:\n    \"\"\"Process a complaint through the agent endpoint.\"\"\"\n    client = OpenAI(\n        api_key=DATABRICKS_TOKEN,\n        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n    )\n    \n    default_response = json.dumps({\n        \"order_id\": order_id,\n        \"complaint_category\": \"other\",\n        \"decision\": \"escalate\",\n        \"credit_amount\": 0.0,\n        \"rationale\": \"agent did not return valid JSON\",\n        \"customer_response\": \"We're reviewing your complaint and will get back to you shortly.\"\n    })\n    \n    for _ in range(3):\n        try:\n            # Call agent endpoint using Responses SDK\n            response_obj = client.responses.create(\n                model=f\"{COMPLAINT_AGENT_ENDPOINT_NAME}\",\n                input=[{\n                    \"role\": \"user\", \n                    \"content\": f\"{complaint_text} (Order ID: {order_id})\"\n                }]\n            )\n            # Extract text from ResponsesAgent output structure\n            response = response_obj.output[-1].content[0].text\n            \n            # Validate JSON\n            json.loads(response)\n            return response\n        except Exception as e:\n            # If call fails, continue to retry\n            continue\n    \n    # After 3 retries, return default response\n    return default_response\n\nprocess_complaint_udf = udf(process_complaint, StringType())"
-  },
-  {
-   "cell_type": "code",
-   "source": "# Stream processing\ncomplaint_responses = (\n    spark.readStream\n    .table(f\"{CATALOG}.complaints.raw_complaints\")\n    .select(\n        F.col(\"complaint_id\"),\n        F.col(\"order_id\"),\n        F.current_timestamp().alias(\"ts\"),\n        process_complaint_udf(F.col(\"complaint_text\"), F.col(\"order_id\")).alias(\"agent_response\")\n    )\n)",
-   "metadata": {},
-   "execution_count": null,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.complaints;\n",
-    "CREATE VOLUME IF NOT EXISTS ${CATALOG}.complaints.checkpoints;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE TABLE IF NOT EXISTS ${CATALOG}.complaints.complaint_responses (\n",
-    "  complaint_id STRING,\n",
-    "  order_id STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  agent_response STRING\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "-- Enable Change Data Feed for Lakebase sync\n",
-    "ALTER TABLE ${CATALOG}.complaints.complaint_responses \n",
-    "SET TBLPROPERTIES (delta.enableChangeDataFeed = true)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "complaint_responses.writeStream \\\n",
-    "    .option(\"checkpointLocation\", f\"/Volumes/{CATALOG}/complaints/checkpoints/complaint_agent_stream\") \\\n",
-    "    .trigger(availableNow=True) \\\n",
-    "    .table(f\"{CATALOG}.complaints.complaint_responses\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
+  "nbformat": 4,
+  "nbformat_minor": 2
 }
\ No newline at end of file
diff --git a/jobs/complaint_generator.ipynb b/jobs/complaint_generator.ipynb
index 294a371..26f781e 100644
--- a/jobs/complaint_generator.ipynb
+++ b/jobs/complaint_generator.ipynb
@@ -1,141 +1,339 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Complaint Generator\n",
-    "\n",
-    "This notebook generates synthetic customer complaints from delivered orders using AI SQL functions"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Complaint Generator\n",
+        "\n",
+        "This notebook generates synthetic customer complaints from delivered orders using AI SQL functions"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "COMPLAINT_RATE = float(dbutils.widgets.get(\"COMPLAINT_RATE\"))\n",
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import os\n",
+        "import random\n",
+        "\n",
+        "from pyspark.sql import functions as F\n",
+        "from pyspark.sql.types import StringType\n",
+        "from pyspark.sql.window import Window\n",
+        "\n",
+        "# Complaint category weights\n",
+        "CATEGORIES = [\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"other\"]\n",
+        "WEIGHTS = [0.40, 0.25, 0.20, 0.10, 0.05]\n",
+        "\n",
+        "\n",
+        "@F.udf(returnType=StringType())\n",
+        "def assign_category(order_id: str) -> str:\n",
+        "    \"\"\"Assign category based on hash of order_id for deterministic but varied distribution.\"\"\"\n",
+        "    seed = hash(order_id) % (2**31)\n",
+        "    rng = random.Random(seed)\n",
+        "    return rng.choices(CATEGORIES, weights=WEIGHTS, k=1)[0]\n",
+        "\n",
+        "\n",
+        "# ── Per-batch inference cap ───────────────────────────────────────────────────\n",
+        "# Why this exists: previously this stream piped every sampled delivered event\n",
+        "# straight through `ai_gen()` in a `selectExpr`, then `.toTable(...)`. With\n",
+        "# `availableNow=True` and a fresh deploy, the canonical replay (60× speed)\n",
+        "# leaves a multi-thousand-row backlog of `delivered` events on day one. At\n",
+        "# COMPLAINT_RATE=0.15 that's still hundreds of `ai_gen()` calls per micro-batch,\n",
+        "# which routinely blew the 10-min `timeout_seconds` budget.  The cron would\n",
+        "# then queue another run (now disabled), and the backlog kept growing forever.\n",
+        "#\n",
+        "# Same pattern used in jobs/complaint_agent_stream.ipynb: split each batch into\n",
+        "# a small \"real\" slice (calls ai_gen) and an \"overflow\" slice (deterministic\n",
+        "# templated text).  Caps wall time at roughly MAX_INFERENCES_PER_BATCH *\n",
+        "# worst_case_latency.\n",
+        "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/complaints/checkpoints/complaint_generator\"\n",
+        "MAX_INFERENCES_PER_BATCH = 50\n",
+        "\n",
+        "\n",
+        "def is_first_run():\n",
+        "    \"\"\"True when no micro-batch has been committed yet — drives the\n",
+        "    fake-it-till-up backfill path on cold start.\n",
+        "\n",
+        "    Looks at the `commits/` subdirectory specifically.  Spark Structured\n",
+        "    Streaming creates `offsets/`, `commits/`, `metadata`, `sources/` *before*\n",
+        "    the first call to `process_batch`, so the older heuristic of\n",
+        "    `os.listdir(CHECKPOINT_PATH) == 0` always returned False on the very first\n",
+        "    batch — silently disabling the fast path and forcing the entire historical\n",
+        "    backlog through `ai_gen()` in a single micro-batch.  A non-hidden file\n",
+        "    under `commits/` is the unambiguous signal that this is not the first run.\n",
+        "    \"\"\"\n",
+        "    commits_dir = os.path.join(CHECKPOINT_PATH, \"commits\")\n",
+        "    if not os.path.exists(commits_dir):\n",
+        "        return True\n",
+        "    return not any(\n",
+        "        not f.startswith(\".\") and not f.startswith(\"_\")\n",
+        "        for f in os.listdir(commits_dir)\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "# ── Deterministic fallback complaint templates ────────────────────────────────\n",
+        "# Used both during initial backfill (drain the historical backlog instantly)\n",
+        "# and as the per-batch overflow path beyond MAX_INFERENCES_PER_BATCH.  Texts\n",
+        "# are realistic but obviously not LLM-generated — that's fine: at demo time\n",
+        "# the LLM-generated rows ride on top of a base of templated rows.\n",
+        "FAKE_COMPLAINTS = {\n",
+        "    \"delivery_delay\": [\n",
+        "        \"My order took way too long to arrive, the food was cold by the time it got here.\",\n",
+        "        \"I waited over an hour for my food, this is completely unacceptable.\",\n",
+        "        \"The delivery was extremely late and no one bothered to let me know.\",\n",
+        "    ],\n",
+        "    \"missing_items\": [\n",
+        "        \"Half my order is missing and I was still charged the full amount.\",\n",
+        "        \"The drinks and sides I paid for never arrived with the order.\",\n",
+        "        \"Several items were missing from my bag, this is the third time this month.\",\n",
+        "    ],\n",
+        "    \"food_quality\": [\n",
+        "        \"The food was cold and tasted stale, completely inedible.\",\n",
+        "        \"My meal was overcooked and dry, totally unenjoyable.\",\n",
+        "        \"The food quality was awful, nothing like what I expected.\",\n",
+        "    ],\n",
+        "    \"service_issue\": [\n",
+        "        \"The driver was rude and threw my bag on the doorstep.\",\n",
+        "        \"I tried calling customer service three times and got nowhere.\",\n",
+        "        \"Worst service I've ever had, no one will take responsibility.\",\n",
+        "    ],\n",
+        "    \"other\": [\n",
+        "        \"I had a bad experience with my order and want this resolved quickly.\",\n",
+        "        \"Something went wrong with my order and I'd like a refund.\",\n",
+        "        \"Disappointed with this whole experience, please get back to me.\",\n",
+        "    ],\n",
+        "}\n",
+        "\n",
+        "\n",
+        "@F.udf(returnType=StringType())\n",
+        "def get_fake_complaint(order_id: str, category: str) -> str:\n",
+        "    \"\"\"Deterministic fake complaint text keyed by (order_id, category).\n",
+        "    Cheap fast path for backfill + overflow rows.\"\"\"\n",
+        "    pool = FAKE_COMPLAINTS.get(category, FAKE_COMPLAINTS[\"other\"])\n",
+        "    seed = hash(f\"{order_id}|{category}\") % (2**31)\n",
+        "    return random.Random(seed).choice(pool)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Create schema and checkpoint volume\n",
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.complaints\")\n",
+        "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.complaints.checkpoints\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Stream processing pipeline.\n",
+        "# Samples COMPLAINT_RATE of both historical and new delivered orders, but no\n",
+        "# longer calls `ai_gen()` inline — that happens (capped) inside process_batch.\n",
+        "# Wrapped in a builder so the retry path can pass startingVersion=\"latest\"\n",
+        "# and skip a multi-million-row historical backfill after a table recreate.\n",
+        "def _build_complaints_source(starting_version=None):\n",
+        "    reader = spark.readStream\n",
+        "    if starting_version is not None:\n",
+        "        reader = reader.option(\"startingVersion\", str(starting_version))\n",
+        "    return (\n",
+        "        reader\n",
+        "        .table(f\"{CATALOG}.lakeflow.all_events\")\n",
+        "        .filter(\"event_type = 'delivered'\")\n",
+        "        .filter(F.rand() < COMPLAINT_RATE)\n",
+        "        .withColumn(\"complaint_id\", F.expr(\"uuid()\"))\n",
+        "        .withColumn(\"complaint_category\", assign_category(F.col(\"order_id\")))\n",
+        "        .withColumn(\"source_ts\", F.current_timestamp())\n",
+        "        .select(\"complaint_id\", \"order_id\", \"complaint_category\", \"source_ts\")\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "complaints_source = _build_complaints_source()\n",
+        "\n",
+        "\n",
+        "def process_batch(batch_df, batch_id):\n",
+        "    \"\"\"Process each micro-batch with inference capping.\n",
+        "\n",
+        "    - First run (no checkpoint): ALL rows get templated complaints (fast\n",
+        "      backfill — drains the entire historical backlog without an LLM call).\n",
+        "    - Subsequent runs: first MAX_INFERENCES_PER_BATCH rows get real `ai_gen()`\n",
+        "      output, rest fall back to templated text.  Bounds per-run wall time so\n",
+        "      a backlog cannot blow the 10-min task timeout.\n",
+        "    \"\"\"\n",
+        "    if batch_df.isEmpty():\n",
+        "        return\n",
+        "\n",
+        "    first_run = is_first_run()\n",
+        "    row_count = batch_df.count()\n",
+        "\n",
+        "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
+        "\n",
+        "    target = f\"{CATALOG}.complaints.raw_complaints\"\n",
+        "\n",
+        "    if first_run:\n",
+        "        print(f\"  -> First run detected, using templated complaints for all {row_count} rows\")\n",
+        "        result_df = batch_df.select(\n",
+        "            F.col(\"complaint_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            F.col(\"complaint_category\"),\n",
+        "            get_fake_complaint(F.col(\"order_id\"), F.col(\"complaint_category\")).alias(\"complaint_text\"),\n",
+        "            F.lit(\"template_backfill\").alias(\"generated_by\"),\n",
+        "        )\n",
+        "        result_df.write.mode(\"append\").saveAsTable(target)\n",
+        "        return\n",
+        "\n",
+        "    # Stable order so the cap is deterministic and resumable.\n",
+        "    windowed = batch_df.withColumn(\n",
+        "        \"row_num\",\n",
+        "        F.row_number().over(Window.orderBy(F.col(\"source_ts\"), F.col(\"complaint_id\"))),\n",
+        "    )\n",
+        "\n",
+        "    real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
+        "    fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
+        "    print(f\"  -> Real ai_gen(): {real_count} rows, templated: {fake_count} rows\")\n",
+        "\n",
+        "    real_df = (\n",
+        "        windowed\n",
+        "        .filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\")\n",
+        "        .selectExpr(\n",
+        "            \"complaint_id\",\n",
+        "            \"order_id\",\n",
+        "            \"current_timestamp() as ts\",\n",
+        "            \"complaint_category\",\n",
+        "            \"\"\"ai_gen(\n",
+        "                concat(\n",
+        "                    'You are an upset customer writing a complaint about your food delivery. ',\n",
+        "                    'Write a realistic 1-2 sentence complaint about: ',\n",
+        "                    complaint_category,\n",
+        "                    '. Order ID: ', order_id,\n",
+        "                    '. Be specific and sound frustrated but realistic. Do not include greeting or signature.'\n",
+        "                )\n",
+        "            ) as complaint_text\"\"\",\n",
+        "            \"'llm_generator' as generated_by\",\n",
+        "        )\n",
+        "    )\n",
+        "\n",
+        "    fake_df = (\n",
+        "        windowed\n",
+        "        .filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\")\n",
+        "        .select(\n",
+        "            F.col(\"complaint_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            F.col(\"complaint_category\"),\n",
+        "            get_fake_complaint(F.col(\"order_id\"), F.col(\"complaint_category\")).alias(\"complaint_text\"),\n",
+        "            F.lit(\"template_overflow\").alias(\"generated_by\"),\n",
+        "        )\n",
+        "    )\n",
+        "\n",
+        "    real_df.union(fake_df).write.mode(\"append\").saveAsTable(target)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Create target table schema\n",
+        "spark.sql(f\"\"\"\n",
+        "CREATE TABLE IF NOT EXISTS {CATALOG}.complaints.raw_complaints (\n",
+        "  complaint_id STRING,\n",
+        "  order_id STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  complaint_category STRING,\n",
+        "  complaint_text STRING,\n",
+        "  generated_by STRING\n",
+        ")\n",
+        "\"\"\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Write stream to raw_complaints table via foreachBatch so process_batch can\n",
+        "# apply the per-batch inference cap (see the cell that defines\n",
+        "# MAX_INFERENCES_PER_BATCH).\n",
+        "#\n",
+        "# The checkpoint lives in a UC volume that survives catalog/table rebuilds,\n",
+        "# so if the source Delta table (`all_events`) is dropped and recreated by\n",
+        "# the lakeflow pipeline, or if the checkpoint dir is partially wiped by\n",
+        "# `bundle run cleanup`, Spark will refuse to start.  Recover by clearing\n",
+        "# the stale checkpoint and retrying once from `latest`.\n",
+        "def _run_stream(stream_df):\n",
+        "    q = (\n",
+        "        stream_df.writeStream\n",
+        "        .foreachBatch(process_batch)\n",
+        "        .option(\"checkpointLocation\", CHECKPOINT_PATH)\n",
+        "        .trigger(availableNow=True)\n",
+        "        .start()\n",
+        "    )\n",
+        "    q.awaitTermination()\n",
+        "\n",
+        "\n",
+        "# Recoverable errors that all warrant clearing the checkpoint and restarting\n",
+        "# from the LATEST version of the source:\n",
+        "#   - DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE: source table was recreated.\n",
+        "#   - STREAMING_CHECKPOINT_METADATA_ERROR / MISSING_METADATA_FILE: checkpoint\n",
+        "#     directory was partially wiped (e.g. by `bundle run cleanup`) leaving\n",
+        "#     offsets/commits without the metadata file, which Spark refuses to start on.\n",
+        "_RECOVERABLE_MARKERS = (\n",
+        "    \"DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE\",\n",
+        "    \"STREAMING_CHECKPOINT_METADATA_ERROR\",\n",
+        "    \"MISSING_METADATA_FILE\",\n",
+        ")\n",
+        "\n",
+        "try:\n",
+        "    _run_stream(complaints_source)\n",
+        "except Exception as e:\n",
+        "    msg = str(e)\n",
+        "    if any(marker in msg for marker in _RECOVERABLE_MARKERS):\n",
+        "        first_line = msg.splitlines()[0] if msg else \"\"\n",
+        "        print(\n",
+        "            f\"⚠️ Streaming state unrecoverable ({first_line}). \"\n",
+        "            f\"Clearing stale checkpoint at {CHECKPOINT_PATH} and restarting \"\n",
+        "            f\"from the LATEST version of the source (historical backfill skipped).\"\n",
+        "        )\n",
+        "        dbutils.fs.rm(CHECKPOINT_PATH, recurse=True)\n",
+        "        print(f\"✅ Cleared {CHECKPOINT_PATH}\")\n",
+        "        _run_stream(_build_complaints_source(starting_version=\"latest\"))\n",
+        "    else:\n",
+        "        raise"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9.0"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "COMPLAINT_RATE = float(dbutils.widgets.get(\"COMPLAINT_RATE\"))\n",
-    "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyspark.sql import functions as F\n",
-    "from pyspark.sql.types import StringType\n",
-    "import random\n",
-    "\n",
-    "# Complaint category weights\n",
-    "CATEGORIES = [\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"other\"]\n",
-    "WEIGHTS = [0.40, 0.25, 0.20, 0.10, 0.05]\n",
-    "\n",
-    "# Create a deterministic but varied category assignment\n",
-    "# Using hash of order_id to ensure same order always gets same category\n",
-    "@F.udf(returnType=StringType())\n",
-    "def assign_category(order_id: str) -> str:\n",
-    "    \"\"\"Assign category based on hash of order_id for deterministic but varied distribution.\"\"\"\n",
-    "    # Use hash to get deterministic random selection\n",
-    "    seed = hash(order_id) % (2**31)\n",
-    "    rng = random.Random(seed)\n",
-    "    return rng.choices(CATEGORIES, weights=WEIGHTS, k=1)[0]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Create schema and checkpoint volume\n",
-    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.complaints\")\n",
-    "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.complaints.checkpoints\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Stream processing pipeline\n",
-    "# Samples COMPLAINT_RATE of both historical and new delivered orders\n",
-    "complaints_stream = (\n",
-    "    spark.readStream\n",
-    "    .table(f\"{CATALOG}.lakeflow.all_events\")\n",
-    "    .filter(\"event_type = 'delivered'\")\n",
-    "    .filter(F.rand() < COMPLAINT_RATE)  # Sample orders for complaints (same rate for historical and new)\n",
-    "    .withColumn(\"complaint_id\", F.expr(\"uuid()\"))\n",
-    "    .withColumn(\"complaint_category\", assign_category(F.col(\"order_id\")))\n",
-    "    .withColumn(\"ts\", F.current_timestamp())\n",
-    "    .selectExpr(\n",
-    "        \"complaint_id\",\n",
-    "        \"order_id\",\n",
-    "        \"ts\",\n",
-    "        \"complaint_category\",\n",
-    "        f\"\"\"ai_gen(\n",
-    "            concat(\n",
-    "                'You are an upset customer writing a complaint about your food delivery. ',\n",
-    "                'Write a realistic 1-2 sentence complaint about: ', \n",
-    "                complaint_category, \n",
-    "                '. Order ID: ', \n",
-    "                order_id, \n",
-    "                '. Be specific and sound frustrated but realistic. Do not include greeting or signature.'\n",
-    "            )\n",
-    "        ) as complaint_text\"\"\",\n",
-    "        \"'llm_generator' as generated_by\"\n",
-    "    )\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Create target table schema\n",
-    "spark.sql(f\"\"\"\n",
-    "CREATE TABLE IF NOT EXISTS {CATALOG}.complaints.raw_complaints (\n",
-    "  complaint_id STRING,\n",
-    "  order_id STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  complaint_category STRING,\n",
-    "  complaint_text STRING,\n",
-    "  generated_by STRING\n",
-    ")\n",
-    "\"\"\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Write stream to raw_complaints table\n",
-    "complaints_stream.writeStream \\\n",
-    "    .option(\"checkpointLocation\", f\"/Volumes/{CATALOG}/complaints/checkpoints/complaint_generator\") \\\n",
-    "    .trigger(availableNow=True) \\\n",
-    "    .table(f\"{CATALOG}.complaints.raw_complaints\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
+  "nbformat": 4,
+  "nbformat_minor": 2
+}
\ No newline at end of file
diff --git a/jobs/refund_recommender_stream.ipynb b/jobs/refund_recommender_stream.ipynb
index 304e5e1..f41370b 100644
--- a/jobs/refund_recommender_stream.ipynb
+++ b/jobs/refund_recommender_stream.ipynb
@@ -1,452 +1,571 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "d9dd8d3e-2923-4e16-9435-bd2fd134d94f",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### refunder stream\n",
-    "\n",
-    "this notebook starts a stream to score completed orders for potential refunds"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "54b5ea14-d02b-413b-9f69-86b932322ec0",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
-    "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "REFUND_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"REFUND_AGENT_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "b2af6e4b-0a96-4810-9c15-eedb7e84db67",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%pip install openai"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# In the canonical full demo run this stream job will start BEFORE the agent is actually ready\n",
-    "# (because model serving deployment from previous stage takes 15~20min)\n",
-    "# So, we seed some fake responses, and return them instead while the model isn't yet loaded\n",
-    "# See next cell too\n",
-    "fake_responses = [\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 4.47,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered late by 1.6 minutes\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered on time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 8.91,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered late by 5.5875 minutes\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 5.48,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered 1.9 minutes after the P75 delivery time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered on time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 9.25,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered 18.9 minutes after creation, which is less than the P75 delivery time of 32.804165 minutes, but still late compared to the P50 delivery time of 29.016666 minutes\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 11.34,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered in 25.35 minutes, which is between the 75th percentile (32.80 minutes) and the 99th percentile (38.84 minutes) for the Bellevue location\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 8.66,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was late by 2.6625 minutes\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 4.93,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was late by 2.175 minutes\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered on time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 12.34,\n",
-    "        \"refund_class\": \"partial\",\n",
-    "        \"reason\": \"Order was delivered 7.97 minutes after the P75 delivery time\",\n",
-    "    },\n",
-    "    {\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"none\",\n",
-    "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
-    "    },\n",
-    "]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "5540baa0-a16b-4bd1-a61d-dcb80eb2ce98",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "from pyspark.sql import functions as F\n",
-    "from pyspark.sql.types import StringType\n",
-    "from pyspark.sql.functions import udf\n",
-    "from pyspark.sql.window import Window\n",
-    "import json\n",
-    "import random\n",
-    "import os\n",
-    "\n",
-    "from openai import OpenAI\n",
-    "\n",
-    "# Configuration for inference capping\n",
-    "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/recommender/checkpoints/refundrecommenderstream\"\n",
-    "MAX_INFERENCES_PER_BATCH = 50\n",
-    "\n",
-    "def is_first_run():\n",
-    "    \"\"\"Check if checkpoint exists (indicates this is NOT the first run)\"\"\"\n",
-    "    return not os.path.exists(CHECKPOINT_PATH) or len(os.listdir(CHECKPOINT_PATH)) == 0\n",
-    "\n",
-    "def get_chat_completion(content: str) -> str:\n",
-    "    \"\"\"Call the refund agent endpoint for real inference\"\"\"\n",
-    "    client = OpenAI(\n",
-    "        api_key=DATABRICKS_TOKEN,\n",
-    "        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n",
-    "    )\n",
-    "    default_response = json.dumps({\n",
-    "        \"refund_usd\": 0.0,\n",
-    "        \"refund_class\": \"error\",\n",
-    "        \"reason\": \"agent did not return valid JSON\"\n",
-    "    })\n",
-    "\n",
-    "    for _ in range(3):\n",
-    "        try:\n",
-    "            chat_completion = client.chat.completions.create(\n",
-    "                model=f\"{REFUND_AGENT_ENDPOINT_NAME}\",\n",
-    "                messages=[{\"role\": \"user\", \"content\": content}],\n",
-    "            )\n",
-    "        except Exception as e:\n",
-    "            # Fake data injection when serving endpoint isn't available\n",
-    "            response = json.dumps(random.choice(fake_responses))\n",
-    "        else:\n",
-    "            response = chat_completion.messages[-1].get(\"content\")\n",
-    "\n",
-    "        try:\n",
-    "            json.loads(response)\n",
-    "            return response\n",
-    "        except json.JSONDecodeError:\n",
-    "            continue\n",
-    "\n",
-    "    return default_response\n",
-    "\n",
-    "def get_fake_response(order_id: str) -> str:\n",
-    "    \"\"\"Return a fake response (fast path for backfill and overflow)\"\"\"\n",
-    "    return json.dumps(random.choice(fake_responses))\n",
-    "\n",
-    "get_chat_completion_udf = udf(get_chat_completion, StringType())\n",
-    "get_fake_response_udf = udf(get_fake_response, StringType())\n",
-    "\n",
-    "def process_batch(batch_df, batch_id):\n",
-    "    \"\"\"Process each micro-batch with inference capping\n",
-    "\n",
-    "    - First run (no checkpoint): ALL rows get fake responses (fast backfill)\n",
-    "    - Subsequent runs: First 50 rows get real inference, rest get fake\n",
-    "    \"\"\"\n",
-    "    if batch_df.isEmpty():\n",
-    "        return\n",
-    "\n",
-    "    first_run = is_first_run()\n",
-    "    row_count = batch_df.count()\n",
-    "\n",
-    "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
-    "\n",
-    "    if first_run:\n",
-    "        # First run: ALL rows get fake responses (fast)\n",
-    "        print(f\"  -> First run detected, using fake responses for all {row_count} rows\")\n",
-    "        result_df = batch_df.select(\n",
-    "            F.col(\"order_id\"),\n",
-    "            F.current_timestamp().alias(\"ts\"),\n",
-    "            F.to_timestamp(F.col(\"ts\")).alias(\"order_ts\"),\n",
-    "            get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
-    "        )\n",
-    "    else:\n",
-    "        # Subsequent runs: First N rows get real inference, rest get fake\n",
-    "        windowed = batch_df \\\n",
-    "            .withColumn(\"order_ts\", F.to_timestamp(F.col(\"ts\"))) \\\n",
-    "            .withColumn(\"row_num\", F.row_number().over(Window.orderBy(F.col(\"order_ts\"), F.col(\"order_id\"))))\n",
-    "\n",
-    "        real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
-    "        fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
-    "        print(f\"  -> Real inference: {real_count} rows, fake: {fake_count} rows\")\n",
-    "\n",
-    "        # Split into real inference vs fake\n",
-    "        real_inference_df = windowed.filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\") \\\n",
-    "            .select(\n",
-    "                F.col(\"order_id\"),\n",
-    "                F.current_timestamp().alias(\"ts\"),\n",
-    "                F.col(\"order_ts\"),\n",
-    "                get_chat_completion_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
-    "            )\n",
-    "\n",
-    "        fake_response_df = windowed.filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\") \\\n",
-    "            .select(\n",
-    "                F.col(\"order_id\"),\n",
-    "                F.current_timestamp().alias(\"ts\"),\n",
-    "                F.col(\"order_ts\"),\n",
-    "                get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
-    "            )\n",
-    "\n",
-    "        result_df = real_inference_df.union(fake_response_df)\n",
-    "\n",
-    "    # Write to table\n",
-    "    result_df.write.mode(\"append\").saveAsTable(f\"{CATALOG}.recommender.refund_recommendations\")\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "4aa36d99-1219-4998-878e-7d49ff9dad2d",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": "# Read stream of delivered events - no sampling needed, we control volume in foreachBatch\ndelivered_events = spark.readStream.table(f\"{CATALOG}.lakeflow.all_events\") \\\n    .filter(\"event_type = 'delivered'\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "1cf733f0-a483-4c1b-a142-e0f0e0539bd1",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.recommender;\n",
-    "CREATE VOLUME IF NOT EXISTS ${CATALOG}.recommender.checkpoints;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "9a12df85-36d4-485d-ac94-74dd12266a89",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE TABLE IF NOT EXISTS ${CATALOG}.recommender.refund_recommendations (\n",
-    "  order_id STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  order_ts TIMESTAMP,\n",
-    "  agent_response STRING\n",
-    ")\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "implicitDf": true,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "77a3cd40-e993-4308-a860-139372ba8d12",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": "# Enable CDC only if not already enabled (avoids unnecessary table writes)\ntable_name = f\"{CATALOG}.recommender.refund_recommendations\"\n\ntry:\n    props = spark.sql(f\"SHOW TBLPROPERTIES {table_name}\").collect()\n    cdc_enabled = any(row.key == \"delta.enableChangeDataFeed\" and row.value == \"true\" for row in props)\nexcept Exception:\n    cdc_enabled = False\n\nif not cdc_enabled:\n    print(f\"Enabling CDC on {table_name}\")\n    spark.sql(f\"ALTER TABLE {table_name} SET TBLPROPERTIES (delta.enableChangeDataFeed = true)\")\nelse:\n    print(f\"CDC already enabled on {table_name}, skipping\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "40d33309-fcdc-4e94-a65c-de78aac4422e",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": "# Process with foreachBatch for fine-grained control over inference volume\ndelivered_events.writeStream \\\n    .foreachBatch(process_batch) \\\n    .option(\"checkpointLocation\", f\"/Volumes/{CATALOG}/recommender/checkpoints/refundrecommenderstream\") \\\n    .trigger(availableNow=True) \\\n    .start() \\\n    .awaitTermination()"
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "mostRecentlyExecutedCommandWithImplicitDF": {
-     "commandId": 8812248119570203,
-     "dataframes": [
-      "_sqldf"
-     ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "d9dd8d3e-2923-4e16-9435-bd2fd134d94f",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "\n",
+        "##### refunder stream\n",
+        "\n",
+        "this notebook starts a stream to score completed orders for potential refunds"
+      ]
     },
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "refund_recommender_stream",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "cazzper",
-     "nuid": "4fed5096-973b-4a59-acc5-e4a96cc00360",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "54b5ea14-d02b-413b-9f69-86b932322ec0",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
       },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
+      "source": [
+        "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
+        "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "REFUND_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"REFUND_AGENT_ENDPOINT_NAME\")"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "b2af6e4b-0a96-4810-9c15-eedb7e84db67",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
       },
-      "widgetType": "text"
-     }
+      "source": [
+        "%pip install openai"
+      ],
+      "execution_count": 0,
+      "outputs": []
     },
-    "REFUND_AGENT_ENDPOINT_NAME": {
-     "currentValue": "",
-     "nuid": "bf162244-8e75-4570-82f4-ef93955c6891",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "REFUND_AGENT_ENDPOINT_NAME",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# In the canonical full demo run this stream job will start BEFORE the agent is actually ready\n",
+        "# (because model serving deployment from previous stage takes 15~20min)\n",
+        "# So, we seed some fake responses, and return them instead while the model isn't yet loaded\n",
+        "# See next cell too\n",
+        "fake_responses = [\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 4.47,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered late by 1.6 minutes\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered on time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 8.91,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered late by 5.5875 minutes\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 5.48,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered 1.9 minutes after the P75 delivery time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered on time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 9.25,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered 18.9 minutes after creation, which is less than the P75 delivery time of 32.804165 minutes, but still late compared to the P50 delivery time of 29.016666 minutes\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 11.34,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered in 25.35 minutes, which is between the 75th percentile (32.80 minutes) and the 99th percentile (38.84 minutes) for the Bellevue location\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 8.66,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was late by 2.6625 minutes\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 4.93,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was late by 2.175 minutes\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered on time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 12.34,\n",
+        "        \"refund_class\": \"partial\",\n",
+        "        \"reason\": \"Order was delivered 7.97 minutes after the P75 delivery time\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"none\",\n",
+        "        \"reason\": \"Order was delivered within the P75 delivery time\",\n",
+        "    },\n",
+        "]"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "5540baa0-a16b-4bd1-a61d-dcb80eb2ce98",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
       },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "REFUND_AGENT_ENDPOINT_NAME",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
+      "source": [
+        "from pyspark.sql import functions as F\n",
+        "from pyspark.sql.types import StringType\n",
+        "from pyspark.sql.functions import udf\n",
+        "from pyspark.sql.window import Window\n",
+        "import json\n",
+        "import random\n",
+        "import os\n",
+        "\n",
+        "from openai import OpenAI\n",
+        "\n",
+        "# Configuration for inference capping\n",
+        "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/recommender/checkpoints/refundrecommenderstream\"\n",
+        "# Sized so that even at single-core executor parallelism the batch fits the\n",
+        "# 600s task timeout: measured agent latency is ~12s per call (3 LLM round-trips\n",
+        "# for tool-calling), so 15 × 12 ≈ 180s leaves comfortable headroom for cold\n",
+        "# starts, Delta write, count(), and is_first_run() probes.  Previous value of\n",
+        "# 50 sized for ~2s/call (fast-fail path while endpoint was UPDATE_FAILED); once\n",
+        "# the endpoint actually became READY, 50 × 12s = 600s pinned the wall and the\n",
+        "# stream began timing out under a healthy agent.  Counter-intuitively, fixing\n",
+        "# the agent broke the stream — so the cap moves with reality.\n",
+        "MAX_INFERENCES_PER_BATCH = 15\n",
+        "\n",
+        "# Per-call timeout (seconds) for the agent endpoint.  Without this, a wedged\n",
+        "# endpoint can hang the UDF forever and pin the 10-min task timeout against\n",
+        "# us.  30s bounds worst-case per-row wall time so MAX_INFERENCES_PER_BATCH\n",
+        "# real calls (capped, Spark-parallel) fit well inside the 600s task budget.\n",
+        "# No retries inside the UDF — see get_chat_completion docstring for why.\n",
+        "_CALL_TIMEOUT_S = 30\n",
+        "\n",
+        "def is_first_run():\n",
+        "    \"\"\"True when no micro-batch has been committed yet — drives the\n",
+        "    fake-it-till-up backfill path on cold start.\n",
+        "\n",
+        "    Looks at the `commits/` subdirectory specifically.  Spark Structured\n",
+        "    Streaming creates `offsets/`, `commits/`, `metadata`, `sources/` *before*\n",
+        "    the first call to `process_batch`, so the older heuristic of\n",
+        "    `os.listdir(CHECKPOINT_PATH) == 0` always returned False on the very first\n",
+        "    batch — silently disabling the fast path and forcing the entire historical\n",
+        "    backlog through the real-inference codepath in a single micro-batch.  A\n",
+        "    non-hidden file under `commits/` is the unambiguous signal that this is\n",
+        "    not the first run.\n",
+        "    \"\"\"\n",
+        "    commits_dir = os.path.join(CHECKPOINT_PATH, \"commits\")\n",
+        "    if not os.path.exists(commits_dir):\n",
+        "        return True\n",
+        "    return not any(\n",
+        "        not f.startswith(\".\") and not f.startswith(\"_\")\n",
+        "        for f in os.listdir(commits_dir)\n",
+        "    )\n",
+        "\n",
+        "def get_chat_completion(content: str) -> str:\n",
+        "    \"\"\"Call the refund agent endpoint for real inference.\n",
+        "\n",
+        "    Single attempt only.  Previous versions did 3 blind retries, which made\n",
+        "    the worst-case per-row cost 3 × _CALL_TIMEOUT_S = 90s and blew the 600s\n",
+        "    task budget under endpoint stress (see jobs/complaint_agent_stream.ipynb\n",
+        "    cell defining process_complaint for the same lesson).  For an\n",
+        "    availableNow catch-up stream the next 10-min cron tick will re-process\n",
+        "    anything that errored here, so fail-fast keeps each batch bounded.\n",
+        "\n",
+        "    Failure policy:\n",
+        "      - Endpoint unreachable / timeout → fake response (keep batch flowing).\n",
+        "      - Endpoint returned invalid shape or non-JSON → default_response\n",
+        "        with refund_class='error' so downstream consumers can spot it.\n",
+        "    \"\"\"\n",
+        "    client = OpenAI(\n",
+        "        api_key=DATABRICKS_TOKEN,\n",
+        "        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n",
+        "        timeout=_CALL_TIMEOUT_S,\n",
+        "    )\n",
+        "    default_response = json.dumps({\n",
+        "        \"refund_usd\": 0.0,\n",
+        "        \"refund_class\": \"error\",\n",
+        "        \"reason\": \"agent did not return valid JSON\"\n",
+        "    })\n",
+        "\n",
+        "    try:\n",
+        "        chat_completion = client.chat.completions.create(\n",
+        "            model=f\"{REFUND_AGENT_ENDPOINT_NAME}\",\n",
+        "            messages=[{\"role\": \"user\", \"content\": content}],\n",
+        "            timeout=_CALL_TIMEOUT_S,\n",
+        "        )\n",
+        "    except Exception:\n",
+        "        # Endpoint unreachable — keep the batch flowing with a fake.\n",
+        "        return json.dumps(random.choice(fake_responses))\n",
+        "\n",
+        "    # OpenAI-compatible chat completion: response is in choices[0].message.content,\n",
+        "    # NOT in .messages (older code path raised AttributeError once the agent was up).\n",
+        "    #\n",
+        "    # Defend broadly against the agent returning an unexpected response shape: the\n",
+        "    # OpenAI client best-effort-maps the Databricks model-serving response, and we've\n",
+        "    # observed it materializing `choices=None` (not just empty list) which raises\n",
+        "    # `TypeError: 'NoneType' object is not subscriptable` on `.choices[0]`.  A narrow\n",
+        "    # `except (AttributeError, IndexError)` is NOT enough — the TypeError escapes the\n",
+        "    # UDF, surfaces as PythonException, and crashes the whole foreachBatch\n",
+        "    # saveAsTable call.\n",
+        "    try:\n",
+        "        choices = getattr(chat_completion, \"choices\", None) or []\n",
+        "        response = choices[0].message.content if choices else \"\"\n",
+        "    except Exception:\n",
+        "        response = \"\"\n",
+        "\n",
+        "    try:\n",
+        "        json.loads(response)\n",
+        "        return response\n",
+        "    except (json.JSONDecodeError, TypeError):\n",
+        "        return default_response\n",
+        "\n",
+        "def get_fake_response(order_id: str) -> str:\n",
+        "    \"\"\"Return a fake response (fast path for backfill and overflow)\"\"\"\n",
+        "    return json.dumps(random.choice(fake_responses))\n",
+        "\n",
+        "get_chat_completion_udf = udf(get_chat_completion, StringType())\n",
+        "get_fake_response_udf = udf(get_fake_response, StringType())\n",
+        "\n",
+        "def process_batch(batch_df, batch_id):\n",
+        "    \"\"\"Process each micro-batch with inference capping\n",
+        "\n",
+        "    - First run (no checkpoint): ALL rows get fake responses (fast backfill)\n",
+        "    - Subsequent runs: First 50 rows get real inference, rest get fake\n",
+        "    \"\"\"\n",
+        "    if batch_df.isEmpty():\n",
+        "        return\n",
+        "\n",
+        "    first_run = is_first_run()\n",
+        "    row_count = batch_df.count()\n",
+        "\n",
+        "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
+        "\n",
+        "    if first_run:\n",
+        "        # First run: ALL rows get fake responses (fast)\n",
+        "        print(f\"  -> First run detected, using fake responses for all {row_count} rows\")\n",
+        "        result_df = batch_df.select(\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            F.to_timestamp(F.col(\"ts\")).alias(\"order_ts\"),\n",
+        "            get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
+        "        )\n",
+        "    else:\n",
+        "        # Subsequent runs: First N rows get real inference, rest get fake\n",
+        "        windowed = batch_df \\\n",
+        "            .withColumn(\"order_ts\", F.to_timestamp(F.col(\"ts\"))) \\\n",
+        "            .withColumn(\"row_num\", F.row_number().over(Window.orderBy(F.col(\"order_ts\"), F.col(\"order_id\"))))\n",
+        "\n",
+        "        real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
+        "        fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
+        "        print(f\"  -> Real inference: {real_count} rows, fake: {fake_count} rows\")\n",
+        "\n",
+        "        # Split into real inference vs fake\n",
+        "        real_inference_df = windowed.filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\") \\\n",
+        "            .select(\n",
+        "                F.col(\"order_id\"),\n",
+        "                F.current_timestamp().alias(\"ts\"),\n",
+        "                F.col(\"order_ts\"),\n",
+        "                get_chat_completion_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
+        "            )\n",
+        "\n",
+        "        fake_response_df = windowed.filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\") \\\n",
+        "            .select(\n",
+        "                F.col(\"order_id\"),\n",
+        "                F.current_timestamp().alias(\"ts\"),\n",
+        "                F.col(\"order_ts\"),\n",
+        "                get_fake_response_udf(F.col(\"order_id\")).alias(\"agent_response\")\n",
+        "            )\n",
+        "\n",
+        "        result_df = real_inference_df.union(fake_response_df)\n",
+        "\n",
+        "    # Write to table\n",
+        "    result_df.write.mode(\"append\").saveAsTable(f\"{CATALOG}.recommender.refund_recommendations\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "4aa36d99-1219-4998-878e-7d49ff9dad2d",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "# Read stream of delivered events - no sampling needed, we control volume in foreachBatch.\n",
+        "# Wrapped in a builder so the retry path can pass startingVersion=\"latest\" and\n",
+        "# skip a multi-million-row historical backfill after a table recreate.\n",
+        "def _build_delivered_events(starting_version=None):\n",
+        "    reader = spark.readStream\n",
+        "    if starting_version is not None:\n",
+        "        reader = reader.option(\"startingVersion\", str(starting_version))\n",
+        "    return reader.table(f\"{CATALOG}.lakeflow.all_events\").filter(\"event_type = 'delivered'\")\n",
+        "\n",
+        "\n",
+        "delivered_events = _build_delivered_events()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "1cf733f0-a483-4c1b-a142-e0f0e0539bd1",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "%sql\n",
+        "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.recommender;\n",
+        "CREATE VOLUME IF NOT EXISTS ${CATALOG}.recommender.checkpoints;"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "9a12df85-36d4-485d-ac94-74dd12266a89",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
       },
-      "widgetType": "text"
-     }
+      "source": [
+        "%sql\n",
+        "CREATE TABLE IF NOT EXISTS ${CATALOG}.recommender.refund_recommendations (\n",
+        "  order_id STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  order_ts TIMESTAMP,\n",
+        "  agent_response STRING\n",
+        ")\n"
+      ],
+      "execution_count": 0,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {
+            "byteLimit": 2048000,
+            "implicitDf": true,
+            "rowLimit": 10000
+          },
+          "inputWidgets": {},
+          "nuid": "77a3cd40-e993-4308-a860-139372ba8d12",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": "# Enable CDC only if not already enabled (avoids unnecessary table writes)\ntable_name = f\"{CATALOG}.recommender.refund_recommendations\"\n\ntry:\n    props = spark.sql(f\"SHOW TBLPROPERTIES {table_name}\").collect()\n    cdc_enabled = any(row.key == \"delta.enableChangeDataFeed\" and row.value == \"true\" for row in props)\nexcept Exception:\n    cdc_enabled = False\n\nif not cdc_enabled:\n    print(f\"Enabling CDC on {table_name}\")\n    spark.sql(f\"ALTER TABLE {table_name} SET TBLPROPERTIES (delta.enableChangeDataFeed = true)\")\nelse:\n    print(f\"CDC already enabled on {table_name}, skipping\")",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {
+        "application/vnd.databricks.v1+cell": {
+          "cellMetadata": {},
+          "inputWidgets": {},
+          "nuid": "40d33309-fcdc-4e94-a65c-de78aac4422e",
+          "showTitle": false,
+          "tableResultSettingsMap": {},
+          "title": ""
+        }
+      },
+      "source": [
+        "# Process with foreachBatch for fine-grained control over inference volume.\n",
+        "# Recover automatically if the source Delta table id has changed since the\n",
+        "# last run (DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE).  On recovery we\n",
+        "# rebuild the source stream with startingVersion=\"latest\" so we do NOT\n",
+        "# reprocess the entire recreated table (which is 90 days × 8 locations of\n",
+        "# canonical data — tens of millions of rows — and was timing out the cluster\n",
+        "# in one giant availableNow micro-batch).  Real-time data continues to flow\n",
+        "# from the new version onward.\n",
+        "def _run_stream(events):\n",
+        "    q = (\n",
+        "        events.writeStream\n",
+        "        .foreachBatch(process_batch)\n",
+        "        .option(\"checkpointLocation\", CHECKPOINT_PATH)\n",
+        "        .trigger(availableNow=True)\n",
+        "        .start()\n",
+        "    )\n",
+        "    q.awaitTermination()\n",
+        "\n",
+        "\n",
+        "# Recoverable errors that all warrant clearing the checkpoint and restarting\n",
+        "# from the LATEST version of the source:\n",
+        "#   - DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE: source table was recreated\n",
+        "#   - STREAMING_CHECKPOINT_METADATA_ERROR / MISSING_METADATA_FILE: checkpoint\n",
+        "#     directory was partially wiped (e.g. by `bundle run cleanup`) leaving\n",
+        "#     offsets/commits without the metadata file, which Spark refuses to start on.\n",
+        "_RECOVERABLE_MARKERS = (\n",
+        "    \"DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE\",\n",
+        "    \"STREAMING_CHECKPOINT_METADATA_ERROR\",\n",
+        "    \"MISSING_METADATA_FILE\",\n",
+        ")\n",
+        "\n",
+        "try:\n",
+        "    _run_stream(delivered_events)\n",
+        "except Exception as e:\n",
+        "    msg = str(e)\n",
+        "    if any(marker in msg for marker in _RECOVERABLE_MARKERS):\n",
+        "        first_line = msg.splitlines()[0] if msg else \"\"\n",
+        "        print(\n",
+        "            f\"⚠️ Streaming state unrecoverable ({first_line}). \"\n",
+        "            f\"Clearing stale checkpoint at {CHECKPOINT_PATH} and restarting \"\n",
+        "            f\"from the LATEST version of the source (historical backfill skipped).\"\n",
+        "        )\n",
+        "        dbutils.fs.rm(CHECKPOINT_PATH, recurse=True)\n",
+        "        print(f\"✅ Cleared {CHECKPOINT_PATH}\")\n",
+        "        _run_stream(_build_delivered_events(starting_version=\"latest\"))\n",
+        "    else:\n",
+        "        raise"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
+      },
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "mostRecentlyExecutedCommandWithImplicitDF": {
+          "commandId": 8812248119570203,
+          "dataframes": [
+            "_sqldf"
+          ]
+        },
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "refund_recommender_stream",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "cazzper",
+          "nuid": "4fed5096-973b-4a59-acc5-e4a96cc00360",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        },
+        "REFUND_AGENT_ENDPOINT_NAME": {
+          "currentValue": "",
+          "nuid": "bf162244-8e75-4570-82f4-ef93955c6891",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "REFUND_AGENT_ENDPOINT_NAME",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "REFUND_AGENT_ENDPOINT_NAME",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
     }
-   }
   },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
+  "nbformat": 4,
+  "nbformat_minor": 0
 }
\ No newline at end of file
diff --git a/jobs/support_request_agent_stream.ipynb b/jobs/support_request_agent_stream.ipynb
index 8458a62..520ed8b 100644
--- a/jobs/support_request_agent_stream.ipynb
+++ b/jobs/support_request_agent_stream.ipynb
@@ -1,320 +1,407 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Support Request Agent Stream\n",
-    "\n",
-    "Stream support requests through the support agent endpoint and persist reports.\n",
-    "\n",
-    "Uses fake-it-till-up pattern: deterministic responses during backfill and when\n",
-    "the agent endpoint is not yet ready, real inference with capping once available."
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Support Request Agent Stream\n",
+        "\n",
+        "Stream support requests through the support agent endpoint and persist reports.\n",
+        "\n",
+        "Uses fake-it-till-up pattern: deterministic responses during backfill and when\n",
+        "the agent endpoint is not yet ready, real inference with capping once available."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
+        "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install openai"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "import random\n",
+        "import os\n",
+        "\n",
+        "from pyspark.sql import functions as F\n",
+        "from pyspark.sql.types import StringType\n",
+        "from pyspark.sql.functions import udf\n",
+        "from pyspark.sql.window import Window\n",
+        "from openai import OpenAI\n",
+        "\n",
+        "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/support/checkpoints/support_request_agent_stream\"\n",
+        "# Sized for the 600s task timeout.  Real agent latency is in the 12-40s range\n",
+        "# per call depending on tool-calling depth, so we cap at 15 to keep worst-case\n",
+        "# sequential cost (15 × 40s = 600s) bounded and to leave headroom once Spark\n",
+        "# parallelism is factored in.  The previous value of 50 was sized for a\n",
+        "# fast-failing endpoint and started timing out the 10-min task as soon as\n",
+        "# the agent endpoint became actually responsive (matching the same bug we\n",
+        "# saw in jobs/refund_recommender_stream.ipynb).\n",
+        "MAX_INFERENCES_PER_BATCH = 15\n",
+        "\n",
+        "# Per-call timeout (seconds) for the agent endpoint.  Without this, a wedged\n",
+        "# endpoint can hang the UDF forever and pin the 10-min task timeout against\n",
+        "# us.  30s bounds worst-case per-row wall time so MAX_INFERENCES_PER_BATCH\n",
+        "# real calls (capped, Spark-parallel) fit well inside the 600s task budget.\n",
+        "# No retries inside the UDF — see call_support_agent docstring for why.\n",
+        "_CALL_TIMEOUT_S = 30\n",
+        "\n",
+        "\n",
+        "def is_first_run():\n",
+        "    \"\"\"True when no micro-batch has been committed yet — drives the\n",
+        "    fake-it-till-up backfill path on cold start.\n",
+        "\n",
+        "    Looks at the `commits/` subdirectory specifically.  Spark Structured\n",
+        "    Streaming creates `offsets/`, `commits/`, `metadata`, `sources/` *before*\n",
+        "    the first call to `process_batch`, so the older heuristic of\n",
+        "    `os.listdir(CHECKPOINT_PATH) == 0` always returned False on the very first\n",
+        "    batch — silently disabling the fast path and forcing the entire historical\n",
+        "    backlog through the real-inference codepath in a single micro-batch.  A\n",
+        "    non-hidden file under `commits/` is the unambiguous signal that this is\n",
+        "    not the first run.\n",
+        "    \"\"\"\n",
+        "    commits_dir = os.path.join(CHECKPOINT_PATH, \"commits\")\n",
+        "    if not os.path.exists(commits_dir):\n",
+        "        return True\n",
+        "    return not any(\n",
+        "        not f.startswith(\".\") and not f.startswith(\"_\")\n",
+        "        for f in os.listdir(commits_dir)\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "# ── Deterministic fallback responses ──────────────────────────────────────────\n",
+        "# These mirror the policy resolution logic from the agent, providing realistic\n",
+        "# structured responses when the endpoint is unavailable or during backfill.\n",
+        "\n",
+        "fake_responses = [\n",
+        "    {\n",
+        "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
+        "        \"credit_recommendation\": {\"amount_usd\": 3.0, \"reason\": \"Goodwill credit for minor service issue.\"},\n",
+        "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"No verified severe failure.\"},\n",
+        "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $3.00 credit on this case.\",\n",
+        "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
+        "        \"order_details_summary\": \"Standard delivery order.\",\n",
+        "        \"decision_confidence\": \"medium\",\n",
+        "        \"escalation_flag\": False,\n",
+        "    },\n",
+        "    {\n",
+        "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
+        "        \"credit_recommendation\": {\"amount_usd\": 5.0, \"reason\": \"Moderate service issue with customer impact.\"},\n",
+        "        \"refund_recommendation\": {\"amount_usd\": 10.0, \"reason\": \"Moderate service issue with customer impact.\"},\n",
+        "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $10.00 refund and a $5.00 credit on this case.\",\n",
+        "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
+        "        \"order_details_summary\": \"Delivery with reported delay.\",\n",
+        "        \"decision_confidence\": \"high\",\n",
+        "        \"escalation_flag\": False,\n",
+        "    },\n",
+        "    {\n",
+        "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
+        "        \"credit_recommendation\": {\"amount_usd\": 2.0, \"reason\": \"Minor issue or low-confidence compensable case.\"},\n",
+        "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"No severe failure identified.\"},\n",
+        "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $2.00 credit on this case.\",\n",
+        "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
+        "        \"order_details_summary\": \"Standard delivery order.\",\n",
+        "        \"decision_confidence\": \"medium\",\n",
+        "        \"escalation_flag\": False,\n",
+        "    },\n",
+        "    {\n",
+        "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
+        "        \"credit_recommendation\": {\"amount_usd\": 5.0, \"reason\": \"Repeated or high-risk service failure.\"},\n",
+        "        \"refund_recommendation\": {\"amount_usd\": 18.0, \"reason\": \"Repeated or high-risk service failure.\"},\n",
+        "        \"draft_response\": \"I see this is at least the 2nd time you've had to contact us for similar issues, and that is not acceptable. We are offering a $18.00 refund and a $5.00 credit on this case.\",\n",
+        "        \"past_interactions_summary\": \"Multiple prior contacts for similar issues.\",\n",
+        "        \"order_details_summary\": \"Repeat issue with delivery.\",\n",
+        "        \"decision_confidence\": \"high\",\n",
+        "        \"escalation_flag\": False,\n",
+        "    },\n",
+        "    {\n",
+        "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
+        "        \"credit_recommendation\": {\"amount_usd\": 3.0, \"reason\": \"Abusive/spammy pattern detected; restricted compensation with escalation.\"},\n",
+        "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"Abusive/spammy pattern detected.\"},\n",
+        "        \"draft_response\": \"Thanks for contacting us. We are escalating this case for manual review and will follow up quickly.\",\n",
+        "        \"past_interactions_summary\": \"Pattern of escalation detected.\",\n",
+        "        \"order_details_summary\": \"Order under review.\",\n",
+        "        \"decision_confidence\": \"medium\",\n",
+        "        \"escalation_flag\": True,\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "\n",
+        "def get_fake_response(support_request_id: str, user_id: str, order_id: str) -> str:\n",
+        "    \"\"\"Return a deterministic fake response with IDs filled in.\"\"\"\n",
+        "    resp = random.choice(fake_responses).copy()\n",
+        "    resp[\"support_request_id\"] = support_request_id\n",
+        "    resp[\"user_id\"] = user_id\n",
+        "    resp[\"order_id\"] = order_id\n",
+        "    return json.dumps(resp)\n",
+        "\n",
+        "\n",
+        "def call_support_agent(payload_json: str) -> str:\n",
+        "    \"\"\"Call the support agent endpoint with the case payload.\n",
+        "\n",
+        "    Single attempt only.  Previous versions did 3 blind retries, which made\n",
+        "    the worst-case per-row cost 3 × _CALL_TIMEOUT_S = 90s and blew the 600s\n",
+        "    task budget under endpoint stress (see jobs/complaint_agent_stream.ipynb\n",
+        "    cell defining process_complaint for the same lesson).  For an\n",
+        "    availableNow catch-up stream the next 10-min cron tick will re-process\n",
+        "    anything that errored here, so fail-fast keeps each batch bounded.\n",
+        "\n",
+        "    Failure policy: any exception (timeout, invalid shape, non-JSON) →\n",
+        "    deterministic fake response so the batch keeps flowing.\n",
+        "    \"\"\"\n",
+        "    payload = json.loads(payload_json)\n",
+        "    support_request_id = payload.get(\"support_request_id\", \"\")\n",
+        "    user_id = payload.get(\"user_id\", \"\")\n",
+        "    order_id = payload.get(\"order_id\", \"\")\n",
+        "\n",
+        "    client = OpenAI(\n",
+        "        api_key=DATABRICKS_TOKEN,\n",
+        "        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n",
+        "        timeout=_CALL_TIMEOUT_S,\n",
+        "    )\n",
+        "\n",
+        "    try:\n",
+        "        response_obj = client.responses.create(\n",
+        "            model=SUPPORT_AGENT_ENDPOINT_NAME,\n",
+        "            input=[{\"role\": \"user\", \"content\": payload_json}],\n",
+        "            timeout=_CALL_TIMEOUT_S,\n",
+        "        )\n",
+        "        response = response_obj.output[-1].content[0].text\n",
+        "        json.loads(response)  # validate JSON\n",
+        "        return response\n",
+        "    except Exception:\n",
+        "        return get_fake_response(support_request_id, user_id, order_id)\n",
+        "\n",
+        "\n",
+        "call_support_agent_udf = udf(call_support_agent, StringType())\n",
+        "get_fake_response_udf = udf(get_fake_response, StringType())"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.support\")\n",
+        "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.support.checkpoints\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(f\"\"\"\n",
+        "CREATE TABLE IF NOT EXISTS {CATALOG}.support.support_agent_reports (\n",
+        "  support_request_id STRING,\n",
+        "  user_id STRING,\n",
+        "  order_id STRING,\n",
+        "  request_text STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  agent_response STRING\n",
+        ")\n",
+        "\"\"\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Enable CDC for Lakebase sync\n",
+        "table_name = f\"{CATALOG}.support.support_agent_reports\"\n",
+        "\n",
+        "try:\n",
+        "    props = spark.sql(f\"SHOW TBLPROPERTIES {table_name}\").collect()\n",
+        "    cdc_enabled = any(row.key == \"delta.enableChangeDataFeed\" and row.value == \"true\" for row in props)\n",
+        "except Exception:\n",
+        "    cdc_enabled = False\n",
+        "\n",
+        "if not cdc_enabled:\n",
+        "    print(f\"Enabling CDC on {table_name}\")\n",
+        "    spark.sql(f\"ALTER TABLE {table_name} SET TBLPROPERTIES (delta.enableChangeDataFeed = true)\")\n",
+        "else:\n",
+        "    print(f\"CDC already enabled on {table_name}, skipping\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "def process_batch(batch_df, batch_id):\n",
+        "    \"\"\"Process each micro-batch with inference capping.\n",
+        "\n",
+        "    - First run (no checkpoint): ALL rows get fake responses (fast backfill)\n",
+        "    - Subsequent runs: First N rows get real inference, rest get fake\n",
+        "    \"\"\"\n",
+        "    if batch_df.isEmpty():\n",
+        "        return\n",
+        "\n",
+        "    first_run = is_first_run()\n",
+        "    row_count = batch_df.count()\n",
+        "\n",
+        "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
+        "\n",
+        "    # Build payload JSON from row columns for the agent\n",
+        "    with_payload = batch_df.withColumn(\n",
+        "        \"payload_json\",\n",
+        "        F.to_json(\n",
+        "            F.struct(\n",
+        "                F.col(\"support_request_id\"),\n",
+        "                F.col(\"user_id\"),\n",
+        "                F.col(\"order_id\"),\n",
+        "                F.col(\"request_type\"),\n",
+        "                F.col(\"edge_case_type\"),\n",
+        "                F.col(\"request_text\"),\n",
+        "            )\n",
+        "        ),\n",
+        "    )\n",
+        "\n",
+        "    if first_run:\n",
+        "        # First run: ALL rows get fake responses (fast backfill)\n",
+        "        print(f\"  -> First run detected, using fake responses for all {row_count} rows\")\n",
+        "        result_df = with_payload.select(\n",
+        "            F.col(\"support_request_id\"),\n",
+        "            F.col(\"user_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.col(\"request_text\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            get_fake_response_udf(\n",
+        "                F.col(\"support_request_id\"), F.col(\"user_id\"), F.col(\"order_id\")\n",
+        "            ).alias(\"agent_response\"),\n",
+        "        )\n",
+        "    else:\n",
+        "        # Subsequent runs: first N rows get real inference, rest get fake\n",
+        "        windowed = with_payload.withColumn(\n",
+        "            \"row_num\",\n",
+        "            F.row_number().over(Window.orderBy(F.col(\"ts\"), F.col(\"support_request_id\"))),\n",
+        "        )\n",
+        "\n",
+        "        real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
+        "        fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
+        "        print(f\"  -> Real inference: {real_count} rows, fake: {fake_count} rows\")\n",
+        "\n",
+        "        real_inference_df = windowed.filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\").select(\n",
+        "            F.col(\"support_request_id\"),\n",
+        "            F.col(\"user_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.col(\"request_text\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            call_support_agent_udf(F.col(\"payload_json\")).alias(\"agent_response\"),\n",
+        "        )\n",
+        "\n",
+        "        fake_response_df = windowed.filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\").select(\n",
+        "            F.col(\"support_request_id\"),\n",
+        "            F.col(\"user_id\"),\n",
+        "            F.col(\"order_id\"),\n",
+        "            F.col(\"request_text\"),\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            get_fake_response_udf(\n",
+        "                F.col(\"support_request_id\"), F.col(\"user_id\"), F.col(\"order_id\")\n",
+        "            ).alias(\"agent_response\"),\n",
+        "        )\n",
+        "\n",
+        "        result_df = real_inference_df.union(fake_response_df)\n",
+        "\n",
+        "    result_df.write.mode(\"append\").saveAsTable(f\"{CATALOG}.support.support_agent_reports\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Read stream from raw support requests.\n",
+        "# Recover automatically if the source Delta table id has changed since the\n",
+        "# last run (DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE).  On recovery we\n",
+        "# rebuild the source stream with startingVersion=\"latest\" so we do NOT\n",
+        "# reprocess the entire recreated table in one giant availableNow micro-batch\n",
+        "# (which was timing out the cluster).  Real-time data flows from the new\n",
+        "# version onward.\n",
+        "def _build_support_requests(starting_version=None):\n",
+        "    reader = spark.readStream\n",
+        "    if starting_version is not None:\n",
+        "        reader = reader.option(\"startingVersion\", str(starting_version))\n",
+        "    return reader.table(f\"{CATALOG}.support.raw_support_requests\")\n",
+        "\n",
+        "\n",
+        "support_requests = _build_support_requests()\n",
+        "\n",
+        "\n",
+        "def _run_stream(stream_df):\n",
+        "    q = (\n",
+        "        stream_df.writeStream\n",
+        "        .foreachBatch(process_batch)\n",
+        "        .option(\"checkpointLocation\", CHECKPOINT_PATH)\n",
+        "        .trigger(availableNow=True)\n",
+        "        .start()\n",
+        "    )\n",
+        "    q.awaitTermination()\n",
+        "\n",
+        "\n",
+        "# Recoverable errors that all warrant clearing the checkpoint and restarting\n",
+        "# from the LATEST version of the source:\n",
+        "#   - DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE: source table was recreated.\n",
+        "#   - STREAMING_CHECKPOINT_METADATA_ERROR / MISSING_METADATA_FILE: checkpoint\n",
+        "#     directory was partially wiped (e.g. by `bundle run cleanup`) leaving\n",
+        "#     offsets/commits without the metadata file, which Spark refuses to start on.\n",
+        "_RECOVERABLE_MARKERS = (\n",
+        "    \"DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE\",\n",
+        "    \"STREAMING_CHECKPOINT_METADATA_ERROR\",\n",
+        "    \"MISSING_METADATA_FILE\",\n",
+        ")\n",
+        "\n",
+        "try:\n",
+        "    _run_stream(support_requests)\n",
+        "except Exception as e:\n",
+        "    msg = str(e)\n",
+        "    if any(marker in msg for marker in _RECOVERABLE_MARKERS):\n",
+        "        first_line = msg.splitlines()[0] if msg else \"\"\n",
+        "        print(\n",
+        "            f\"⚠️ Streaming state unrecoverable ({first_line}). \"\n",
+        "            f\"Clearing stale checkpoint at {CHECKPOINT_PATH} and restarting \"\n",
+        "            f\"from the LATEST version of the source (historical backfill skipped).\"\n",
+        "        )\n",
+        "        dbutils.fs.rm(CHECKPOINT_PATH, recurse=True)\n",
+        "        print(f\"✅ Cleared {CHECKPOINT_PATH}\")\n",
+        "        _run_stream(_build_support_requests(starting_version=\"latest\"))\n",
+        "    else:\n",
+        "        raise"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "DATABRICKS_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().getOrElse(None)\n",
-    "DATABRICKS_HOST = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().getOrElse(None)\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install openai"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "import random\n",
-    "import os\n",
-    "\n",
-    "from pyspark.sql import functions as F\n",
-    "from pyspark.sql.types import StringType\n",
-    "from pyspark.sql.functions import udf\n",
-    "from pyspark.sql.window import Window\n",
-    "from openai import OpenAI\n",
-    "\n",
-    "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/support/checkpoints/support_request_agent_stream\"\n",
-    "MAX_INFERENCES_PER_BATCH = 50\n",
-    "\n",
-    "\n",
-    "def is_first_run():\n",
-    "    \"\"\"Check if checkpoint exists (indicates this is NOT the first run)\"\"\"\n",
-    "    return not os.path.exists(CHECKPOINT_PATH) or len(os.listdir(CHECKPOINT_PATH)) == 0\n",
-    "\n",
-    "\n",
-    "# ── Deterministic fallback responses ──────────────────────────────────────────\n",
-    "# These mirror the policy resolution logic from the agent, providing realistic\n",
-    "# structured responses when the endpoint is unavailable or during backfill.\n",
-    "\n",
-    "fake_responses = [\n",
-    "    {\n",
-    "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
-    "        \"credit_recommendation\": {\"amount_usd\": 3.0, \"reason\": \"Goodwill credit for minor service issue.\"},\n",
-    "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"No verified severe failure.\"},\n",
-    "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $3.00 credit on this case.\",\n",
-    "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
-    "        \"order_details_summary\": \"Standard delivery order.\",\n",
-    "        \"decision_confidence\": \"medium\",\n",
-    "        \"escalation_flag\": False,\n",
-    "    },\n",
-    "    {\n",
-    "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
-    "        \"credit_recommendation\": {\"amount_usd\": 5.0, \"reason\": \"Moderate service issue with customer impact.\"},\n",
-    "        \"refund_recommendation\": {\"amount_usd\": 10.0, \"reason\": \"Moderate service issue with customer impact.\"},\n",
-    "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $10.00 refund and a $5.00 credit on this case.\",\n",
-    "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
-    "        \"order_details_summary\": \"Delivery with reported delay.\",\n",
-    "        \"decision_confidence\": \"high\",\n",
-    "        \"escalation_flag\": False,\n",
-    "    },\n",
-    "    {\n",
-    "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
-    "        \"credit_recommendation\": {\"amount_usd\": 2.0, \"reason\": \"Minor issue or low-confidence compensable case.\"},\n",
-    "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"No severe failure identified.\"},\n",
-    "        \"draft_response\": \"Thanks for contacting us, and I am really sorry about this experience. We are offering a $2.00 credit on this case.\",\n",
-    "        \"past_interactions_summary\": \"No prior interactions found.\",\n",
-    "        \"order_details_summary\": \"Standard delivery order.\",\n",
-    "        \"decision_confidence\": \"medium\",\n",
-    "        \"escalation_flag\": False,\n",
-    "    },\n",
-    "    {\n",
-    "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
-    "        \"credit_recommendation\": {\"amount_usd\": 5.0, \"reason\": \"Repeated or high-risk service failure.\"},\n",
-    "        \"refund_recommendation\": {\"amount_usd\": 18.0, \"reason\": \"Repeated or high-risk service failure.\"},\n",
-    "        \"draft_response\": \"I see this is at least the 2nd time you've had to contact us for similar issues, and that is not acceptable. We are offering a $18.00 refund and a $5.00 credit on this case.\",\n",
-    "        \"past_interactions_summary\": \"Multiple prior contacts for similar issues.\",\n",
-    "        \"order_details_summary\": \"Repeat issue with delivery.\",\n",
-    "        \"decision_confidence\": \"high\",\n",
-    "        \"escalation_flag\": False,\n",
-    "    },\n",
-    "    {\n",
-    "        \"support_request_id\": \"\", \"user_id\": \"\", \"order_id\": \"\",\n",
-    "        \"credit_recommendation\": {\"amount_usd\": 3.0, \"reason\": \"Abusive/spammy pattern detected; restricted compensation with escalation.\"},\n",
-    "        \"refund_recommendation\": {\"amount_usd\": 0.0, \"reason\": \"Abusive/spammy pattern detected.\"},\n",
-    "        \"draft_response\": \"Thanks for contacting us. We are escalating this case for manual review and will follow up quickly.\",\n",
-    "        \"past_interactions_summary\": \"Pattern of escalation detected.\",\n",
-    "        \"order_details_summary\": \"Order under review.\",\n",
-    "        \"decision_confidence\": \"medium\",\n",
-    "        \"escalation_flag\": True,\n",
-    "    },\n",
-    "]\n",
-    "\n",
-    "\n",
-    "def get_fake_response(support_request_id: str, user_id: str, order_id: str) -> str:\n",
-    "    \"\"\"Return a deterministic fake response with IDs filled in.\"\"\"\n",
-    "    resp = random.choice(fake_responses).copy()\n",
-    "    resp[\"support_request_id\"] = support_request_id\n",
-    "    resp[\"user_id\"] = user_id\n",
-    "    resp[\"order_id\"] = order_id\n",
-    "    return json.dumps(resp)\n",
-    "\n",
-    "\n",
-    "def call_support_agent(payload_json: str) -> str:\n",
-    "    \"\"\"Call the support agent endpoint with the case payload.\"\"\"\n",
-    "    payload = json.loads(payload_json)\n",
-    "    support_request_id = payload.get(\"support_request_id\", \"\")\n",
-    "    user_id = payload.get(\"user_id\", \"\")\n",
-    "    order_id = payload.get(\"order_id\", \"\")\n",
-    "\n",
-    "    client = OpenAI(\n",
-    "        api_key=DATABRICKS_TOKEN,\n",
-    "        base_url=f\"{DATABRICKS_HOST}/serving-endpoints\",\n",
-    "    )\n",
-    "\n",
-    "    for _ in range(3):\n",
-    "        try:\n",
-    "            response_obj = client.responses.create(\n",
-    "                model=SUPPORT_AGENT_ENDPOINT_NAME,\n",
-    "                input=[{\"role\": \"user\", \"content\": payload_json}],\n",
-    "            )\n",
-    "            response = response_obj.output[-1].content[0].text\n",
-    "            json.loads(response)  # validate JSON\n",
-    "            return response\n",
-    "        except Exception:\n",
-    "            continue\n",
-    "\n",
-    "    # All retries failed — return fake\n",
-    "    return get_fake_response(support_request_id, user_id, order_id)\n",
-    "\n",
-    "\n",
-    "call_support_agent_udf = udf(call_support_agent, StringType())\n",
-    "get_fake_response_udf = udf(get_fake_response, StringType())"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.support\")\n",
-    "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.support.checkpoints\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "spark.sql(f\"\"\"\n",
-    "CREATE TABLE IF NOT EXISTS {CATALOG}.support.support_agent_reports (\n",
-    "  support_request_id STRING,\n",
-    "  user_id STRING,\n",
-    "  order_id STRING,\n",
-    "  request_text STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  agent_response STRING\n",
-    ")\n",
-    "\"\"\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Enable CDC for Lakebase sync\n",
-    "table_name = f\"{CATALOG}.support.support_agent_reports\"\n",
-    "\n",
-    "try:\n",
-    "    props = spark.sql(f\"SHOW TBLPROPERTIES {table_name}\").collect()\n",
-    "    cdc_enabled = any(row.key == \"delta.enableChangeDataFeed\" and row.value == \"true\" for row in props)\n",
-    "except Exception:\n",
-    "    cdc_enabled = False\n",
-    "\n",
-    "if not cdc_enabled:\n",
-    "    print(f\"Enabling CDC on {table_name}\")\n",
-    "    spark.sql(f\"ALTER TABLE {table_name} SET TBLPROPERTIES (delta.enableChangeDataFeed = true)\")\n",
-    "else:\n",
-    "    print(f\"CDC already enabled on {table_name}, skipping\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "def process_batch(batch_df, batch_id):\n",
-    "    \"\"\"Process each micro-batch with inference capping.\n",
-    "\n",
-    "    - First run (no checkpoint): ALL rows get fake responses (fast backfill)\n",
-    "    - Subsequent runs: First N rows get real inference, rest get fake\n",
-    "    \"\"\"\n",
-    "    if batch_df.isEmpty():\n",
-    "        return\n",
-    "\n",
-    "    first_run = is_first_run()\n",
-    "    row_count = batch_df.count()\n",
-    "\n",
-    "    print(f\"Processing batch {batch_id}: {row_count} rows, first_run={first_run}\")\n",
-    "\n",
-    "    # Build payload JSON from row columns for the agent\n",
-    "    with_payload = batch_df.withColumn(\n",
-    "        \"payload_json\",\n",
-    "        F.to_json(\n",
-    "            F.struct(\n",
-    "                F.col(\"support_request_id\"),\n",
-    "                F.col(\"user_id\"),\n",
-    "                F.col(\"order_id\"),\n",
-    "                F.col(\"request_type\"),\n",
-    "                F.col(\"edge_case_type\"),\n",
-    "                F.col(\"request_text\"),\n",
-    "            )\n",
-    "        ),\n",
-    "    )\n",
-    "\n",
-    "    if first_run:\n",
-    "        # First run: ALL rows get fake responses (fast backfill)\n",
-    "        print(f\"  -> First run detected, using fake responses for all {row_count} rows\")\n",
-    "        result_df = with_payload.select(\n",
-    "            F.col(\"support_request_id\"),\n",
-    "            F.col(\"user_id\"),\n",
-    "            F.col(\"order_id\"),\n",
-    "            F.col(\"request_text\"),\n",
-    "            F.current_timestamp().alias(\"ts\"),\n",
-    "            get_fake_response_udf(\n",
-    "                F.col(\"support_request_id\"), F.col(\"user_id\"), F.col(\"order_id\")\n",
-    "            ).alias(\"agent_response\"),\n",
-    "        )\n",
-    "    else:\n",
-    "        # Subsequent runs: first N rows get real inference, rest get fake\n",
-    "        windowed = with_payload.withColumn(\n",
-    "            \"row_num\",\n",
-    "            F.row_number().over(Window.orderBy(F.col(\"ts\"), F.col(\"support_request_id\"))),\n",
-    "        )\n",
-    "\n",
-    "        real_count = min(row_count, MAX_INFERENCES_PER_BATCH)\n",
-    "        fake_count = max(0, row_count - MAX_INFERENCES_PER_BATCH)\n",
-    "        print(f\"  -> Real inference: {real_count} rows, fake: {fake_count} rows\")\n",
-    "\n",
-    "        real_inference_df = windowed.filter(f\"row_num <= {MAX_INFERENCES_PER_BATCH}\").select(\n",
-    "            F.col(\"support_request_id\"),\n",
-    "            F.col(\"user_id\"),\n",
-    "            F.col(\"order_id\"),\n",
-    "            F.col(\"request_text\"),\n",
-    "            F.current_timestamp().alias(\"ts\"),\n",
-    "            call_support_agent_udf(F.col(\"payload_json\")).alias(\"agent_response\"),\n",
-    "        )\n",
-    "\n",
-    "        fake_response_df = windowed.filter(f\"row_num > {MAX_INFERENCES_PER_BATCH}\").select(\n",
-    "            F.col(\"support_request_id\"),\n",
-    "            F.col(\"user_id\"),\n",
-    "            F.col(\"order_id\"),\n",
-    "            F.col(\"request_text\"),\n",
-    "            F.current_timestamp().alias(\"ts\"),\n",
-    "            get_fake_response_udf(\n",
-    "                F.col(\"support_request_id\"), F.col(\"user_id\"), F.col(\"order_id\")\n",
-    "            ).alias(\"agent_response\"),\n",
-    "        )\n",
-    "\n",
-    "        result_df = real_inference_df.union(fake_response_df)\n",
-    "\n",
-    "    result_df.write.mode(\"append\").saveAsTable(f\"{CATALOG}.support.support_agent_reports\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Read stream from raw support requests\n",
-    "support_requests = spark.readStream.table(f\"{CATALOG}.support.raw_support_requests\")\n",
-    "\n",
-    "support_requests.writeStream \\\n",
-    "    .foreachBatch(process_batch) \\\n",
-    "    .option(\"checkpointLocation\", CHECKPOINT_PATH) \\\n",
-    "    .trigger(availableNow=True) \\\n",
-    "    .start() \\\n",
-    "    .awaitTermination()"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/jobs/support_request_generator.ipynb b/jobs/support_request_generator.ipynb
index 1402179..722e1bf 100644
--- a/jobs/support_request_generator.ipynb
+++ b/jobs/support_request_generator.ipynb
@@ -1,191 +1,228 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Support Request Generator\n",
-    "\n",
-    "Generate synthetic support requests from delivered orders with deterministic user IDs and edge-case distribution"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Support Request Generator\n",
+        "\n",
+        "Generate synthetic support requests from delivered orders with deterministic user IDs and edge-case distribution"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "SUPPORT_RATE = float(dbutils.widgets.get(\"SUPPORT_RATE\"))\n",
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.support\")\n",
+        "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.support.checkpoints\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(\n",
+        "    f\"\"\"\n",
+        "    CREATE TABLE IF NOT EXISTS {CATALOG}.support.raw_support_requests (\n",
+        "      support_request_id STRING,\n",
+        "      user_id STRING,\n",
+        "      order_id STRING,\n",
+        "      ts TIMESTAMP,\n",
+        "      request_type STRING,\n",
+        "      request_text STRING,\n",
+        "      edge_case_type STRING,\n",
+        "      request_attempt INT,\n",
+        "      generated_by STRING\n",
+        "    )\n",
+        "    \"\"\"\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from pyspark.sql import functions as F\n",
+        "\n",
+        "# Deterministic repeatable user IDs and controlled edge-case distribution.\n",
+        "# - ~10% create an extra follow-up request for same order/user\n",
+        "# - ~3% create two extra follow-ups (spam/repeat bursts)\n",
+        "# - ~5% spammy/escalation phrasing\n",
+        "# - ~2% abusive phrasing\n",
+        "#\n",
+        "# Wrapped in a builder so the retry path can pass startingVersion=\"latest\"\n",
+        "# and skip a multi-million-row historical backfill after a table recreate.\n",
+        "def _build_support_stream(starting_version=None):\n",
+        "    reader = spark.readStream\n",
+        "    if starting_version is not None:\n",
+        "        reader = reader.option(\"startingVersion\", str(starting_version))\n",
+        "    source = (\n",
+        "        reader\n",
+        "        .table(f\"{CATALOG}.lakeflow.all_events\")\n",
+        "        .filter(F.col(\"event_type\") == \"delivered\")\n",
+        "        .filter(F.rand() < SUPPORT_RATE)\n",
+        "        .withColumn(\"seed\", F.abs(F.hash(F.col(\"order_id\"))))\n",
+        "        .withColumn(\"hash_bucket\", F.col(\"seed\") % F.lit(25))\n",
+        "        .withColumn(\"user_id\", F.concat(F.lit(\"user-\"), F.format_string(\"%03d\", F.col(\"hash_bucket\"))))\n",
+        "        .withColumn(\n",
+        "            \"request_type\",\n",
+        "            F.expr(\n",
+        "                \"\"\"\n",
+        "                CASE\n",
+        "                  WHEN hash_bucket % 5 = 0 THEN 'delivery_delay'\n",
+        "                  WHEN hash_bucket % 5 = 1 THEN 'missing_items'\n",
+        "                  WHEN hash_bucket % 5 = 2 THEN 'food_quality'\n",
+        "                  WHEN hash_bucket % 5 = 3 THEN 'billing'\n",
+        "                  ELSE 'general_support'\n",
+        "                END\n",
+        "                \"\"\"\n",
+        "            ),\n",
+        "        )\n",
+        "        .withColumn(\n",
+        "            \"edge_case_type\",\n",
+        "            F.expr(\n",
+        "                \"\"\"\n",
+        "                CASE\n",
+        "                  WHEN seed % 100 < 2 THEN 'abusive_language'\n",
+        "                  WHEN seed % 100 < 7 THEN 'spammy_escalation'\n",
+        "                  WHEN seed % 100 < 15 THEN 'repeat_follow_up'\n",
+        "                  WHEN seed % 100 < 21 THEN 'non_compensable_confusion'\n",
+        "                  ELSE 'standard'\n",
+        "                END\n",
+        "                \"\"\"\n",
+        "            ),\n",
+        "        )\n",
+        "        .withColumn(\n",
+        "            \"repeat_multiplier\",\n",
+        "            F.expr(\n",
+        "                \"\"\"\n",
+        "                CASE\n",
+        "                  WHEN seed % 100 < 3 THEN 3\n",
+        "                  WHEN seed % 100 < 13 THEN 2\n",
+        "                  ELSE 1\n",
+        "                END\n",
+        "                \"\"\"\n",
+        "            ),\n",
+        "        )\n",
+        "    )\n",
+        "\n",
+        "    return (\n",
+        "        source\n",
+        "        .withColumn(\"repeat_idx\", F.explode(F.sequence(F.lit(1), F.col(\"repeat_multiplier\"))))\n",
+        "        .withColumn(\"support_request_id\", F.expr(\"uuid()\"))\n",
+        "        .withColumn(\"request_attempt\", F.col(\"repeat_idx\"))\n",
+        "        .withColumn(\n",
+        "            \"request_text\",\n",
+        "            F.expr(\n",
+        "                \"\"\"\n",
+        "                CASE\n",
+        "                  WHEN edge_case_type = 'abusive_language' THEN\n",
+        "                    'This is unacceptable and ridiculous. Your team keeps messing this up. Fix this now.'\n",
+        "                  WHEN edge_case_type = 'spammy_escalation' AND request_attempt > 1 THEN\n",
+        "                    'Third message: still unresolved. Refund me immediately and escalate this to a supervisor now.'\n",
+        "                  WHEN edge_case_type = 'spammy_escalation' THEN\n",
+        "                    'Second request today. Please resolve this immediately. I need clear compensation details now.'\n",
+        "                  WHEN edge_case_type = 'repeat_follow_up' AND request_attempt > 1 THEN\n",
+        "                    'Following up again because this is not the first time this happened. Please review previous cases and offer a fair resolution.'\n",
+        "                  WHEN request_type = 'delivery_delay' AND request_attempt > 1 THEN\n",
+        "                    'This is another delay issue for me. I need a concrete resolution with refund and credit details.'\n",
+        "                  WHEN request_type = 'delivery_delay' THEN\n",
+        "                    'My delivery arrived much later than expected. Can you help with a credit or refund?'\n",
+        "                  WHEN request_type = 'missing_items' AND request_attempt > 1 THEN\n",
+        "                    'This is the second time items were missing from my order. Please make this right with a concrete offer.'\n",
+        "                  WHEN request_type = 'missing_items' THEN\n",
+        "                    'My order was missing one or more items. Please review and advise next steps.'\n",
+        "                  WHEN request_type = 'food_quality' THEN\n",
+        "                    'I had a quality issue with my food. I would like support and possible compensation.'\n",
+        "                  WHEN request_type = 'billing' THEN\n",
+        "                    'I think there is a billing issue on my recent order. Can you verify the charge?'\n",
+        "                  WHEN edge_case_type = 'non_compensable_confusion' THEN\n",
+        "                    'I changed my mind after ordering and wanted to check if I can still get a courtesy credit.'\n",
+        "                  ELSE\n",
+        "                    'I need help with a recent order. Please review my request and let me know what you can do.'\n",
+        "                END\n",
+        "                \"\"\"\n",
+        "            ),\n",
+        "        )\n",
+        "        .select(\n",
+        "            \"support_request_id\",\n",
+        "            \"user_id\",\n",
+        "            \"order_id\",\n",
+        "            F.current_timestamp().alias(\"ts\"),\n",
+        "            \"request_type\",\n",
+        "            \"request_text\",\n",
+        "            \"edge_case_type\",\n",
+        "            \"request_attempt\",\n",
+        "            F.lit(\"generator-v2\").alias(\"generated_by\"),\n",
+        "        )\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "expanded = _build_support_stream()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Recover automatically if the source Delta table id has changed since the\n",
+        "# last run (DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE) — see\n",
+        "# jobs/complaint_generator.ipynb for the same pattern.\n",
+        "CHECKPOINT_PATH = f\"/Volumes/{CATALOG}/support/checkpoints/support_request_generator\"\n",
+        "TARGET_TABLE = f\"{CATALOG}.support.raw_support_requests\"\n",
+        "\n",
+        "\n",
+        "def _run_stream(stream_df):\n",
+        "    q = (\n",
+        "        stream_df.writeStream\n",
+        "        .option(\"checkpointLocation\", CHECKPOINT_PATH)\n",
+        "        .trigger(availableNow=True)\n",
+        "        .toTable(TARGET_TABLE)\n",
+        "    )\n",
+        "    q.awaitTermination()\n",
+        "\n",
+        "\n",
+        "try:\n",
+        "    _run_stream(expanded)\n",
+        "except Exception as e:\n",
+        "    if \"DIFFERENT_DELTA_TABLE_READ_BY_STREAMING_SOURCE\" in str(e):\n",
+        "        print(\n",
+        "            f\"⚠️ Source Delta table id changed (table was recreated). \"\n",
+        "            f\"Clearing stale checkpoint at {CHECKPOINT_PATH} and restarting \"\n",
+        "            f\"from the LATEST version of the source (historical backfill skipped).\"\n",
+        "        )\n",
+        "        dbutils.fs.rm(CHECKPOINT_PATH, recurse=True)\n",
+        "        print(f\"✅ Cleared {CHECKPOINT_PATH}\")\n",
+        "        _run_stream(_build_support_stream(starting_version=\"latest\"))\n",
+        "    else:\n",
+        "        raise"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "SUPPORT_RATE = float(dbutils.widgets.get(\"SUPPORT_RATE\"))\n",
-    "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.support\")\n",
-    "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.support.checkpoints\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "spark.sql(\n",
-    "    f\"\"\"\n",
-    "    CREATE TABLE IF NOT EXISTS {CATALOG}.support.raw_support_requests (\n",
-    "      support_request_id STRING,\n",
-    "      user_id STRING,\n",
-    "      order_id STRING,\n",
-    "      ts TIMESTAMP,\n",
-    "      request_type STRING,\n",
-    "      request_text STRING,\n",
-    "      edge_case_type STRING,\n",
-    "      request_attempt INT,\n",
-    "      generated_by STRING\n",
-    "    )\n",
-    "    \"\"\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyspark.sql import functions as F\n",
-    "\n",
-    "# Deterministic repeatable user IDs and controlled edge-case distribution.\n",
-    "# - ~10% create an extra follow-up request for same order/user\n",
-    "# - ~3% create two extra follow-ups (spam/repeat bursts)\n",
-    "# - ~5% spammy/escalation phrasing\n",
-    "# - ~2% abusive phrasing\n",
-    "source = (\n",
-    "    spark.readStream\n",
-    "    .table(f\"{CATALOG}.lakeflow.all_events\")\n",
-    "    .filter(F.col(\"event_type\") == \"delivered\")\n",
-    "    .filter(F.rand() < SUPPORT_RATE)\n",
-    "    .withColumn(\"seed\", F.abs(F.hash(F.col(\"order_id\"))))\n",
-    "    .withColumn(\"hash_bucket\", F.col(\"seed\") % F.lit(25))\n",
-    "    .withColumn(\"user_id\", F.concat(F.lit(\"user-\"), F.format_string(\"%03d\", F.col(\"hash_bucket\"))))\n",
-    "    .withColumn(\n",
-    "        \"request_type\",\n",
-    "        F.expr(\n",
-    "            \"\"\"\n",
-    "            CASE\n",
-    "              WHEN hash_bucket % 5 = 0 THEN 'delivery_delay'\n",
-    "              WHEN hash_bucket % 5 = 1 THEN 'missing_items'\n",
-    "              WHEN hash_bucket % 5 = 2 THEN 'food_quality'\n",
-    "              WHEN hash_bucket % 5 = 3 THEN 'billing'\n",
-    "              ELSE 'general_support'\n",
-    "            END\n",
-    "            \"\"\"\n",
-    "        ),\n",
-    "    )\n",
-    "    .withColumn(\n",
-    "        \"edge_case_type\",\n",
-    "        F.expr(\n",
-    "            \"\"\"\n",
-    "            CASE\n",
-    "              WHEN seed % 100 < 2 THEN 'abusive_language'\n",
-    "              WHEN seed % 100 < 7 THEN 'spammy_escalation'\n",
-    "              WHEN seed % 100 < 15 THEN 'repeat_follow_up'\n",
-    "              WHEN seed % 100 < 21 THEN 'non_compensable_confusion'\n",
-    "              ELSE 'standard'\n",
-    "            END\n",
-    "            \"\"\"\n",
-    "        ),\n",
-    "    )\n",
-    "    .withColumn(\n",
-    "        \"repeat_multiplier\",\n",
-    "        F.expr(\n",
-    "            \"\"\"\n",
-    "            CASE\n",
-    "              WHEN seed % 100 < 3 THEN 3\n",
-    "              WHEN seed % 100 < 13 THEN 2\n",
-    "              ELSE 1\n",
-    "            END\n",
-    "            \"\"\"\n",
-    "        ),\n",
-    "    )\n",
-    ")\n",
-    "\n",
-    "expanded = (\n",
-    "    source\n",
-    "    .withColumn(\"repeat_idx\", F.explode(F.sequence(F.lit(1), F.col(\"repeat_multiplier\"))))\n",
-    "    .withColumn(\"support_request_id\", F.expr(\"uuid()\"))\n",
-    "    .withColumn(\"request_attempt\", F.col(\"repeat_idx\"))\n",
-    "    .withColumn(\n",
-    "        \"request_text\",\n",
-    "        F.expr(\n",
-    "            \"\"\"\n",
-    "            CASE\n",
-    "              WHEN edge_case_type = 'abusive_language' THEN\n",
-    "                'This is unacceptable and ridiculous. Your team keeps messing this up. Fix this now.'\n",
-    "              WHEN edge_case_type = 'spammy_escalation' AND request_attempt > 1 THEN\n",
-    "                'Third message: still unresolved. Refund me immediately and escalate this to a supervisor now.'\n",
-    "              WHEN edge_case_type = 'spammy_escalation' THEN\n",
-    "                'Second request today. Please resolve this immediately. I need clear compensation details now.'\n",
-    "              WHEN edge_case_type = 'repeat_follow_up' AND request_attempt > 1 THEN\n",
-    "                'Following up again because this is not the first time this happened. Please review previous cases and offer a fair resolution.'\n",
-    "              WHEN request_type = 'delivery_delay' AND request_attempt > 1 THEN\n",
-    "                'This is another delay issue for me. I need a concrete resolution with refund and credit details.'\n",
-    "              WHEN request_type = 'delivery_delay' THEN\n",
-    "                'My delivery arrived much later than expected. Can you help with a credit or refund?'\n",
-    "              WHEN request_type = 'missing_items' AND request_attempt > 1 THEN\n",
-    "                'This is the second time items were missing from my order. Please make this right with a concrete offer.'\n",
-    "              WHEN request_type = 'missing_items' THEN\n",
-    "                'My order was missing one or more items. Please review and advise next steps.'\n",
-    "              WHEN request_type = 'food_quality' THEN\n",
-    "                'I had a quality issue with my food. I would like support and possible compensation.'\n",
-    "              WHEN request_type = 'billing' THEN\n",
-    "                'I think there is a billing issue on my recent order. Can you verify the charge?'\n",
-    "              WHEN edge_case_type = 'non_compensable_confusion' THEN\n",
-    "                'I changed my mind after ordering and wanted to check if I can still get a courtesy credit.'\n",
-    "              ELSE\n",
-    "                'I need help with a recent order. Please review my request and let me know what you can do.'\n",
-    "            END\n",
-    "            \"\"\"\n",
-    "        ),\n",
-    "    )\n",
-    "    .select(\n",
-    "        \"support_request_id\",\n",
-    "        \"user_id\",\n",
-    "        \"order_id\",\n",
-    "        F.current_timestamp().alias(\"ts\"),\n",
-    "        \"request_type\",\n",
-    "        \"request_text\",\n",
-    "        \"edge_case_type\",\n",
-    "        \"request_attempt\",\n",
-    "        F.lit(\"generator-v2\").alias(\"generated_by\"),\n",
-    "    )\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "expanded.writeStream \\\n",
-    "    .option(\"checkpointLocation\", f\"/Volumes/{CATALOG}/support/checkpoints/support_request_generator\") \\\n",
-    "    .trigger(availableNow=True) \\\n",
-    "    .table(f\"{CATALOG}.support.raw_support_requests\")"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/pipelines/order_items/transformations/transformation.py b/pipelines/order_items/transformations/transformation.py
index 28908a5..1dce480 100644
--- a/pipelines/order_items/transformations/transformation.py
+++ b/pipelines/order_items/transformations/transformation.py
@@ -71,7 +71,7 @@ def silver_order_items():
                F.col("item.name").alias("item_name"),
                F.col("item.price"),
                F.col("item.qty"),
-               "extended_price"
+               "extended_price",
            )
     )
     return df
@@ -154,4 +154,61 @@ def gold_location_sales_hourly():
                F.approx_count_distinct("order_id").alias("orders"),
                F.sum("extended_price").alias("revenue")
            )
+    )
+
+# ──────────────────────────────────────────────────────────────
+# 2-E. Gold – daily order STATUS per location  (created / delivered / cancelled)
+# ──────────────────────────────────────────────────────────────
+#
+# Why a materialized view (batch `dlt.read`) instead of a streaming
+# aggregation:  "cancelled" is the absence of a `delivered` event for an
+# `order_created`, so it requires joining two event streams.  A
+# stream-stream anti-join with watermarks is fragile (late-arriving
+# `delivered` events flip a previously-cancelled order back to delivered
+# only inside the watermark window).  A full-refresh materialized view
+# recomputed every pipeline trigger is correct, cheap on a serverless
+# Lakeflow pipeline, and lets the ops dashboard read pre-aggregated
+# location/day rows instead of scanning the raw `all_events` table.
+#
+# Consumer:  apps/caspers-ops-dashboard /api/revenue and /api/locations.
+# Before this table existed the dashboard ran two `SELECT DISTINCT` scans
+# over 30 days of raw events + a LEFT JOIN on every page load, adding
+# ~1.8s per request — see commit history for context.
+@dlt.table(
+    name           = "gold_location_order_status_daily",
+    partition_cols = ["day"],
+    comment        = "Gold – per-location daily created / delivered / cancelled order counts.",
+)
+def gold_location_order_status_daily():
+    events = dlt.read("all_events")
+    created = (
+        events.filter(F.col("event_type") == "order_created")
+              .select(
+                  F.col("order_id"),
+                  F.col("location_id"),
+                  F.to_date(F.to_timestamp("ts")).alias("day"),
+              )
+              .dropDuplicates(["order_id"])
+    )
+    delivered = (
+        events.filter(F.col("event_type") == "delivered")
+              .select(F.col("order_id").alias("delivered_order_id"))
+              .dropDuplicates(["delivered_order_id"])
+    )
+    return (
+        created.join(
+            delivered,
+            created["order_id"] == delivered["delivered_order_id"],
+            "left",
+        )
+        .withColumn(
+            "is_delivered",
+            F.when(F.col("delivered_order_id").isNotNull(), 1).otherwise(0),
+        )
+        .groupBy("location_id", "day")
+        .agg(
+            F.count("order_id").alias("created_count"),
+            F.sum("is_delivered").alias("delivered_count"),
+            (F.count("order_id") - F.sum("is_delivered")).alias("cancelled_count"),
+        )
     )
\ No newline at end of file
diff --git a/resources/dashboards/caspers_kitchen_ai_agent_performance.lvdash.json b/resources/dashboards/caspers_kitchen_ai_agent_performance.lvdash.json
new file mode 100644
index 0000000..405c7c4
--- /dev/null
+++ b/resources/dashboards/caspers_kitchen_ai_agent_performance.lvdash.json
@@ -0,0 +1,541 @@
+{
+  "datasets": [
+    {
+      "name": "agent_requests",
+      "displayName": "Agent Requests",
+      "queryLines": [
+        "SELECT\n",
+        "  databricks_request_id,\n",
+        "  request_date,\n",
+        "  request_time,\n",
+        "  status_code,\n",
+        "  execution_duration_ms\n",
+        "FROM\n",
+        "  ai.complaint_agent_payload"
+      ],
+      "columns": [
+        {
+          "displayName": "Successful Requests",
+          "expression": "SUM(CASE WHEN `status_code` = 200 THEN 1 ELSE 0 END)"
+        }
+      ]
+    },
+    {
+      "name": "agent_decisions",
+      "displayName": "Agent Decisions",
+      "queryLines": [
+        "SELECT\n",
+        "  databricks_request_id,\n",
+        "  request_date,\n",
+        "  request_time,\n",
+        "  status_code,\n",
+        "  execution_duration_ms,\n",
+        "  get_json_object(\n",
+        "    get_json_object(response, '$.output[0].content[0].text'),\n",
+        "    '$.complaint_category'\n",
+        "  ) AS complaint_category,\n",
+        "  get_json_object(\n",
+        "    get_json_object(response, '$.output[0].content[0].text'),\n",
+        "    '$.decision'\n",
+        "  ) AS decision,\n",
+        "  CAST(\n",
+        "    get_json_object(\n",
+        "      get_json_object(response, '$.output[0].content[0].text'),\n",
+        "      '$.credit_amount'\n",
+        "    ) AS DOUBLE\n",
+        "  ) AS credit_amount,\n",
+        "  get_json_object(\n",
+        "    get_json_object(response, '$.output[0].content[0].text'),\n",
+        "    '$.confidence'\n",
+        "  ) AS confidence,\n",
+        "  get_json_object(\n",
+        "    get_json_object(response, '$.output[0].content[0].text'),\n",
+        "    '$.priority'\n",
+        "  ) AS priority\n",
+        "FROM\n",
+        "  ai.complaint_agent_payload\n",
+        "WHERE\n",
+        "  status_code = 200"
+      ],
+      "columns": [
+        {
+          "displayName": "Escalation Rate",
+          "expression": "SUM(CASE WHEN `decision` = 'escalate' THEN 1 ELSE 0 END) * 1.0 / COUNT(`databricks_request_id`)"
+        }
+      ]
+    }
+  ],
+  "pages": [
+    {
+      "name": "c3e54a1b",
+      "displayName": "Agent Performance",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Complaint Agent Performance"
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 1
+          }
+        },
+        {
+          "widget": {
+            "name": "total_requests",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_requests",
+                  "fields": [
+                    {
+                      "name": "count(databricks_request_id)",
+                      "expression": "COUNT(`databricks_request_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Requests",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "count(databricks_request_id)",
+                  "displayName": "Total Requests"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 1,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "success_rate",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_requests",
+                  "fields": [
+                    {
+                      "name": "measure(Successful Requests)",
+                      "expression": "MEASURE(`Successful Requests`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Success Rate",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(Successful Requests)",
+                  "displayName": "Successful Requests"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 1,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "avg_latency",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_requests",
+                  "fields": [
+                    {
+                      "name": "avg(execution_duration_ms)",
+                      "expression": "AVG(`execution_duration_ms`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Avg Latency (s)",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "avg(execution_duration_ms)",
+                  "format": {
+                    "type": "number-plain",
+                    "abbreviation": "compact"
+                  },
+                  "displayName": "Avg Latency (ms)"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 1,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "p95_latency",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_requests",
+                  "fields": [
+                    {
+                      "name": "percentile(execution_duration_ms, percentage=0_95)",
+                      "expression": "PERCENTILE(`execution_duration_ms`, 0.95)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "P95 Latency (ms)",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "percentile(execution_duration_ms, percentage=0_95)",
+                  "format": {
+                    "type": "number-plain",
+                    "abbreviation": "compact"
+                  },
+                  "displayName": "P95 Latency (ms)"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 1,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "decision_pie",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_decisions",
+                  "fields": [
+                    {
+                      "name": "count(databricks_request_id)",
+                      "expression": "COUNT(`databricks_request_id`)"
+                    },
+                    {
+                      "name": "decision",
+                      "expression": "`decision`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Decision Distribution",
+                "showTitle": true
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "count(databricks_request_id)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "decision",
+                  "displayName": "Decision",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "label": {
+                  "show": true
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 4,
+            "width": 4,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "confidence_bar",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_decisions",
+                  "fields": [
+                    {
+                      "name": "confidence",
+                      "expression": "`confidence`"
+                    },
+                    {
+                      "name": "count(databricks_request_id)",
+                      "expression": "COUNT(`databricks_request_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Confidence Breakdown",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "confidence",
+                  "displayName": "Confidence",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "count(databricks_request_id)",
+                  "displayName": "Request Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 4,
+            "width": 4,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "category_bar",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_decisions",
+                  "fields": [
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "count(databricks_request_id)",
+                      "expression": "COUNT(`databricks_request_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Complaint Categories",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "count(databricks_request_id)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 8,
+            "y": 4,
+            "width": 4,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "latency_over_time",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_requests",
+                  "fields": [
+                    {
+                      "name": "request_time",
+                      "expression": "`request_time`"
+                    },
+                    {
+                      "name": "avg(execution_duration_ms)",
+                      "expression": "AVG(`execution_duration_ms`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Latency Over Time",
+                "showTitle": true
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "request_time",
+                  "displayName": "Request Time",
+                  "scale": {
+                    "type": "temporal"
+                  }
+                },
+                "y": {
+                  "fieldName": "avg(execution_duration_ms)",
+                  "displayName": "Avg Latency (ms)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 10,
+            "width": 8,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "credits_by_decision",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "agent_decisions",
+                  "fields": [
+                    {
+                      "name": "measure(Escalation Rate)",
+                      "expression": "MEASURE(`Escalation Rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Escalation Rate",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(Escalation Rate)",
+                  "format": {
+                    "type": "number-percent",
+                    "decimalPlaces": {
+                      "type": "exact",
+                      "places": 1
+                    }
+                  },
+                  "displayName": "Escalation Rate"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 8,
+            "y": 10,
+            "width": 4,
+            "height": 6
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    }
+  ],
+  "uiSettings": {
+    "theme": {
+      "widgetHeaderAlignment": "ALIGNMENT_UNSPECIFIED"
+    },
+    "applyModeEnabled": false
+  }
+}
+
diff --git a/resources/dashboards/caspers_kitchen_delivery_performance.lvdash.json b/resources/dashboards/caspers_kitchen_delivery_performance.lvdash.json
new file mode 100644
index 0000000..86e4976
--- /dev/null
+++ b/resources/dashboards/caspers_kitchen_delivery_performance.lvdash.json
@@ -0,0 +1,530 @@
+{
+  "datasets": [
+    {
+      "name": "delivery_times",
+      "displayName": "Delivery Times",
+      "queryLines": [
+        "SELECT\n",
+        "  *\n",
+        "FROM\n",
+        "  ai.order_delivery_times_per_location_view"
+      ]
+    },
+    {
+      "name": "order_kpis",
+      "displayName": "Order KPIs",
+      "queryLines": [
+        "SELECT\n",
+        "  *\n",
+        "FROM\n",
+        "  lakeflow.gold_order_header"
+      ]
+    },
+    {
+      "name": "orders_by_location",
+      "displayName": "Orders by Location",
+      "queryLines": [
+        "SELECT\n",
+        "  o.order_id,\n",
+        "  o.location_id,\n",
+        "  l.name AS location_name,\n",
+        "  o.order_day,\n",
+        "  o.order_revenue,\n",
+        "  o.total_qty,\n",
+        "  o.total_items\n",
+        "FROM\n",
+        "  lakeflow.gold_order_header o\n",
+        "    JOIN simulator.locations l\n",
+        "      ON o.location_id = CAST(l.location_id AS STRING)"
+      ]
+    }
+  ],
+  "pages": [
+    {
+      "name": "24c18e2e",
+      "displayName": "Overview",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Caspers Kitchen - Delivery Performance & SLA"
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 1
+          }
+        },
+        {
+          "widget": {
+            "name": "total_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_kpis",
+                  "fields": [
+                    {
+                      "name": "count(order_id)",
+                      "expression": "COUNT(`order_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Orders",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "count(order_id)",
+                  "format": {
+                    "type": "number-plain",
+                    "abbreviation": "compact"
+                  },
+                  "displayName": "Total Orders"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 1,
+            "width": 4,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "total_revenue",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_kpis",
+                  "fields": [
+                    {
+                      "name": "sum(order_revenue)",
+                      "expression": "SUM(`order_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Revenue",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "sum(order_revenue)",
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "compact",
+                    "currencyCode": "USD"
+                  },
+                  "displayName": "Total Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 1,
+            "width": 4,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "avg_order_value",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_kpis",
+                  "fields": [
+                    {
+                      "name": "avg(order_revenue)",
+                      "expression": "AVG(`order_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Avg Order Value",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "avg(order_revenue)",
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "none",
+                    "currencyCode": "USD",
+                    "decimalPlaces": {
+                      "type": "exact",
+                      "places": 2
+                    }
+                  },
+                  "displayName": "Avg Order Value"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 8,
+            "y": 1,
+            "width": 4,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "delivery_time_chart",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "delivery_times",
+                  "fields": [
+                    {
+                      "name": "location",
+                      "expression": "`location`"
+                    },
+                    {
+                      "name": "sum(P50)",
+                      "expression": "SUM(`P50`)"
+                    },
+                    {
+                      "name": "sum(P75)",
+                      "expression": "SUM(`P75`)"
+                    },
+                    {
+                      "name": "sum(P99)",
+                      "expression": "SUM(`P99`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Delivery Time Percentiles by Location",
+                "showTitle": true,
+                "showDescription": true,
+                "description": "Minutes from order to delivery"
+              },
+              "mark": {
+                "layout": "group"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fields": [
+                    {
+                      "fieldName": "sum(P50)",
+                      "displayName": "P50 (min)"
+                    },
+                    {
+                      "fieldName": "sum(P75)",
+                      "displayName": "P75 (min)"
+                    },
+                    {
+                      "fieldName": "sum(P99)",
+                      "displayName": "P99 (min)"
+                    }
+                  ],
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 4,
+            "width": 7,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "daily_revenue_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_kpis",
+                  "fields": [
+                    {
+                      "name": "order_day",
+                      "expression": "`order_day`"
+                    },
+                    {
+                      "name": "sum(order_revenue)",
+                      "expression": "SUM(`order_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Daily Revenue Trend",
+                "showTitle": true
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "order_day",
+                  "displayName": "Order Day",
+                  "scale": {
+                    "type": "temporal"
+                  }
+                },
+                "y": {
+                  "fieldName": "sum(order_revenue)",
+                  "displayName": "Revenue ($)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 7,
+            "y": 4,
+            "width": 5,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "orders_by_location",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "sum(order_revenue)",
+                      "expression": "SUM(`order_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Revenue by Location",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "sum(order_revenue)",
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "compact",
+                    "currencyCode": "USD"
+                  },
+                  "displayName": "Revenue ($)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 10,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "orders_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "orders_by_location",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "count(order_id)",
+                      "expression": "COUNT(`order_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Orders by Location",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "count(order_id)",
+                  "displayName": "Order Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 10,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "weekly_orders_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "orders_by_location",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "weekly(order_day)",
+                      "expression": "DATE_TRUNC(\"WEEK\", `order_day`)"
+                    },
+                    {
+                      "name": "count(order_id)",
+                      "expression": "COUNT(`order_id`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Weekly Order Volume by Location",
+                "showTitle": true
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "weekly(order_day)",
+                  "displayName": "Week",
+                  "scale": {
+                    "type": "temporal"
+                  }
+                },
+                "y": {
+                  "fieldName": "count(order_id)",
+                  "displayName": "Orders",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 16,
+            "width": 12,
+            "height": 6
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    }
+  ],
+  "uiSettings": {
+    "theme": {
+      "widgetHeaderAlignment": "ALIGNMENT_UNSPECIFIED"
+    },
+    "applyModeEnabled": false
+  }
+}
+
diff --git a/resources/dashboards/caspers_kitchen_menu_intelligence.lvdash.json b/resources/dashboards/caspers_kitchen_menu_intelligence.lvdash.json
new file mode 100644
index 0000000..250c72b
--- /dev/null
+++ b/resources/dashboards/caspers_kitchen_menu_intelligence.lvdash.json
@@ -0,0 +1,760 @@
+{
+  "datasets": [
+    {
+      "name": "healthy_options",
+      "displayName": "Healthy Options",
+      "queryLines": [
+        "SELECT\n",
+        "  item_name,\n",
+        "  brand_name,\n",
+        "  cuisine,\n",
+        "  category,\n",
+        "  price,\n",
+        "  calories,\n",
+        "  protein_g,\n",
+        "  fat_g,\n",
+        "  carbs_g,\n",
+        "  protein_pct\n",
+        "FROM\n",
+        "  menu_documents.silver_menu_items\n",
+        "WHERE\n",
+        "  is_high_protein = true\n",
+        "  AND is_low_calorie = true\n",
+        "ORDER BY\n",
+        "  protein_pct DESC"
+      ]
+    },
+    {
+      "name": "menu_items_metrics",
+      "displayName": "Menu Items Metrics",
+      "config": {
+        "version": 1.1,
+        "source": "menu_documents.silver_menu_items",
+        "dimensions": [
+          {
+            "name": "brand_name",
+            "expr": "brand_name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine",
+            "expr": "cuisine",
+            "displayName": "Cuisine"
+          },
+          {
+            "name": "category",
+            "expr": "category",
+            "displayName": "Category"
+          },
+          {
+            "name": "price_tier",
+            "expr": "price_tier",
+            "displayName": "Price Tier"
+          },
+          {
+            "name": "calorie_category",
+            "expr": "calorie_category",
+            "displayName": "Calorie Category"
+          },
+          {
+            "name": "item_name",
+            "expr": "item_name",
+            "displayName": "Item Name"
+          },
+          {
+            "name": "price",
+            "expr": "price",
+            "displayName": "Price"
+          },
+          {
+            "name": "calories",
+            "expr": "calories",
+            "displayName": "Calories"
+          },
+          {
+            "name": "protein_g",
+            "expr": "protein_g",
+            "displayName": "Protein (g)"
+          },
+          {
+            "name": "is_high_protein",
+            "expr": "is_high_protein",
+            "displayName": "High Protein"
+          },
+          {
+            "name": "is_low_calorie",
+            "expr": "is_low_calorie",
+            "displayName": "Low Calorie"
+          },
+          {
+            "name": "is_allergen_free",
+            "expr": "is_allergen_free",
+            "displayName": "Allergen Free"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_items",
+            "expr": "COUNT(*)",
+            "displayName": "Total Menu Items"
+          },
+          {
+            "name": "avg_price",
+            "expr": "AVG(price)",
+            "displayName": "Avg Price",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          },
+          {
+            "name": "avg_calories",
+            "expr": "AVG(calories)",
+            "displayName": "Avg Calories",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "allergen_free_count",
+            "expr": "COUNT(CASE WHEN is_allergen_free = true THEN 1 END)",
+            "displayName": "Allergen-Free Items"
+          },
+          {
+            "name": "pct_allergen_free",
+            "expr": "MEASURE(allergen_free_count) * 100.0 / MEASURE(total_items)",
+            "displayName": "% Allergen Free",
+            "format": {
+              "type": "percentage",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "allergen_prevalence",
+      "displayName": "Allergen Prevalence",
+      "queryLines": [
+        "SELECT\n",
+        "  allergen_type,\n",
+        "  COUNT(*) as item_count\n",
+        "FROM\n",
+        "  menu_documents.allergens\n",
+        "    UNPIVOT (\n",
+        "      contains_allergen FOR allergen_type IN (\n",
+        "        contains_wheat AS Wheat,\n",
+        "        contains_milk AS Milk,\n",
+        "        contains_egg AS Egg,\n",
+        "        contains_soy AS Soy,\n",
+        "        contains_peanut AS Peanut,\n",
+        "        contains_tree_nut AS Tree_Nut,\n",
+        "        contains_fish AS Fish,\n",
+        "        contains_shellfish AS Shellfish,\n",
+        "        contains_sesame AS Sesame\n",
+        "      )\n",
+        "    )\n",
+        "WHERE\n",
+        "  contains_allergen = true\n",
+        "GROUP BY\n",
+        "  allergen_type\n",
+        "ORDER BY\n",
+        "  item_count DESC"
+      ]
+    }
+  ],
+  "pages": [
+    {
+      "name": "8d91abd2",
+      "displayName": "Page 1",
+      "layout": [
+        {
+          "widget": {
+            "name": "title",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Menu Intelligence & Nutrition Analytics"
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 1
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_total_items",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "measure(total_items)",
+                      "expression": "MEASURE(`total_items`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Menu Items",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_items)",
+                  "displayName": "Total Menu Items"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 1,
+            "width": 3,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_price",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "measure(avg_price)",
+                      "expression": "MEASURE(`avg_price`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Average Price",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_price)",
+                  "displayName": "Avg Price"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 1,
+            "width": 3,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_allergen_free",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "measure(pct_allergen_free)",
+                      "expression": "MEASURE(`pct_allergen_free`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "% Allergen Free",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(pct_allergen_free)",
+                  "displayName": "% Allergen Free"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 1,
+            "width": 3,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_calories",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "measure(avg_calories)",
+                      "expression": "MEASURE(`avg_calories`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Average Calories",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_calories)",
+                  "displayName": "Avg Calories"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 1,
+            "width": 3,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "avg_price_by_cuisine",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "cuisine",
+                      "expression": "`cuisine`"
+                    },
+                    {
+                      "name": "measure(avg_price)",
+                      "expression": "MEASURE(`avg_price`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Average Price by Cuisine"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "cuisine",
+                  "displayName": "Cuisine",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_price)",
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "none",
+                    "currencyCode": "USD",
+                    "decimalPlaces": {
+                      "type": "exact",
+                      "places": 2
+                    }
+                  },
+                  "displayName": "Avg Price",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 3,
+            "width": 6,
+            "height": 5
+          }
+        },
+        {
+          "widget": {
+            "name": "price_tier_pie",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "measure(total_items)",
+                      "expression": "MEASURE(`total_items`)"
+                    },
+                    {
+                      "name": "price_tier",
+                      "expression": "`price_tier`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Price Tier Distribution"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_items)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Items"
+                },
+                "color": {
+                  "fieldName": "price_tier",
+                  "displayName": "Price Tier",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 3,
+            "width": 6,
+            "height": 5
+          }
+        },
+        {
+          "widget": {
+            "name": "allergen_prevalence",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "allergen_prevalence",
+                  "fields": [
+                    {
+                      "name": "allergen_type",
+                      "expression": "`allergen_type`"
+                    },
+                    {
+                      "name": "item_count",
+                      "expression": "`item_count`"
+                    }
+                  ],
+                  "disaggregated": true
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Allergen Prevalence"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "allergen_type",
+                  "displayName": "Allergen",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "item_count",
+                  "displayName": "Items Containing",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 8,
+            "width": 6,
+            "height": 5
+          }
+        },
+        {
+          "widget": {
+            "name": "items_per_category",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "category",
+                      "expression": "`category`"
+                    },
+                    {
+                      "name": "measure(total_items)",
+                      "expression": "MEASURE(`total_items`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Items per Category"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_items)",
+                  "displayName": "Items",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 8,
+            "width": 6,
+            "height": 5
+          }
+        },
+        {
+          "widget": {
+            "name": "price_vs_calories",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "menu_items_metrics",
+                  "fields": [
+                    {
+                      "name": "cuisine",
+                      "expression": "`cuisine`"
+                    },
+                    {
+                      "name": "price",
+                      "expression": "`price`"
+                    },
+                    {
+                      "name": "calories",
+                      "expression": "`calories`"
+                    }
+                  ],
+                  "disaggregated": true
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Price vs Calories"
+              },
+              "widgetType": "scatter",
+              "encodings": {
+                "x": {
+                  "fieldName": "price",
+                  "displayName": "Price ($)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "y": {
+                  "fieldName": "calories",
+                  "displayName": "Calories",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "cuisine",
+                  "displayName": "Cuisine",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 13,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "healthy_options_table",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "healthy_options",
+                  "fields": [
+                    {
+                      "name": "item_name",
+                      "expression": "`item_name`"
+                    },
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "cuisine",
+                      "expression": "`cuisine`"
+                    },
+                    {
+                      "name": "calories",
+                      "expression": "`calories`"
+                    },
+                    {
+                      "name": "protein_g",
+                      "expression": "`protein_g`"
+                    },
+                    {
+                      "name": "price",
+                      "expression": "`price`"
+                    }
+                  ],
+                  "disaggregated": true
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Healthy Options"
+              },
+              "widgetType": "table",
+              "encodings": {
+                "columns": [
+                  {
+                    "fieldName": "item_name",
+                    "displayName": "Item"
+                  },
+                  {
+                    "fieldName": "brand_name",
+                    "displayName": "Brand"
+                  },
+                  {
+                    "fieldName": "cuisine",
+                    "displayName": "Cuisine"
+                  },
+                  {
+                    "fieldName": "calories",
+                    "displayName": "Calories"
+                  },
+                  {
+                    "fieldName": "protein_g",
+                    "displayName": "Protein (g)"
+                  },
+                  {
+                    "fieldName": "price",
+                    "format": {
+                      "type": "number-currency",
+                      "abbreviation": "none",
+                      "currencyCode": "USD",
+                      "decimalPlaces": {
+                        "type": "exact",
+                        "places": 2
+                      }
+                    },
+                    "displayName": "Price"
+                  }
+                ]
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 13,
+            "width": 6,
+            "height": 6
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    }
+  ],
+  "uiSettings": {
+    "theme": {
+      "widgetHeaderAlignment": "ALIGNMENT_UNSPECIFIED"
+    },
+    "applyModeEnabled": false
+  }
+}
+
diff --git a/resources/dashboards/caspers_kitchen_operations.lvdash.json b/resources/dashboards/caspers_kitchen_operations.lvdash.json
new file mode 100644
index 0000000..75b4fa0
--- /dev/null
+++ b/resources/dashboards/caspers_kitchen_operations.lvdash.json
@@ -0,0 +1,3123 @@
+{
+  "datasets": [
+    {
+      "name": "locations",
+      "displayName": "Locations Overview",
+      "config": {
+        "version": 1.1,
+        "source": "simulator.locations",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "name",
+            "displayName": "Location"
+          },
+          {
+            "name": "narrative",
+            "expr": "narrative",
+            "displayName": "Growth Status"
+          },
+          {
+            "name": "address",
+            "expr": "address",
+            "displayName": "Address"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_locations",
+            "expr": "COUNT(*)",
+            "displayName": "Total Locations"
+          },
+          {
+            "name": "avg_daily_orders",
+            "expr": "AVG(base_orders_day)",
+            "displayName": "Avg Daily Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "complaints",
+      "displayName": "Customer Complaints",
+      "config": {
+        "version": 1.1,
+        "source": "complaints.raw_complaints",
+        "dimensions": [
+          {
+            "name": "complaint_category",
+            "expr": "complaint_category",
+            "displayName": "Complaint Category"
+          },
+          {
+            "name": "complaint_date",
+            "expr": "DATE(ts)",
+            "displayName": "Complaint Date"
+          },
+          {
+            "name": "complaint_month",
+            "expr": "DATE_TRUNC('MONTH', ts)",
+            "displayName": "Complaint Month"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_complaints",
+            "expr": "COUNT(*)",
+            "displayName": "Total Complaints"
+          },
+          {
+            "name": "unique_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Unique Orders"
+          }
+        ]
+      }
+    },
+    {
+      "name": "inspections",
+      "displayName": "Food Safety Inspections",
+      "config": {
+        "version": 1.1,
+        "source": "food_safety.inspections",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "inspection_date",
+            "expr": "inspection_date",
+            "displayName": "Inspection Date"
+          },
+          {
+            "name": "grade",
+            "expr": "grade",
+            "displayName": "Grade"
+          },
+          {
+            "name": "inspector_name",
+            "expr": "inspector_name",
+            "displayName": "Inspector"
+          },
+          {
+            "name": "follow_up_status",
+            "expr": "follow_up_status",
+            "displayName": "Follow-up Status"
+          }
+        ],
+        "measures": [
+          {
+            "name": "avg_score",
+            "expr": "AVG(score)",
+            "displayName": "Avg Inspection Score",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          },
+          {
+            "name": "total_inspections",
+            "expr": "COUNT(*)",
+            "displayName": "Total Inspections"
+          },
+          {
+            "name": "total_violations",
+            "expr": "SUM(violation_count)",
+            "displayName": "Total Violations"
+          },
+          {
+            "name": "total_critical",
+            "expr": "SUM(critical_count)",
+            "displayName": "Critical Violations"
+          }
+        ]
+      }
+    },
+    {
+      "name": "violations",
+      "displayName": "Safety Violations",
+      "config": {
+        "version": 1.1,
+        "source": "food_safety.violations",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "severity",
+            "expr": "severity",
+            "displayName": "Severity"
+          },
+          {
+            "name": "category",
+            "expr": "category",
+            "displayName": "Category"
+          },
+          {
+            "name": "inspection_date",
+            "expr": "inspection_date",
+            "displayName": "Inspection Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "violation_count",
+            "expr": "COUNT(*)",
+            "displayName": "Violation Count"
+          },
+          {
+            "name": "avg_deadline_days",
+            "expr": "AVG(deadline_days)",
+            "displayName": "Avg Deadline Days",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "brands",
+      "displayName": "Restaurant Brands",
+      "config": {
+        "version": 1.1,
+        "source": "simulator.brands",
+        "dimensions": [
+          {
+            "name": "brand_name",
+            "expr": "name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_brands",
+            "expr": "COUNT(*)",
+            "displayName": "Total Brands"
+          },
+          {
+            "name": "avg_prep_time",
+            "expr": "AVG(avg_prep_time_min)",
+            "displayName": "Avg Prep Time (min)",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "order_revenue",
+      "displayName": "Order Revenue",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  oi.order_id,\n  oi.location_id,\n  oi.order_day,\n  oi.order_ts,\n  oi.brand_id,\n  b.name AS brand_name,\n  b.cuisine_type,\n  l.name AS location_name,\n  oi.item_name,\n  oi.price,\n  oi.qty,\n  oi.extended_price\nFROM lakeflow.silver_order_items oi JOIN simulator.brands b ON oi.brand_id = b.brand_id JOIN simulator.locations l ON CAST(oi.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "order_day",
+            "expr": "order_day",
+            "displayName": "Order Date"
+          },
+          {
+            "name": "order_month",
+            "expr": "DATE_TRUNC('MONTH', order_day)",
+            "displayName": "Order Month"
+          },
+          {
+            "name": "brand_name",
+            "expr": "brand_name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          },
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "item_name",
+            "expr": "item_name",
+            "displayName": "Item"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_revenue",
+            "expr": "SUM(extended_price)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Total Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_items_sold",
+            "expr": "SUM(qty)",
+            "displayName": "Items Sold",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_order_value",
+            "expr": "SUM(extended_price) / COUNT(DISTINCT order_id)",
+            "displayName": "Avg Order Value",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "resolutions",
+      "displayName": "Complaint Resolutions",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  complaint_id,\n  order_id,\n  ts,\n  DATE(ts) as resolution_date,\n  agent_response:complaint_category::STRING as complaint_category,\n  agent_response:decision::STRING as decision,\n  agent_response:credit_amount::DOUBLE as credit_amount,\n  agent_response:confidence::STRING as confidence,\n  agent_response:priority::STRING as priority\nFROM complaints.complaint_responses\n",
+        "dimensions": [
+          {
+            "name": "complaint_category",
+            "expr": "complaint_category",
+            "displayName": "Complaint Category"
+          },
+          {
+            "name": "decision",
+            "expr": "decision",
+            "displayName": "Decision"
+          },
+          {
+            "name": "confidence",
+            "expr": "confidence",
+            "displayName": "Confidence Level"
+          },
+          {
+            "name": "priority",
+            "expr": "priority",
+            "displayName": "Priority"
+          },
+          {
+            "name": "resolution_date",
+            "expr": "resolution_date",
+            "displayName": "Resolution Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_resolutions",
+            "expr": "COUNT(*)",
+            "displayName": "Total Resolutions"
+          },
+          {
+            "name": "total_credits_issued",
+            "expr": "SUM(credit_amount)",
+            "displayName": "Total Credits Issued",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_credit_amount",
+            "expr": "AVG(CASE WHEN credit_amount > 0 THEN credit_amount END)",
+            "displayName": "Avg Credit Amount",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          },
+          {
+            "name": "escalation_rate",
+            "expr": "COUNT(CASE WHEN decision = 'escalate' THEN 1 END) * 1.0 / COUNT(*)",
+            "displayName": "Escalation Rate"
+          }
+        ]
+      }
+    },
+    {
+      "name": "refunds",
+      "displayName": "Refund Recommendations",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  order_id,\n  ts as processed_ts,\n  order_ts,\n  DATE(order_ts) as order_date,\n  DATE_TRUNC('MONTH', order_ts) as order_month,\n  agent_response:refund_usd::DOUBLE as refund_usd,\n  agent_response:refund_class::STRING as refund_class,\n  agent_response:reason::STRING as reason,\n  SUBSTRING(order_id, -2) as location_code\nFROM recommender.refund_recommendations\n",
+        "dimensions": [
+          {
+            "name": "refund_class",
+            "expr": "refund_class",
+            "displayName": "Refund Class"
+          },
+          {
+            "name": "order_date",
+            "expr": "order_date",
+            "displayName": "Order Date"
+          },
+          {
+            "name": "order_month",
+            "expr": "order_month",
+            "displayName": "Order Month"
+          },
+          {
+            "name": "location_code",
+            "expr": "location_code",
+            "displayName": "Location Code"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_refund_requests",
+            "expr": "COUNT(*)",
+            "displayName": "Total Refund Requests"
+          },
+          {
+            "name": "total_refunded_usd",
+            "expr": "SUM(refund_usd)",
+            "displayName": "Total Refunded",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_refund_amount",
+            "expr": "AVG(CASE WHEN refund_usd > 0 THEN refund_usd END)",
+            "displayName": "Avg Refund Amount",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          },
+          {
+            "name": "refund_rate",
+            "expr": "COUNT(CASE WHEN refund_class IN ('partial', 'full') THEN 1 END) * 1.0 / COUNT(*)",
+            "displayName": "Refund Rate"
+          }
+        ]
+      }
+    },
+    {
+      "name": "brand_growth",
+      "displayName": "Brand Growth",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  bl.brand_location_id,\n  b.name AS brand_name,\n  b.cuisine_type,\n  l.name AS location_name,\n  bl.trajectory,\n  bl.growth_rate_monthly\nFROM simulator.brand_locations bl JOIN simulator.brands b ON bl.brand_id = b.brand_id JOIN simulator.locations l ON bl.location_id = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "brand_name",
+            "expr": "brand_name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          },
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "trajectory",
+            "expr": "trajectory",
+            "displayName": "Growth Trajectory"
+          }
+        ],
+        "measures": [
+          {
+            "name": "brand_location_count",
+            "expr": "COUNT(*)",
+            "displayName": "Brand-Location Count"
+          },
+          {
+            "name": "avg_growth_rate",
+            "expr": "AVG(growth_rate_monthly)",
+            "displayName": "Avg Monthly Growth Rate",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "hourly_demand",
+      "displayName": "Hourly Demand",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  h.location_id,\n  l.name AS location_name,\n  h.hour_ts,\n  DATE(h.hour_ts) as order_date,\n  HOUR(h.hour_ts) as hour_of_day,\n  h.orders,\n  h.revenue\nFROM lakeflow.gold_location_sales_hourly h JOIN simulator.locations l ON CAST(h.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "hour_of_day",
+            "expr": "hour_of_day",
+            "displayName": "Hour of Day"
+          },
+          {
+            "name": "order_date",
+            "expr": "order_date",
+            "displayName": "Order Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_orders",
+            "expr": "SUM(orders)",
+            "displayName": "Total Orders"
+          },
+          {
+            "name": "total_revenue",
+            "expr": "SUM(revenue)",
+            "displayName": "Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_orders_per_hour",
+            "expr": "AVG(orders)",
+            "displayName": "Avg Orders/Hour",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "location_map",
+      "displayName": "Location Revenue Map",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  oi.order_id,\n  l.name AS location_name,\n  l.lat,\n  l.lon,\n  oi.extended_price\nFROM lakeflow.silver_order_items oi JOIN simulator.locations l ON CAST(oi.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "latitude",
+            "expr": "lat",
+            "displayName": "Latitude"
+          },
+          {
+            "name": "longitude",
+            "expr": "lon",
+            "displayName": "Longitude"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_revenue",
+            "expr": "SUM(extended_price)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Total Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "refund_revenue_ratio",
+      "displayName": "Refund-to-Revenue Ratio",
+      "config": {
+        "version": 1.1,
+        "source": "WITH refund_total AS (\n  SELECT SUM(agent_response:refund_usd::DOUBLE) as refund_amt\n  FROM recommender.refund_recommendations\n), revenue_total AS (\n  SELECT SUM(extended_price) as revenue_amt\n  FROM lakeflow.silver_order_items\n) SELECT refund_amt, revenue_amt FROM refund_total CROSS JOIN revenue_total\n",
+        "dimensions": [
+          {
+            "name": "all_data",
+            "expr": "'all'"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_refunded",
+            "expr": "SUM(refund_amt)",
+            "displayName": "Total Refunded",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_revenue_base",
+            "expr": "SUM(revenue_amt)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "refund_to_revenue_ratio",
+            "expr": "MEASURE(total_refunded) / MEASURE(total_revenue_base)",
+            "displayName": "Refund-to-Revenue Ratio",
+            "format": {
+              "type": "percentage",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "pages": [
+    {
+      "name": "52169638",
+      "displayName": "Quality & Compliance",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Caspers Kitchen Operations\n",
+                "Multi-location food delivery operations monitoring across 8 locations and 24 restaurant brands."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_complaints",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Complaints",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Total Complaints"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_locations",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "locations",
+                  "fields": [
+                    {
+                      "name": "measure(total_locations)",
+                      "expression": "MEASURE(`total_locations`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Locations",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_locations)",
+                  "displayName": "Total Locations"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_brands",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brands",
+                  "fields": [
+                    {
+                      "name": "measure(total_brands)",
+                      "expression": "MEASURE(`total_brands`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Brands",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_brands)",
+                  "displayName": "Total Brands"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_score",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "measure(avg_score)",
+                      "expression": "MEASURE(`avg_score`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Avg Inspection Score",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_score)",
+                  "displayName": "Avg Inspection Score"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "complaints_by_category",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Complaints by Category"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "inspection_scores",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(avg_score)",
+                      "expression": "MEASURE(`avg_score`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Inspection Scores by Location"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_score)",
+                  "displayName": "Avg Score",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 5,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "violations_severity",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "violations",
+                  "fields": [
+                    {
+                      "name": "measure(violation_count)",
+                      "expression": "MEASURE(`violation_count`)"
+                    },
+                    {
+                      "name": "severity",
+                      "expression": "`severity`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Violations by Severity"
+              },
+              "mark": {
+                "colors": [
+                  "#E74C3C",
+                  "#F39C12",
+                  "#3498DB"
+                ]
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(violation_count)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "severity",
+                  "displayName": "Severity",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 12,
+            "width": 4,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "complaint_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "complaint_month",
+                      "expression": "`complaint_month`"
+                    },
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Complaint Trend"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Complaints",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 12,
+            "width": 8,
+            "height": 7
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "revenue_performance",
+      "displayName": "Revenue & Performance",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Revenue & Restaurant Performance\n",
+                "Order data from Mar 2026 to Apr 2027 across all locations and brands."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_revenue",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Revenue"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Total Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Orders"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Total Orders"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_aov",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(avg_order_value)",
+                      "expression": "MEASURE(`avg_order_value`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Order Value"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_order_value)",
+                  "displayName": "Avg Order Value"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_items",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_items_sold)",
+                      "expression": "MEASURE(`total_items_sold`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Items Sold"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_items_sold)",
+                  "displayName": "Items Sold"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "order_month",
+                      "expression": "`order_month`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue Trend"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "order_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 12,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_brand",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Brand"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Location"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "orders_by_cuisine",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    },
+                    {
+                      "name": "cuisine_type",
+                      "expression": "`cuisine_type`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Orders by Cuisine Type"
+              },
+              "mark": {},
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_orders)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Orders"
+                },
+                "color": {
+                  "fieldName": "cuisine_type",
+                  "displayName": "Cuisine",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 5,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_location_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "order_month",
+                      "expression": "`order_month`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Location Over Time"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "order_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 5,
+            "y": 18,
+            "width": 7,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "top_items_table",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "item_name",
+                      "expression": "`item_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    },
+                    {
+                      "name": "measure(total_items_sold)",
+                      "expression": "MEASURE(`total_items_sold`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Top-Selling Items",
+                "showTitle": true
+              },
+              "widgetType": "table",
+              "encodings": {
+                "columns": [
+                  {
+                    "fieldName": "item_name",
+                    "displayName": "Item"
+                  },
+                  {
+                    "fieldName": "measure(total_revenue)",
+                    "format": {
+                      "type": "number-currency",
+                      "abbreviation": "compact",
+                      "currencyCode": "USD"
+                    },
+                    "displayName": "Revenue"
+                  },
+                  {
+                    "fieldName": "measure(total_items_sold)",
+                    "format": {
+                      "type": "number-plain",
+                      "abbreviation": "compact"
+                    },
+                    "displayName": "Qty Sold"
+                  }
+                ]
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 25,
+            "width": 6,
+            "height": 8
+          }
+        },
+        {
+          "widget": {
+            "name": "location_map",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "location_map",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "latitude",
+                      "expression": "`latitude`"
+                    },
+                    {
+                      "name": "longitude",
+                      "expression": "`longitude`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Revenue by Location (Map)",
+                "showTitle": true
+              },
+              "widgetType": "symbol-map",
+              "encodings": {
+                "coordinates": {
+                  "coordinateType": "longitude-latitude",
+                  "latitude": {
+                    "fieldName": "latitude"
+                  },
+                  "longitude": {
+                    "fieldName": "longitude"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "size": {
+                  "fieldName": "measure(total_revenue)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "compact",
+                    "currencyCode": "USD"
+                  },
+                  "displayName": "Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 25,
+            "width": 6,
+            "height": 8
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "refunds_resolution",
+      "displayName": "Refunds & Resolution",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Refunds & Complaint Resolution\n",
+                "AI-driven refund recommendations and complaint resolution outcomes. Tracks financial impact of operational issues."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_total_refunded",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(total_refunded_usd)",
+                      "expression": "MEASURE(`total_refunded_usd`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Refunded"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_refunded_usd)",
+                  "displayName": "Total Refunded"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_refund_requests",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(total_refund_requests)",
+                      "expression": "MEASURE(`total_refund_requests`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Refund Requests"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_refund_requests)",
+                  "displayName": "Refund Requests"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_refund",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(avg_refund_amount)",
+                      "expression": "MEASURE(`avg_refund_amount`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Refund Amount"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_refund_amount)",
+                  "displayName": "Avg Refund"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_escalation_rate",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(escalation_rate)",
+                      "expression": "MEASURE(`escalation_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Escalation Rate"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(escalation_rate)",
+                  "displayName": "Escalation Rate"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "refunds_by_class",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "refund_class",
+                      "expression": "`refund_class`"
+                    },
+                    {
+                      "name": "measure(total_refund_requests)",
+                      "expression": "MEASURE(`total_refund_requests`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Refunds by Class"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "refund_class",
+                  "displayName": "Refund Class",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_refund_requests)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "resolution_decisions",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    },
+                    {
+                      "name": "decision",
+                      "expression": "`decision`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Resolution Decisions"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_resolutions)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "decision",
+                  "displayName": "Decision",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 5,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "credits_by_category",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_credits_issued)",
+                      "expression": "MEASURE(`total_credits_issued`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Credits by Complaint Category"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_credits_issued)",
+                  "displayName": "Credits ($)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "confidence_breakdown",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    },
+                    {
+                      "name": "confidence",
+                      "expression": "`confidence`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "AI Confidence Level"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_resolutions)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "confidence",
+                  "displayName": "Confidence",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "refund_amount_by_class",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "refund_class",
+                      "expression": "`refund_class`"
+                    },
+                    {
+                      "name": "measure(total_refunded_usd)",
+                      "expression": "MEASURE(`total_refunded_usd`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Refund $ by Class"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "refund_class",
+                  "displayName": "Refund Class",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_refunded_usd)",
+                  "displayName": "$ Refunded",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "category_escalations",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "decision",
+                      "expression": "`decision`"
+                    },
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Escalations by Category"
+              },
+              "mark": {
+                "layout": "stack"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_resolutions)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "decision",
+                  "displayName": "Decision",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 18,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_refund_ratio",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refund_revenue_ratio",
+                  "fields": [
+                    {
+                      "name": "measure(refund_to_revenue_ratio)",
+                      "expression": "MEASURE(`refund_to_revenue_ratio`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Refund-to-Revenue Ratio",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(refund_to_revenue_ratio)",
+                  "displayName": "Refund/Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 24,
+            "width": 4,
+            "height": 3
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "demand_growth",
+      "displayName": "Demand & Growth",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Demand Patterns & Brand Growth\n",
+                "Hourly order patterns for capacity planning and brand-location growth trajectories."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_peak_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Orders (Hourly Data)"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Total Orders"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_hourly_revenue",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Revenue (Hourly)"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_growing_brands",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    }
+                  ],
+                  "filters": [
+                    {
+                      "expression": "`trajectory` = 'growing'"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Growing Brand-Locations"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(brand_location_count)",
+                  "displayName": "Growing"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_growth",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(avg_growth_rate)",
+                      "expression": "MEASURE(`avg_growth_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Monthly Growth"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_growth_rate)",
+                  "displayName": "Avg Growth Rate"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "hourly_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Orders by Hour of Day"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour of Day",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Orders",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 12,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "hourly_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Hourly Demand by Location"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Orders",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 7,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_hour_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Hour"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 7,
+            "y": 11,
+            "width": 5,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "growth_trajectory",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    },
+                    {
+                      "name": "trajectory",
+                      "expression": "`trajectory`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "mark": {
+                "colors": [
+                  "#27AE60",
+                  "#F39C12",
+                  "#E74C3C"
+                ]
+              },
+              "frame": {
+                "showTitle": true,
+                "title": "Brand Growth Trajectories"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(brand_location_count)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "trajectory",
+                  "displayName": "Trajectory",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 4,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "brand_growth_rates",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(avg_growth_rate)",
+                      "expression": "MEASURE(`avg_growth_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Growth Rate by Brand"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_growth_rate)",
+                  "displayName": "Avg Growth Rate",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 18,
+            "width": 8,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "growth_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "trajectory",
+                      "expression": "`trajectory`"
+                    },
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "frame": {
+                "showTitle": true,
+                "title": "Growth by Location"
+              },
+              "version": 3,
+              "mark": {
+                "layout": "stack"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(brand_location_count)",
+                  "displayName": "Brands",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "trajectory",
+                  "displayName": "Trajectory",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 25,
+            "width": 12,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "prep_time_chart",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brands",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(avg_prep_time)",
+                      "expression": "MEASURE(`avg_prep_time`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Avg Prep Time by Brand",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_prep_time)",
+                  "displayName": "Avg Prep Time (min)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 32,
+            "width": 12,
+            "height": 6
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "global_filters",
+      "displayName": "Global Filters",
+      "layout": [
+        {
+          "widget": {
+            "name": "location_filter",
+            "queries": [
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360526a1eccacd5cfc7259251fd_location_name",
+                "query": {
+                  "datasetName": "locations",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153622f8b18738e45a3eebce6a56d_location_name",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f1536056bc1df583823e9954e1ed08_location_name",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360587b1b9e985f894a3baae886_location_name",
+                "query": {
+                  "datasetName": "violations",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646476146aa0cb4e1e717f6c98_location_name",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646299154195e403455b344102_location_name",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15365fe0714858af9fb564993e59a_location_name",
+                "query": {
+                  "datasetName": "location_map",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Location",
+                "showTitle": true
+              },
+              "widgetType": "filter-multi-select",
+              "encodings": {
+                "fields": [
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360526a1eccacd5cfc7259251fd_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153622f8b18738e45a3eebce6a56d_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f1536056bc1df583823e9954e1ed08_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360587b1b9e985f894a3baae886_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646476146aa0cb4e1e717f6c98_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646299154195e403455b344102_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15365fe0714858af9fb564993e59a_location_name"
+                  }
+                ]
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 3,
+            "height": 2
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_GLOBAL_FILTERS",
+      "layoutVersion": "GRID_V1"
+    }
+  ],
+  "uiSettings": {
+    "theme": {
+      "canvasBackgroundColor": {
+        "light": "#F8F9FA",
+        "dark": "#0D1117"
+      },
+      "widgetBackgroundColor": {
+        "light": "#FFFFFF",
+        "dark": "#161B22"
+      },
+      "widgetBorderColor": {
+        "light": "#E1E4E8",
+        "dark": "#30363D"
+      },
+      "fontColor": {
+        "light": "#1F2328",
+        "dark": "#E6EDF3"
+      },
+      "selectionColor": {
+        "light": "#0969DA",
+        "dark": "#58A6FF"
+      },
+      "visualizationColors": [
+        "#58A6FF",
+        "#3FB950",
+        "#F78166",
+        "#D2A8FF",
+        "#79C0FF",
+        "#56D364",
+        "#FFA657",
+        "#FF7B72",
+        "#A5D6FF",
+        "#7EE787"
+      ],
+      "widgetHeaderAlignment": "CENTER",
+      "fontFamily": "Trebuchet MS"
+    },
+    "applyModeEnabled": false
+  }
+}
diff --git a/resources/dashboards/caspers_kitchen_operations_dark.lvdash.json b/resources/dashboards/caspers_kitchen_operations_dark.lvdash.json
new file mode 100644
index 0000000..8a736c6
--- /dev/null
+++ b/resources/dashboards/caspers_kitchen_operations_dark.lvdash.json
@@ -0,0 +1,3123 @@
+{
+  "datasets": [
+    {
+      "name": "locations",
+      "displayName": "Locations Overview",
+      "config": {
+        "version": 1.1,
+        "source": "simulator.locations",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "name",
+            "displayName": "Location"
+          },
+          {
+            "name": "narrative",
+            "expr": "narrative",
+            "displayName": "Growth Status"
+          },
+          {
+            "name": "address",
+            "expr": "address",
+            "displayName": "Address"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_locations",
+            "expr": "COUNT(*)",
+            "displayName": "Total Locations"
+          },
+          {
+            "name": "avg_daily_orders",
+            "expr": "AVG(base_orders_day)",
+            "displayName": "Avg Daily Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "complaints",
+      "displayName": "Customer Complaints",
+      "config": {
+        "version": 1.1,
+        "source": "complaints.raw_complaints",
+        "dimensions": [
+          {
+            "name": "complaint_category",
+            "expr": "complaint_category",
+            "displayName": "Complaint Category"
+          },
+          {
+            "name": "complaint_date",
+            "expr": "DATE(ts)",
+            "displayName": "Complaint Date"
+          },
+          {
+            "name": "complaint_month",
+            "expr": "DATE_TRUNC('MONTH', ts)",
+            "displayName": "Complaint Month"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_complaints",
+            "expr": "COUNT(*)",
+            "displayName": "Total Complaints"
+          },
+          {
+            "name": "unique_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Unique Orders"
+          }
+        ]
+      }
+    },
+    {
+      "name": "inspections",
+      "displayName": "Food Safety Inspections",
+      "config": {
+        "version": 1.1,
+        "source": "food_safety.inspections",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "inspection_date",
+            "expr": "inspection_date",
+            "displayName": "Inspection Date"
+          },
+          {
+            "name": "grade",
+            "expr": "grade",
+            "displayName": "Grade"
+          },
+          {
+            "name": "inspector_name",
+            "expr": "inspector_name",
+            "displayName": "Inspector"
+          },
+          {
+            "name": "follow_up_status",
+            "expr": "follow_up_status",
+            "displayName": "Follow-up Status"
+          }
+        ],
+        "measures": [
+          {
+            "name": "avg_score",
+            "expr": "AVG(score)",
+            "displayName": "Avg Inspection Score",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          },
+          {
+            "name": "total_inspections",
+            "expr": "COUNT(*)",
+            "displayName": "Total Inspections"
+          },
+          {
+            "name": "total_violations",
+            "expr": "SUM(violation_count)",
+            "displayName": "Total Violations"
+          },
+          {
+            "name": "total_critical",
+            "expr": "SUM(critical_count)",
+            "displayName": "Critical Violations"
+          }
+        ]
+      }
+    },
+    {
+      "name": "violations",
+      "displayName": "Safety Violations",
+      "config": {
+        "version": 1.1,
+        "source": "food_safety.violations",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "severity",
+            "expr": "severity",
+            "displayName": "Severity"
+          },
+          {
+            "name": "category",
+            "expr": "category",
+            "displayName": "Category"
+          },
+          {
+            "name": "inspection_date",
+            "expr": "inspection_date",
+            "displayName": "Inspection Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "violation_count",
+            "expr": "COUNT(*)",
+            "displayName": "Violation Count"
+          },
+          {
+            "name": "avg_deadline_days",
+            "expr": "AVG(deadline_days)",
+            "displayName": "Avg Deadline Days",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "brands",
+      "displayName": "Restaurant Brands",
+      "config": {
+        "version": 1.1,
+        "source": "simulator.brands",
+        "dimensions": [
+          {
+            "name": "brand_name",
+            "expr": "name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_brands",
+            "expr": "COUNT(*)",
+            "displayName": "Total Brands"
+          },
+          {
+            "name": "avg_prep_time",
+            "expr": "AVG(avg_prep_time_min)",
+            "displayName": "Avg Prep Time (min)",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "order_revenue",
+      "displayName": "Order Revenue",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  oi.order_id,\n  oi.location_id,\n  oi.order_day,\n  oi.order_ts,\n  oi.brand_id,\n  b.name AS brand_name,\n  b.cuisine_type,\n  l.name AS location_name,\n  oi.item_name,\n  oi.price,\n  oi.qty,\n  oi.extended_price\nFROM lakeflow.silver_order_items oi JOIN simulator.brands b ON oi.brand_id = b.brand_id JOIN simulator.locations l ON CAST(oi.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "order_day",
+            "expr": "order_day",
+            "displayName": "Order Date"
+          },
+          {
+            "name": "order_month",
+            "expr": "DATE_TRUNC('MONTH', order_day)",
+            "displayName": "Order Month"
+          },
+          {
+            "name": "brand_name",
+            "expr": "brand_name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          },
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "item_name",
+            "expr": "item_name",
+            "displayName": "Item"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_revenue",
+            "expr": "SUM(extended_price)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Total Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_items_sold",
+            "expr": "SUM(qty)",
+            "displayName": "Items Sold",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_order_value",
+            "expr": "SUM(extended_price) / COUNT(DISTINCT order_id)",
+            "displayName": "Avg Order Value",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "resolutions",
+      "displayName": "Complaint Resolutions",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  complaint_id,\n  order_id,\n  ts,\n  DATE(ts) as resolution_date,\n  agent_response:complaint_category::STRING as complaint_category,\n  agent_response:decision::STRING as decision,\n  agent_response:credit_amount::DOUBLE as credit_amount,\n  agent_response:confidence::STRING as confidence,\n  agent_response:priority::STRING as priority\nFROM complaints.complaint_responses\n",
+        "dimensions": [
+          {
+            "name": "complaint_category",
+            "expr": "complaint_category",
+            "displayName": "Complaint Category"
+          },
+          {
+            "name": "decision",
+            "expr": "decision",
+            "displayName": "Decision"
+          },
+          {
+            "name": "confidence",
+            "expr": "confidence",
+            "displayName": "Confidence Level"
+          },
+          {
+            "name": "priority",
+            "expr": "priority",
+            "displayName": "Priority"
+          },
+          {
+            "name": "resolution_date",
+            "expr": "resolution_date",
+            "displayName": "Resolution Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_resolutions",
+            "expr": "COUNT(*)",
+            "displayName": "Total Resolutions"
+          },
+          {
+            "name": "total_credits_issued",
+            "expr": "SUM(credit_amount)",
+            "displayName": "Total Credits Issued",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_credit_amount",
+            "expr": "AVG(CASE WHEN credit_amount > 0 THEN credit_amount END)",
+            "displayName": "Avg Credit Amount",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          },
+          {
+            "name": "escalation_rate",
+            "expr": "COUNT(CASE WHEN decision = 'escalate' THEN 1 END) * 1.0 / COUNT(*)",
+            "displayName": "Escalation Rate"
+          }
+        ]
+      }
+    },
+    {
+      "name": "refunds",
+      "displayName": "Refund Recommendations",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  order_id,\n  ts as processed_ts,\n  order_ts,\n  DATE(order_ts) as order_date,\n  DATE_TRUNC('MONTH', order_ts) as order_month,\n  agent_response:refund_usd::DOUBLE as refund_usd,\n  agent_response:refund_class::STRING as refund_class,\n  agent_response:reason::STRING as reason,\n  SUBSTRING(order_id, -2) as location_code\nFROM recommender.refund_recommendations\n",
+        "dimensions": [
+          {
+            "name": "refund_class",
+            "expr": "refund_class",
+            "displayName": "Refund Class"
+          },
+          {
+            "name": "order_date",
+            "expr": "order_date",
+            "displayName": "Order Date"
+          },
+          {
+            "name": "order_month",
+            "expr": "order_month",
+            "displayName": "Order Month"
+          },
+          {
+            "name": "location_code",
+            "expr": "location_code",
+            "displayName": "Location Code"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_refund_requests",
+            "expr": "COUNT(*)",
+            "displayName": "Total Refund Requests"
+          },
+          {
+            "name": "total_refunded_usd",
+            "expr": "SUM(refund_usd)",
+            "displayName": "Total Refunded",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_refund_amount",
+            "expr": "AVG(CASE WHEN refund_usd > 0 THEN refund_usd END)",
+            "displayName": "Avg Refund Amount",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          },
+          {
+            "name": "refund_rate",
+            "expr": "COUNT(CASE WHEN refund_class IN ('partial', 'full') THEN 1 END) * 1.0 / COUNT(*)",
+            "displayName": "Refund Rate"
+          }
+        ]
+      }
+    },
+    {
+      "name": "brand_growth",
+      "displayName": "Brand Growth",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  bl.brand_location_id,\n  b.name AS brand_name,\n  b.cuisine_type,\n  l.name AS location_name,\n  bl.trajectory,\n  bl.growth_rate_monthly\nFROM simulator.brand_locations bl JOIN simulator.brands b ON bl.brand_id = b.brand_id JOIN simulator.locations l ON bl.location_id = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "brand_name",
+            "expr": "brand_name",
+            "displayName": "Brand"
+          },
+          {
+            "name": "cuisine_type",
+            "expr": "cuisine_type",
+            "displayName": "Cuisine Type"
+          },
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "trajectory",
+            "expr": "trajectory",
+            "displayName": "Growth Trajectory"
+          }
+        ],
+        "measures": [
+          {
+            "name": "brand_location_count",
+            "expr": "COUNT(*)",
+            "displayName": "Brand-Location Count"
+          },
+          {
+            "name": "avg_growth_rate",
+            "expr": "AVG(growth_rate_monthly)",
+            "displayName": "Avg Monthly Growth Rate",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 2.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "hourly_demand",
+      "displayName": "Hourly Demand",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  h.location_id,\n  l.name AS location_name,\n  h.hour_ts,\n  DATE(h.hour_ts) as order_date,\n  HOUR(h.hour_ts) as hour_of_day,\n  h.orders,\n  h.revenue\nFROM lakeflow.gold_location_sales_hourly h JOIN simulator.locations l ON CAST(h.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "hour_of_day",
+            "expr": "hour_of_day",
+            "displayName": "Hour of Day"
+          },
+          {
+            "name": "order_date",
+            "expr": "order_date",
+            "displayName": "Order Date"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_orders",
+            "expr": "SUM(orders)",
+            "displayName": "Total Orders"
+          },
+          {
+            "name": "total_revenue",
+            "expr": "SUM(revenue)",
+            "displayName": "Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "avg_orders_per_hour",
+            "expr": "AVG(orders)",
+            "displayName": "Avg Orders/Hour",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "location_map",
+      "displayName": "Location Revenue Map",
+      "config": {
+        "version": 1.1,
+        "source": "SELECT\n  oi.order_id,\n  l.name AS location_name,\n  l.lat,\n  l.lon,\n  oi.extended_price\nFROM lakeflow.silver_order_items oi JOIN simulator.locations l ON CAST(oi.location_id AS BIGINT) = l.location_id\n",
+        "dimensions": [
+          {
+            "name": "location_name",
+            "expr": "location_name",
+            "displayName": "Location"
+          },
+          {
+            "name": "latitude",
+            "expr": "lat",
+            "displayName": "Latitude"
+          },
+          {
+            "name": "longitude",
+            "expr": "lon",
+            "displayName": "Longitude"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_revenue",
+            "expr": "SUM(extended_price)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_orders",
+            "expr": "COUNT(DISTINCT order_id)",
+            "displayName": "Total Orders",
+            "format": {
+              "type": "number",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "refund_revenue_ratio",
+      "displayName": "Refund-to-Revenue Ratio",
+      "config": {
+        "version": 1.1,
+        "source": "WITH refund_total AS (\n  SELECT SUM(agent_response:refund_usd::DOUBLE) as refund_amt\n  FROM recommender.refund_recommendations\n), revenue_total AS (\n  SELECT SUM(extended_price) as revenue_amt\n  FROM lakeflow.silver_order_items\n) SELECT refund_amt, revenue_amt FROM refund_total CROSS JOIN revenue_total\n",
+        "dimensions": [
+          {
+            "name": "all_data",
+            "expr": "'all'"
+          }
+        ],
+        "measures": [
+          {
+            "name": "total_refunded",
+            "expr": "SUM(refund_amt)",
+            "displayName": "Total Refunded",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "total_revenue_base",
+            "expr": "SUM(revenue_amt)",
+            "displayName": "Total Revenue",
+            "format": {
+              "type": "currency",
+              "currencyCode": "USD",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 0.0
+              }
+            }
+          },
+          {
+            "name": "refund_to_revenue_ratio",
+            "expr": "MEASURE(total_refunded) / MEASURE(total_revenue_base)",
+            "displayName": "Refund-to-Revenue Ratio",
+            "format": {
+              "type": "percentage",
+              "decimalPlaces": {
+                "type": "exact",
+                "places": 1.0
+              }
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "pages": [
+    {
+      "name": "52169638",
+      "displayName": "Quality & Compliance",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Caspers Kitchen Operations\n",
+                "Multi-location food delivery operations monitoring across 8 locations and 24 restaurant brands."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_complaints",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Complaints",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Total Complaints"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_locations",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "locations",
+                  "fields": [
+                    {
+                      "name": "measure(total_locations)",
+                      "expression": "MEASURE(`total_locations`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Locations",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_locations)",
+                  "displayName": "Total Locations"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_brands",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brands",
+                  "fields": [
+                    {
+                      "name": "measure(total_brands)",
+                      "expression": "MEASURE(`total_brands`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Total Brands",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_brands)",
+                  "displayName": "Total Brands"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_score",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "measure(avg_score)",
+                      "expression": "MEASURE(`avg_score`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Avg Inspection Score",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_score)",
+                  "displayName": "Avg Inspection Score"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "complaints_by_category",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Complaints by Category"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "inspection_scores",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(avg_score)",
+                      "expression": "MEASURE(`avg_score`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Inspection Scores by Location"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_score)",
+                  "displayName": "Avg Score",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 5,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "violations_severity",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "violations",
+                  "fields": [
+                    {
+                      "name": "measure(violation_count)",
+                      "expression": "MEASURE(`violation_count`)"
+                    },
+                    {
+                      "name": "severity",
+                      "expression": "`severity`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Violations by Severity"
+              },
+              "mark": {
+                "colors": [
+                  "#E74C3C",
+                  "#F39C12",
+                  "#3498DB"
+                ]
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(violation_count)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "severity",
+                  "displayName": "Severity",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 12,
+            "width": 4,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "complaint_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "complaints",
+                  "fields": [
+                    {
+                      "name": "complaint_month",
+                      "expression": "`complaint_month`"
+                    },
+                    {
+                      "name": "measure(total_complaints)",
+                      "expression": "MEASURE(`total_complaints`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Complaint Trend"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_complaints)",
+                  "displayName": "Complaints",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 12,
+            "width": 8,
+            "height": 7
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "revenue_performance",
+      "displayName": "Revenue & Performance",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Revenue & Restaurant Performance\n",
+                "Order data from Mar 2026 to Apr 2027 across all locations and brands."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_revenue",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Revenue"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Total Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Orders"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Total Orders"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_aov",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(avg_order_value)",
+                      "expression": "MEASURE(`avg_order_value`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Order Value"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_order_value)",
+                  "displayName": "Avg Order Value"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_items",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_items_sold)",
+                      "expression": "MEASURE(`total_items_sold`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Items Sold"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_items_sold)",
+                  "displayName": "Items Sold"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "order_month",
+                      "expression": "`order_month`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue Trend"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "order_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 12,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_brand",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Brand"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Location"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "orders_by_cuisine",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    },
+                    {
+                      "name": "cuisine_type",
+                      "expression": "`cuisine_type`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Orders by Cuisine Type"
+              },
+              "mark": {},
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_orders)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Orders"
+                },
+                "color": {
+                  "fieldName": "cuisine_type",
+                  "displayName": "Cuisine",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 5,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_location_trend",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "order_month",
+                      "expression": "`order_month`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Location Over Time"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "order_month",
+                  "displayName": "Month",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 5,
+            "y": 18,
+            "width": 7,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "top_items_table",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "item_name",
+                      "expression": "`item_name`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    },
+                    {
+                      "name": "measure(total_items_sold)",
+                      "expression": "MEASURE(`total_items_sold`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Top-Selling Items",
+                "showTitle": true
+              },
+              "widgetType": "table",
+              "encodings": {
+                "columns": [
+                  {
+                    "fieldName": "item_name",
+                    "displayName": "Item"
+                  },
+                  {
+                    "fieldName": "measure(total_revenue)",
+                    "format": {
+                      "type": "number-currency",
+                      "abbreviation": "compact",
+                      "currencyCode": "USD"
+                    },
+                    "displayName": "Revenue"
+                  },
+                  {
+                    "fieldName": "measure(total_items_sold)",
+                    "format": {
+                      "type": "number-plain",
+                      "abbreviation": "compact"
+                    },
+                    "displayName": "Qty Sold"
+                  }
+                ]
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 25,
+            "width": 6,
+            "height": 8
+          }
+        },
+        {
+          "widget": {
+            "name": "location_map",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "location_map",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "latitude",
+                      "expression": "`latitude`"
+                    },
+                    {
+                      "name": "longitude",
+                      "expression": "`longitude`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Revenue by Location (Map)",
+                "showTitle": true
+              },
+              "widgetType": "symbol-map",
+              "encodings": {
+                "coordinates": {
+                  "coordinateType": "longitude-latitude",
+                  "latitude": {
+                    "fieldName": "latitude"
+                  },
+                  "longitude": {
+                    "fieldName": "longitude"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "size": {
+                  "fieldName": "measure(total_revenue)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "format": {
+                    "type": "number-currency",
+                    "abbreviation": "compact",
+                    "currencyCode": "USD"
+                  },
+                  "displayName": "Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 25,
+            "width": 6,
+            "height": 8
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "refunds_resolution",
+      "displayName": "Refunds & Resolution",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Refunds & Complaint Resolution\n",
+                "AI-driven refund recommendations and complaint resolution outcomes. Tracks financial impact of operational issues."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_total_refunded",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(total_refunded_usd)",
+                      "expression": "MEASURE(`total_refunded_usd`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Refunded"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_refunded_usd)",
+                  "displayName": "Total Refunded"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_refund_requests",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(total_refund_requests)",
+                      "expression": "MEASURE(`total_refund_requests`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Refund Requests"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_refund_requests)",
+                  "displayName": "Refund Requests"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_refund",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "measure(avg_refund_amount)",
+                      "expression": "MEASURE(`avg_refund_amount`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Refund Amount"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_refund_amount)",
+                  "displayName": "Avg Refund"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_escalation_rate",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(escalation_rate)",
+                      "expression": "MEASURE(`escalation_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Escalation Rate"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(escalation_rate)",
+                  "displayName": "Escalation Rate"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "refunds_by_class",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "refund_class",
+                      "expression": "`refund_class`"
+                    },
+                    {
+                      "name": "measure(total_refund_requests)",
+                      "expression": "MEASURE(`total_refund_requests`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Refunds by Class"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "refund_class",
+                  "displayName": "Refund Class",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_refund_requests)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "resolution_decisions",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    },
+                    {
+                      "name": "decision",
+                      "expression": "`decision`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Resolution Decisions"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_resolutions)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "decision",
+                  "displayName": "Decision",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 5,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "credits_by_category",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_credits_issued)",
+                      "expression": "MEASURE(`total_credits_issued`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Credits by Complaint Category"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_credits_issued)",
+                  "displayName": "Credits ($)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "confidence_breakdown",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    },
+                    {
+                      "name": "confidence",
+                      "expression": "`confidence`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "AI Confidence Level"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(total_resolutions)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "confidence",
+                  "displayName": "Confidence",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 11,
+            "width": 6,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "refund_amount_by_class",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refunds",
+                  "fields": [
+                    {
+                      "name": "refund_class",
+                      "expression": "`refund_class`"
+                    },
+                    {
+                      "name": "measure(total_refunded_usd)",
+                      "expression": "MEASURE(`total_refunded_usd`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Refund $ by Class"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "refund_class",
+                  "displayName": "Refund Class",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_refunded_usd)",
+                  "displayName": "$ Refunded",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "category_escalations",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "resolutions",
+                  "fields": [
+                    {
+                      "name": "decision",
+                      "expression": "`decision`"
+                    },
+                    {
+                      "name": "complaint_category",
+                      "expression": "`complaint_category`"
+                    },
+                    {
+                      "name": "measure(total_resolutions)",
+                      "expression": "MEASURE(`total_resolutions`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Escalations by Category"
+              },
+              "mark": {
+                "layout": "stack"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "complaint_category",
+                  "displayName": "Category",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_resolutions)",
+                  "displayName": "Count",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "decision",
+                  "displayName": "Decision",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 18,
+            "width": 6,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_refund_ratio",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "refund_revenue_ratio",
+                  "fields": [
+                    {
+                      "name": "measure(refund_to_revenue_ratio)",
+                      "expression": "MEASURE(`refund_to_revenue_ratio`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Refund-to-Revenue Ratio",
+                "showTitle": true
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(refund_to_revenue_ratio)",
+                  "displayName": "Refund/Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 24,
+            "width": 4,
+            "height": 3
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "demand_growth",
+      "displayName": "Demand & Growth",
+      "layout": [
+        {
+          "widget": {
+            "name": "header",
+            "multilineTextboxSpec": {
+              "lines": [
+                "## Demand Patterns & Brand Growth\n",
+                "Hourly order patterns for capacity planning and brand-location growth trajectories."
+              ]
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 2
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_peak_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Orders (Hourly Data)"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Total Orders"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_hourly_revenue",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Total Revenue (Hourly)"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 3,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_growing_brands",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    }
+                  ],
+                  "filters": [
+                    {
+                      "expression": "`trajectory` = 'growing'"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Growing Brand-Locations"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(brand_location_count)",
+                  "displayName": "Growing"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 6,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "kpi_avg_growth",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(avg_growth_rate)",
+                      "expression": "MEASURE(`avg_growth_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "showTitle": true,
+                "title": "Avg Monthly Growth"
+              },
+              "widgetType": "counter",
+              "encodings": {
+                "value": {
+                  "fieldName": "measure(avg_growth_rate)",
+                  "displayName": "Avg Growth Rate"
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 9,
+            "y": 2,
+            "width": 3,
+            "height": 3
+          }
+        },
+        {
+          "widget": {
+            "name": "hourly_orders",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Orders by Hour of Day"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour of Day",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Orders",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 5,
+            "width": 12,
+            "height": 6
+          }
+        },
+        {
+          "widget": {
+            "name": "hourly_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_orders)",
+                      "expression": "MEASURE(`total_orders`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Hourly Demand by Location"
+              },
+              "widgetType": "line",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_orders)",
+                  "displayName": "Orders",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 11,
+            "width": 7,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "revenue_by_hour_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "hour_of_day",
+                      "expression": "`hour_of_day`"
+                    },
+                    {
+                      "name": "measure(total_revenue)",
+                      "expression": "MEASURE(`total_revenue`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Revenue by Hour"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "hour_of_day",
+                  "displayName": "Hour",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "natural-order"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(total_revenue)",
+                  "displayName": "Revenue",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 7,
+            "y": 11,
+            "width": 5,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "growth_trajectory",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    },
+                    {
+                      "name": "trajectory",
+                      "expression": "`trajectory`"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "mark": {
+                "colors": [
+                  "#27AE60",
+                  "#F39C12",
+                  "#E74C3C"
+                ]
+              },
+              "frame": {
+                "showTitle": true,
+                "title": "Brand Growth Trajectories"
+              },
+              "widgetType": "pie",
+              "encodings": {
+                "angle": {
+                  "fieldName": "measure(brand_location_count)",
+                  "scale": {
+                    "type": "quantitative"
+                  },
+                  "displayName": "Count"
+                },
+                "color": {
+                  "fieldName": "trajectory",
+                  "displayName": "Trajectory",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 18,
+            "width": 4,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "brand_growth_rates",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(avg_growth_rate)",
+                      "expression": "MEASURE(`avg_growth_rate`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "showTitle": true,
+                "title": "Growth Rate by Brand"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_growth_rate)",
+                  "displayName": "Avg Growth Rate",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 4,
+            "y": 18,
+            "width": 8,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "growth_by_location",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "trajectory",
+                      "expression": "`trajectory`"
+                    },
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "measure(brand_location_count)",
+                      "expression": "MEASURE(`brand_location_count`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "frame": {
+                "showTitle": true,
+                "title": "Growth by Location"
+              },
+              "version": 3,
+              "mark": {
+                "layout": "stack"
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "location_name",
+                  "displayName": "Location",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(brand_location_count)",
+                  "displayName": "Brands",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                },
+                "color": {
+                  "fieldName": "trajectory",
+                  "displayName": "Trajectory",
+                  "scale": {
+                    "type": "categorical"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 25,
+            "width": 12,
+            "height": 7
+          }
+        },
+        {
+          "widget": {
+            "name": "prep_time_chart",
+            "queries": [
+              {
+                "name": "main_query",
+                "query": {
+                  "datasetName": "brands",
+                  "fields": [
+                    {
+                      "name": "brand_name",
+                      "expression": "`brand_name`"
+                    },
+                    {
+                      "name": "measure(avg_prep_time)",
+                      "expression": "MEASURE(`avg_prep_time`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 3,
+              "frame": {
+                "title": "Avg Prep Time by Brand",
+                "showTitle": true
+              },
+              "widgetType": "bar",
+              "encodings": {
+                "x": {
+                  "fieldName": "brand_name",
+                  "displayName": "Brand",
+                  "scale": {
+                    "type": "categorical",
+                    "sort": {
+                      "by": "y-reversed"
+                    }
+                  }
+                },
+                "y": {
+                  "fieldName": "measure(avg_prep_time)",
+                  "displayName": "Avg Prep Time (min)",
+                  "scale": {
+                    "type": "quantitative"
+                  }
+                }
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 32,
+            "width": 12,
+            "height": 6
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_CANVAS",
+      "layoutVersion": "GRID_V1"
+    },
+    {
+      "name": "global_filters",
+      "displayName": "Global Filters",
+      "layout": [
+        {
+          "widget": {
+            "name": "location_filter",
+            "queries": [
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360526a1eccacd5cfc7259251fd_location_name",
+                "query": {
+                  "datasetName": "locations",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153622f8b18738e45a3eebce6a56d_location_name",
+                "query": {
+                  "datasetName": "order_revenue",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f1536056bc1df583823e9954e1ed08_location_name",
+                "query": {
+                  "datasetName": "inspections",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360587b1b9e985f894a3baae886_location_name",
+                "query": {
+                  "datasetName": "violations",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646476146aa0cb4e1e717f6c98_location_name",
+                "query": {
+                  "datasetName": "hourly_demand",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646299154195e403455b344102_location_name",
+                "query": {
+                  "datasetName": "brand_growth",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              },
+              {
+                "name": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15365fe0714858af9fb564993e59a_location_name",
+                "query": {
+                  "datasetName": "location_map",
+                  "fields": [
+                    {
+                      "name": "location_name",
+                      "expression": "`location_name`"
+                    },
+                    {
+                      "name": "location_name_associativity",
+                      "expression": "COUNT_IF(`associative_filter_predicate_group`)"
+                    }
+                  ],
+                  "disaggregated": false
+                }
+              }
+            ],
+            "spec": {
+              "version": 2,
+              "frame": {
+                "title": "Location",
+                "showTitle": true
+              },
+              "widgetType": "filter-multi-select",
+              "encodings": {
+                "fields": [
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360526a1eccacd5cfc7259251fd_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153622f8b18738e45a3eebce6a56d_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f1536056bc1df583823e9954e1ed08_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15360587b1b9e985f894a3baae886_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646476146aa0cb4e1e717f6c98_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f153646299154195e403455b344102_location_name"
+                  },
+                  {
+                    "fieldName": "location_name",
+                    "queryName": "dashboards/01f1535d8321198cb4e400d9afc379f4/datasets/01f15365fe0714858af9fb564993e59a_location_name"
+                  }
+                ]
+              }
+            }
+          },
+          "position": {
+            "x": 0,
+            "y": 0,
+            "width": 3,
+            "height": 2
+          }
+        }
+      ],
+      "pageType": "PAGE_TYPE_GLOBAL_FILTERS",
+      "layoutVersion": "GRID_V1"
+    }
+  ],
+  "uiSettings": {
+    "theme": {
+      "canvasBackgroundColor": {
+        "light": "#0D1117",
+        "dark": "#0D1117"
+      },
+      "widgetBackgroundColor": {
+        "light": "#161B22",
+        "dark": "#161B22"
+      },
+      "widgetBorderColor": {
+        "light": "#30363D",
+        "dark": "#30363D"
+      },
+      "fontColor": {
+        "light": "#E6EDF3",
+        "dark": "#E6EDF3"
+      },
+      "selectionColor": {
+        "light": "#58A6FF",
+        "dark": "#58A6FF"
+      },
+      "visualizationColors": [
+        "#FF3621",
+        "#3ecf8e",
+        "#f5a623",
+        "#5A9CFF",
+        "#D2A8FF",
+        "#56D364",
+        "#FFA657",
+        "#FF7B72",
+        "#A5D6FF",
+        "#7EE787"
+      ],
+      "widgetHeaderAlignment": "CENTER",
+      "fontFamily": "Trebuchet MS"
+    },
+    "applyModeEnabled": false
+  }
+}
\ No newline at end of file
diff --git a/stages/apps.ipynb b/stages/apps.ipynb
index a7975f4..6e7e69d 100644
--- a/stages/apps.ipynb
+++ b/stages/apps.ipynb
@@ -41,7 +41,15 @@
       "source": [
         "import re\n",
         "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-        "REFUNDMANAGER_LAKEBASE_INSTANCE_NAME = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}refundmanager\".lower())"
+        "\n",
+        "# Coordinates for the shared Lakebase Autoscaling project (created by\n",
+        "# stages/lakebase_project.ipynb).  The refund-manager app reads/writes the\n",
+        "# caspers_refund database inside this project; see stages/lakebase.ipynb\n",
+        "# for the synced table that materialises agent recommendations there.\n",
+        "PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "BRANCH_PATH = f\"projects/{PROJECT_ID}/branches/production\"\n",
+        "ENDPOINT_PATH = f\"{BRANCH_PATH}/endpoints/primary\"\n",
+        "LAKEBASE_DB = \"caspers-refund\"  # Lakebase Autoscale requires DNS-safe names"
       ]
     },
     {
@@ -134,21 +142,24 @@
       "outputs": [],
       "source": [
         "app_yaml_contents = f\"\"\"command:\n",
-        "  - uvicorn \n",
+        "  - uvicorn\n",
         "  - app.main:app\n",
         "env:\n",
         "  - name: DATABRICKS_WAREHOUSE_ID\n",
         "    value: '{warehouse.id}'\n",
         "  - name: DATABRICKS_CATALOG\n",
         "    value: '{CATALOG}'\n",
+        "  - name: LAKEBASE_ENDPOINT_PATH\n",
+        "    value: '{ENDPOINT_PATH}'\n",
+        "  - name: LAKEBASE_DATABASE_NAME\n",
+        "    value: '{LAKEBASE_DB}'\n",
         "\"\"\"\n",
         "\n",
-        "# for some reason we need to remove it first before this works\n",
-        "import os\n",
+        "# Rewriting app.yaml on every stage run gives downstream apps deterministic\n",
+        "# env vars regardless of how many bundle deploys have happened.\n",
+        "import os, time\n",
         "if os.path.exists(\"../apps/refund-manager/app.yaml\"):\n",
         "    os.remove(\"../apps/refund-manager/app.yaml\")\n",
-        "\n",
-        "import time\n",
         "time.sleep(3)\n",
         "\n",
         "with open(\"../apps/refund-manager/app.yaml\", \"w\") as f:\n",
@@ -173,14 +184,31 @@
       },
       "outputs": [],
       "source": [
-        "from databricks.sdk.service.apps import App, AppResource, AppResourceSqlWarehouse, AppResourceDatabase, AppResourceSqlWarehouseSqlWarehousePermission, AppResourceDatabaseDatabasePermission\n",
+        "from databricks.sdk.service.apps import App, AppResource, AppResourceSqlWarehouse, AppResourceSqlWarehouseSqlWarehousePermission\n",
         "import os\n",
+        "import re as _re\n",
         "\n",
         "source_code_path = os.path.abspath(\"../apps/refund-manager\")\n",
-        "APP_NAME = f\"refundmanager\"\n",
         "\n",
+        "# P1-18: catalog-scope the app name so two users on the same workspace don't\n",
+        "# fight over the global `refundmanager` slug.  Sanitise to lowercase\n",
+        "# alphanumerics+hyphens (Databricks Apps constraint) and cap at 30 chars.\n",
+        "APP_NAME = _re.sub(r\"-+\", \"-\", _re.sub(r\"[^a-z0-9-]\", \"-\", f\"refundmanager-{CATALOG}\".lower())).strip(\"-\")[:30]\n",
+        "print(f\"App name: {APP_NAME}\")\n",
+        "\n",
+        "# AppResourceDatabase is the Provisioned-Lakebase binding; the consolidated\n",
+        "# Autoscaling project doesn't need (and can't accept) it.  The app reaches\n",
+        "# Lakebase via its own service-principal OAuth + a per-endpoint credential\n",
+        "# minted in app/db.py.  See the role-grant cell below for the Postgres-side\n",
+        "# binding that gives the app's SP a role in caspers_refund.\n",
+        "APP_DESCRIPTION = (\n",
+        "    \"Casper's Refund Manager — operator console for the refund recommender \"\n",
+        "    \"agent: queue of pending orders, structured agent decisions, and \"\n",
+        "    \"one-click application of refunds against Lakebase.\"\n",
+        ")\n",
         "app_def = App(\n",
         "    name=APP_NAME,\n",
+        "    description=APP_DESCRIPTION,\n",
         "    default_source_code_path=source_code_path,\n",
         "    resources=[\n",
         "        AppResource(\n",
@@ -189,14 +217,6 @@
         "                id=warehouse.id,\n",
         "                permission=AppResourceSqlWarehouseSqlWarehousePermission.CAN_USE),\n",
         "        ),\n",
-        "        AppResource(\n",
-        "            name=\"database\",\n",
-        "            database=AppResourceDatabase(\n",
-        "                instance_name=f\"{REFUNDMANAGER_LAKEBASE_INSTANCE_NAME}\",\n",
-        "                database_name=\"caspers\",\n",
-        "                permission=AppResourceDatabaseDatabasePermission.CAN_CONNECT_AND_CREATE,\n",
-        "            ),\n",
-        "        ),\n",
         "    ],\n",
         ")\n",
         "\n",
@@ -226,11 +246,43 @@
       },
       "outputs": [],
       "source": [
-        "# blocks until app is ready\n",
-        "app_status = app.result()\n",
+        "import time\n",
         "\n",
-        "# add to state\n",
-        "add(CATALOG, \"apps\", app_status)"
+        "def _app_state(a):\n",
+        "    cs = getattr(a, \"compute_status\", None)\n",
+        "    s = getattr(cs, \"state\", None) if cs is not None else None\n",
+        "    if s is None:\n",
+        "        s = getattr(a, \"state\", None)\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current = w.apps.get(APP_NAME)\n",
+        "    state = _app_state(current)\n",
+        "    print(f\"App {APP_NAME} state: {state}\")\n",
+        "    if state in (\"ACTIVE\", \"RUNNING\", \"READY\"):\n",
+        "        app_status = current\n",
+        "        break\n",
+        "    if state in (\"ERROR\", \"FAILED\"):\n",
+        "        raise RuntimeError(f\"App {APP_NAME} entered failure state: {state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"App {APP_NAME} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(15)\n",
+        "\n",
+        "add(CATALOG, \"apps\", app_status)\n",
+        "\n",
+        "# Discover Domain tagging.  The refund-manager app surfaces in BOTH the\n",
+        "# Operations and Revenue & Customers domains: ops/manager personas use it\n",
+        "# to reverse-decide automated refunds (operational tool), and the same\n",
+        "# data drives revenue analytics (refund leakage, cohort impact).  See\n",
+        "# SETUP.ipynb §4 for the manual one-time Domain creation step.\n",
+        "import sys as _sys, os as _os\n",
+        "_sys.path.insert(0, _os.path.abspath(\"..\"))  # stages/ -> repo root\n",
+        "from utils.domain_tags import ensure_domain_tag_policies, tag_workspace_entity\n",
+        "print(\"\\n— Tagging refund-manager app for Discover Domains —\")\n",
+        "ensure_domain_tag_policies(w, verbose=False)\n",
+        "tag_workspace_entity(w, \"apps\", APP_NAME, [\"operations\", \"revenue\"],\n",
+        "                     label=f\"app {APP_NAME!r}\")"
       ]
     },
     {
@@ -239,41 +291,73 @@
       "metadata": {},
       "outputs": [],
       "source": [
-        "# grant app permissions to catalog, schema, `all_events` table for reading events\n",
-        "from databricks.sdk.service import catalog\n",
+        "# Upload the app thumbnail.  Best-effort: purely visual polish for the\n",
+        "# Discover / Workspace card and the app launcher icon, so we never let a\n",
+        "# missing API surface fail the whole stage.\n",
+        "#\n",
+        "# Runtime requirement: databricks-sdk >= 0.83 (has w.apps.update_app_thumbnail).\n",
+        "# Thumbnail source: utils/casperslogo_green.png (synced by DABs).\n",
+        "import base64, os\n",
         "\n",
-        "w.grants.update(\n",
-        "    full_name=f\"{CATALOG}\",\n",
-        "    securable_type=\"CATALOG\",\n",
-        "    changes=[\n",
-        "        catalog.PermissionsChange(\n",
-        "            add=[catalog.Privilege.USE_CATALOG],\n",
-        "            principal=app_status.id\n",
-        "        )\n",
-        "    ]\n",
-        ")\n",
+        "try:\n",
+        "    from databricks.sdk.service.apps import AppThumbnail\n",
         "\n",
-        "w.grants.update(\n",
-        "    full_name=f\"{CATALOG}.lakeflow\",\n",
-        "    securable_type=\"SCHEMA\",\n",
-        "    changes=[\n",
-        "        catalog.PermissionsChange(\n",
-        "            add=[catalog.Privilege.USE_SCHEMA],\n",
-        "            principal=app_status.id\n",
+        "    if not hasattr(w.apps, \"update_app_thumbnail\"):\n",
+        "        print(\"\\u26a0\\ufe0f  w.apps.update_app_thumbnail not available \"\n",
+        "              \"(databricks-sdk too old) \\u2014 skipping thumbnail upload.\")\n",
+        "    else:\n",
+        "        thumb_path = os.path.abspath(\"../utils/casperslogo_green.png\")\n",
+        "        with open(thumb_path, \"rb\") as _f:\n",
+        "            thumb_b64 = base64.b64encode(_f.read()).decode(\"ascii\")\n",
+        "        w.apps.update_app_thumbnail(\n",
+        "            APP_NAME,\n",
+        "            app_thumbnail=AppThumbnail(thumbnail=thumb_b64),\n",
         "        )\n",
-        "    ]\n",
-        ")\n",
+        "        print(f\"\\U0001f5bc\\ufe0f  Uploaded thumbnail for {APP_NAME}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f  Could not upload thumbnail for {APP_NAME}: {e}\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Grant app permissions to UC.  The refund manager app calls the refund\n",
+        "# agent endpoint (and, via the supervisor flow surfaced in the ops app,\n",
+        "# may transitively trigger other agents) which is deployed in OBO mode —\n",
+        "# the app SP's identity propagates all the way down to the UC function\n",
+        "# calls inside the agent.  Without USE_SCHEMA + EXECUTE on `ai`, the\n",
+        "# agent surfaces PermissionError(\"EXECUTE on Routine '<catalog>.ai.<fn>'\")\n",
+        "# on the first tool call.  The `account users` grant the refunder_agent\n",
+        "# stage applies does NOT cover app SPs — workspace-local app SPs are not\n",
+        "# members of `account users` (an account-level group).\n",
+        "from databricks.sdk.service import catalog\n",
         "\n",
-        "w.grants.update(\n",
-        "    full_name=f\"{CATALOG}.lakeflow.all_events\",\n",
-        "    securable_type=\"TABLE\",\n",
-        "    changes=[\n",
-        "        catalog.PermissionsChange(\n",
-        "            add=[catalog.Privilege.SELECT],\n",
-        "            principal=app_status.id\n",
+        "for full_name, securable_type, privilege in [\n",
+        "    (f\"{CATALOG}\",                       \"CATALOG\", catalog.Privilege.USE_CATALOG),\n",
+        "    (f\"{CATALOG}.ai\",                    \"SCHEMA\",  catalog.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.ai\",                    \"SCHEMA\",  catalog.Privilege.EXECUTE),\n",
+        "    (f\"{CATALOG}.lakeflow\",              \"SCHEMA\",  catalog.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.lakeflow.all_events\",   \"TABLE\",   catalog.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.simulator\",             \"SCHEMA\",  catalog.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.simulator.locations\",   \"TABLE\",   catalog.Privilege.SELECT),\n",
+        "]:\n",
+        "    try:\n",
+        "        w.grants.update(\n",
+        "            full_name=full_name,\n",
+        "            securable_type=securable_type,\n",
+        "            changes=[\n",
+        "                catalog.PermissionsChange(\n",
+        "                    add=[privilege],\n",
+        "                    principal=app_status.id,\n",
+        "                )\n",
+        "            ],\n",
         "        )\n",
-        "    ]\n",
-        ")"
+        "        print(f\"\\u2705 Granted {privilege} on {securable_type} {full_name}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f  Could not grant {privilege} on {full_name}: {e}\")"
       ]
     },
     {
@@ -300,24 +384,84 @@
         "      Role,\n",
         "      RoleRoleSpec,\n",
         "      RoleMembershipRole,\n",
-        "      RoleAuthMethod,\n",
         "      RoleIdentityType,\n",
-        "      RoleAttributes,\n",
         ")\n",
         "\n",
-        "PROJECT = f\"projects/{REFUNDMANAGER_LAKEBASE_INSTANCE_NAME}\"\n",
-        "PRODUCTION = list(w.postgres.list_branches(PROJECT))[0].name\n",
-        "APP_ROLE = list(w.postgres.list_roles(PRODUCTION))[1]\n",
+        "# Shared Autoscale project provisioned by stages/lakebase_project.ipynb.\n",
+        "PROJECT = f\"projects/{PROJECT_ID}\"\n",
+        "\n",
+        "# Pick the production branch by `status.default` rather than list index;\n",
+        "# the Postgres API doesn't guarantee list ordering.\n",
+        "branches = list(w.postgres.list_branches(PROJECT))\n",
+        "PRODUCTION = next(\n",
+        "    (b for b in branches if getattr(getattr(b, \"status\", None), \"default\", False)),\n",
+        "    branches[0],\n",
+        ").name\n",
         "\n",
-        "APP_ROLE.spec = RoleRoleSpec(\n",
-        "    membership_roles=[RoleMembershipRole.DATABRICKS_SUPERUSER]\n",
+        "# Resolve the app's service-principal client ID.  The app's pod authenticates\n",
+        "# to Lakebase as this SP via OAuth, so we need a Postgres role bound to this\n",
+        "# identity in order to GRANT it access to the caspers_refund DB.\n",
+        "app_sp_id = (\n",
+        "    getattr(app_status, \"service_principal_client_id\", None)\n",
+        "    or (app_status.as_dict() if hasattr(app_status, \"as_dict\") else {}).get(\"service_principal_client_id\")\n",
         ")\n",
+        "assert app_sp_id, \"Could not determine refund-manager app service principal ID\"\n",
         "\n",
-        "w.postgres.update_role(\n",
-        "    name=APP_ROLE.name,\n",
-        "    role=APP_ROLE,\n",
-        "    update_mask=FieldMask([\"spec.membership_roles\"]),\n",
-        ")"
+        "# Find-or-create-or-update the SP's role at DATABRICKS_SUPERUSER.  This\n",
+        "# mirrors stages/operational_app.ipynb's pattern for the same project; both\n",
+        "# apps need the same membership in the shared Autoscale project.  The role\n",
+        "# is scoped to the branch (production), not to a specific database — the\n",
+        "# SUPERUSER membership covers every DB in the project, which is fine for a\n",
+        "# demo (in prod you'd grant per-database privileges instead).\n",
+        "try:\n",
+        "    existing_roles = list(w.postgres.list_roles(PRODUCTION))\n",
+        "    app_role = next(\n",
+        "        (r for r in existing_roles\n",
+        "         if getattr(getattr(r, \"spec\", None), \"postgres_role\", None) == app_sp_id),\n",
+        "        None,\n",
+        "    )\n",
+        "    if app_role:\n",
+        "        app_role.spec = RoleRoleSpec(\n",
+        "            identity_type=RoleIdentityType.SERVICE_PRINCIPAL,\n",
+        "            postgres_role=app_sp_id,\n",
+        "            membership_roles=[RoleMembershipRole.DATABRICKS_SUPERUSER],\n",
+        "        )\n",
+        "        w.postgres.update_role(\n",
+        "            name=app_role.name,\n",
+        "            role=app_role,\n",
+        "            update_mask=FieldMask(field_mask=[\"spec.membership_roles\"]),\n",
+        "        )\n",
+        "        print(f\"✅ Updated app role to DATABRICKS_SUPERUSER (SP {app_sp_id})\")\n",
+        "    else:\n",
+        "        try:\n",
+        "            w.postgres.create_role(\n",
+        "                parent=PRODUCTION,\n",
+        "                role=Role(\n",
+        "                    spec=RoleRoleSpec(\n",
+        "                        identity_type=RoleIdentityType.SERVICE_PRINCIPAL,\n",
+        "                        postgres_role=app_sp_id,\n",
+        "                        membership_roles=[RoleMembershipRole.DATABRICKS_SUPERUSER],\n",
+        "                    ),\n",
+        "                ),\n",
+        "            )\n",
+        "            print(f\"✅ Created DATABRICKS_SUPERUSER role for app SP {app_sp_id}\")\n",
+        "        except Exception as _ce:\n",
+        "            # Idempotent path: if the server says the role already exists,\n",
+        "            # the list_roles() match above didn't recognise it (most likely\n",
+        "            # because spec.postgres_role on the returned role isn't exactly\n",
+        "            # equal to the SP client_id we used to filter — UUID casing or\n",
+        "            # a different identity field).  The role is already configured\n",
+        "            # for our SP, so treat as success and continue.\n",
+        "            _msg = str(_ce).lower()\n",
+        "            if \"already exists\" in _msg:\n",
+        "                print(f\"♻ DATABRICKS_SUPERUSER role for app SP {app_sp_id} already exists — skipping create\")\n",
+        "            else:\n",
+        "                raise\n",
+        "except Exception as e:\n",
+        "    # Non-fatal: the app deploy below still proceeds.  If the SP grant didn't\n",
+        "    # land, the app's first Postgres query will surface the error and we can\n",
+        "    # repair manually.\n",
+        "    print(f\"⚠\\ufe0f Could not grant Lakebase role to app SP: {type(e).__name__}: {e}\")"
       ]
     },
     {
@@ -359,6 +503,7 @@
       },
       "outputs": [],
       "source": [
+        "import time\n",
         "from databricks.sdk.service.apps import AppDeployment\n",
         "\n",
         "deployment = w.apps.deploy(\n",
@@ -367,7 +512,26 @@
         "        source_code_path=source_code_path\n",
         "    )\n",
         ")\n",
-        "deployment_status = deployment.result()\n",
+        "\n",
+        "def _deploy_state(d):\n",
+        "    st = getattr(d, \"status\", None)\n",
+        "    s = getattr(st, \"state\", None) if st is not None else None\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current_dep = w.apps.get_deployment(app_name=app_status.name, deployment_id=deployment.deployment_id)\n",
+        "    state = _deploy_state(current_dep)\n",
+        "    print(f\"Deployment state: {state}\")\n",
+        "    if state == \"SUCCEEDED\":\n",
+        "        deployment_status = current_dep\n",
+        "        break\n",
+        "    if state in (\"FAILED\", \"STOPPED\"):\n",
+        "        raise RuntimeError(f\"Deployment failed for {app_status.name}: state={state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"Deployment for {app_status.name} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(10)\n",
+        "\n",
         "display(deployment_status)"
       ]
     }
diff --git a/stages/canonical_data.ipynb b/stages/canonical_data.ipynb
index 93cf25b..f75d3ae 100644
--- a/stages/canonical_data.ipynb
+++ b/stages/canonical_data.ipynb
@@ -13,25 +13,27 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "%pip install --upgrade databricks-sdk"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "dbutils.library.restartPython()"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
         "EVENTS_VOLUME = dbutils.widgets.get(\"EVENTS_VOLUME\")\n",
@@ -39,9 +41,7 @@
         "START_DAY = dbutils.widgets.get(\"START_DAY\") if dbutils.widgets.get(\"START_DAY\") else \"20\"\n",
         "SPEED_MULTIPLIER = dbutils.widgets.get(\"SPEED_MULTIPLIER\") if dbutils.widgets.get(\"SPEED_MULTIPLIER\") else \"1.0\"\n",
         "SCHEDULE_MINUTES = dbutils.widgets.get(\"SCHEDULE_MINUTES\") if dbutils.widgets.get(\"SCHEDULE_MINUTES\") else \"5\""
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -52,16 +52,22 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "%sql\n",
         "CREATE CATALOG IF NOT EXISTS ${CATALOG};\n",
+        "-- Required for model-serving endpoints (refunder/complaint/support agents) to\n",
+        "-- resolve UC functions at model-load time.  Without this, the first deploy of a\n",
+        "-- new agent endpoint fails with `Permission denied: User does not have EXECUTE\n",
+        "-- on Routine` because the endpoint's auto-generated SP can't traverse the\n",
+        "-- catalog.  Granting here means every downstream stage inherits it.\n",
+        "GRANT USE CATALOG ON CATALOG ${CATALOG} TO `account users`;\n",
         "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.${SIMULATOR_SCHEMA};\n",
         "CREATE VOLUME IF NOT EXISTS ${CATALOG}.${SIMULATOR_SCHEMA}.${EVENTS_VOLUME};\n",
         "CREATE VOLUME IF NOT EXISTS ${CATALOG}.${SIMULATOR_SCHEMA}.misc;"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -74,7 +80,9 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "import pandas as pd\n",
         "\n",
@@ -98,9 +106,7 @@
         "    .write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.{SIMULATOR_SCHEMA}.brand_locations\")\n",
         "\n",
         "print(\"✅ Dimensional tables created from canonical dataset\")"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -113,7 +119,9 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "from databricks.sdk import WorkspaceClient\n",
         "import databricks.sdk.service.jobs as j\n",
@@ -173,9 +181,7 @@
         "\n",
         "w.jobs.run_now(job_id=job_id)\n",
         "print(f\"🚀 Started initial run of job {job_id}\")"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -190,7 +196,9 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {},
+      "outputs": [],
       "source": [
         "import time\n",
         "\n",
@@ -217,9 +225,7 @@
         "    raise TimeoutError(f\"No data found in {path} after {timeout} seconds.\")\n",
         "\n",
         "wait_for_data(volume_path)"
-      ],
-      "execution_count": null,
-      "outputs": []
+      ]
     }
   ],
   "metadata": {
@@ -235,4 +241,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 4
-}
\ No newline at end of file
+}
diff --git a/stages/complaint_agent.ipynb b/stages/complaint_agent.ipynb
index 6dd2a0a..1dd8ffb 100644
--- a/stages/complaint_agent.ipynb
+++ b/stages/complaint_agent.ipynb
@@ -1,732 +1,1335 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "cell-0",
-   "metadata": {},
-   "source": "#### complaint agent\n\nBuilds and ships an order-complaint agent using DSPy: author Unity Catalog tools, assemble the DSPy ReAct workflow, evaluate it, and promote the packaged model into production."
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### complaint agent\n\nBuilds and ships an order-complaint agent using DSPy: author Unity Catalog tools, assemble the DSPy ReAct workflow, evaluate it, and promote the packaged model into production.",
+      "id": "cell-0"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Tool & View Registration\n",
+        "\n",
+        "- `CREATE SCHEMA` guarantees the shared `${CATALOG}.ai` workspace exists for agent assets.\n",
+        "- `order_delivery_times_per_location_view` summarizes delivery percentiles per brand/location.\n",
+        "- `get_order_overview(oid)` returns structured order metadata, items, and customer info.\n",
+        "- `get_order_timing(oid)` exposes created/delivered timestamps plus transit duration.\n",
+        "- `get_location_timings(loc)` yields P50/P75/P99 delivery benchmarks for benchmarking complaints.\n"
+      ],
+      "id": "cell-1"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.ai;"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-2"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE VIEW ${CATALOG}.ai.order_delivery_times_per_location_view AS\n",
+        "WITH order_times AS (\n",
+        "  SELECT\n",
+        "    ae.order_id,\n",
+        "    loc.name AS location,\n",
+        "    MAX(CASE WHEN ae.event_type = 'order_created' THEN try_to_timestamp(ae.ts) END) AS order_created_time,\n",
+        "    MAX(CASE WHEN ae.event_type = 'delivered' THEN try_to_timestamp(ae.ts) END) AS delivered_time\n",
+        "  FROM\n",
+        "    ${CATALOG}.lakeflow.all_events ae\n",
+        "    LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n",
+        "  WHERE\n",
+        "    try_to_timestamp(ae.ts) >= CURRENT_TIMESTAMP() - INTERVAL 1 DAY\n",
+        "  GROUP BY\n",
+        "    ae.order_id,\n",
+        "    loc.name\n",
+        "),\n",
+        "total_order_times AS (\n",
+        "  SELECT\n",
+        "    order_id,\n",
+        "    location,\n",
+        "    (UNIX_TIMESTAMP(delivered_time) - UNIX_TIMESTAMP(order_created_time)) / 60 AS total_order_time_minutes\n",
+        "  FROM\n",
+        "    order_times\n",
+        "  WHERE\n",
+        "    order_created_time IS NOT NULL\n",
+        "    AND delivered_time IS NOT NULL\n",
+        ")\n",
+        "SELECT\n",
+        "  location,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.50) AS P50,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.75) AS P75,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.99) AS P99\n",
+        "FROM\n",
+        "  total_order_times\n",
+        "GROUP BY\n",
+        "  location"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "tdy6yy3gheg"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_overview(oid STRING COMMENT 'The unique order identifier to retrieve information for')\n",
+        "RETURNS TABLE (\n",
+        "  order_id STRING COMMENT 'The order id',\n",
+        "  location STRING COMMENT 'Order location',\n",
+        "  items_json STRING COMMENT 'JSON array of ordered items with details',\n",
+        "  customer_address STRING COMMENT 'Customer delivery address',\n",
+        "  brand_id BIGINT COMMENT 'Brand ID for the order',\n",
+        "  order_created_ts TIMESTAMP COMMENT 'When the order was created'\n",
+        ")\n",
+        "COMMENT 'Returns basic order information including items, location, and customer details'\n",
+        "RETURN\n",
+        "  WITH order_created_events AS (\n",
+        "    SELECT\n",
+        "      ae.order_id,\n",
+        "      loc.name AS location,\n",
+        "      get_json_object(ae.body, '$.items') as items_json,\n",
+        "      get_json_object(ae.body, '$.customer_addr') as customer_address,\n",
+        "      -- Extract brand_id from first item in the order\n",
+        "      CAST(get_json_object(get_json_object(ae.body, '$.items[0]'), '$.brand_id') AS BIGINT) as brand_id,\n",
+        "      try_to_timestamp(ae.ts) as order_created_ts\n",
+        "    FROM ${CATALOG}.lakeflow.all_events ae\n",
+        "    LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n",
+        "    WHERE ae.order_id = oid AND ae.event_type = 'order_created'\n",
+        "    LIMIT 1\n",
+        "  )\n",
+        "  SELECT\n",
+        "    order_id,\n",
+        "    location,\n",
+        "    items_json,\n",
+        "    customer_address,\n",
+        "    brand_id,\n",
+        "    order_created_ts\n",
+        "  FROM order_created_events;"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-3"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_timing(oid STRING COMMENT 'The unique order identifier to get timing information for')\n",
+        "RETURNS TABLE (\n",
+        "  order_id STRING COMMENT 'The order id',\n",
+        "  order_created_ts TIMESTAMP COMMENT 'When the order was created',\n",
+        "  delivered_ts TIMESTAMP COMMENT 'When the order was delivered (NULL if not delivered)',\n",
+        "  delivery_duration_minutes FLOAT COMMENT 'Time from order creation to delivery in minutes (NULL if not delivered)',\n",
+        "  delivery_status STRING COMMENT 'Current delivery status: delivered, in_progress, or unknown'\n",
+        ")\n",
+        "COMMENT 'Returns timing information for a specific order'\n",
+        "RETURN\n",
+        "  WITH order_events AS (\n",
+        "    SELECT\n",
+        "      order_id,\n",
+        "      event_type,\n",
+        "      try_to_timestamp(ts) as event_ts\n",
+        "    FROM ${CATALOG}.lakeflow.all_events\n",
+        "    WHERE order_id = oid\n",
+        "  ),\n",
+        "  timing_summary AS (\n",
+        "    SELECT\n",
+        "      order_id,\n",
+        "      MIN(CASE WHEN event_type = 'order_created' THEN event_ts END) as order_created_ts,\n",
+        "      MAX(CASE WHEN event_type = 'delivered' THEN event_ts END) as delivered_ts\n",
+        "    FROM order_events\n",
+        "    GROUP BY order_id\n",
+        "  )\n",
+        "  SELECT\n",
+        "    order_id,\n",
+        "    order_created_ts,\n",
+        "    delivered_ts,\n",
+        "    CASE\n",
+        "      WHEN delivered_ts IS NOT NULL AND order_created_ts IS NOT NULL THEN\n",
+        "        CAST((UNIX_TIMESTAMP(delivered_ts) - UNIX_TIMESTAMP(order_created_ts)) / 60 AS FLOAT)\n",
+        "      ELSE NULL\n",
+        "    END as delivery_duration_minutes,\n",
+        "    CASE\n",
+        "      WHEN delivered_ts IS NOT NULL THEN 'delivered'\n",
+        "      WHEN order_created_ts IS NOT NULL THEN 'in_progress'\n",
+        "      ELSE 'unknown'\n",
+        "    END as delivery_status\n",
+        "  FROM timing_summary;"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-4"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_location_timings(loc STRING COMMENT 'Location name as a string')\n",
+        "RETURNS TABLE (\n",
+        "  location STRING COMMENT 'Location of the order source',\n",
+        "  P50 FLOAT COMMENT '50th percentile delivery time in minutes',\n",
+        "  P75 FLOAT COMMENT '75th percentile delivery time in minutes',\n",
+        "  P99 FLOAT COMMENT '99th percentile delivery time in minutes'\n",
+        ")\n",
+        "COMMENT 'Returns the 50/75/99th percentile of delivery times for a location to benchmark order timing'\n",
+        "RETURN\n",
+        "  SELECT location, P50, P75, P99\n",
+        "  FROM ${CATALOG}.ai.order_delivery_times_per_location_view AS odlt\n",
+        "  WHERE odlt.location = loc;"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-5"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "-- USE CATALOG is needed in addition to USE SCHEMA + EXECUTE so the serving\n",
+        "-- endpoint's auto-generated SP can traverse the catalog to reach the UC\n",
+        "-- functions at model-load time.  Normally granted by the root data stage\n",
+        "-- (canonical_data/raw_data), but repeated here so this stage is self-\n",
+        "-- sufficient if run standalone or against a pre-existing catalog.\n",
+        "GRANT USE CATALOG ON CATALOG ${CATALOG} TO `account users`;\n",
+        "GRANT USE SCHEMA ON SCHEMA ${CATALOG}.ai TO `account users`;"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "-- Grant EXECUTE to all workspace principals so the serving endpoint SP\n",
+        "-- (created by agents.deploy) can call these tools at inference time.\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_order_overview    TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_order_timing      TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_location_timings  TO `account users`;"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### Model\n\n- Install DSPy, Databricks agent packages, and restart Python for a clean runtime.\n- Capture widget inputs (`CATALOG`, `LLM_MODEL`) and create an MLflow dev experiment for trace logging.\n- Define a templated `%%writefilev` magic that emits files with notebook variable substitution.\n- Materialize `agent.py` containing the DSPy ReAct complaint workflow wired to UC SQL tools and the chosen LLM endpoint.\n- Pull a delivered `order_id` sample and build the MLflow model signature/resources for logging.",
+      "id": "dq5ml4wp6v"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "%pip install -U -qqqq typing_extensions dspy-ai mlflow unitycatalog-openai[databricks] openai databricks-sdk databricks-agents pydantic\n%restart_python",
+      "execution_count": null,
+      "outputs": [],
+      "id": "bd3tu3r2gso"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
+        "\n",
+        "# Unity AI Gateway (v2 Beta) endpoint name.  Defined as a job parameter on\n",
+        "# the `all` target only — empty string everywhere else.  When set, the\n",
+        "# agent routes its DSPy LM calls through the gateway URL\n",
+        "# `<host>/ai-gateway/mlflow/v1` instead of calling a foundation-model\n",
+        "# serving endpoint directly.  Mirror of the same plumbing in\n",
+        "# stages/refunder_agent.ipynb — see databricks.yml comment on the param\n",
+        "# for the full rationale + UI setup steps.\n",
+        "try:\n",
+        "    AI_GATEWAY_ENDPOINT_NAME = dbutils.widgets.get(\"AI_GATEWAY_ENDPOINT_NAME\")\n",
+        "except Exception:\n",
+        "    AI_GATEWAY_ENDPOINT_NAME = \"\"\n",
+        "\n",
+        "if AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    print(f\"⛩  Routing complaint agent LLM calls through AI Gateway: {AI_GATEWAY_ENDPOINT_NAME}\")\n",
+        "else:\n",
+        "    print(f\"→ Complaint agent LLM calls go directly to foundation-model endpoint: {LLM_MODEL}\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "dl04kgwv9ap"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "\n",
+        "# Create/set dev experiment for development and evaluation traces\n",
+        "# Use shared path for job compatibility\n",
+        "dev_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_dev\"\n",
+        "\n",
+        "# set_experiment creates the experiment if it doesn't exist, or activates it if it does\n",
+        "dev_experiment = mlflow.set_experiment(dev_experiment_name)\n",
+        "dev_experiment_id = dev_experiment.experiment_id\n",
+        "print(f\"✅ Using dev experiment: {dev_experiment_name} (ID: {dev_experiment_id})\")\n",
+        "\n",
+        "# Add experiment to UC state for cleanup\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "experiment_data = {\n",
+        "    \"experiment_id\": dev_experiment_id,\n",
+        "    \"name\": dev_experiment_name\n",
+        "}\n",
+        "add(CATALOG, \"experiments\", experiment_data)\n",
+        "print(f\"✅ Added dev experiment to UC state\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "ktoahik8tl"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "import os\n",
+        "from IPython.core.magic import register_cell_magic\n",
+        "\n",
+        "# Records absolute paths of files written by `%%writefilev`, keyed by the\n",
+        "# filename argument.  The import cell below imports `from agent import LLM_MODEL`.\n",
+        "#\n",
+        "# Earlier versions wrote to `os.path.abspath(filename)` (i.e. CWD), but CWD\n",
+        "# on serverless notebooks is usually a `/Workspace/Users/...` path, and the\n",
+        "# workspace-files-as-Python-modules feature is not reliably wired through\n",
+        "# on serverless — the file ends up on disk, `os.path.exists()` returns True,\n",
+        "# but `import agent` still raises `ModuleNotFoundError`.  Pinning the write\n",
+        "# dir to a regular local-disk path (`/local_disk0/tmp/...`, falling back to\n",
+        "# `/tmp/...`) sidesteps the workspace-files importer entirely.\n",
+        "_WRITEFILEV_ABS_PATHS = {}\n",
+        "\n",
+        "_WRITEFILEV_DIR = \"/local_disk0/tmp/caspers_writefilev\"\n",
+        "if not os.path.isdir(\"/local_disk0\"):\n",
+        "    _WRITEFILEV_DIR = \"/tmp/caspers_writefilev\"\n",
+        "os.makedirs(_WRITEFILEV_DIR, exist_ok=True)\n",
+        "\n",
+        "@register_cell_magic\n",
+        "def writefilev(line, cell):\n",
+        "    \"\"\"\n",
+        "    %%writefilev file.py\n",
+        "    Allows {{var}} substitutions while leaving normal {} intact.\n",
+        "\n",
+        "    Writes to a stable local-disk path (NOT CWD) so subsequent\n",
+        "    `from <module> import ...` always succeeds, even on serverless\n",
+        "    where CWD is a /Workspace path.\n",
+        "    \"\"\"\n",
+        "    filename = line.strip()\n",
+        "\n",
+        "    def replacer(match):\n",
+        "        expr = match.group(1)\n",
+        "        return str(eval(expr, globals(), locals()))\n",
+        "\n",
+        "    content = re.sub(r\"\\{\\{(.*?)\\}\\}\", replacer, cell)\n",
+        "\n",
+        "    abs_path = os.path.join(_WRITEFILEV_DIR, filename)\n",
+        "    with open(abs_path, \"w\") as f:\n",
+        "        f.write(content)\n",
+        "    _WRITEFILEV_ABS_PATHS[filename] = abs_path\n",
+        "    print(f\"Wrote file with substitutions: {abs_path}\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "bruu85upqq5"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%%writefilev agent.py\n",
+        "import warnings\n",
+        "from typing import Optional, Literal\n",
+        "from uuid import uuid4\n",
+        "from pydantic import BaseModel, Field, field_validator, ValidationError\n",
+        "\n",
+        "warnings.filterwarnings(\"ignore\", message=\".*Ignoring the default notebook Spark session.*\")\n",
+        "\n",
+        "import dspy\n",
+        "import mlflow\n",
+        "from unitycatalog.ai.core.base import get_uc_function_client\n",
+        "from mlflow.pyfunc import ResponsesAgent\n",
+        "from mlflow.types.responses import (\n",
+        "    ResponsesAgentRequest,\n",
+        "    ResponsesAgentResponse,\n",
+        ")\n",
+        "\n",
+        "# Enable DSPy autologging for automatic trace capture\n",
+        "mlflow.dspy.autolog(log_traces=True)\n",
+        "\n",
+        "LLM_MODEL = \"{{LLM_MODEL}}\"\n",
+        "CATALOG = \"{{CATALOG}}\"\n",
+        "\n",
+        "# When non-empty, routes every DSPy LM call through the Unity AI Gateway\n",
+        "# (v2 Beta) URL `<host>/ai-gateway/mlflow/v1` so the gateway's guardrails\n",
+        "# / inference table / usage tracking / rate limits apply centrally.  When\n",
+        "# empty, calls the foundation-model serving endpoint named by LLM_MODEL\n",
+        "# directly via the `databricks/<model>` litellm provider (legacy\n",
+        "# behaviour, used by the `default` and `complaints` targets).\n",
+        "AI_GATEWAY_ENDPOINT_NAME = \"{{AI_GATEWAY_ENDPOINT_NAME}}\"\n",
+        "\n",
+        "# `LLM_ENDPOINT_NAME` is the name we expose for the resources=[...] list\n",
+        "# in the log_model cell.  When the AI Gateway is wired up it points at\n",
+        "# the gateway endpoint (so we know what the agent calls at runtime),\n",
+        "# but we deliberately do NOT include the gateway in the resources list —\n",
+        "# v2 Beta gateway endpoints are not discoverable via the regular\n",
+        "# /api/2.0/serving-endpoints/* API and listing them causes\n",
+        "# `agents.deploy()` to fail with \"NOT_FOUND: Dependent serving endpoint\n",
+        "# <gateway> does not exist\".  See the resources cell + SETUP.ipynb\n",
+        "# step 5.7 for the manual CAN_QUERY grant the deployment SP needs.\n",
+        "LLM_ENDPOINT_NAME = AI_GATEWAY_ENDPOINT_NAME or LLM_MODEL\n",
+        "\n",
+        "# Configure DSPy with Databricks LM.\n",
+        "#  - num_retries makes litellm back off and retry every individual LLM call\n",
+        "#    on REQUEST_LIMIT_EXCEEDED, so a single 429 inside DSPy's ReAct loop\n",
+        "#    doesn't fail the whole agent invocation.\n",
+        "#  - cache=False is required for the retry loop in ComplaintTriageModule.forward\n",
+        "#    to actually retry — with cache=True every retry returns the same cached\n",
+        "#    response and the same ValidationError fires every time.\n",
+        "if AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    # Auth: in Model Serving the runtime authenticates as the deployed\n",
+        "    # endpoint's service principal via OAuth M2M.  In M2M mode there is\n",
+        "    # NO static token — `WorkspaceClient().config.token` returns None.\n",
+        "    # `config.authenticate()` returns the auth headers the SDK would\n",
+        "    # attach to a request right now (`{\"Authorization\": \"Bearer <tok>\"}`),\n",
+        "    # regardless of whether the underlying provider is PAT, OAuth U2M, or\n",
+        "    # OAuth M2M.  We strip the bearer prefix and hand the raw token to\n",
+        "    # litellm-via-dspy as `api_key`.\n",
+        "    #\n",
+        "    # Token rotation: the bearer we extract is whatever the SDK has at\n",
+        "    # the moment of this call.  In OAuth M2M mode the SDK rotates the\n",
+        "    # underlying token periodically (~1h window).  litellm caches the\n",
+        "    # api_key inside the dspy.LM object, so a single dspy.LM built at\n",
+        "    # module load goes stale and surfaces as 400 BAD_REQUEST / \"Invalid\n",
+        "    # Token\" from the gateway on a warm endpoint.  Fix: build a fresh\n",
+        "    # dspy.LM per request via `_build_gateway_lm()`.  `DSPyComplaintAgent.\n",
+        "    # predict` reconfigures dspy with the fresh LM before invoking the\n",
+        "    # module so every request picks up the SDK's current token.  The SDK\n",
+        "    # internally caches/refreshes the token, so per-call overhead is one\n",
+        "    # dict lookup in steady state and one OAuth refresh roughly hourly.\n",
+        "    from databricks.sdk import WorkspaceClient as _WorkspaceClient\n",
+        "    _w = _WorkspaceClient()\n",
+        "    _gateway_base_url = f\"{_w.config.host.rstrip('/')}/ai-gateway/mlflow/v1\"\n",
+        "\n",
+        "    def _build_gateway_lm():\n",
+        "        \"\"\"Construct a dspy.LM pointing at the AI Gateway with the SDK's\n",
+        "        *current* bearer token.  Called fresh on every request by\n",
+        "        `DSPyComplaintAgent.predict` so a rotated OAuth M2M token in the\n",
+        "        credentials provider is picked up immediately.\"\"\"\n",
+        "        _auth_headers = _w.config.authenticate()\n",
+        "        _bearer = _auth_headers.get(\"Authorization\", \"\")\n",
+        "        if not _bearer.lower().startswith(\"bearer \"):\n",
+        "            raise RuntimeError(\n",
+        "                f\"Databricks SDK auth headers do not contain a Bearer token \"\n",
+        "                f\"(got header keys: {list(_auth_headers.keys())}). \"\n",
+        "                f\"Cannot route complaint agent through AI Gateway in this auth \"\n",
+        "                f\"mode — fall back to direct foundation-model endpoint by \"\n",
+        "                f\"unsetting AI_GATEWAY_ENDPOINT_NAME.\"\n",
+        "            )\n",
+        "        # litellm uses `openai/<model>` to route through any OpenAI-compatible\n",
+        "        # endpoint.  api_base is the gateway URL; the gateway expects the\n",
+        "        # gateway-endpoint-name as the `model` field in the request body.\n",
+        "        return dspy.LM(\n",
+        "            f'openai/{AI_GATEWAY_ENDPOINT_NAME}',\n",
+        "            api_base=_gateway_base_url,\n",
+        "            api_key=_bearer[len(\"Bearer \"):],\n",
+        "            max_tokens=2000,\n",
+        "            num_retries=20,\n",
+        "            cache=False,\n",
+        "        )\n",
+        "\n",
+        "    # Initial instance: needed so `dspy.configure(lm=...)` succeeds at\n",
+        "    # module load and `ComplaintTriageModule.__init__` can construct its\n",
+        "    # `dspy.ReAct(...)`.  NOT what serves requests in steady state —\n",
+        "    # `DSPyComplaintAgent.predict` reconfigures with a fresh LM per\n",
+        "    # invocation to pick up rotated tokens.\n",
+        "    lm = _build_gateway_lm()\n",
+        "else:\n",
+        "    # Direct foundation-model endpoint (default behaviour for `default` and\n",
+        "    # `complaints` targets — no gateway routing).  The `databricks/<model>`\n",
+        "    # litellm provider uses MLflow's auto-auth, which refreshes from the\n",
+        "    # SDK on every call, so no per-call rebuild is needed.\n",
+        "    _build_gateway_lm = None\n",
+        "    lm = dspy.LM(f'databricks/{LLM_MODEL}', max_tokens=2000, num_retries=20, cache=False)\n",
+        "\n",
+        "dspy.configure(lm=lm)\n",
+        "\n",
+        "# Initialize UC function client\n",
+        "uc_client = get_uc_function_client()\n",
+        "\n",
+        "\n",
+        "class ComplaintResponse(BaseModel):\n",
+        "    \"\"\"Structured output for complaint triage decisions.\"\"\"\n",
+        "    order_id: str\n",
+        "    complaint_category: Literal[\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"billing\", \"other\"] = Field(\n",
+        "        description=\"Exactly ONE primary complaint category\"\n",
+        "    )\n",
+        "    decision: Literal[\"suggest_credit\", \"escalate\"]\n",
+        "    credit_amount: Optional[float] = None\n",
+        "    confidence: Optional[Literal[\"high\", \"medium\", \"low\"]] = None\n",
+        "    priority: Optional[Literal[\"standard\", \"urgent\"]] = None\n",
+        "    rationale: str\n",
+        "    \n",
+        "    @field_validator('complaint_category', mode='before')\n",
+        "    @classmethod\n",
+        "    def parse_category(cls, v):\n",
+        "        \"\"\"Extract first valid category if multiple provided.\"\"\"\n",
+        "        if not isinstance(v, str):\n",
+        "            return v\n",
+        "            \n",
+        "        valid_categories = [\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"billing\", \"other\"]\n",
+        "        v_lower = v.lower().strip()\n",
+        "        \n",
+        "        # Exact match\n",
+        "        if v_lower in valid_categories:\n",
+        "            return v_lower\n",
+        "        \n",
+        "        # Find first valid category in string\n",
+        "        for cat in valid_categories:\n",
+        "            if cat in v_lower:\n",
+        "                return cat\n",
+        "        \n",
+        "        return \"other\"\n",
+        "    \n",
+        "    @field_validator('confidence', mode='before')\n",
+        "    @classmethod\n",
+        "    def parse_confidence(cls, v):\n",
+        "        \"\"\"Ensure valid confidence value.\"\"\"\n",
+        "        if v is None or (isinstance(v, str) and v.lower() == \"null\"):\n",
+        "            return None\n",
+        "        if isinstance(v, str):\n",
+        "            v_lower = v.lower().strip()\n",
+        "            if v_lower in [\"high\", \"medium\", \"low\"]:\n",
+        "                return v_lower\n",
+        "            return \"medium\"\n",
+        "        return v\n",
+        "    \n",
+        "    @field_validator('priority', mode='before')\n",
+        "    @classmethod\n",
+        "    def parse_priority(cls, v):\n",
+        "        \"\"\"Ensure valid priority value.\"\"\"\n",
+        "        if v is None or (isinstance(v, str) and v.lower() == \"null\"):\n",
+        "            return None\n",
+        "        if isinstance(v, str):\n",
+        "            v_lower = v.lower().strip()\n",
+        "            if v_lower in [\"standard\", \"urgent\"]:\n",
+        "                return v_lower\n",
+        "            return \"standard\"\n",
+        "        return v\n",
+        "\n",
+        "\n",
+        "class ComplaintTriage(dspy.Signature):\n",
+        "    \"\"\"Analyze customer complaints for Casper's Kitchens and recommend triage actions.\n",
+        "    \n",
+        "    Process:\n",
+        "    1. Extract order_id from complaint\n",
+        "    2. Use get_order_overview(order_id) for order details and items\n",
+        "    3. Use get_order_timing(order_id) for delivery timing\n",
+        "    4. For delays, use get_location_timings(location) for percentile benchmarks\n",
+        "    5. Make data-backed decision\n",
+        "    \n",
+        "    Decision Framework:\n",
+        "    \n",
+        "    SUGGEST_CREDIT (with credit_amount and confidence):\n",
+        "    - Delivery delays: Compare actual delivery time to location percentiles\n",
+        "      * <P75: Suggest $0 credit (low confidence - on-time or minimal delay)\n",
+        "      * P75-P99: Suggest 15% of order total (medium to high confidence)\n",
+        "      * >P99: Suggest 25% of order total (high confidence)\n",
+        "    - Missing items: Use actual item prices from order data when available\n",
+        "      * Verify claimed item exists in order (affects confidence)\n",
+        "      * Use real costs from order data, or estimate $8-12 per item if unavailable\n",
+        "    - Food quality: 20-40% of order total based on severity\n",
+        "      * Minor issues (slightly cold, minor preparation issue): 20% (medium confidence)\n",
+        "      * Major issues (completely inedible, wrong preparation, health concern): 40% (high confidence)\n",
+        "      * Vague complaints (\"bad\", \"gross\"): escalate instead\n",
+        "    \n",
+        "    ESCALATE (with priority):\n",
+        "    - priority=\"standard\": Vague complaints, missing data, billing issues, service complaints\n",
+        "    - priority=\"urgent\": Legal threats, health/safety concerns, suspected fraud, abusive language\n",
+        "    \n",
+        "    Output Requirements:\n",
+        "    - For suggest_credit: credit_amount is REQUIRED and must be a number (can be 0.0 if no credit warranted), confidence is REQUIRED, priority must be null\n",
+        "    - For escalate: priority is REQUIRED, credit_amount and confidence must be null\n",
+        "    - complaint_category: Choose EXACTLY ONE category (the primary one)\n",
+        "    - Rationale must cite specific evidence (delivery times, percentiles, item verification, order total)\n",
+        "    - Rationale should be detailed but under 150 words\n",
+        "    - Round credit amounts to nearest $0.50\n",
+        "    - Confidence: high (strong data), medium (reasonable inference), low (weak/contradictory)\n",
+        "    \"\"\"\n",
+        "    \n",
+        "    complaint: str = dspy.InputField(desc=\"Customer complaint text\")\n",
+        "    order_id: str = dspy.OutputField(desc=\"Extracted order ID\")\n",
+        "    complaint_category: str = dspy.OutputField(desc=\"EXACTLY ONE category: delivery_delay, missing_items, food_quality, service_issue, billing, or other\")\n",
+        "    decision: str = dspy.OutputField(desc=\"EXACTLY ONE: suggest_credit or escalate\")\n",
+        "    credit_amount: str = dspy.OutputField(desc=\"If suggest_credit: MUST be a number (e.g., 0.0, 10.5). If escalate: null\")\n",
+        "    confidence: str = dspy.OutputField(desc=\"If suggest_credit: EXACTLY ONE of high, medium, low. If escalate: null\")\n",
+        "    priority: str = dspy.OutputField(desc=\"If escalate: EXACTLY ONE of standard or urgent. If suggest_credit: null\")\n",
+        "    rationale: str = dspy.OutputField(desc=\"Data-focused justification citing specific evidence\")\n",
+        "\n",
+        "\n",
+        "# Unity Catalog tool wrappers\n",
+        "def get_order_overview(order_id: str) -> str:\n",
+        "    \"\"\"Get order details including items, location, and customer info.\"\"\"\n",
+        "    result = uc_client.execute_function(\n",
+        "        f\"{CATALOG}.ai.get_order_overview\",\n",
+        "        {\"oid\": order_id}\n",
+        "    )\n",
+        "    return str(result.value)\n",
+        "\n",
+        "\n",
+        "def get_order_timing(order_id: str) -> str:\n",
+        "    \"\"\"Get timing information for a specific order.\"\"\"\n",
+        "    result = uc_client.execute_function(\n",
+        "        f\"{CATALOG}.ai.get_order_timing\",\n",
+        "        {\"oid\": order_id}\n",
+        "    )\n",
+        "    return str(result.value)\n",
+        "\n",
+        "\n",
+        "def get_location_timings(location: str) -> str:\n",
+        "    \"\"\"Get delivery time percentiles for a specific location.\"\"\"\n",
+        "    result = uc_client.execute_function(\n",
+        "        f\"{CATALOG}.ai.get_location_timings\",\n",
+        "        {\"loc\": location}\n",
+        "    )\n",
+        "    return str(result.value)\n",
+        "\n",
+        "\n",
+        "class ComplaintTriageModule(dspy.Module):\n",
+        "    \"\"\"DSPy module for complaint triage with tool calling.\"\"\"\n",
+        "    \n",
+        "    def __init__(self):\n",
+        "        super().__init__()\n",
+        "        self.react = dspy.ReAct(\n",
+        "            signature=ComplaintTriage,\n",
+        "            tools=[get_order_overview, get_order_timing, get_location_timings],\n",
+        "            max_iters=10\n",
+        "        )\n",
+        "    \n",
+        "    def forward(self, complaint: str, max_retries: int = 2) -> ComplaintResponse:\n",
+        "        \"\"\"Process complaint and return structured triage decision with retry on validation failure.\"\"\"\n",
+        "        \n",
+        "        for attempt in range(max_retries + 1):\n",
+        "            try:\n",
+        "                result = self.react(complaint=complaint)\n",
+        "                \n",
+        "                # Parse credit_amount.  $0 credit is a valid suggest_credit\n",
+        "                # response (per the eval scorer: \"credit_amount of $0 is valid\n",
+        "                # when rationale indicates no issue\"), so when the LLM emits\n",
+        "                # decision='suggest_credit' but no parseable credit_amount we\n",
+        "                # treat it as $0 rather than failing the whole call.  Other\n",
+        "                # malformed fields (Literal types) still raise via Pydantic\n",
+        "                # and trigger the retry loop below.\n",
+        "                credit_amount = None\n",
+        "                if result.credit_amount and result.credit_amount.lower() != \"null\":\n",
+        "                    try:\n",
+        "                        credit_amount = float(result.credit_amount)\n",
+        "                    except (ValueError, TypeError):\n",
+        "                        credit_amount = None\n",
+        "\n",
+        "                if result.decision == \"suggest_credit\" and credit_amount is None:\n",
+        "                    credit_amount = 0.0\n",
+        "                \n",
+        "                # Construct Pydantic model - field validators run here\n",
+        "                return ComplaintResponse(\n",
+        "                    order_id=result.order_id,\n",
+        "                    complaint_category=result.complaint_category,\n",
+        "                    decision=result.decision,\n",
+        "                    credit_amount=credit_amount,\n",
+        "                    confidence=result.confidence,\n",
+        "                    priority=result.priority,\n",
+        "                    rationale=result.rationale\n",
+        "                )\n",
+        "                \n",
+        "            except (ValidationError, ValueError) as e:\n",
+        "                if attempt < max_retries:\n",
+        "                    # Retry - DSPy will regenerate with potentially different output\n",
+        "                    continue\n",
+        "                else:\n",
+        "                    # Final attempt failed - re-raise\n",
+        "                    raise\n",
+        "\n",
+        "\n",
+        "class DSPyComplaintAgent(ResponsesAgent):\n",
+        "    \"\"\"ResponsesAgent wrapper for DSPy complaint triage module.\"\"\"\n",
+        "    \n",
+        "    def __init__(self):\n",
+        "        self.module = ComplaintTriageModule()\n",
+        "    \n",
+        "    def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:\n",
+        "        \"\"\"Process complaint request and return structured response.\"\"\"\n",
+        "        complaint = None\n",
+        "        for msg in request.input:\n",
+        "            msg_dict = msg.model_dump() if hasattr(msg, \"model_dump\") else msg\n",
+        "            if msg_dict.get(\"role\") == \"user\":\n",
+        "                complaint = msg_dict.get(\"content\", \"\")\n",
+        "                break\n",
+        "        \n",
+        "        if not complaint:\n",
+        "            raise ValueError(\"No user message found in request\")\n",
+        "        \n",
+        "        # Gateway-mode token refresh: rebuild dspy.LM with a fresh OAuth\n",
+        "        # M2M bearer from the SDK and apply it as a thread-local override\n",
+        "        # before invoking the module.  Without this, warm endpoints fail\n",
+        "        # with HTTP 400 / \"Invalid Token\" from the gateway once the cached\n",
+        "        # token's ~1h window closes.  Direct `databricks/<model>` mode (no\n",
+        "        # gateway) uses MLflow's auto-auth and needs no rebuild.\n",
+        "        #\n",
+        "        # IMPORTANT: must use `dspy.context(...)`, NOT `dspy.configure(...)`.\n",
+        "        # `dspy.configure()` enforces thread-affinity — only the thread\n",
+        "        # that first called configure (module load on the main thread)\n",
+        "        # can call it again.  Model serving runs `predict()` on a worker\n",
+        "        # thread, so `dspy.configure()` from there raises:\n",
+        "        #   \"dspy.settings can only be changed by the thread that\n",
+        "        #    initially configured it.\"\n",
+        "        # `dspy.context()` is the thread-safe per-request override.\n",
+        "        if _build_gateway_lm is not None:\n",
+        "            with dspy.context(lm=_build_gateway_lm()):\n",
+        "                result = self.module(complaint=complaint)\n",
+        "        else:\n",
+        "            result = self.module(complaint=complaint)\n",
+        "        \n",
+        "        return ResponsesAgentResponse(\n",
+        "            output=[\n",
+        "                self.create_text_output_item(\n",
+        "                    text=result.model_dump_json(),\n",
+        "                    id=str(uuid4())\n",
+        "                )\n",
+        "            ],\n",
+        "            custom_outputs=request.custom_inputs\n",
+        "        )\n",
+        "\n",
+        "\n",
+        "# Initialize agent\n",
+        "AGENT = DSPyComplaintAgent()\n",
+        "mlflow.models.set_model(AGENT)"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "w2c70l4ca8"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Get an actual order_id for the input example.  In continuous-pipeline\n",
+        "# mode the lakeflow stage finishes before any data has flowed through, so\n",
+        "# poll up to 6 minutes for the first delivered event (same pattern as\n",
+        "# stages/refunder_agent.ipynb).\n",
+        "import time\n",
+        "\n",
+        "sample_order_id = None\n",
+        "for attempt in range(12):\n",
+        "    rows = spark.sql(f\"\"\"\n",
+        "        SELECT order_id\n",
+        "        FROM {CATALOG}.lakeflow.all_events\n",
+        "        WHERE event_type='delivered'\n",
+        "        LIMIT 1\n",
+        "    \"\"\").collect()\n",
+        "    if rows:\n",
+        "        sample_order_id = rows[0]['order_id']\n",
+        "        break\n",
+        "    print(f\"No delivered events yet (attempt {attempt+1}/12). Waiting 30s for pipeline data...\")\n",
+        "    time.sleep(30)\n",
+        "\n",
+        "if not sample_order_id:\n",
+        "    raise RuntimeError(\n",
+        "        f\"No delivered events found in {CATALOG}.lakeflow.all_events after 6 minutes. \"\n",
+        "        \"Ensure the Canonical_Data and Lakeflow pipeline stages completed and processed data.\"\n",
+        "    )"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "dd6gjrp4mx6"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "assert sample_order_id is not None\n",
+        "print(sample_order_id)"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "ih3tt5qeb5"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import sys\n",
+        "import os\n",
+        "\n",
+        "# Use the absolute path captured by `%%writefilev` (see cell 13). This is\n",
+        "# stable across CWD drift / kernel restarts; the older `sys.path.append(os.getcwd())`\n",
+        "# pattern was failing with `ModuleNotFoundError: No module named 'agent'` when\n",
+        "# CWD changed between the writefile cell and this one.\n",
+        "_agent_py_path = _WRITEFILEV_ABS_PATHS.get(\"agent.py\")\n",
+        "if _agent_py_path and os.path.exists(_agent_py_path):\n",
+        "    _agent_dir = os.path.dirname(_agent_py_path)\n",
+        "    print(f\"Importing agent from: {_agent_py_path}\")\n",
+        "else:\n",
+        "    # Defensive fallback: try the same locations the old code did, plus\n",
+        "    # /databricks/driver which is the typical CWD on classic clusters,\n",
+        "    # and the new pinned local-disk dir used by `%%writefilev`.\n",
+        "    _candidate_dirs = [\n",
+        "        os.getcwd(),\n",
+        "        \"/databricks/driver\",\n",
+        "        \"/local_disk0/tmp/caspers_writefilev\",\n",
+        "        \"/local_disk0/tmp\",\n",
+        "        \"/tmp/caspers_writefilev\",\n",
+        "        \"/tmp\",\n",
+        "    ]\n",
+        "    try:\n",
+        "        _nb_path = dbutils.notebook.entry_point.getDbutils().notebook().getContext().notebookPath().get()\n",
+        "        _candidate_dirs.append(os.path.dirname(_nb_path))\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    _agent_dir = next((d for d in _candidate_dirs if os.path.exists(os.path.join(d, \"agent.py\"))), None)\n",
+        "    if _agent_dir is None:\n",
+        "        raise FileNotFoundError(\n",
+        "            f\"agent.py not found. _WRITEFILEV_ABS_PATHS={_WRITEFILEV_ABS_PATHS}, \"\n",
+        "            f\"CWD={os.getcwd()}, candidates tried: {_candidate_dirs}\"\n",
+        "        )\n",
+        "    _agent_py_path = os.path.join(_agent_dir, \"agent.py\")\n",
+        "    print(f\"Importing agent from fallback dir: {_agent_py_path}\")\n",
+        "\n",
+        "if _agent_dir not in sys.path:\n",
+        "    sys.path.insert(0, _agent_dir)\n",
+        "\n",
+        "# Invalidate any cached `agent` module that may be left over from a prior\n",
+        "# attempt on the same warehouse (e.g. after a transient failure).\n",
+        "sys.modules.pop(\"agent\", None)\n",
+        "\n",
+        "from agent import LLM_MODEL, AI_GATEWAY_ENDPOINT_NAME\n",
+        "from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint\n",
+        "from pkg_resources import get_distribution\n",
+        "\n",
+        "# Resource list for `agents.deploy()` — auto-grants permissions on each\n",
+        "# resource to the deployment SP at deploy time.\n",
+        "#\n",
+        "# IMPORTANT — gateway routing is special:\n",
+        "# When AI_GATEWAY_ENDPOINT_NAME is set, we deliberately do NOT add a\n",
+        "# DatabricksServingEndpoint(...) entry for it.  v2 Beta Unity AI Gateway\n",
+        "# endpoints live under a separate API surface and are NOT discoverable\n",
+        "# via `/api/2.0/serving-endpoints/*` — listing one here makes\n",
+        "# `agents.deploy()` crash with\n",
+        "# `NOT_FOUND: Dependent serving endpoint <gateway> does not exist`.\n",
+        "# The deployment SP must therefore have CAN_QUERY on the gateway via\n",
+        "# some other path (manual grant or `account users` ACL on the gateway).\n",
+        "# Mirror of the same logic in stages/refunder_agent.ipynb.\n",
+        "resources = []\n",
+        "if not AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    # No gateway → direct foundation-model endpoint, which IS a regular\n",
+        "    # serving endpoint and CAN safely be auto-granted via resources.\n",
+        "    resources.append(DatabricksServingEndpoint(endpoint_name=LLM_MODEL))\n",
+        "\n",
+        "uc_tool_names = [\n",
+        "    f\"{CATALOG}.ai.get_order_overview\",\n",
+        "    f\"{CATALOG}.ai.get_order_timing\",\n",
+        "    f\"{CATALOG}.ai.get_location_timings\",\n",
+        "]\n",
+        "for func_name in uc_tool_names:\n",
+        "    resources.append(DatabricksFunction(function_name=func_name))\n",
+        "\n",
+        "input_example = {\n",
+        "    \"input\": [\n",
+        "        {\n",
+        "            \"role\": \"user\",\n",
+        "            \"content\": f\"My order was really late! Order ID: {sample_order_id}\"\n",
+        "        }\n",
+        "    ]\n",
+        "}\n",
+        "\n",
+        "# Create custom conda environment with mlflow explicitly specified\n",
+        "conda_env = {\n",
+        "    \"channels\": [\"conda-forge\"],\n",
+        "    \"dependencies\": [\n",
+        "        \"python=3.11\",\n",
+        "        \"pip\",\n",
+        "        {\n",
+        "            \"pip\": [\n",
+        "                \"mlflow==3.6\",\n",
+        "                f\"typing_extensions=={get_distribution('typing_extensions').version}\",\n",
+        "                f\"dspy-ai=={get_distribution('dspy-ai').version}\",\n",
+        "                f\"unitycatalog-openai[databricks]=={get_distribution('unitycatalog-openai').version}\",\n",
+        "                f\"pydantic=={get_distribution('pydantic').version}\",\n",
+        "            ]\n",
+        "        }\n",
+        "    ],\n",
+        "    \"name\": \"mlflow-env\"\n",
+        "}\n",
+        "\n",
+        "with mlflow.start_run():\n",
+        "    logged_agent_info = mlflow.pyfunc.log_model(\n",
+        "        name=\"complaint_agent\",\n",
+        "        python_model=_agent_py_path,\n",
+        "        input_example=input_example,\n",
+        "        resources=resources,\n",
+        "        conda_env=conda_env,\n",
+        "    )\n",
+        "\n",
+        "mlflow.set_active_model(model_id = logged_agent_info.model_id)"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "23o4h7j6amzh"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### Log the Agent to Unity Catalog\n\n- Point MLflow at the Unity Catalog registry and name the artifact `${CATALOG}.ai.complaint_agent`.\n- Register the run-produced model so versioned deployments can be promoted through UC stages.",
+      "id": "ttse3kj3pcj"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.serving import EndpointStateReady\n",
+        "\n",
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "\n",
+        "UC_MODEL_NAME = f\"{CATALOG}.ai.complaint_agent\"\n",
+        "endpoint_name = dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")\n",
+        "\n",
+        "\n",
+        "def _endpoint_already_serving(name: str, uc_model_name: str) -> bool:\n",
+        "    \"\"\"Return True iff a serving endpoint is READY and already serving uc_model_name.\n",
+        "\n",
+        "    Used to short-circuit register_model + agents.deploy on re-runs of this\n",
+        "    stage when the endpoint from a previous run is still healthy — saves ~15\n",
+        "    minutes of cold container build + serving provisioning.  To force a fresh\n",
+        "    deploy after editing agent code, delete the endpoint and rerun the stage.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        ep = WorkspaceClient().serving_endpoints.get(name)\n",
+        "    except Exception:\n",
+        "        return False\n",
+        "    if not ep.state or ep.state.ready != EndpointStateReady.READY:\n",
+        "        return False\n",
+        "    cfg = getattr(ep, \"config\", None) or getattr(ep, \"pending_config\", None)\n",
+        "    if not cfg:\n",
+        "        return False\n",
+        "    served = []\n",
+        "    for se in (getattr(cfg, \"served_entities\", None) or []):\n",
+        "        n = getattr(se, \"entity_name\", None)\n",
+        "        if n:\n",
+        "            served.append(n)\n",
+        "    for sm in (getattr(cfg, \"served_models\", None) or []):\n",
+        "        n = getattr(sm, \"model_name\", None)\n",
+        "        if n:\n",
+        "            served.append(n)\n",
+        "    return uc_model_name in served\n",
+        "\n",
+        "\n",
+        "_reuse_endpoint = _endpoint_already_serving(endpoint_name, UC_MODEL_NAME)\n",
+        "\n",
+        "if _reuse_endpoint:\n",
+        "    print(\n",
+        "        f\"\\u267b\\ufe0f Endpoint {endpoint_name} is already READY and serving {UC_MODEL_NAME}; \"\n",
+        "        f\"skipping register_model + agents.deploy (saves ~15 min). \"\n",
+        "        f\"Delete the endpoint to force a fresh deploy.\"\n",
+        "    )\n",
+        "    uc_registered_model_info = None\n",
+        "else:\n",
+        "    # register the model to UC\n",
+        "    uc_registered_model_info = mlflow.register_model(\n",
+        "        model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
+        "    )"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "y8lfco9zzn"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### Deploy the Agent to Model Serving\n\n- Create a production MLflow experiment for live trace capture.\n- Use `agents.deploy` to create/update the Databricks Model Serving endpoint backed by the UC model version.\n- Wait until the serving endpoint reports READY before continuing to downstream steps.\n- Pass the prod experiment ID via environment variables so inference traces are logged automatically.",
+      "id": "me3m6ovfqkd"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "\n",
+        "# Create prod experiment for production inference traces\n",
+        "# Use shared path for job compatibility and visibility\n",
+        "prod_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_prod\"\n",
+        "\n",
+        "# set_experiment creates the experiment if it doesn't exist, or activates it if it does\n",
+        "prod_experiment = mlflow.set_experiment(prod_experiment_name)\n",
+        "prod_experiment_id = prod_experiment.experiment_id\n",
+        "print(f\"✅ Using prod experiment: {prod_experiment_name} (ID: {prod_experiment_id})\")\n",
+        "\n",
+        "# Add experiment to UC state for cleanup\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "experiment_data = {\n",
+        "    \"experiment_id\": prod_experiment_id,\n",
+        "    \"name\": prod_experiment_name\n",
+        "}\n",
+        "add(CATALOG, \"experiments\", experiment_data)\n",
+        "print(f\"✅ Added prod experiment to UC state\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "qjnjjztbbna"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from datetime import timedelta\n",
+        "\n",
+        "from databricks import agents\n",
+        "\n",
+        "if _reuse_endpoint:\n",
+        "    deployment_info = None\n",
+        "    print(f\"\\u2705 Endpoint {endpoint_name} is READY (reused from previous deploy)\")\n",
+        "else:\n",
+        "    deployment_info = agents.deploy(\n",
+        "        model_name=UC_MODEL_NAME,\n",
+        "        model_version=uc_registered_model_info.version,\n",
+        "        scale_to_zero=False,\n",
+        "        endpoint_name=endpoint_name,\n",
+        "        environment_vars={\"MLFLOW_EXPERIMENT_ID\": str(prod_experiment_id)},\n",
+        "    )\n",
+        "\n",
+        "    workspace = WorkspaceClient()\n",
+        "    ready_endpoint = workspace.serving_endpoints.wait_get_serving_endpoint_not_updating(\n",
+        "        name=endpoint_name,\n",
+        "        timeout=timedelta(minutes=30),\n",
+        "    )\n",
+        "\n",
+        "    if ready_endpoint.state.ready != EndpointStateReady.READY:\n",
+        "        raise RuntimeError(\n",
+        "            f\"Endpoint {endpoint_name} is {ready_endpoint.state.ready} after deployment; retry or investigate.\"\n",
+        "        )\n",
+        "\n",
+        "    print(f\"\\u2705 Endpoint {endpoint_name} is READY\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "exckljo2zx4"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# === Grant UC perms to the endpoint's runtime System Service Principal ===\n",
+        "#\n",
+        "# Model serving endpoints run inference as a workspace-level SCIM SP whose\n",
+        "# displayName is \"System Service Principal\".  These SPs are NOT members of\n",
+        "# `account users`, so grants made above to `account users` do NOT apply to\n",
+        "# them — every fresh endpoint would fail on its first tool call with\n",
+        "# PERMISSION_DENIED (\"USE CATALOG\" / \"USE SCHEMA\" / \"EXECUTE\") until\n",
+        "# permissions were granted manually.\n",
+        "#\n",
+        "# See utils/agent_runtime_grants.py for the full rationale.  Grants are\n",
+        "# idempotent.  Skipped on the reuse path (no fresh SP to grant to).\n",
+        "if deployment_info is not None:\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from agent_runtime_grants import grant_agent_runtime_perms\n",
+        "\n",
+        "    # Pass endpoint_name so the helper also grants to the endpoint\n",
+        "    # creator — that's the actual runtime identity in EMBEDDED_CREDENTIALS\n",
+        "    # mode workspaces (where 'System Service Principal' isn't created and\n",
+        "    # `account users` may be empty at the workspace level).\n",
+        "    grant_agent_runtime_perms(\n",
+        "        spark,\n",
+        "        CATALOG,\n",
+        "        workspace_client=workspace,\n",
+        "        endpoint_name=endpoint_name,\n",
+        "    )\n",
+        "else:\n",
+        "    print(\"♻ Endpoint reused — skipping runtime SP grants (already applied on first deploy).\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "00fc632e"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "print(deployment_info)"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "i1syfkwcivl"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### Record Model in State\n\n- Store the deployment metadata with `uc_state.add` to facilitate cleanup in the future.",
+      "id": "4i9yj8vjs2"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Also add to UC-state — but only when we actually deployed a new endpoint.\n",
+        "# On the reuse path (_reuse_endpoint) the endpoint was already registered by a\n",
+        "# previous run, so deployment_info is None and re-adding would either crash\n",
+        "# uc_state.add() or persist a null row that cleanup can't resolve.  Mirror the\n",
+        "# guard used in refunder_agent for symmetry.\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "if deployment_info is not None:\n",
+        "    add(dbutils.widgets.get(\"CATALOG\"), \"endpoints\", deployment_info)\n",
+        "else:\n",
+        "    print(\"✅ Endpoint already tracked in uc_state from a previous deploy; skipping add.\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "ihnhnv5plw"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "#### Production Monitoring\n\n- Register MLflow guideline scorers to monitor decision quality and refund reasoning on production traffic.\n- Enable 10% sampling to flag decision drift or policy regressions without impacting performance.",
+      "id": "bhjj7zuan9g"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from mlflow.genai.scorers import (\n",
+        "    Safety,\n",
+        "    RelevanceToQuery,\n",
+        "    Guidelines,\n",
+        "    ScorerSamplingConfig,\n",
+        "    list_scorers,\n",
+        ")\n",
+        "\n",
+        "\n",
+        "def _register_scorer(scorer_obj, name: str, sample_rate: float = 1.0):\n",
+        "    # Same idempotent pattern used in stages/operational_evaluation.ipynb.\n",
+        "    # On re-runs the scorer already exists in the experiment; calling .register()\n",
+        "    # would raise ValueError, so we restart the existing one instead.\n",
+        "    existing = {s.name: s for s in list_scorers(experiment_id=prod_experiment_id)}\n",
+        "    sampling = ScorerSamplingConfig(sample_rate=sample_rate)\n",
+        "    if name in existing:\n",
+        "        monitor = existing[name].start(sampling_config=sampling)\n",
+        "        print(f\"  \\u267b\\ufe0f {name} \\u2014 restarted at {sample_rate:.0%} sample rate\")\n",
+        "        return monitor\n",
+        "    registered = scorer_obj.register(name=name, experiment_id=prod_experiment_id)\n",
+        "    monitor = registered.start(sampling_config=sampling)\n",
+        "    print(f\"  \\u2705 {name} \\u2014 registered + started at {sample_rate:.0%} sample rate\")\n",
+        "    return monitor\n",
+        "\n",
+        "\n",
+        "# Baseline (every agent in the bundle gets these three).\n",
+        "_register_scorer(Safety(),           name=\"safety\",             sample_rate=1.0)\n",
+        "_register_scorer(RelevanceToQuery(), name=\"relevance_to_query\", sample_rate=1.0)\n",
+        "_register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"operational_quality\",\n",
+        "        guidelines=(\n",
+        "            \"The response must include specific data points such as numbers, \"\n",
+        "            \"percentages, dates, order IDs, complaint categories, or named locations. \"\n",
+        "            \"The response must not be a generic hedge or refusal \"\n",
+        "            \"(e.g. 'I don't have access'). \"\n",
+        "            \"The response must directly answer the question asked.\"\n",
+        "        ),\n",
+        "    ),\n",
+        "    name=\"operational_quality\",\n",
+        "    sample_rate=1.0,\n",
+        ")\n",
+        "\n",
+        "# Domain — complaint-specific decision and refund-reason guidelines.\n",
+        "decision_quality_monitor = _register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"decision_quality_prod\",\n",
+        "        guidelines=[\n",
+        "            \"Food quality complaints should be classified as 'investigate', not 'auto_credit'\",\n",
+        "            \"Missing item complaints should be classified as 'investigate', not 'auto_credit'\",\n",
+        "            \"Legal threats or serious health concerns should be classified as 'escalate'\",\n",
+        "        ],\n",
+        "    ),\n",
+        "    name=f\"{UC_MODEL_NAME}_decision_quality\",\n",
+        ")\n",
+        "\n",
+        "refund_reason_monitor = _register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"refund_reason_prod\",\n",
+        "        guidelines=[\n",
+        "            \"If a refund is offered, it must clearly relate to the complaint made by the user\",\n",
+        "        ],\n",
+        "    ),\n",
+        "    name=f\"{UC_MODEL_NAME}_refund_reason\",\n",
+        ")\n",
+        "\n",
+        "print(\"\\u2705 Production monitoring enabled — 5 scorers active at 100% sampling\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "v1j0a0y21ct"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Prompt Registry\n",
+        "\n",
+        "Register the `ComplaintTriage` signature docstring (the actual instructions the\n",
+        "DSPy ReAct agent operates on) under `{CATALOG}.prompts.complaint_system` so it\n",
+        "lives alongside the deployed model in Unity Catalog.\n",
+        "\n",
+        "**Important**: unlike the Refund agent (which calls `mlflow.genai.load_prompt`\n",
+        "at endpoint startup and so can hot-swap), the Complaint agent's prompt is\n",
+        "baked into the DSPy Signature class at model-log time. Registry entries here\n",
+        "are **audit / governance**, not runtime hot-swap. Changing the production\n",
+        "prompt requires a redeploy that bakes the new docstring into a new model\n",
+        "version.\n",
+        "\n",
+        "The registry is seeded with **three versions** on first deploy\n",
+        "(v1 → v2 → v3) so the MLflow Prompt Registry UI shows a meaningful version\n",
+        "history. The seeded versions are tagged `is_demo_seed=\"true\"` to make it\n",
+        "clear they're synthetic baselines, not a real engineering changelog."
+      ],
+      "id": "60e5b88f"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "import sys\n",
+        "\n",
+        "sys.path.append('../utils')\n",
+        "from prompt_registry import seed_prompt_history\n",
+        "\n",
+        "# Use the absolute path captured by %%writefilev (see cell 14) so this works\n",
+        "# even when CWD has drifted between cells (notebooks on serverless / shared\n",
+        "# clusters don't have a stable CWD across %pip installs and kernel restarts).\n",
+        "_agent_py_path = _WRITEFILEV_ABS_PATHS.get(\"agent.py\", \"agent.py\")\n",
+        "with open(_agent_py_path) as f:\n",
+        "    _agent_py = f.read()\n",
+        "\n",
+        "# Extract the ComplaintTriage signature docstring — that's the prompt content\n",
+        "# DSPy ReAct uses to drive the agent. NOTE: DSPy adds its own ReAct scaffold\n",
+        "# around this at runtime; the registry entry captures only the domain\n",
+        "# instructions, which is the part a human would actually iterate on.\n",
+        "_match = re.search(\n",
+        "    r'class ComplaintTriage\\(dspy\\.Signature\\):\\s*\"\"\"(.*?)\"\"\"',\n",
+        "    _agent_py,\n",
+        "    re.DOTALL,\n",
+        ")\n",
+        "if not _match:\n",
+        "    raise RuntimeError(\n",
+        "        \"Could not extract ComplaintTriage docstring from agent.py. \"\n",
+        "        \"If the Signature class was renamed, update this regex.\"\n",
+        "    )\n",
+        "_current_complaint_prompt = _match.group(1).strip()\n",
+        "\n",
+        "# Two earlier versions, seeded on first deploy so the Prompt Registry UI shows\n",
+        "# v1 → v2 → v3 history. These are demo seeds, NOT a real engineering changelog\n",
+        "# — seed_prompt_history tags each with is_demo_seed=\"true\" so anyone auditing\n",
+        "# the registry can tell synthetic baselines apart from real iterations.\n",
+        "_COMPLAINT_V1 = (\n",
+        "    \"Analyze customer complaints and recommend a triage action.\\n\\n\"\n",
+        "    \"For each complaint:\\n\"\n",
+        "    \"- Extract the order_id\\n\"\n",
+        "    \"- Choose a decision: suggest_credit OR escalate\\n\"\n",
+        "    \"- Provide a rationale\\n\\n\"\n",
+        "    \"Output: order_id, decision, rationale.\"\n",
+        ")\n",
+        "_COMPLAINT_V2 = (\n",
+        "    \"Analyze customer complaints for Casper's Kitchens and recommend triage actions.\\n\\n\"\n",
+        "    \"Process:\\n\"\n",
+        "    \"1. Extract order_id from complaint\\n\"\n",
+        "    \"2. Use get_order_overview(order_id) for order details and items\\n\"\n",
+        "    \"3. Make a decision: suggest_credit (with credit_amount) or escalate (with priority)\\n\\n\"\n",
+        "    \"Decision Framework:\\n\\n\"\n",
+        "    \"SUGGEST_CREDIT:\\n\"\n",
+        "    \"- Delivery delays: 10-20% of order total\\n\"\n",
+        "    \"- Missing items: estimate $10 per item\\n\"\n",
+        "    \"- Food quality: 20-40% of order total based on severity\\n\\n\"\n",
+        "    \"ESCALATE:\\n\"\n",
+        "    \"- priority=\\\"standard\\\": vague complaints, billing issues, service complaints\\n\"\n",
+        "    \"- priority=\\\"urgent\\\": legal threats, health/safety concerns, abusive language\\n\\n\"\n",
+        "    \"Output: order_id, complaint_category, decision, credit_amount, confidence, priority, rationale.\"\n",
+        ")\n",
+        "\n",
+        "_uc_version = (\n",
+        "    uc_registered_model_info.version\n",
+        "    if \"uc_registered_model_info\" in dir() and uc_registered_model_info is not None\n",
+        "    else \"reused-endpoint\"\n",
+        ")\n",
+        "\n",
+        "_common_tags = {\n",
+        "    \"agent\": \"complaint\",\n",
+        "    \"stage\": \"complaint_agent\",\n",
+        "    \"uc_model\": UC_MODEL_NAME,\n",
+        "    \"consumed_via\": \"baked into DSPy Signature docstring at model-log time (no runtime hot-swap)\",\n",
+        "}\n",
+        "\n",
+        "seed_prompt_history(\n",
+        "    spark=spark,\n",
+        "    catalog=CATALOG,\n",
+        "    name=\"complaint_system\",\n",
+        "    historical=[\n",
+        "        {\n",
+        "            \"template\": _COMPLAINT_V1,\n",
+        "            \"commit_message\": \"v1: minimal triage — decision + rationale only, no tool use (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "        {\n",
+        "            \"template\": _COMPLAINT_V2,\n",
+        "            \"commit_message\": \"v2: added decision framework with categories + flat credit heuristics (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "    ],\n",
+        "    current={\n",
+        "        \"template\": _current_complaint_prompt,\n",
+        "        \"commit_message\": f\"v3 (production): percentile-based credit calc + get_order_timing/get_location_timings tools — UC model version {_uc_version}\",\n",
+        "        \"tags\": {**_common_tags, \"uc_model_version\": str(_uc_version)},\n",
+        "    },\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "9f25ed8c"
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9.0"
+    }
   },
-  {
-   "cell_type": "markdown",
-   "id": "cell-1",
-   "metadata": {},
-   "source": [
-    "#### Tool & View Registration\n",
-    "\n",
-    "- `CREATE SCHEMA` guarantees the shared `${CATALOG}.ai` workspace exists for agent assets.\n",
-    "- `order_delivery_times_per_location_view` summarizes delivery percentiles per brand/location.\n",
-    "- `get_order_overview(oid)` returns structured order metadata, items, and customer info.\n",
-    "- `get_order_timing(oid)` exposes created/delivered timestamps plus transit duration.\n",
-    "- `get_location_timings(loc)` yields P50/P75/P99 delivery benchmarks for benchmarking complaints.\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cell-2",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.ai;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "tdy6yy3gheg",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE VIEW ${CATALOG}.ai.order_delivery_times_per_location_view AS\n",
-    "WITH order_times AS (\n",
-    "  SELECT\n",
-    "    order_id,\n",
-    "    location,\n",
-    "    MAX(CASE WHEN event_type = 'order_created' THEN try_to_timestamp(ts) END) AS order_created_time,\n",
-    "    MAX(CASE WHEN event_type = 'delivered' THEN try_to_timestamp(ts) END) AS delivered_time\n",
-    "  FROM\n",
-    "    ${CATALOG}.lakeflow.all_events\n",
-    "  WHERE\n",
-    "    try_to_timestamp(ts) >= CURRENT_TIMESTAMP() - INTERVAL 1 DAY\n",
-    "  GROUP BY\n",
-    "    order_id,\n",
-    "    location\n",
-    "),\n",
-    "total_order_times AS (\n",
-    "  SELECT\n",
-    "    order_id,\n",
-    "    location,\n",
-    "    (UNIX_TIMESTAMP(delivered_time) - UNIX_TIMESTAMP(order_created_time)) / 60 AS total_order_time_minutes\n",
-    "  FROM\n",
-    "    order_times\n",
-    "  WHERE\n",
-    "    order_created_time IS NOT NULL\n",
-    "    AND delivered_time IS NOT NULL\n",
-    ")\n",
-    "SELECT\n",
-    "  location,\n",
-    "  PERCENTILE(total_order_time_minutes, 0.50) AS P50,\n",
-    "  PERCENTILE(total_order_time_minutes, 0.75) AS P75,\n",
-    "  PERCENTILE(total_order_time_minutes, 0.99) AS P99\n",
-    "FROM\n",
-    "  total_order_times\n",
-    "GROUP BY\n",
-    "  location"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cell-3",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_overview(oid STRING COMMENT 'The unique order identifier to retrieve information for')\n",
-    "RETURNS TABLE (\n",
-    "  order_id STRING COMMENT 'The order id',\n",
-    "  location STRING COMMENT 'Order location',\n",
-    "  items_json STRING COMMENT 'JSON array of ordered items with details',\n",
-    "  customer_address STRING COMMENT 'Customer delivery address',\n",
-    "  brand_id BIGINT COMMENT 'Brand ID for the order',\n",
-    "  order_created_ts TIMESTAMP COMMENT 'When the order was created'\n",
-    ")\n",
-    "COMMENT 'Returns basic order information including items, location, and customer details'\n",
-    "RETURN\n",
-    "  WITH order_created_events AS (\n",
-    "    SELECT\n",
-    "      order_id,\n",
-    "      location,\n",
-    "      get_json_object(body, '$.items') as items_json,\n",
-    "      get_json_object(body, '$.customer_addr') as customer_address,\n",
-    "      -- Extract brand_id from first item in the order\n",
-    "      CAST(get_json_object(get_json_object(body, '$.items[0]'), '$.brand_id') AS BIGINT) as brand_id,\n",
-    "      try_to_timestamp(ts) as order_created_ts\n",
-    "    FROM ${CATALOG}.lakeflow.all_events\n",
-    "    WHERE order_id = oid AND event_type = 'order_created'\n",
-    "    LIMIT 1\n",
-    "  )\n",
-    "  SELECT\n",
-    "    order_id,\n",
-    "    location,\n",
-    "    items_json,\n",
-    "    customer_address,\n",
-    "    brand_id,\n",
-    "    order_created_ts\n",
-    "  FROM order_created_events;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cell-4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_timing(oid STRING COMMENT 'The unique order identifier to get timing information for')\n",
-    "RETURNS TABLE (\n",
-    "  order_id STRING COMMENT 'The order id',\n",
-    "  order_created_ts TIMESTAMP COMMENT 'When the order was created',\n",
-    "  delivered_ts TIMESTAMP COMMENT 'When the order was delivered (NULL if not delivered)',\n",
-    "  delivery_duration_minutes FLOAT COMMENT 'Time from order creation to delivery in minutes (NULL if not delivered)',\n",
-    "  delivery_status STRING COMMENT 'Current delivery status: delivered, in_progress, or unknown'\n",
-    ")\n",
-    "COMMENT 'Returns timing information for a specific order'\n",
-    "RETURN\n",
-    "  WITH order_events AS (\n",
-    "    SELECT\n",
-    "      order_id,\n",
-    "      event_type,\n",
-    "      try_to_timestamp(ts) as event_ts\n",
-    "    FROM ${CATALOG}.lakeflow.all_events\n",
-    "    WHERE order_id = oid\n",
-    "  ),\n",
-    "  timing_summary AS (\n",
-    "    SELECT\n",
-    "      order_id,\n",
-    "      MIN(CASE WHEN event_type = 'order_created' THEN event_ts END) as order_created_ts,\n",
-    "      MAX(CASE WHEN event_type = 'delivered' THEN event_ts END) as delivered_ts\n",
-    "    FROM order_events\n",
-    "    GROUP BY order_id\n",
-    "  )\n",
-    "  SELECT\n",
-    "    order_id,\n",
-    "    order_created_ts,\n",
-    "    delivered_ts,\n",
-    "    CASE\n",
-    "      WHEN delivered_ts IS NOT NULL AND order_created_ts IS NOT NULL THEN\n",
-    "        CAST((UNIX_TIMESTAMP(delivered_ts) - UNIX_TIMESTAMP(order_created_ts)) / 60 AS FLOAT)\n",
-    "      ELSE NULL\n",
-    "    END as delivery_duration_minutes,\n",
-    "    CASE\n",
-    "      WHEN delivered_ts IS NOT NULL THEN 'delivered'\n",
-    "      WHEN order_created_ts IS NOT NULL THEN 'in_progress'\n",
-    "      ELSE 'unknown'\n",
-    "    END as delivery_status\n",
-    "  FROM timing_summary;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cell-5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_location_timings(loc STRING COMMENT 'Location name as a string')\n",
-    "RETURNS TABLE (\n",
-    "  location STRING COMMENT 'Location of the order source',\n",
-    "  P50 FLOAT COMMENT '50th percentile delivery time in minutes',\n",
-    "  P75 FLOAT COMMENT '75th percentile delivery time in minutes',\n",
-    "  P99 FLOAT COMMENT '99th percentile delivery time in minutes'\n",
-    ")\n",
-    "COMMENT 'Returns the 50/75/99th percentile of delivery times for a location to benchmark order timing'\n",
-    "RETURN\n",
-    "  SELECT location, P50, P75, P99\n",
-    "  FROM ${CATALOG}.ai.order_delivery_times_per_location_view AS odlt\n",
-    "  WHERE odlt.location = loc;"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "dq5ml4wp6v",
-   "metadata": {},
-   "source": "#### Model\n\n- Install DSPy, Databricks agent packages, and restart Python for a clean runtime.\n- Capture widget inputs (`CATALOG`, `LLM_MODEL`) and create an MLflow dev experiment for trace logging.\n- Define a templated `%%writefilev` magic that emits files with notebook variable substitution.\n- Materialize `agent.py` containing the DSPy ReAct complaint workflow wired to UC SQL tools and the chosen LLM endpoint.\n- Pull a delivered `order_id` sample and build the MLflow model signature/resources for logging."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "bd3tu3r2gso",
-   "metadata": {},
-   "outputs": [],
-   "source": "%pip install -U -qqqq typing_extensions dspy-ai mlflow unitycatalog-openai[databricks] openai databricks-sdk databricks-agents pydantic\n%restart_python"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "dl04kgwv9ap",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ktoahik8tl",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import mlflow\n",
-    "\n",
-    "# Create/set dev experiment for development and evaluation traces\n",
-    "# Use shared path for job compatibility\n",
-    "dev_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_dev\"\n",
-    "\n",
-    "# set_experiment creates the experiment if it doesn't exist, or activates it if it does\n",
-    "dev_experiment = mlflow.set_experiment(dev_experiment_name)\n",
-    "dev_experiment_id = dev_experiment.experiment_id\n",
-    "print(f\"✅ Using dev experiment: {dev_experiment_name} (ID: {dev_experiment_id})\")\n",
-    "\n",
-    "# Add experiment to UC state for cleanup\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "experiment_data = {\n",
-    "    \"experiment_id\": dev_experiment_id,\n",
-    "    \"name\": dev_experiment_name\n",
-    "}\n",
-    "add(CATALOG, \"experiments\", experiment_data)\n",
-    "print(f\"✅ Added dev experiment to UC state\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "bruu85upqq5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import re\n",
-    "from IPython.core.magic import register_cell_magic\n",
-    "\n",
-    "@register_cell_magic\n",
-    "def writefilev(line, cell):\n",
-    "    \"\"\"\n",
-    "    %%writefilev file.py\n",
-    "    Allows {{var}} substitutions while leaving normal {} intact.\n",
-    "    \"\"\"\n",
-    "    filename = line.strip()\n",
-    "\n",
-    "    def replacer(match):\n",
-    "        expr = match.group(1)\n",
-    "        return str(eval(expr, globals(), locals()))\n",
-    "\n",
-    "    # Replace only double braces {{var}}\n",
-    "    content = re.sub(r\"\\{\\{(.*?)\\}\\}\", replacer, cell)\n",
-    "\n",
-    "    with open(filename, \"w\") as f:\n",
-    "        f.write(content)\n",
-    "    print(f\"Wrote file with substitutions: {filename}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "w2c70l4ca8",
-   "metadata": {},
-   "outputs": [],
-   "source": "%%writefilev agent.py\nimport warnings\nfrom typing import Optional, Literal\nfrom uuid import uuid4\nfrom pydantic import BaseModel, Field, field_validator, ValidationError\n\nwarnings.filterwarnings(\"ignore\", message=\".*Ignoring the default notebook Spark session.*\")\n\nimport dspy\nimport mlflow\nfrom unitycatalog.ai.core.base import get_uc_function_client\nfrom mlflow.pyfunc import ResponsesAgent\nfrom mlflow.types.responses import (\n    ResponsesAgentRequest,\n    ResponsesAgentResponse,\n)\n\n# Enable DSPy autologging for automatic trace capture\nmlflow.dspy.autolog(log_traces=True)\n\nLLM_MODEL = \"{{LLM_MODEL}}\"\nCATALOG = \"{{CATALOG}}\"\n\n# Configure DSPy with Databricks LM\nlm = dspy.LM(f'databricks/{LLM_MODEL}', max_tokens=2000)\ndspy.configure(lm=lm)\n\n# Initialize UC function client\nuc_client = get_uc_function_client()\n\n\nclass ComplaintResponse(BaseModel):\n    \"\"\"Structured output for complaint triage decisions.\"\"\"\n    order_id: str\n    complaint_category: Literal[\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"billing\", \"other\"] = Field(\n        description=\"Exactly ONE primary complaint category\"\n    )\n    decision: Literal[\"suggest_credit\", \"escalate\"]\n    credit_amount: Optional[float] = None\n    confidence: Optional[Literal[\"high\", \"medium\", \"low\"]] = None\n    priority: Optional[Literal[\"standard\", \"urgent\"]] = None\n    rationale: str\n    \n    @field_validator('complaint_category', mode='before')\n    @classmethod\n    def parse_category(cls, v):\n        \"\"\"Extract first valid category if multiple provided.\"\"\"\n        if not isinstance(v, str):\n            return v\n            \n        valid_categories = [\"delivery_delay\", \"missing_items\", \"food_quality\", \"service_issue\", \"billing\", \"other\"]\n        v_lower = v.lower().strip()\n        \n        # Exact match\n        if v_lower in valid_categories:\n            return v_lower\n        \n        # Find first valid category in string\n        for cat in valid_categories:\n            if cat in v_lower:\n                return cat\n        \n        return \"other\"\n    \n    @field_validator('confidence', mode='before')\n    @classmethod\n    def parse_confidence(cls, v):\n        \"\"\"Ensure valid confidence value.\"\"\"\n        if v is None or (isinstance(v, str) and v.lower() == \"null\"):\n            return None\n        if isinstance(v, str):\n            v_lower = v.lower().strip()\n            if v_lower in [\"high\", \"medium\", \"low\"]:\n                return v_lower\n            return \"medium\"\n        return v\n    \n    @field_validator('priority', mode='before')\n    @classmethod\n    def parse_priority(cls, v):\n        \"\"\"Ensure valid priority value.\"\"\"\n        if v is None or (isinstance(v, str) and v.lower() == \"null\"):\n            return None\n        if isinstance(v, str):\n            v_lower = v.lower().strip()\n            if v_lower in [\"standard\", \"urgent\"]:\n                return v_lower\n            return \"standard\"\n        return v\n\n\nclass ComplaintTriage(dspy.Signature):\n    \"\"\"Analyze customer complaints for Casper's Kitchens and recommend triage actions.\n    \n    Process:\n    1. Extract order_id from complaint\n    2. Use get_order_overview(order_id) for order details and items\n    3. Use get_order_timing(order_id) for delivery timing\n    4. For delays, use get_location_timings(location) for percentile benchmarks\n    5. Make data-backed decision\n    \n    Decision Framework:\n    \n    SUGGEST_CREDIT (with credit_amount and confidence):\n    - Delivery delays: Compare actual delivery time to location percentiles\n      * <P75: Suggest $0 credit (low confidence - on-time or minimal delay)\n      * P75-P99: Suggest 15% of order total (medium to high confidence)\n      * >P99: Suggest 25% of order total (high confidence)\n    - Missing items: Use actual item prices from order data when available\n      * Verify claimed item exists in order (affects confidence)\n      * Use real costs from order data, or estimate $8-12 per item if unavailable\n    - Food quality: 20-40% of order total based on severity\n      * Minor issues (slightly cold, minor preparation issue): 20% (medium confidence)\n      * Major issues (completely inedible, wrong preparation, health concern): 40% (high confidence)\n      * Vague complaints (\"bad\", \"gross\"): escalate instead\n    \n    ESCALATE (with priority):\n    - priority=\"standard\": Vague complaints, missing data, billing issues, service complaints\n    - priority=\"urgent\": Legal threats, health/safety concerns, suspected fraud, abusive language\n    \n    Output Requirements:\n    - For suggest_credit: credit_amount is REQUIRED and must be a number (can be 0.0 if no credit warranted), confidence is REQUIRED, priority must be null\n    - For escalate: priority is REQUIRED, credit_amount and confidence must be null\n    - complaint_category: Choose EXACTLY ONE category (the primary one)\n    - Rationale must cite specific evidence (delivery times, percentiles, item verification, order total)\n    - Rationale should be detailed but under 150 words\n    - Round credit amounts to nearest $0.50\n    - Confidence: high (strong data), medium (reasonable inference), low (weak/contradictory)\n    \"\"\"\n    \n    complaint: str = dspy.InputField(desc=\"Customer complaint text\")\n    order_id: str = dspy.OutputField(desc=\"Extracted order ID\")\n    complaint_category: str = dspy.OutputField(desc=\"EXACTLY ONE category: delivery_delay, missing_items, food_quality, service_issue, billing, or other\")\n    decision: str = dspy.OutputField(desc=\"EXACTLY ONE: suggest_credit or escalate\")\n    credit_amount: str = dspy.OutputField(desc=\"If suggest_credit: MUST be a number (e.g., 0.0, 10.5). If escalate: null\")\n    confidence: str = dspy.OutputField(desc=\"If suggest_credit: EXACTLY ONE of high, medium, low. If escalate: null\")\n    priority: str = dspy.OutputField(desc=\"If escalate: EXACTLY ONE of standard or urgent. If suggest_credit: null\")\n    rationale: str = dspy.OutputField(desc=\"Data-focused justification citing specific evidence\")\n\n\n# Unity Catalog tool wrappers\ndef get_order_overview(order_id: str) -> str:\n    \"\"\"Get order details including items, location, and customer info.\"\"\"\n    result = uc_client.execute_function(\n        f\"{CATALOG}.ai.get_order_overview\",\n        {\"oid\": order_id}\n    )\n    return str(result.value)\n\n\ndef get_order_timing(order_id: str) -> str:\n    \"\"\"Get timing information for a specific order.\"\"\"\n    result = uc_client.execute_function(\n        f\"{CATALOG}.ai.get_order_timing\",\n        {\"oid\": order_id}\n    )\n    return str(result.value)\n\n\ndef get_location_timings(location: str) -> str:\n    \"\"\"Get delivery time percentiles for a specific location.\"\"\"\n    result = uc_client.execute_function(\n        f\"{CATALOG}.ai.get_location_timings\",\n        {\"loc\": location}\n    )\n    return str(result.value)\n\n\nclass ComplaintTriageModule(dspy.Module):\n    \"\"\"DSPy module for complaint triage with tool calling.\"\"\"\n    \n    def __init__(self):\n        super().__init__()\n        self.react = dspy.ReAct(\n            signature=ComplaintTriage,\n            tools=[get_order_overview, get_order_timing, get_location_timings],\n            max_iters=10\n        )\n    \n    def forward(self, complaint: str, max_retries: int = 2) -> ComplaintResponse:\n        \"\"\"Process complaint and return structured triage decision with retry on validation failure.\"\"\"\n        \n        for attempt in range(max_retries + 1):\n            try:\n                result = self.react(complaint=complaint)\n                \n                # Parse credit_amount\n                credit_amount = None\n                if result.credit_amount and result.credit_amount.lower() != \"null\":\n                    try:\n                        credit_amount = float(result.credit_amount)\n                    except (ValueError, TypeError):\n                        if result.decision == \"suggest_credit\":\n                            raise ValidationError(\"suggest_credit requires valid numeric credit_amount\")\n                \n                # Validate business rules before Pydantic construction\n                if result.decision == \"suggest_credit\" and credit_amount is None:\n                    raise ValidationError(\"suggest_credit requires credit_amount to be a number (can be 0.0)\")\n                \n                # Construct Pydantic model - field validators run here\n                return ComplaintResponse(\n                    order_id=result.order_id,\n                    complaint_category=result.complaint_category,\n                    decision=result.decision,\n                    credit_amount=credit_amount,\n                    confidence=result.confidence,\n                    priority=result.priority,\n                    rationale=result.rationale\n                )\n                \n            except (ValidationError, ValueError) as e:\n                if attempt < max_retries:\n                    # Retry - DSPy will regenerate with potentially different output\n                    continue\n                else:\n                    # Final attempt failed - re-raise\n                    raise\n\n\nclass DSPyComplaintAgent(ResponsesAgent):\n    \"\"\"ResponsesAgent wrapper for DSPy complaint triage module.\"\"\"\n    \n    def __init__(self):\n        self.module = ComplaintTriageModule()\n    \n    def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:\n        \"\"\"Process complaint request and return structured response.\"\"\"\n        complaint = None\n        for msg in request.input:\n            msg_dict = msg.model_dump() if hasattr(msg, \"model_dump\") else msg\n            if msg_dict.get(\"role\") == \"user\":\n                complaint = msg_dict.get(\"content\", \"\")\n                break\n        \n        if not complaint:\n            raise ValueError(\"No user message found in request\")\n        \n        result = self.module(complaint=complaint)\n        \n        return ResponsesAgentResponse(\n            output=[\n                self.create_text_output_item(\n                    text=result.model_dump_json(),\n                    id=str(uuid4())\n                )\n            ],\n            custom_outputs=request.custom_inputs\n        )\n\n\n# Initialize agent\nAGENT = DSPyComplaintAgent()\nmlflow.models.set_model(AGENT)"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "dd6gjrp4mx6",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# get an actual order_id for input example\n",
-    "sample_order_id = spark.sql(f\"\"\"\n",
-    "    SELECT order_id \n",
-    "    FROM {CATALOG}.lakeflow.all_events \n",
-    "    WHERE event_type='delivered'\n",
-    "    LIMIT 1\n",
-    "\"\"\").collect()[0]['order_id']"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ih3tt5qeb5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "assert sample_order_id is not None\n",
-    "print(sample_order_id)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "23o4h7j6amzh",
-   "metadata": {},
-   "outputs": [],
-   "source": "import mlflow\nfrom agent import LLM_MODEL\nfrom mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint\nfrom pkg_resources import get_distribution\n\nresources = [DatabricksServingEndpoint(endpoint_name=LLM_MODEL)]\n# Add UC function resources\nuc_tool_names = [\n    f\"{CATALOG}.ai.get_order_overview\",\n    f\"{CATALOG}.ai.get_order_timing\",\n    f\"{CATALOG}.ai.get_location_timings\",\n]\nfor func_name in uc_tool_names:\n    resources.append(DatabricksFunction(function_name=func_name))\n\ninput_example = {\n    \"input\": [\n        {\n            \"role\": \"user\",\n            \"content\": f\"My order was really late! Order ID: {sample_order_id}\"\n        }\n    ]\n}\n\n# Create custom conda environment with mlflow explicitly specified\nconda_env = {\n    \"channels\": [\"conda-forge\"],\n    \"dependencies\": [\n        \"python=3.11\",\n        \"pip\",\n        {\n            \"pip\": [\n                \"mlflow==3.6\",\n                f\"typing_extensions=={get_distribution('typing_extensions').version}\",\n                f\"dspy-ai=={get_distribution('dspy-ai').version}\",\n                f\"unitycatalog-openai[databricks]=={get_distribution('unitycatalog-openai').version}\",\n                f\"pydantic=={get_distribution('pydantic').version}\",\n            ]\n        }\n    ],\n    \"name\": \"mlflow-env\"\n}\n\nwith mlflow.start_run():\n    logged_agent_info = mlflow.pyfunc.log_model(\n        name=\"complaint_agent\",\n        python_model=\"agent.py\",\n        input_example=input_example,\n        resources=resources,\n        conda_env=conda_env,\n    )\n\nmlflow.set_active_model(model_id = logged_agent_info.model_id)"
-  },
-  {
-   "cell_type": "markdown",
-   "id": "gfympowd7q",
-   "metadata": {},
-   "source": "#### Evaluate the Agent\n\n- Synthesize diverse complaint scenarios from recent orders covering delivery delays, food quality issues, missing items, service complaints, and edge cases.\n- Configure MLflow `Guidelines` scorers to evaluate evidence-based reasoning, credit amount reasonableness, and decision metadata consistency.\n- Run batch evaluations with rate limiting (2s delay per request) to quantify decision quality before promotion."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "2loovjto96g",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Comprehensive complaint scenarios for evaluation\n",
-    "import random\n",
-    "\n",
-    "# Get sample order IDs for different scenarios\n",
-    "all_order_ids = [\n",
-    "    row['order_id'] for row in spark.sql(f\"\"\"\n",
-    "        SELECT DISTINCT order_id \n",
-    "        FROM {CATALOG}.lakeflow.all_events \n",
-    "        WHERE event_type='delivered'\n",
-    "        LIMIT 50\n",
-    "    \"\"\").collect()\n",
-    "]\n",
-    "\n",
-    "# Create diverse, realistic complaint scenarios\n",
-    "complaint_scenarios = []\n",
-    "\n",
-    "# 1. Delivery delay complaints - mix of legitimate and questionable\n",
-    "for oid in all_order_ids[:8]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"My order took forever to arrive! Order ID: {oid}\",\n",
-    "        f\"Been waiting 2 hours, this is ridiculous. Order {oid}\",\n",
-    "        f\"Order {oid} arrived late and cold\",\n",
-    "        f\"Delivery was slower than usual for order {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 2. Food quality issues - range from specific to vague\n",
-    "for oid in all_order_ids[8:12]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"My falafel was completely soggy and inedible. Order: {oid}\",\n",
-    "        f\"The food was cold when it arrived, very disappointing. Order: {oid}\",\n",
-    "        f\"Everything tasted bad. Order {oid}\",\n",
-    "        f\"Not happy with the quality. {oid}\",\n",
-    "        f\"The gyro meat was overcooked and dry, very disappointing. Order: {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 3. Missing items - some verifiable, some suspicious\n",
-    "for oid in all_order_ids[12:16]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"My entire falafel bowl was missing from the order! Order: {oid}\",\n",
-    "        f\"No drinks or sides in my order {oid}\",\n",
-    "        f\"Missing my gyro from order {oid}\",\n",
-    "        f\"You forgot half my items. {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 4. Items claimed that might not match the order\n",
-    "for oid in all_order_ids[16:18]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"Where are my chicken wings?! Order {oid}\",\n",
-    "        f\"Missing my pizza from order {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 5. Service issues - should escalate\n",
-    "for oid in all_order_ids[18:20]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"Your driver was extremely rude to me. Order: {oid}\",\n",
-    "        f\"Driver left my food at wrong address. Order: {oid}\",\n",
-    "        f\"The delivery person refused to come to my door. {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 6. Multiple issues in one complaint\n",
-    "for oid in all_order_ids[20:22]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"Order {oid} was late AND missing items AND cold!\",\n",
-    "        f\"Late delivery, rude driver, and food quality was poor. Order: {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# 7. Escalation triggers - legal threats, health concerns\n",
-    "for oid in all_order_ids[22:24]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"I'm calling my lawyer about this terrible service! Order: {oid}\",\n",
-    "        f\"This food made me sick, possible food poisoning. Order: {oid}\",\n",
-    "        f\"Found a piece of plastic in my food! Order {oid} - this is dangerous!\",\n",
-    "    ])\n",
-    "\n",
-    "# 8. Vague complaints without specifics\n",
-    "for oid in all_order_ids[24:26]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"Not satisfied with order {oid}\",\n",
-    "        f\"Bad experience. {oid}\",\n",
-    "        f\"Order {oid} was wrong\",\n",
-    "    ])\n",
-    "\n",
-    "# 9. Billing/promo issues\n",
-    "for oid in all_order_ids[26:28]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"My promo code didn't work on order {oid}\",\n",
-    "        f\"I was charged twice for order {oid}!\",\n",
-    "    ])\n",
-    "\n",
-    "# 10. Edge cases - no order ID or invalid format\n",
-    "complaint_scenarios.extend([\n",
-    "    \"My order was really late and the food was cold!\",  # Missing order ID\n",
-    "    \"terrible service, do better\",  # No order ID, vague\n",
-    "    \"Order ABC123 never arrived\",  # Invalid order ID format\n",
-    "])\n",
-    "\n",
-    "# 11. Non-complaints / comments\n",
-    "for oid in all_order_ids[28:30]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"Great food, loved it! Order {oid}\",  # Positive comment\n",
-    "        f\"Just wanted to say the driver was very polite today. {oid}\",  # Positive feedback\n",
-    "        f\"How do I reorder my previous order {oid}?\",  # Question, not complaint\n",
-    "    ])\n",
-    "\n",
-    "# 12. Unfounded complaints (on-time delivery but claiming delay)\n",
-    "for oid in all_order_ids[30:32]:\n",
-    "    complaint_scenarios.extend([\n",
-    "        f\"This took way too long! Order {oid}\",\n",
-    "    ])\n",
-    "\n",
-    "# Sample for reasonable eval size (aim for ~25-30 scenarios)\n",
-    "complaint_scenarios = random.sample(complaint_scenarios, min(30, len(complaint_scenarios)))\n",
-    "\n",
-    "# Wrap in correct input schema for ResponsesAgent\n",
-    "data = []\n",
-    "for complaint in complaint_scenarios:\n",
-    "    data.append({\n",
-    "        \"inputs\": {\n",
-    "            \"input\": [{\n",
-    "                \"role\": \"user\",\n",
-    "                \"content\": complaint\n",
-    "            }]\n",
-    "        }\n",
-    "    })\n",
-    "\n",
-    "print(f\"Created {len(data)} diverse evaluation scenarios including:\")\n",
-    "print(\"  - Delivery delays (legitimate & questionable)\")\n",
-    "print(\"  - Food quality issues (specific & vague)\")\n",
-    "print(\"  - Missing items (verifiable & suspicious)\")\n",
-    "print(\"  - Service complaints\")\n",
-    "print(\"  - Escalation triggers (health/legal)\")\n",
-    "print(\"  - Edge cases (no order ID, invalid ID)\")\n",
-    "print(\"  - Non-complaints (positive feedback, questions)\")\n",
-    "print(\"  - Multiple issues in one complaint\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "9l6zrp5n03b",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Create three focused scorers and run evaluation\n",
-    "\n",
-    "from mlflow.genai.scorers import Guidelines\n",
-    "import mlflow\n",
-    "import sys\n",
-    "import os\n",
-    "import time\n",
-    "sys.path.append(os.getcwd())\n",
-    "\n",
-    "notebook_path = dbutils.notebook.entry_point.getDbutils().notebook().getContext().notebookPath().get()\n",
-    "project_directory = os.path.dirname(notebook_path)\n",
-    "sys.path.append(project_directory)\n",
-    "\n",
-    "from agent import AGENT\n",
-    "\n",
-    "# Scorer 1: Evidence-Based Reasoning - Does the rationale support the decision?\n",
-    "evidence_reasoning = Guidelines(\n",
-    "    name=\"evidence_reasoning\",\n",
-    "    guidelines=[\n",
-    "        \"The rationale should provide specific evidence or reasoning for the decision made\",\n",
-    "        \"For timing complaints, rationale should mention delivery times or timing data if available\",\n",
-    "        \"For missing item complaints, rationale should reference the items in question\",\n",
-    "        \"For escalations, rationale should explain why human judgment is needed\"\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "# Scorer 2: Credit Amount Reasonableness - Is the refund amount appropriate?\n",
-    "credit_reasonableness = Guidelines(\n",
-    "    name=\"credit_reasonableness\",\n",
-    "    guidelines=[\n",
-    "        \"If decision='escalate', automatically pass this check\",\n",
-    "        \"If decision='suggest_credit' with credit_amount > $0, amount should be reasonable ($5-$50)\",\n",
-    "        \"A credit_amount of $0 is valid when rationale indicates no issue\"\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "# Scorer 3: Decision Metadata Consistency - Are confidence and priority used correctly?\n",
-    "decision_metadata = Guidelines(\n",
-    "    name=\"decision_metadata\",\n",
-    "    guidelines=[\n",
-    "        \"If decision='suggest_credit': confidence should be present and priority should be null\",\n",
-    "        \"If decision='escalate': priority should be present and confidence should be null\"\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "# ResponsesAgent predict wrapper with rate limiting\n",
-    "def predict_fn(input):\n",
-    "    from mlflow.types.responses import ResponsesAgentRequest\n",
-    "    time.sleep(2)  # Rate limiting to avoid hitting API limits\n",
-    "    request = ResponsesAgentRequest(input=input)\n",
-    "    response = AGENT.predict(request)\n",
-    "    output_item = response.output[-1]\n",
-    "    if hasattr(output_item, 'content') and output_item.content:\n",
-    "        return output_item.content[0][\"text\"]\n",
-    "    return str(output_item)\n",
-    "\n",
-    "# Run evaluation\n",
-    "results = mlflow.genai.evaluate(\n",
-    "    data=data,\n",
-    "    scorers=[evidence_reasoning, credit_reasonableness, decision_metadata],\n",
-    "    predict_fn=predict_fn\n",
-    ")\n",
-    "\n",
-    "print(f\"✅ Evaluation complete\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "ttse3kj3pcj",
-   "metadata": {},
-   "source": "#### Log the Agent to Unity Catalog\n\n- Point MLflow at the Unity Catalog registry and name the artifact `${CATALOG}.ai.complaint_agent`.\n- Register the run-produced model so versioned deployments can be promoted through UC stages."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "y8lfco9zzn",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "mlflow.set_registry_uri(\"databricks-uc\")\n",
-    "\n",
-    "UC_MODEL_NAME = f\"{CATALOG}.ai.complaint_agent\"\n",
-    "\n",
-    "# register the model to UC\n",
-    "uc_registered_model_info = mlflow.register_model(\n",
-    "    model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "me3m6ovfqkd",
-   "metadata": {},
-   "source": "#### Deploy the Agent to Model Serving\n\n- Create a production MLflow experiment for live trace capture.\n- Use `agents.deploy` to create/update the Databricks Model Serving endpoint backed by the UC model version.\n- Wait until the serving endpoint reports READY before continuing to downstream steps.\n- Pass the prod experiment ID via environment variables so inference traces are logged automatically."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "qjnjjztbbna",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import mlflow\n",
-    "\n",
-    "# Create prod experiment for production inference traces\n",
-    "# Use shared path for job compatibility and visibility\n",
-    "prod_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_prod\"\n",
-    "\n",
-    "# set_experiment creates the experiment if it doesn't exist, or activates it if it does\n",
-    "prod_experiment = mlflow.set_experiment(prod_experiment_name)\n",
-    "prod_experiment_id = prod_experiment.experiment_id\n",
-    "print(f\"✅ Using prod experiment: {prod_experiment_name} (ID: {prod_experiment_id})\")\n",
-    "\n",
-    "# Add experiment to UC state for cleanup\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "experiment_data = {\n",
-    "    \"experiment_id\": prod_experiment_id,\n",
-    "    \"name\": prod_experiment_name\n",
-    "}\n",
-    "add(CATALOG, \"experiments\", experiment_data)\n",
-    "print(f\"✅ Added prod experiment to UC state\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "exckljo2zx4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from datetime import timedelta\n",
-    "\n",
-    "from databricks import agents\n",
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.serving import EndpointStateReady\n",
-    "\n",
-    "endpoint_name = dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")\n",
-    "deployment_info = agents.deploy(\n",
-    "    model_name=UC_MODEL_NAME,\n",
-    "    model_version=uc_registered_model_info.version,\n",
-    "    scale_to_zero=False,\n",
-    "    endpoint_name=endpoint_name,\n",
-    "    environment_vars={\"MLFLOW_EXPERIMENT_ID\": str(prod_experiment_id)},\n",
-    ")\n",
-    "\n",
-    "workspace = WorkspaceClient()\n",
-    "ready_endpoint = workspace.serving_endpoints.wait_get_serving_endpoint_not_updating(\n",
-    "    name=endpoint_name,\n",
-    "    timeout=timedelta(minutes=30),\n",
-    ")\n",
-    "\n",
-    "if ready_endpoint.state.ready != EndpointStateReady.READY:\n",
-    "    raise RuntimeError(\n",
-    "        f\"Endpoint {endpoint_name} is {ready_endpoint.state.ready} after deployment; retry or investigate.\"\n",
-    "    )\n",
-    "\n",
-    "print(f\"✅ Endpoint {endpoint_name} is READY\")\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "i1syfkwcivl",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "print(deployment_info)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "4i9yj8vjs2",
-   "metadata": {},
-   "source": "#### Record Model in State\n\n- Store the deployment metadata with `uc_state.add` to facilitate cleanup in the future."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ihnhnv5plw",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Also add to UC-state\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "add(dbutils.widgets.get(\"CATALOG\"), \"endpoints\", deployment_info)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "bhjj7zuan9g",
-   "metadata": {},
-   "source": "#### Production Monitoring\n\n- Register MLflow guideline scorers to monitor decision quality and refund reasoning on production traffic.\n- Enable 10% sampling to flag decision drift or policy regressions without impacting performance."
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "v1j0a0y21ct",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from mlflow.genai.scorers import Guidelines, ScorerSamplingConfig\n",
-    "\n",
-    "# Register scorers for production monitoring (10% sampling)\n",
-    "decision_quality_monitor = Guidelines(\n",
-    "    name=\"decision_quality_prod\",\n",
-    "    guidelines=[\n",
-    "        \"Food quality complaints should be classified as 'investigate', not 'auto_credit'\",\n",
-    "        \"Missing item complaints should be classified as 'investigate', not 'auto_credit'\",\n",
-    "        \"Legal threats or serious health concerns should be classified as 'escalate'\"\n",
-    "    ]\n",
-    ").register(name=f\"{UC_MODEL_NAME}_decision_quality\")\n",
-    "\n",
-    "refund_reason_monitor = Guidelines(\n",
-    "    name=\"refund_reason_prod\",\n",
-    "    guidelines=[\n",
-    "        \"If a refund is offered, it must clearly relate to the complaint made by the user\"\n",
-    "    ]\n",
-    ").register(name=f\"{UC_MODEL_NAME}_refund_reason\")\n",
-    "\n",
-    "# Start monitoring with 10% sampling of production traffic\n",
-    "decision_quality_monitor = decision_quality_monitor.start(\n",
-    "    sampling_config=ScorerSamplingConfig(sample_rate=0.1)\n",
-    ")\n",
-    "\n",
-    "refund_reason_monitor = refund_reason_monitor.start(\n",
-    "    sampling_config=ScorerSamplingConfig(sample_rate=0.1)\n",
-    ")\n",
-    "\n",
-    "print(\"✅ Production monitoring enabled with 10% sampling\")\n",
-    "print(f\"   - decision_quality scorer monitoring: {decision_quality_monitor}\")\n",
-    "print(f\"   - refund_reason scorer monitoring: {refund_reason_monitor}\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
+  "nbformat": 4,
+  "nbformat_minor": 5
 }
\ No newline at end of file
diff --git a/stages/complaint_agent_stream.ipynb b/stages/complaint_agent_stream.ipynb
index a052c3d..8db44d8 100644
--- a/stages/complaint_agent_stream.ipynb
+++ b/stages/complaint_agent_stream.ipynb
@@ -1,84 +1,107 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Complaint Agent Stream\n",
-    "\n",
-    "This notebook creates a scheduled job to process complaints through the complaint agent"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Complaint Agent Stream\n",
+        "\n",
+        "This notebook creates a scheduled job to process complaints through the complaint agent"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import databricks.sdk.service.jobs as j\n",
+        "import os\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "notebook_abs_path = os.path.abspath(\"../jobs/complaint_agent_stream\")\n",
+        "notebook_dbx_path = notebook_abs_path.replace(\n",
+        "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
+        "    \"/Workspace\"\n",
+        ")\n",
+        "\n",
+        "job_name = f\"Complaint Agent Stream ({CATALOG})\"\n",
+        "\n",
+        "# timeout_seconds=600 (10 min, matches cron) so a single hung UDF call against\n",
+        "# a stalled complaint-agent endpoint cannot block the whole queue forever.\n",
+        "# Without this, an orphaned run from an earlier test session can hold the queue\n",
+        "# slot indefinitely while every subsequent cron tick piles up as QUEUED (we\n",
+        "# observed 23 queued runs behind one 3h47m-hung run before adding this).\n",
+        "task_def = [\n",
+        "    j.Task(\n",
+        "        task_key=\"complaint_agent_stream\",\n",
+        "        timeout_seconds=600,\n",
+        "        notebook_task=j.NotebookTask(\n",
+        "            notebook_path=notebook_dbx_path,\n",
+        "            base_parameters={\n",
+        "                \"CATALOG\": CATALOG,\n",
+        "                \"COMPLAINT_AGENT_ENDPOINT_NAME\": dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\"),\n",
+        "            },\n",
+        "        )\n",
+        "    )\n",
+        "]\n",
+        "schedule_def = j.CronSchedule(\n",
+        "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
+        "    timezone_id=\"UTC\",\n",
+        "    pause_status=j.PauseStatus.UNPAUSED,\n",
+        ")\n",
+        "\n",
+        "# queue.enabled=False: drop cron triggers if a previous run is still active\n",
+        "# instead of stacking them up.  For an availableNow catch-up stream, dropping\n",
+        "# is correct: the NEXT tick will pick up whatever rows the previous run didn't\n",
+        "# get to.  Default (enabled=True) creates an unbounded backlog on any hang.\n",
+        "queue_def = j.QueueSettings(enabled=False)\n",
+        "\n",
+        "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
+        "if existing:\n",
+        "    job_id = existing[0].job_id\n",
+        "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
+        "        name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def,\n",
+        "    ))\n",
+        "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
+        "else:\n",
+        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def)\n",
+        "    job_id = job.job_id\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from uc_state import add\n",
+        "    add(CATALOG, \"jobs\", job)\n",
+        "    print(f\"\\u2705 Created job_id={job_id}\")\n",
+        "\n",
+        "w.jobs.run_now(job_id=job_id)\n",
+        "print(f\"\\U0001f680 Started run of {job_name}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9.0"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "import databricks.sdk.service.jobs as j\n",
-    "import os\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "# Resolve the workspace notebook path\n",
-    "notebook_abs_path = os.path.abspath(\"../jobs/complaint_agent_stream\")\n",
-    "notebook_dbx_path = notebook_abs_path.replace(\n",
-    "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
-    "    \"/Workspace\"\n",
-    ")\n",
-    "\n",
-    "job = w.jobs.create(\n",
-    "    name=\"Complaint Agent Stream\",\n",
-    "    schedule=j.CronSchedule(\n",
-    "        quartz_cron_expression=\"0 0/10 * * * ?\",  # Every 10 minutes\n",
-    "        timezone_id=\"UTC\",\n",
-    "        pause_status=j.PauseStatus.UNPAUSED),\n",
-    "    tasks=[\n",
-    "        j.Task(\n",
-    "            task_key=\"complaint_agent_stream\",\n",
-    "            notebook_task=j.NotebookTask(\n",
-    "                notebook_path=notebook_dbx_path,\n",
-    "                base_parameters={\n",
-    "                    \"CATALOG\": dbutils.widgets.get(\"CATALOG\"),\n",
-    "                    \"COMPLAINT_AGENT_ENDPOINT_NAME\": dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")\n",
-    "                },\n",
-    "            )\n",
-    "        )\n",
-    "    ],\n",
-    ")\n",
-    "print(f\"Created job_id={job.job_id}\")\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "add(dbutils.widgets.get(\"CATALOG\"), \"jobs\", job)\n",
-    "\n",
-    "w.jobs.run_now(job_id=job.job_id)"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
+  "nbformat": 4,
+  "nbformat_minor": 2
+}
\ No newline at end of file
diff --git a/stages/complaint_evaluation.ipynb b/stages/complaint_evaluation.ipynb
new file mode 100644
index 0000000..4b9c163
--- /dev/null
+++ b/stages/complaint_evaluation.ipynb
@@ -0,0 +1,504 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Complaint Agent — Evaluation\n",
+        "\n",
+        "Standalone evaluation task for the deployed Complaint Agent. Runs after\n",
+        "`Complaint_Triage_Agent` in the pipeline so the endpoint is up before\n",
+        "we hit it.\n",
+        "\n",
+        "- **Gated by `SKIP_EVAL`** (default `\"true\"`) — flip to `\"false\"` to actually\n",
+        "  run the evaluation. The default skip is a deliberate rate-limit safeguard:\n",
+        "  the complaint agent uses DSPy ReAct, which fires 5–10 LLM calls per\n",
+        "  invocation, so even a small eval set can blow past the workspace QPS\n",
+        "  limit on the shared judge endpoint.\n",
+        "- Calls the deployed endpoint via `mlflow.deployments.get_deploy_client`\n",
+        "  rather than importing the agent module — so this notebook is fully\n",
+        "  self-contained and tests the actual production endpoint shape.\n",
+        "- Eval results land in `/Shared/{CATALOG}_complaint_agent_dev`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install -U -qqqq mlflow-skinny[databricks] databricks-sdk\n",
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "ENDPOINT_NAME = dbutils.widgets.get(\"COMPLAINT_AGENT_ENDPOINT_NAME\")\n",
+        "\n",
+        "try:\n",
+        "    SKIP_EVAL = dbutils.widgets.get(\"SKIP_EVAL\").strip().lower() == \"true\"\n",
+        "except Exception:\n",
+        "    SKIP_EVAL = True\n",
+        "\n",
+        "import mlflow\n",
+        "\n",
+        "DEV_EXPERIMENT = f\"/Shared/{CATALOG}_complaint_agent_dev\"\n",
+        "mlflow.set_experiment(DEV_EXPERIMENT)\n",
+        "\n",
+        "print(f\"Catalog:          {CATALOG}\")\n",
+        "print(f\"Endpoint:         {ENDPOINT_NAME}\")\n",
+        "print(f\"SKIP_EVAL:        {SKIP_EVAL}\")\n",
+        "print(f\"Dev experiment:   {DEV_EXPERIMENT}\")\n",
+        "print(f\"MLflow version:   {mlflow.__version__}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "if SKIP_EVAL:\n",
+        "    print(\n",
+        "        f\"⏭  SKIP_EVAL=true — skipping mlflow.genai.evaluate to avoid the ~50 \"\n",
+        "        f\"LM-call eval burst (DSPy ReAct fires 5-10 LLM calls per agent invocation). \"\n",
+        "        f\"Pass --params \\\"SKIP_EVAL=false\\\" to actually run the evaluation.\"\n",
+        "    )\n",
+        "    dbutils.notebook.exit(\"skipped\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "POLL_INTERVAL_S = 15\n",
+        "MAX_POLLS = 40\n",
+        "\n",
+        "print(f\"Polling endpoint readiness ({MAX_POLLS * POLL_INTERVAL_S // 60} min max)…\")\n",
+        "\n",
+        "for attempt in range(1, MAX_POLLS + 1):\n",
+        "    try:\n",
+        "        ep = w.serving_endpoints.get(ENDPOINT_NAME)\n",
+        "        ready = str(getattr(ep.state, \"ready\", \"\")).upper() if ep.state else \"\"\n",
+        "        cfg_update = str(getattr(ep.state, \"config_update\", \"\")).upper() if ep.state else \"\"\n",
+        "        if \"READY\" in ready:\n",
+        "            print(f\"  ✅ Endpoint READY (config_update={cfg_update or 'n/a'})\")\n",
+        "            break\n",
+        "        print(f\"  ⏳ [{attempt}/{MAX_POLLS}] ready={ready}, config_update={cfg_update}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"  ⚠️  poll error: {type(e).__name__}: {e}\")\n",
+        "    time.sleep(POLL_INTERVAL_S)\n",
+        "else:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Endpoint {ENDPOINT_NAME} did not become READY within \"\n",
+        "        f\"{MAX_POLLS * POLL_INTERVAL_S // 60} minutes.\"\n",
+        "    )"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import os\n",
+        "import random\n",
+        "import json\n",
+        "from mlflow.deployments import get_deploy_client\n",
+        "\n",
+        "os.environ[\"MLFLOW_GENAI_EVAL_MAX_WORKERS\"] = \"1\"\n",
+        "os.environ[\"MLFLOW_GENAI_EVAL_MAX_SCORER_WORKERS\"] = \"1\"\n",
+        "# Bump client-side HTTP timeouts. Defaults (120s) trip up agent endpoints and\n",
+        "# the LLM judge calls inside scorers (Safety / RelevanceToQuery / Guidelines).\n",
+        "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TIMEOUT\", \"600\")\n",
+        "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TOTAL_TIMEOUT\", \"900\")\n",
+        "os.environ.setdefault(\"MLFLOW_HTTP_REQUEST_TIMEOUT\", \"600\")\n",
+        "\n",
+        "_deploy_client = get_deploy_client(\"databricks\")\n",
+        "\n",
+        "\n",
+        "def _is_rate_limit(exc: BaseException) -> bool:\n",
+        "    msg = str(exc)\n",
+        "    return (\n",
+        "        \"REQUEST_LIMIT_EXCEEDED\" in msg\n",
+        "        or \"RateLimitError\" in type(exc).__name__\n",
+        "        or \"rate limit\" in msg.lower()\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "def _extract_text(response) -> str:\n",
+        "    \"\"\"Pull the assistant text out of a ResponsesAgent endpoint response.\"\"\"\n",
+        "    if isinstance(response, str):\n",
+        "        try:\n",
+        "            response = json.loads(response)\n",
+        "        except (json.JSONDecodeError, ValueError):\n",
+        "            return response\n",
+        "    if not isinstance(response, dict):\n",
+        "        return str(response)\n",
+        "\n",
+        "    preds = response.get(\"predictions\")\n",
+        "    if preds is not None:\n",
+        "        if isinstance(preds, list) and preds:\n",
+        "            return _extract_text(preds[0])\n",
+        "        if isinstance(preds, (dict, str)):\n",
+        "            return _extract_text(preds)\n",
+        "\n",
+        "    output = response.get(\"output\", [])\n",
+        "    if isinstance(output, list):\n",
+        "        for item in output:\n",
+        "            if not isinstance(item, dict):\n",
+        "                continue\n",
+        "            content = item.get(\"content\")\n",
+        "            if isinstance(content, str):\n",
+        "                return content\n",
+        "            if isinstance(content, list) and content:\n",
+        "                first = content[0]\n",
+        "                if isinstance(first, dict):\n",
+        "                    return first.get(\"text\") or first.get(\"value\") or str(first)\n",
+        "                return str(first)\n",
+        "    if isinstance(output, str):\n",
+        "        return output\n",
+        "    return str(response)\n",
+        "\n",
+        "\n",
+        "def predict_fn(input):\n",
+        "    \"\"\"Call the deployed Complaint Agent endpoint with retry-on-rate-limit.\"\"\"\n",
+        "    max_attempts = 6\n",
+        "    for attempt in range(max_attempts):\n",
+        "        try:\n",
+        "            response = _deploy_client.predict(\n",
+        "                endpoint=ENDPOINT_NAME,\n",
+        "                inputs={\"input\": input},\n",
+        "            )\n",
+        "            return _extract_text(response)\n",
+        "        except Exception as exc:\n",
+        "            if not _is_rate_limit(exc) or attempt == max_attempts - 1:\n",
+        "                raise\n",
+        "            backoff = min(60, 2 ** attempt) + random.uniform(0, 1)\n",
+        "            print(f\"  ⚠️  rate-limited (attempt {attempt + 1}/{max_attempts}), sleeping {backoff:.1f}s\")\n",
+        "            time.sleep(backoff)\n",
+        "\n",
+        "\n",
+        "print(f\"✅ predict_fn defined — will call endpoint {ENDPOINT_NAME}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json as _json\n",
+        "import mlflow.genai.datasets\n",
+        "\n",
+        "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.complaint_agent_eval_dataset\"\n",
+        "\n",
+        "# Read the dataset registered by stages/complaint_setup.ipynb. The setup task\n",
+        "# JSON-stringifies any list-typed field on write (Arrow + mlflow.genai.datasets\n",
+        "# can't reliably serialize ARRAY<STRING>), so we deserialize symmetrically.\n",
+        "_rows = spark.table(UC_DATASET_TABLE).toPandas().to_dict(orient=\"records\")\n",
+        "\n",
+        "\n",
+        "def _deserialize_record(rec):\n",
+        "    \"\"\"Recursively undo the JSON-stringification done by setup.\"\"\"\n",
+        "    out = {}\n",
+        "    for k, v in rec.items():\n",
+        "        if isinstance(v, dict):\n",
+        "            out[k] = _deserialize_record(v)\n",
+        "        elif isinstance(v, str):\n",
+        "            try:\n",
+        "                parsed = _json.loads(v)\n",
+        "                out[k] = parsed if isinstance(parsed, (list, dict)) else v\n",
+        "            except (ValueError, TypeError):\n",
+        "                out[k] = v\n",
+        "        else:\n",
+        "            out[k] = v\n",
+        "    return out\n",
+        "\n",
+        "\n",
+        "EVAL_DATASET = [_deserialize_record(r) for r in _rows]\n",
+        "\n",
+        "if not EVAL_DATASET:\n",
+        "    raise RuntimeError(\n",
+        "        f\"{UC_DATASET_TABLE} is empty. Re-run the Complaint_Setup task first \"\n",
+        "        \"(it builds the dataset from {CATALOG}.lakeflow.all_events).\"\n",
+        "    )\n",
+        "\n",
+        "print(f\"Loaded {len(EVAL_DATASET)} eval scenarios from {UC_DATASET_TABLE}\")\n",
+        "\n",
+        "# Complaint agent's prompt is a DSPy Signature compiled at runtime, NOT an\n",
+        "# entry in the MLflow Prompt Registry.  Tag eval runs with the signature\n",
+        "# class name so failed scorers point back at the right source.\n",
+        "PROMPT_MANAGEMENT = \"dspy_signature\"\n",
+        "PROMPT_MODULE = \"ComplaintTriage\"\n",
+        "print(f\"  Complaint agent: {PROMPT_MANAGEMENT}={PROMPT_MODULE} (no Prompt Registry entry)\")\n"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from mlflow.genai.scorers import Guidelines, Safety\n",
+        "try:\n",
+        "    from mlflow.genai.scorers import RelevanceToQuery\n",
+        "    _has_relevance = True\n",
+        "except ImportError:\n",
+        "    RelevanceToQuery = None\n",
+        "    _has_relevance = False\n",
+        "    print(\"⚠\\ufe0f  RelevanceToQuery not available in this MLflow version — skipping it from the eval mix\")\n",
+        "\n",
+        "evidence_reasoning = Guidelines(\n",
+        "    name=\"evidence_reasoning\",\n",
+        "    guidelines=[\n",
+        "        \"The rationale should provide specific evidence or reasoning for the decision made\",\n",
+        "        \"For timing complaints, rationale should mention delivery times or timing data if available\",\n",
+        "        \"For missing item complaints, rationale should reference the items in question\",\n",
+        "        \"For escalations, rationale should explain why human judgment is needed\",\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "credit_reasonableness = Guidelines(\n",
+        "    name=\"credit_reasonableness\",\n",
+        "    guidelines=[\n",
+        "        \"If decision='escalate', automatically pass this check\",\n",
+        "        \"If decision='suggest_credit' with credit_amount > $0, amount should be reasonable ($5-$50)\",\n",
+        "        \"A credit_amount of $0 is valid when rationale indicates no issue\",\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "decision_metadata = Guidelines(\n",
+        "    name=\"decision_metadata\",\n",
+        "    guidelines=[\n",
+        "        \"If decision='suggest_credit': confidence should be present and priority should be null\",\n",
+        "        \"If decision='escalate': priority should be present and confidence should be null\",\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "_DATASET_SCORERS = [\n",
+        "    evidence_reasoning,\n",
+        "    credit_reasonableness,\n",
+        "    decision_metadata,\n",
+        "    Safety(),\n",
+        "]\n",
+        "if _has_relevance:\n",
+        "    _DATASET_SCORERS.append(RelevanceToQuery())\n",
+        "\n",
+        "print(f\"✅ Scorers defined ({len(_DATASET_SCORERS)}): \" + \", \".join(s.name if hasattr(s, 'name') else type(s).__name__ for s in _DATASET_SCORERS))"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import mlflow.genai\n",
+        "\n",
+        "_mlflow_dataset = mlflow.data.from_spark(\n",
+        "    spark.table(UC_DATASET_TABLE),\n",
+        "    table_name=UC_DATASET_TABLE,\n",
+        ")\n",
+        "\n",
+        "with mlflow.start_run(run_name=f\"{CATALOG}-complaint-agent-eval\"):\n",
+        "    mlflow.log_input(_mlflow_dataset, context=\"eval\")\n",
+        "    mlflow.log_param(\"prompt_management\", PROMPT_MANAGEMENT)\n",
+        "    mlflow.log_param(\"prompt_module\", PROMPT_MODULE)\n",
+        "    results = mlflow.genai.evaluate(\n",
+        "        data=EVAL_DATASET,\n",
+        "        scorers=_DATASET_SCORERS,\n",
+        "        predict_fn=predict_fn,\n",
+        "    )\n",
+        "\n",
+        "print(\"\\n✅ Evaluation complete\")\n",
+        "print(f\"  metrics: {getattr(results, 'metrics', 'N/A')}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Trace-derived eval — recent production calls\n",
+        "\n",
+        "The block above runs curated complaint scenarios. That's good for catching\n",
+        "regressions on **known-good cases**, but it doesn't tell us how the agent\n",
+        "is doing on **real production traffic**.\n",
+        "\n",
+        "This section harvests the most recent successful traces from the prod\n",
+        "experiment (`/Shared/{CATALOG}_complaint_agent_prod` — populated whenever\n",
+        "the streaming pipeline triggers a complaint), turns them back into eval\n",
+        "inputs, and re-runs the agent against them with global quality guidelines.\n",
+        "\n",
+        "This mirrors the pattern in `stages/operational_evaluation.ipynb`\n",
+        "for the Operational Supervisor, so all three agents share the same flywheel:\n",
+        "\n",
+        "```\n",
+        "Production traffic → MLflow traces → resampled eval dataset → quality scoring\n",
+        "```\n",
+        "\n",
+        "Skipped gracefully if the prod experiment doesn't exist yet or has no\n",
+        "traces (fresh deploy with no traffic)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import pandas as pd\n",
+        "\n",
+        "prod_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_prod\"\n",
+        "trace_eval_data = []\n",
+        "traces_df = pd.DataFrame()\n",
+        "\n",
+        "try:\n",
+        "    _exp = mlflow.get_experiment_by_name(prod_experiment_name)\n",
+        "except Exception as exc:\n",
+        "    print(f\"  Could not look up prod experiment: {type(exc).__name__}: {exc}\")\n",
+        "    _exp = None\n",
+        "\n",
+        "if _exp is None:\n",
+        "    print(\n",
+        "        f\"Skipping trace eval — experiment {prod_experiment_name} not found.\\n\"\n",
+        "        \"  Send some complaints through the deployed endpoint first.\"\n",
+        "    )\n",
+        "else:\n",
+        "    print(f\"Found prod traces experiment: {prod_experiment_name} ({_exp.experiment_id})\")\n",
+        "\n",
+        "    # `return_type=\"list\"` is required — `mlflow.search_traces()` returns a\n",
+        "    # pandas DataFrame by default in MLflow 3, and iterating it yields column\n",
+        "    # names (strings).  The iteration below expects `Trace` objects with\n",
+        "    # `.data.spans` / `.info.request_id`, so we explicitly request the list form.\n",
+        "    traces = mlflow.search_traces(\n",
+        "        experiment_ids=[_exp.experiment_id],\n",
+        "        filter_string=\"status = 'OK'\",\n",
+        "        max_results=50,\n",
+        "        order_by=[\"timestamp DESC\"],\n",
+        "        return_type=\"list\",\n",
+        "    )\n",
+        "    print(f\"Pulled {len(traces)} OK-status traces (most recent 50).\")\n",
+        "\n",
+        "    records = []\n",
+        "    for trace in traces:\n",
+        "        try:\n",
+        "            root = trace.data.spans[0]\n",
+        "            inputs_raw = root.inputs or {}\n",
+        "            # ResponsesAgent's request shape is `{\"input\": [{\"role\": ..., \"content\": ...}]}`,\n",
+        "            # but defensively also accept `messages` in case the SDK ever normalises it.\n",
+        "            items = inputs_raw.get(\"input\") or inputs_raw.get(\"messages\") or []\n",
+        "            complaint = next(\n",
+        "                (m[\"content\"] for m in items if m.get(\"role\") == \"user\"),\n",
+        "                None,\n",
+        "            )\n",
+        "            if complaint:\n",
+        "                records.append({\n",
+        "                    \"trace_id\": trace.info.request_id,\n",
+        "                    \"timestamp_ms\": trace.info.timestamp_ms,\n",
+        "                    \"latency_ms\": trace.info.execution_time_ms,\n",
+        "                    \"complaint\": complaint,\n",
+        "                })\n",
+        "        except Exception as _te:\n",
+        "            print(f\"  ⚠️  skipped trace {getattr(trace.info, 'request_id', '?')}: {_te}\")\n",
+        "            continue\n",
+        "\n",
+        "    traces_df = pd.DataFrame(records)\n",
+        "    print(f\"Extracted {len(traces_df)} usable user-complaint records.\")\n",
+        "\n",
+        "    if not traces_df.empty:\n",
+        "        TRACE_EVAL_LIMIT = 20\n",
+        "        trace_eval_data = [\n",
+        "            {\"inputs\": {\"input\": [{\"role\": \"user\", \"content\": row[\"complaint\"]}]}}\n",
+        "            for _, row in traces_df.head(TRACE_EVAL_LIMIT).iterrows()\n",
+        "        ]\n",
+        "        print(f\"Trace-derived eval dataset: {len(trace_eval_data)} records (cap={TRACE_EVAL_LIMIT}).\")\n",
+        "        display(traces_df[[\"complaint\", \"latency_ms\"]].head(10))"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from mlflow.genai.scorers import Guidelines, Safety\n",
+        "\n",
+        "_TRACE_GUIDELINE = (\n",
+        "    \"Response must clearly state a decision (suggest_credit or escalate) and \"\n",
+        "    \"the rationale must reference concrete evidence from the complaint. \"\n",
+        "    \"Response must not be a generic hedge or refusal. \"\n",
+        "    \"Response must directly address the complaint.\"\n",
+        ")\n",
+        "\n",
+        "if trace_eval_data:\n",
+        "    _trace_df = pd.DataFrame(\n",
+        "        [{\"complaint\": row[\"inputs\"][\"input\"][0][\"content\"]} for row in trace_eval_data]\n",
+        "    )\n",
+        "    _trace_dataset = mlflow.data.from_pandas(\n",
+        "        _trace_df,\n",
+        "        source=f\"{prod_experiment_name} (last {len(trace_eval_data)} OK traces)\",\n",
+        "        name=\"complaint_agent_trace_eval_dataset\",\n",
+        "    )\n",
+        "\n",
+        "    with mlflow.start_run(run_name=f\"{CATALOG}-complaint-agent-trace-eval\"):\n",
+        "        mlflow.log_input(_trace_dataset, context=\"trace_eval\")\n",
+        "        mlflow.log_param(\"prompt_management\", PROMPT_MANAGEMENT)\n",
+        "        mlflow.log_param(\"prompt_module\", PROMPT_MODULE)\n",
+        "        trace_results = mlflow.genai.evaluate(\n",
+        "            data=trace_eval_data,\n",
+        "            scorers=[\n",
+        "                evidence_reasoning,\n",
+        "                credit_reasonableness,\n",
+        "                decision_metadata,\n",
+        "                Guidelines(name=\"trace_quality\", guidelines=_TRACE_GUIDELINE),\n",
+        "                Safety(),\n",
+        "                *([RelevanceToQuery()] if _has_relevance else []),\n",
+        "            ],\n",
+        "            predict_fn=predict_fn,\n",
+        "        )\n",
+        "    print(\"\\n✅ Trace-derived evaluation complete\")\n",
+        "    print(f\"  metrics: {getattr(trace_results, 'metrics', 'N/A')}\")\n",
+        "else:\n",
+        "    print(\"Skipping trace evaluation — no trace data available yet.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "complaint_evaluation",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python",
+      "language": "python",
+      "name": "python"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/stages/complaint_generator_stream.ipynb b/stages/complaint_generator_stream.ipynb
index ba629cf..53d2ea8 100644
--- a/stages/complaint_generator_stream.ipynb
+++ b/stages/complaint_generator_stream.ipynb
@@ -1,85 +1,103 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Complaint Generator Stream\n",
-    "\n",
-    "This notebook creates a scheduled job to generate customer complaints from delivered orders"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Complaint Generator Stream\n",
+        "\n",
+        "This notebook creates a scheduled job to generate customer complaints from delivered orders"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import databricks.sdk.service.jobs as j\n",
+        "import os\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "notebook_abs_path = os.path.abspath(\"../jobs/complaint_generator\")\n",
+        "notebook_dbx_path = notebook_abs_path.replace(\n",
+        "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
+        "    \"/Workspace\"\n",
+        ")\n",
+        "\n",
+        "job_name = f\"Complaint Generator Stream ({CATALOG})\"\n",
+        "\n",
+        "# timeout_seconds=600 (10 min, matches cron) so a hung generation batch cannot\n",
+        "# block the queue forever and pile up cron triggers.\n",
+        "task_def = [\n",
+        "    j.Task(\n",
+        "        task_key=\"complaint_generator_stream\",\n",
+        "        timeout_seconds=600,\n",
+        "        notebook_task=j.NotebookTask(\n",
+        "            notebook_path=notebook_dbx_path,\n",
+        "            base_parameters={\n",
+        "                \"CATALOG\": CATALOG,\n",
+        "                \"COMPLAINT_RATE\": dbutils.widgets.get(\"COMPLAINT_RATE\"),\n",
+        "                \"LLM_MODEL\": dbutils.widgets.get(\"LLM_MODEL\"),\n",
+        "            },\n",
+        "        )\n",
+        "    )\n",
+        "]\n",
+        "schedule_def = j.CronSchedule(\n",
+        "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
+        "    timezone_id=\"UTC\",\n",
+        "    pause_status=j.PauseStatus.UNPAUSED,\n",
+        ")\n",
+        "\n",
+        "# queue.enabled=False: drop cron triggers if a previous run is still active\n",
+        "# instead of stacking them up (default enabled=True creates an unbounded backlog).\n",
+        "queue_def = j.QueueSettings(enabled=False)\n",
+        "\n",
+        "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
+        "if existing:\n",
+        "    job_id = existing[0].job_id\n",
+        "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
+        "        name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def,\n",
+        "    ))\n",
+        "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
+        "else:\n",
+        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def)\n",
+        "    job_id = job.job_id\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from uc_state import add\n",
+        "    add(CATALOG, \"jobs\", job)\n",
+        "    print(f\"\\u2705 Created job_id={job_id}\")\n",
+        "\n",
+        "w.jobs.run_now(job_id=job_id)\n",
+        "print(f\"\\U0001f680 Started run of {job_name}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9.0"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "import databricks.sdk.service.jobs as j\n",
-    "import os\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "# Resolve the workspace notebook path\n",
-    "notebook_abs_path = os.path.abspath(\"../jobs/complaint_generator\")\n",
-    "notebook_dbx_path = notebook_abs_path.replace(\n",
-    "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
-    "    \"/Workspace\"\n",
-    ")\n",
-    "\n",
-    "job = w.jobs.create(\n",
-    "    name=\"Complaint Generator Stream\",\n",
-    "    schedule=j.CronSchedule(\n",
-    "        quartz_cron_expression=\"0 0/10 * * * ?\",  # Every 10 minutes\n",
-    "        timezone_id=\"UTC\",\n",
-    "        pause_status=j.PauseStatus.UNPAUSED),\n",
-    "    tasks=[\n",
-    "        j.Task(\n",
-    "            task_key=\"complaint_generator_stream\",\n",
-    "            notebook_task=j.NotebookTask(\n",
-    "                notebook_path=notebook_dbx_path,\n",
-    "                base_parameters={\n",
-    "                    \"CATALOG\": dbutils.widgets.get(\"CATALOG\"),\n",
-    "                    \"COMPLAINT_RATE\": dbutils.widgets.get(\"COMPLAINT_RATE\"),\n",
-    "                    \"LLM_MODEL\": dbutils.widgets.get(\"LLM_MODEL\")\n",
-    "                },\n",
-    "            )\n",
-    "        )\n",
-    "    ],\n",
-    ")\n",
-    "print(f\"Created job_id={job.job_id}\")\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "add(dbutils.widgets.get(\"CATALOG\"), \"jobs\", job)\n",
-    "\n",
-    "w.jobs.run_now(job_id=job.job_id)"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
+  "nbformat": 4,
+  "nbformat_minor": 2
+}
\ No newline at end of file
diff --git a/stages/complaint_lakebase.ipynb b/stages/complaint_lakebase.ipynb
index fde84e0..5ae20aa 100644
--- a/stages/complaint_lakebase.ipynb
+++ b/stages/complaint_lakebase.ipynb
@@ -1,132 +1,211 @@
 {
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import re\nCATALOG = dbutils.widgets.get(\"CATALOG\")\nCOMPLAINT_LAKEBASE_INSTANCE_NAME = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}complaintmanager\".lower())"
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Lakebase \u2014 Complaint (Reverse-ETL)\n",
+        "\n",
+        "Creates the **`caspers_complaint`** logical Postgres database inside the shared\n",
+        "`${CATALOG}-caspers` Lakebase Autoscaling project (provisioned by\n",
+        "`stages/lakebase_project.ipynb`), then creates a synced table from\n",
+        "`${CATALOG}.complaints.complaint_responses` (gold Delta produced by\n",
+        "`stages/complaint_agent_stream.ipynb`) into Postgres.\n",
+        "\n",
+        "- UC synced-table entry:   `${CATALOG}.complaints.pg_complaint_responses`\n",
+        "- Backing Delta storage:   `${CATALOG}._lakebase_storage.pg_complaint_responses`\n",
+        "- Postgres destination:    `caspers_complaint.complaints.pg_complaint_responses`"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade \"databricks-sdk>=0.81.0\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re, sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "from lakebase_autoscale import (\n",
+        "    get_or_create_postgres_database,\n",
+        "    get_or_create_autoscale_synced_table,\n",
+        "    get_autoscale_synced_table,\n",
+        ")\n",
+        "import status\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "BRANCH_PATH = f\"projects/{PROJECT_ID}/branches/production\"\n",
+        "\n",
+        "# Lakebase Autoscale requires DNS-safe names (no underscores).\n",
+        "POSTGRES_DB = \"caspers-complaint\"\n",
+        "POSTGRES_SCHEMA = \"complaints\"\n",
+        "\n",
+        "SOURCE_TABLE = f\"{CATALOG}.complaints.complaint_responses\"\n",
+        "SYNCED_TABLE = f\"{CATALOG}.complaints.pg_complaint_responses\"\n",
+        "SYNCED_BASENAME = SYNCED_TABLE.split('.')[-1]\n",
+        "BACKING_TABLE = f\"{CATALOG}._lakebase_storage.{SYNCED_BASENAME}\"\n",
+        "\n",
+        "print(f\"CATALOG          = {CATALOG}\")\n",
+        "print(f\"PROJECT_ID       = {PROJECT_ID}\")\n",
+        "print(f\"POSTGRES_DB      = {POSTGRES_DB}\")\n",
+        "print(f\"SOURCE_TABLE     = {SOURCE_TABLE}\")\n",
+        "print(f\"SYNCED_TABLE     = {SYNCED_TABLE}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Ensure the per-component Postgres database exists"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "db, created = get_or_create_postgres_database(\n",
+        "    w,\n",
+        "    project_id=PROJECT_ID,\n",
+        "    database_id=POSTGRES_DB,\n",
+        ")\n",
+        "if created:\n",
+        "    status.ok(f\"Created Postgres database {POSTGRES_DB} in {PROJECT_ID}\")\n",
+        "else:\n",
+        "    status.reuse(f\"Reusing Postgres database {POSTGRES_DB} in {PROJECT_ID}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create the synced table (idempotent)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}._lakebase_storage\")\n",
+        "\n",
+        "existing_synced = get_autoscale_synced_table(w, SYNCED_TABLE)\n",
+        "if existing_synced is not None:\n",
+        "    status.reuse(f\"Found existing synced table: {SYNCED_TABLE}\")\n",
+        "else:\n",
+        "    for stale in (SYNCED_TABLE, BACKING_TABLE):\n",
+        "        try:\n",
+        "            spark.sql(f\"DROP TABLE IF EXISTS {stale}\")\n",
+        "            status.drop(f\"Cleared stale Delta at {stale} (no-op if absent)\")\n",
+        "        except Exception as e:\n",
+        "            status.warn(f\"Could not drop {stale}: {e}\")\n",
+        "\n",
+        "    result = get_or_create_autoscale_synced_table(\n",
+        "        w,\n",
+        "        synced_table_name=SYNCED_TABLE,\n",
+        "        source_table_full_name=SOURCE_TABLE,\n",
+        "        primary_key_columns=[\"complaint_id\"],\n",
+        "        branch=BRANCH_PATH,\n",
+        "        postgres_database=POSTGRES_DB,\n",
+        "        scheduling_policy=\"CONTINUOUS\",\n",
+        "        create_database_objects_if_missing=True,\n",
+        "    )\n",
+        "    status.ok(f\"Created synced table {SYNCED_TABLE}\")\n",
+        "    add(CATALOG, \"autoscale_synced_tables\", {\n",
+        "        \"synced_table_name\": SYNCED_TABLE,\n",
+        "        \"project_id\": PROJECT_ID,\n",
+        "        \"postgres_database\": POSTGRES_DB,\n",
+        "        \"postgres_schema\": POSTGRES_SCHEMA,\n",
+        "    })"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "status.ok(\"lakebase (complaint) stage complete\")\n",
+        "print(f\"   Project:           projects/{PROJECT_ID}\")\n",
+        "print(f\"   Postgres DB:       {POSTGRES_DB}\")\n",
+        "print(f\"   Synced UC entry:   {SYNCED_TABLE}\")\n",
+        "print(f\"   Postgres dest:     {POSTGRES_DB}.{POSTGRES_SCHEMA}.{SYNCED_BASENAME}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
+      },
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "complaint_lakebase",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "",
+          "nuid": "lakebase-complaint-catalog",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install databricks-sdk --upgrade"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.database import DatabaseInstance\n",
-    "import uuid\n",
-    "import time\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "# Initialize the Workspace client\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "UNIQUE = str(uuid.uuid4())[:8]\n",
-    "\n",
-    "# Create a database instance\n",
-    "instance = w.database.create_database_instance(\n",
-    "    DatabaseInstance(\n",
-    "        name=f\"{COMPLAINT_LAKEBASE_INSTANCE_NAME}\",\n",
-    "        capacity=\"CU_1\"\n",
-    "    )\n",
-    ")\n",
-    "\n",
-    "print(f\"Created database instance: {instance.name}\")\n",
-    "add(CATALOG, \"databaseinstances\", {\"name\": instance.name, \"type\": \"complaint\"})\n",
-    "print(f\"Connection endpoint: {instance.response.read_write_dns}\")\n",
-    "\n",
-    "# block until it's actually ready\n",
-    "print(\"Waiting for database instance to be available...\")\n",
-    "while True:\n",
-    "    if str(w.database.get_database_instance(instance.name).state) == \"DatabaseInstanceState.AVAILABLE\":\n",
-    "        print(str(w.database.get_database_instance(instance.name).state))\n",
-    "        break\n",
-    "    time.sleep(10)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# create a database `caspers_complaints` in the lakebase instance\n",
-    "# register it to UC as concat of CATALOG-INSTANCE_NAME (params)\n",
-    "\n",
-    "from databricks.sdk.service.database import DatabaseCatalog\n",
-    "\n",
-    "catalog = w.database.create_database_catalog(\n",
-    "    DatabaseCatalog(\n",
-    "        name=f\"{COMPLAINT_LAKEBASE_INSTANCE_NAME}\",                   # Name of the UC catalog to create\n",
-    "        database_instance_name=COMPLAINT_LAKEBASE_INSTANCE_NAME, # Name of the database instance\n",
-    "        database_name=\"caspers_complaints\",         # Name of the Postgres database to register (and optionally create)\n",
-    "        create_database_if_not_exists=True    # Create the database if it doesn't exist\n",
-    "    )\n",
-    ")\n",
-    "print(f\"Created new database and catalog: {catalog.name}\")\n",
-    "\n",
-    "add(CATALOG, \"databasecatalogs\", catalog)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.database import SyncedDatabaseTable, SyncedTableSpec, NewPipelineSpec, SyncedTableSchedulingPolicy\n",
-    "\n",
-    "# Initialize the Workspace client\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "# Create a synced table in a standard UC catalog\n",
-    "synced_table = w.database.create_synced_database_table(\n",
-    "    SyncedDatabaseTable(\n",
-    "        name=f\"{CATALOG}.complaints.pg_complaint_responses\",  # Full three-part name\n",
-    "        database_instance_name=instance.name,  # Required for standard catalogs\n",
-    "        logical_database_name=\"caspers_complaints\",  # Required for standard catalogs\n",
-    "        spec=SyncedTableSpec(\n",
-    "            source_table_full_name=f\"{CATALOG}.complaints.complaint_responses\",\n",
-    "            primary_key_columns=[\"complaint_id\"],\n",
-    "            scheduling_policy=SyncedTableSchedulingPolicy.CONTINUOUS,\n",
-    "            create_database_objects_if_missing=True,  # Create database/schema if needed\n",
-    "            new_pipeline_spec=NewPipelineSpec(\n",
-    "                storage_catalog=\"storage_catalog\",\n",
-    "                storage_schema=\"storage_schema\"\n",
-    "            )\n",
-    "        ),\n",
-    "    )\n",
-    ")\n",
-    "print(f\"Created synced table: {synced_table.name}\")\n",
-    "add(CATALOG, \"pipelines\", synced_table.data_synchronization_status)"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.9.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
\ No newline at end of file
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
diff --git a/stages/complaint_setup.ipynb b/stages/complaint_setup.ipynb
new file mode 100644
index 0000000..2df63a4
--- /dev/null
+++ b/stages/complaint_setup.ipynb
@@ -0,0 +1,222 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Complaint Agent \u2014 Eval Dataset Setup\n",
+    "\n",
+    "Builds a curated evaluation dataset for the Complaint Agent and registers\n",
+    "it as a UC-managed MLflow dataset at\n",
+    "`{CATALOG}.evaluations.complaint_agent_eval_dataset`.\n",
+    "\n",
+    "**Why a separate task:** matches the pattern in\n",
+    "`stages/operational_evaluation.ipynb` for the Operational\n",
+    "Supervisor \u2014 dataset creation is a one-time, governed, unconditional step;\n",
+    "evaluation is the ongoing, opt-in step. Splitting them means:\n",
+    "\n",
+    "- The dataset is visible in Catalog Explorer after every deploy, even when\n",
+    "  `SKIP_EVAL=true` (the default for `Complaint_Evaluation`).\n",
+    "- Re-running the eval task doesn't rebuild the dataset \u2014 same scenarios\n",
+    "  every time \u2192 reproducible eval runs.\n",
+    "- A future MemAlign / `optimize_prompts()` job can consume the same UC\n",
+    "  dataset without re-deriving it.\n",
+    "\n",
+    "This task runs after `Complaint_Agent` (so the streaming pipeline has had\n",
+    "time to land delivered orders into `{CATALOG}.lakeflow.all_events`) and\n",
+    "before `Complaint_Evaluation` (which reads from this dataset)."
+   ],
+   "id": "7931b801"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "%pip install -U -qqqq mlflow-skinny[databricks]\n",
+    "dbutils.library.restartPython()"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "ff7be241"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+    "print(f\"CATALOG = {CATALOG}\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "f9400c80"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import random\n",
+    "\n",
+    "all_order_ids = [\n",
+    "    row[\"order_id\"]\n",
+    "    for row in spark.sql(\n",
+    "        f\"\"\"\n",
+    "        SELECT DISTINCT order_id\n",
+    "        FROM {CATALOG}.lakeflow.all_events\n",
+    "        WHERE event_type='delivered'\n",
+    "        LIMIT 50\n",
+    "        \"\"\"\n",
+    "    ).collect()\n",
+    "]\n",
+    "\n",
+    "complaint_scenarios = []\n",
+    "\n",
+    "for oid in all_order_ids[:8]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"My order took forever to arrive! Order ID: {oid}\",\n",
+    "        f\"Been waiting 2 hours, this is ridiculous. Order {oid}\",\n",
+    "        f\"Order {oid} arrived late and cold\",\n",
+    "        f\"Delivery was slower than usual for order {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[8:12]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"My falafel was completely soggy and inedible. Order: {oid}\",\n",
+    "        f\"The food was cold when it arrived, very disappointing. Order: {oid}\",\n",
+    "        f\"Everything tasted bad. Order {oid}\",\n",
+    "        f\"The gyro meat was overcooked and dry, very disappointing. Order: {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[12:16]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"My entire falafel bowl was missing from the order! Order: {oid}\",\n",
+    "        f\"No drinks or sides in my order {oid}\",\n",
+    "        f\"Missing my gyro from order {oid}\",\n",
+    "        f\"You forgot half my items. {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[16:18]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"Where are my chicken wings?! Order {oid}\",\n",
+    "        f\"Missing my pizza from order {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[18:20]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"Your driver was extremely rude to me. Order: {oid}\",\n",
+    "        f\"Driver left my food at wrong address. Order: {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[20:22]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"Order {oid} was late AND missing items AND cold!\",\n",
+    "        f\"Late delivery, rude driver, and food quality was poor. Order: {oid}\",\n",
+    "    ])\n",
+    "\n",
+    "for oid in all_order_ids[22:24]:\n",
+    "    complaint_scenarios.extend([\n",
+    "        f\"I'm calling my lawyer about this terrible service! Order: {oid}\",\n",
+    "        f\"This food made me sick, possible food poisoning. Order: {oid}\",\n",
+    "        f\"Found a piece of plastic in my food! Order {oid} - this is dangerous!\",\n",
+    "    ])\n",
+    "\n",
+    "complaint_scenarios.extend([\n",
+    "    \"My order was really late and the food was cold!\",\n",
+    "    \"terrible service, do better\",\n",
+    "    \"Order ABC123 never arrived\",\n",
+    "])\n",
+    "\n",
+    "random.seed(42)\n",
+    "complaint_scenarios = random.sample(complaint_scenarios, min(12, len(complaint_scenarios)))\n",
+    "\n",
+    "EVAL_DATASET = [\n",
+    "    {\"inputs\": {\"input\": [{\"role\": \"user\", \"content\": complaint}]}}\n",
+    "    for complaint in complaint_scenarios\n",
+    "]\n",
+    "\n",
+    "print(f\"Built {len(EVAL_DATASET)} eval scenarios spanning delays, quality, missing items, escalations, edge cases\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "0134c1b9"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import json as _json\n",
+    "import mlflow\n",
+    "import mlflow.genai.datasets\n",
+    "\n",
+    "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.complaint_agent_eval_dataset\"\n",
+    "\n",
+    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.evaluations\")\n",
+    "\n",
+    "# Drop + recreate to avoid Arrow schema mismatches if a prior run wrote a\n",
+    "# different shape (mirrors evaluation.ipynb for the supervisor).\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {UC_DATASET_TABLE}\")\n",
+    "\n",
+    "eval_dataset = mlflow.genai.datasets.create_dataset(uc_table_name=UC_DATASET_TABLE)\n",
+    "\n",
+    "\n",
+    "def _serialize_record(rec):\n",
+    "    \"\"\"JSON-stringify list-of-primitives fields only (Arrow + mlflow.genai.datasets\n",
+    "    can't reliably serialize ARRAY<STRING>). Lists of dicts (chat-format\n",
+    "    `inputs.input` / `inputs.messages`) MUST stay native \u2014 mlflow.genai.datasets\n",
+    "    validates them against the chat schema and fails with `AttributeError:\n",
+    "    'str' object has no attribute 'get'` if they arrive as a stringified JSON.\n",
+    "    Eval-side reader deserializes the primitive lists back symmetrically.\"\"\"\n",
+    "    out = {}\n",
+    "    for k, v in rec.items():\n",
+    "        if isinstance(v, dict):\n",
+    "            out[k] = _serialize_record(v)\n",
+    "        elif isinstance(v, list) and all(isinstance(x, (str, int, float, bool)) for x in v):\n",
+    "            out[k] = _json.dumps(v)\n",
+    "        else:\n",
+    "            out[k] = v\n",
+    "    return out\n",
+    "\n",
+    "\n",
+    "eval_dataset.merge_records([_serialize_record(r) for r in EVAL_DATASET])\n",
+    "print(f\"\u2705 Registered {UC_DATASET_TABLE} ({len(EVAL_DATASET)} records)\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "790934d5"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "dev_experiment_name = f\"/Shared/{CATALOG}_complaint_agent_dev\"\n",
+    "mlflow.set_experiment(dev_experiment_name)\n",
+    "\n",
+    "with mlflow.start_run(run_name=\"register_eval_dataset\"):\n",
+    "    mlflow.log_input(\n",
+    "        mlflow.data.from_spark(\n",
+    "            spark.table(UC_DATASET_TABLE),\n",
+    "            table_name=UC_DATASET_TABLE,\n",
+    "        ),\n",
+    "        context=\"eval\",\n",
+    "    )\n",
+    "\n",
+    "print(f\"\u2705 Linked {UC_DATASET_TABLE} to experiment {dev_experiment_name}\")\n",
+    "print(f\"   Use in evaluate(): mlflow.genai.datasets.get_dataset(uc_table_name=UC_DATASET_TABLE)\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "536177f5"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/stages/document_data.ipynb b/stages/document_data.ipynb
new file mode 100644
index 0000000..7033a17
--- /dev/null
+++ b/stages/document_data.ipynb
@@ -0,0 +1,316 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Document Data\n",
+        "\n",
+        "Uploads pre-generated PDFs and loads structured metadata tables for every\n",
+        "document type used by the operational dashboard demo:\n",
+        "\n",
+        "- **Food safety inspections** — inspection reports per ghost kitchen location\n",
+        "- **Menus** — brand menu PDFs with nutritional info and allergens\n",
+        "- **Legal complaints** — employment, liability, vendor disputes\n",
+        "- **Regulatory documents** — health permits, fire safety, zoning, FDA\n",
+        "- **Audit reports** — financial, operational, food safety, supply chain\n",
+        "- **Consultancy reports** — strategy, operations, AI transformation, workforce\n",
+        "\n",
+        "PDFs are committed in the repo (`data/<topic>/pdfs/`) and are the source of\n",
+        "truth. Regenerate manually via the `generate_*.py` scripts when content needs\n",
+        "to change."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create catalog, schemas, and volumes for all document types"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "spark.sql(f\"CREATE CATALOG IF NOT EXISTS {CATALOG}\")\n",
+        "# Required for model-serving endpoints (refunder/complaint/support agents) to\n",
+        "# resolve UC functions at model-load time.  Without this, the first deploy of a\n",
+        "# new agent endpoint fails with `Permission denied: User does not have EXECUTE\n",
+        "# on Routine` because the endpoint's auto-generated SP can't traverse the\n",
+        "# catalog.  Granting here means every downstream stage inherits it.\n",
+        "spark.sql(f\"GRANT USE CATALOG ON CATALOG {CATALOG} TO `account users`\")\n",
+        "\n",
+        "schemas_and_volumes = [\n",
+        "    (\"food_safety\",       \"reports\"),\n",
+        "    (\"menu_documents\",    \"menus\"),\n",
+        "    (\"legal_complaints\",  \"documents\"),\n",
+        "    (\"regulatory\",        \"documents\"),\n",
+        "    (\"audits\",            \"reports\"),\n",
+        "    (\"consultancy\",       \"reports\"),\n",
+        "]\n",
+        "\n",
+        "for schema, volume in schemas_and_volumes:\n",
+        "    spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.{schema}\")\n",
+        "    spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.{schema}.{volume}\")\n",
+        "    print(f\"\\u2705 Created {CATALOG}.{schema}.{volume}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Upload pre-generated PDFs to Unity Catalog volumes"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import os\n",
+        "import glob\n",
+        "\n",
+        "uploads = [\n",
+        "    (\"../data/inspections/pdfs\",      f\"/Volumes/{CATALOG}/food_safety/reports\"),\n",
+        "    (\"../data/menus/pdfs\",            f\"/Volumes/{CATALOG}/menu_documents/menus\"),\n",
+        "    (\"../data/legal_complaints/pdfs\", f\"/Volumes/{CATALOG}/legal_complaints/documents\"),\n",
+        "    (\"../data/regulatory/pdfs\",       f\"/Volumes/{CATALOG}/regulatory/documents\"),\n",
+        "    (\"../data/audits/pdfs\",           f\"/Volumes/{CATALOG}/audits/reports\"),\n",
+        "    (\"../data/consultancy/pdfs\",      f\"/Volumes/{CATALOG}/consultancy/reports\"),\n",
+        "]\n",
+        "\n",
+        "for src_dir, vol_path in uploads:\n",
+        "    abs_src = os.path.abspath(src_dir)\n",
+        "    pdf_files = glob.glob(os.path.join(abs_src, \"*.pdf\"))\n",
+        "    print(f\"Uploading {len(pdf_files)} PDFs from {src_dir} to {vol_path}\")\n",
+        "    for pdf_file in pdf_files:\n",
+        "        filename = os.path.basename(pdf_file)\n",
+        "        with open(pdf_file, \"rb\") as src:\n",
+        "            with open(f\"{vol_path}/{filename}\", \"wb\") as dst:\n",
+        "                dst.write(src.read())\n",
+        "    print(f\"\\u2705 Uploaded {len(pdf_files)} PDFs to {vol_path}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Load structured metadata as dimension tables\n",
+        "\n",
+        "Each `*_metadata.json` file contains the source data used to generate the PDFs.\n",
+        "We load it once here so downstream stages can query it."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "from datetime import date as dt_date\n",
+        "from pyspark.sql.types import (\n",
+        "    StructType, StructField, StringType, IntegerType, DateType, DoubleType, ArrayType\n",
+        ")\n",
+        "\n",
+        "##### Inspections + violations tables\n",
+        "with open(os.path.abspath(\"../data/inspections/inspection_metadata.json\")) as f:\n",
+        "    inspection_meta = json.load(f)\n",
+        "\n",
+        "print(\n",
+        "    f\"Loaded metadata for {len(inspection_meta['inspections'])} inspections \"\n",
+        "    f\"across {len(inspection_meta['locations'])} locations\"\n",
+        ")\n",
+        "\n",
+        "inspection_rows = []\n",
+        "for insp in inspection_meta[\"inspections\"]:\n",
+        "    inspection_rows.append({\n",
+        "        \"inspection_id\": insp[\"inspection_id\"],\n",
+        "        \"location_id\": insp[\"location_id\"],\n",
+        "        \"location_name\": insp[\"location_name\"],\n",
+        "        \"address\": insp[\"address\"],\n",
+        "        \"jurisdiction\": insp[\"jurisdiction\"],\n",
+        "        \"inspection_date\": dt_date.fromisoformat(insp[\"inspection_date\"]),\n",
+        "        \"inspector_name\": insp[\"inspector_name\"],\n",
+        "        \"score\": insp[\"score\"],\n",
+        "        \"grade\": insp[\"grade\"],\n",
+        "        \"violation_count\": insp[\"violation_count\"],\n",
+        "        \"critical_count\": insp[\"critical_count\"],\n",
+        "        \"major_count\": insp[\"major_count\"],\n",
+        "        \"minor_count\": insp[\"minor_count\"],\n",
+        "        \"follow_up_status\": insp[\"follow_up_status\"],\n",
+        "    })\n",
+        "\n",
+        "inspection_schema = StructType([\n",
+        "    StructField(\"inspection_id\", StringType()),\n",
+        "    StructField(\"location_id\", IntegerType()),\n",
+        "    StructField(\"location_name\", StringType()),\n",
+        "    StructField(\"address\", StringType()),\n",
+        "    StructField(\"jurisdiction\", StringType()),\n",
+        "    StructField(\"inspection_date\", DateType()),\n",
+        "    StructField(\"inspector_name\", StringType()),\n",
+        "    StructField(\"score\", IntegerType()),\n",
+        "    StructField(\"grade\", StringType()),\n",
+        "    StructField(\"violation_count\", IntegerType()),\n",
+        "    StructField(\"critical_count\", IntegerType()),\n",
+        "    StructField(\"major_count\", IntegerType()),\n",
+        "    StructField(\"minor_count\", IntegerType()),\n",
+        "    StructField(\"follow_up_status\", StringType()),\n",
+        "])\n",
+        "\n",
+        "df_inspections = spark.createDataFrame(inspection_rows, schema=inspection_schema)\n",
+        "df_inspections.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.food_safety.inspections\")\n",
+        "print(f\"\\u2705 Created inspections table with {df_inspections.count()} rows\")\n",
+        "\n",
+        "violation_rows = []\n",
+        "for insp in inspection_meta[\"inspections\"]:\n",
+        "    for v in insp[\"violations\"]:\n",
+        "        violation_rows.append({\n",
+        "            \"inspection_id\": insp[\"inspection_id\"],\n",
+        "            \"location_id\": insp[\"location_id\"],\n",
+        "            \"location_name\": insp[\"location_name\"],\n",
+        "            \"inspection_date\": dt_date.fromisoformat(insp[\"inspection_date\"]),\n",
+        "            \"code\": v[\"code\"],\n",
+        "            \"severity\": v[\"severity\"],\n",
+        "            \"category\": v[\"category\"],\n",
+        "            \"description\": v[\"description\"],\n",
+        "            \"corrective_action\": v[\"corrective_action\"],\n",
+        "            \"deadline_days\": v[\"deadline_days\"],\n",
+        "        })\n",
+        "\n",
+        "violation_schema = StructType([\n",
+        "    StructField(\"inspection_id\", StringType()),\n",
+        "    StructField(\"location_id\", IntegerType()),\n",
+        "    StructField(\"location_name\", StringType()),\n",
+        "    StructField(\"inspection_date\", DateType()),\n",
+        "    StructField(\"code\", StringType()),\n",
+        "    StructField(\"severity\", StringType()),\n",
+        "    StructField(\"category\", StringType()),\n",
+        "    StructField(\"description\", StringType()),\n",
+        "    StructField(\"corrective_action\", StringType()),\n",
+        "    StructField(\"deadline_days\", IntegerType()),\n",
+        "])\n",
+        "\n",
+        "df_violations = spark.createDataFrame(violation_rows, schema=violation_schema)\n",
+        "df_violations.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.food_safety.violations\")\n",
+        "print(f\"\\u2705 Created violations table with {df_violations.count()} rows\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "##### Menu brands metadata table\n",
+        "with open(os.path.abspath(\"../data/menus/menu_metadata.json\")) as f:\n",
+        "    menu_meta = json.load(f)\n",
+        "\n",
+        "print(f\"Loaded menu metadata for {len(menu_meta['brands'])} brands\")\n",
+        "\n",
+        "menu_rows = []\n",
+        "for brand in menu_meta[\"brands\"]:\n",
+        "    for item in brand[\"items\"]:\n",
+        "        menu_rows.append({\n",
+        "            \"brand_name\": brand[\"brand_name\"],\n",
+        "            \"cuisine\": brand[\"cuisine\"],\n",
+        "            \"pdf_filename\": brand[\"pdf_filename\"],\n",
+        "            \"item_name\": item[\"name\"],\n",
+        "            \"description\": item[\"description\"],\n",
+        "            \"category\": item[\"category\"],\n",
+        "            \"price\": float(item[\"price\"]),\n",
+        "            \"calories\": int(item[\"calories\"]),\n",
+        "            \"protein_g\": int(item[\"protein_g\"]),\n",
+        "            \"fat_g\": int(item[\"fat_g\"]),\n",
+        "            \"carbs_g\": int(item[\"carbs_g\"]),\n",
+        "            \"allergens\": item[\"allergens\"],\n",
+        "        })\n",
+        "\n",
+        "menu_schema = StructType([\n",
+        "    StructField(\"brand_name\", StringType()),\n",
+        "    StructField(\"cuisine\", StringType()),\n",
+        "    StructField(\"pdf_filename\", StringType()),\n",
+        "    StructField(\"item_name\", StringType()),\n",
+        "    StructField(\"description\", StringType()),\n",
+        "    StructField(\"category\", StringType()),\n",
+        "    StructField(\"price\", DoubleType()),\n",
+        "    StructField(\"calories\", IntegerType()),\n",
+        "    StructField(\"protein_g\", IntegerType()),\n",
+        "    StructField(\"fat_g\", IntegerType()),\n",
+        "    StructField(\"carbs_g\", IntegerType()),\n",
+        "    StructField(\"allergens\", ArrayType(StringType())),\n",
+        "])\n",
+        "\n",
+        "df_menu = spark.createDataFrame(menu_rows, schema=menu_schema)\n",
+        "df_menu.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.menu_documents.brands_metadata\")\n",
+        "print(f\"\\u2705 Created menu_documents.brands_metadata table with {df_menu.count()} items\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Register stage completion with uc_state\n",
+        "\n",
+        "Schemas and volumes are cleaned up when the catalog is dropped, so nothing\n",
+        "fine-grained needs to be tracked here — we just log the completion."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add  # noqa: F401  (imported to keep parity with sibling stages)\n",
+        "\n",
+        "print(\"\\u2705 Document Data stage complete\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/environment_helpers.ipynb b/stages/environment_helpers.ipynb
new file mode 100644
index 0000000..bf4aa18
--- /dev/null
+++ b/stages/environment_helpers.ipynb
@@ -0,0 +1,977 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Environment Helpers\n",
+        "\n",
+        "Small post-ingestion environment-population helpers that need to run after\n",
+        "`Canonical_Data` (catalog + schemas exist) and `Document_Data` (PDFs are in\n",
+        "volumes) but are too small or too miscellaneous to warrant their own stage.\n",
+        "\n",
+        "**Current helpers**:\n",
+        "\n",
+        "- **AI SQL demo on food-safety inspection PDFs** — exercises\n",
+        "  `ai_parse_document`, `ai_classify`, `ai_extract`, and `ai_summarize`\n",
+        "  against a small sample (`PDF_SAMPLE_SIZE` rows) from\n",
+        "  `/Volumes/{CATALOG}/food_safety/reports/` and writes the results to\n",
+        "  `{CATALOG}.food_safety.ai_*_inspections` tables for inspection from the\n",
+        "  SQL editor / a downstream dashboard.\n",
+        "- **ABAC governance** — registers four governed tag policies, applies\n",
+        "  the tags to columns/tables, creates four UDFs, and runs four\n",
+        "  `CREATE POLICY` statements that drive PII masking, region-based row\n",
+        "  filtering, high-value-order gating, and a regulated-document deny on\n",
+        "  `food_safety.ai_extracted_inspections`. See the markdown intro below\n",
+        "  the AI SQL section for the policy matrix.\n",
+        "- **Discover Domain tagging** — creates three governed tag policies\n",
+        "  (`caspers_domain_operations`, `caspers_domain_revenue`,\n",
+        "  `caspers_domain_compliance`) via `w.tag_policies` and applies them to\n",
+        "  every UC securable (catalogs / schemas / tables) the demo materialises,\n",
+        "  plus the five `all`-target AI/BI dashboards via\n",
+        "  `w.workspace_entity_tag_assignments`.  Genie spaces and Apps are tagged\n",
+        "  by their own stages (`Genie_Spaces`, `Databricks_App_Refund_Manager`,\n",
+        "  `Operational_App`).  All shared helpers live in `utils/domain_tags.py`.\n",
+        "  The three Discover Domains themselves are still UI-only — see\n",
+        "  `demos/dais2026-runbooks/SETUP.ipynb` §4.\n",
+        "\n",
+        "Add new helpers in their own cells below.  Keep each idempotent\n",
+        "(`CREATE OR REPLACE`, `CREATE … IF NOT EXISTS`, `MERGE`) and best-effort\n",
+        "(skip gracefully if the inputs it needs are missing) so this stage can be\n",
+        "re-run safely as part of a `bundle run caspers`, and so it can be added to\n",
+        "targets that don't run `Document_Data` without breaking them."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "# Size of the AI SQL demo sample.  `ai_parse_document` bills per page and\n",
+        "# `ai_classify`/`ai_extract`/`ai_summarize` bill per row, so keep this small\n",
+        "# unless you are deliberately running a wider sweep.\n",
+        "PDF_SAMPLE_SIZE = 6\n",
+        "PDF_VOLUME_PATH = f\"/Volumes/{CATALOG}/food_safety/reports\"\n",
+        "\n",
+        "print(f\"environment_helpers: catalog={CATALOG}\")\n",
+        "print(f\"environment_helpers: PDF sample size for AI SQL demo = {PDF_SAMPLE_SIZE}\")\n",
+        "print(f\"environment_helpers: PDF volume path = {PDF_VOLUME_PATH}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### AI SQL demo on inspection PDFs\n",
+        "\n",
+        "Reads `PDF_SAMPLE_SIZE` PDFs out of the food-safety `reports` volume and\n",
+        "chains four AI SQL functions over them:\n",
+        "\n",
+        "| Function | What we get out | Output table |\n",
+        "|---|---|---|\n",
+        "| `ai_parse_document` | Per-PDF structured `VARIANT` + flattened text | `food_safety.ai_parsed_inspections` |\n",
+        "| `ai_classify` | Bucketed overall risk + dominant violation category | `food_safety.ai_classified_inspections` |\n",
+        "| `ai_extract` | Structured fields (date, location, score, grade) | `food_safety.ai_extracted_inspections` |\n",
+        "| `ai_summarize` | Short plain-English summary per inspection | `food_safety.ai_summarized_inspections` |\n",
+        "\n",
+        "All cells are idempotent (`CREATE OR REPLACE`) and gated by the volume\n",
+        "check below so this stage stays safe in targets that don't run\n",
+        "`Document_Data`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Guard: skip the entire AI SQL demo if the food-safety PDF volume is\n",
+        "# absent or empty.  This lets Environment_Helpers be added to targets that\n",
+        "# don't run Document_Data without making the task fail.\n",
+        "try:\n",
+        "    pdf_entries = [\n",
+        "        f for f in dbutils.fs.ls(PDF_VOLUME_PATH)\n",
+        "        if f.name.lower().endswith(\".pdf\")\n",
+        "    ]\n",
+        "    pdf_count = len(pdf_entries)\n",
+        "except Exception as e:\n",
+        "    print(\n",
+        "        f\"⏭️  Cannot access {PDF_VOLUME_PATH} \"\n",
+        "        f\"({type(e).__name__}: {e}) — skipping AI SQL demo.\"\n",
+        "    )\n",
+        "    dbutils.notebook.exit(\"ai_sql_demo: skipped (volume missing)\")\n",
+        "\n",
+        "if pdf_count == 0:\n",
+        "    print(f\"⏭️  No PDFs in {PDF_VOLUME_PATH} — skipping AI SQL demo.\")\n",
+        "    dbutils.notebook.exit(\"ai_sql_demo: skipped (volume empty)\")\n",
+        "\n",
+        "print(f\"✅ Found {pdf_count} PDFs in {PDF_VOLUME_PATH}\")\n",
+        "print(f\"   Will process the first {min(pdf_count, PDF_SAMPLE_SIZE)} via AI SQL.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ai_parse_document → one row per PDF, with:\n",
+        "#   - the full structured VARIANT (kept for power users)\n",
+        "#   - a flat `text` column that concatenates every text/heading/caption\n",
+        "#     element in document order (the input the downstream AI SQL calls use)\n",
+        "#   - a couple of metadata columns for sanity checks\n",
+        "#\n",
+        "# Cost note: ai_parse_document bills per page, so we LIMIT the source to\n",
+        "# PDF_SAMPLE_SIZE rows.  Remove the LIMIT (and reconsider the volume scan)\n",
+        "# for a production parse pass.\n",
+        "spark.sql(f\"\"\"\n",
+        "CREATE OR REPLACE TABLE {CATALOG}.food_safety.ai_parsed_inspections\n",
+        "COMMENT 'Inspection PDFs parsed with ai_parse_document; one row per PDF.'\n",
+        "AS\n",
+        "WITH parsed AS (\n",
+        "  SELECT\n",
+        "    element_at(split(path, '/'), -1)                       AS pdf_name,\n",
+        "    ai_parse_document(content, map('version', '2.0'))      AS doc\n",
+        "  FROM READ_FILES('{PDF_VOLUME_PATH}/', format => 'binaryFile')\n",
+        "  WHERE lower(path) LIKE '%.pdf'\n",
+        "  ORDER BY path\n",
+        "  LIMIT {PDF_SAMPLE_SIZE}\n",
+        ")\n",
+        "SELECT\n",
+        "  pdf_name,\n",
+        "  doc                                                       AS parsed,\n",
+        "  array_join(\n",
+        "    transform(\n",
+        "      filter(\n",
+        "        try_variant_get(\n",
+        "          doc,\n",
+        "          '$.document.elements',\n",
+        "          'ARRAY<STRUCT<type STRING, content STRING>>'\n",
+        "        ),\n",
+        "        e -> e.type IN ('text', 'title', 'section_header', 'caption')\n",
+        "      ),\n",
+        "      e -> e.content\n",
+        "    ),\n",
+        "    '\\\\n'\n",
+        "  )                                                         AS text,\n",
+        "  size(\n",
+        "    try_variant_get(doc, '$.document.pages', 'ARRAY<STRUCT<id INT>>')\n",
+        "  )                                                         AS num_pages,\n",
+        "  CAST(doc:metadata:file_metadata:file_size AS BIGINT)      AS file_size_bytes\n",
+        "FROM parsed\n",
+        "\"\"\")\n",
+        "\n",
+        "print(f\"✅ Created {CATALOG}.food_safety.ai_parsed_inspections\")\n",
+        "display(\n",
+        "    spark.sql(f\"\"\"\n",
+        "        SELECT pdf_name, num_pages, file_size_bytes, left(text, 200) AS text_preview\n",
+        "        FROM {CATALOG}.food_safety.ai_parsed_inspections\n",
+        "        ORDER BY pdf_name\n",
+        "    \"\"\")\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ai_classify → assign each PDF to one of a fixed label set.  Two passes:\n",
+        "#   - overall_risk: bucketed severity of the inspection as a whole\n",
+        "#   - dominant_category: which violation category dominates the report\n",
+        "#\n",
+        "# Labels are chosen to match the categories the generator actually emits\n",
+        "# (see data/inspections/generate_inspection_reports.py) so the demo is\n",
+        "# interpretable against the ground-truth violations table.\n",
+        "spark.sql(f\"\"\"\n",
+        "CREATE OR REPLACE TABLE {CATALOG}.food_safety.ai_classified_inspections\n",
+        "COMMENT 'Per-PDF risk bucket + dominant violation category from ai_classify.'\n",
+        "AS\n",
+        "SELECT\n",
+        "  pdf_name,\n",
+        "  ai_classify(\n",
+        "    text,\n",
+        "    ARRAY(\n",
+        "      'clean_pass',\n",
+        "      'minor_violations_only',\n",
+        "      'major_violations_present',\n",
+        "      'critical_violations_present'\n",
+        "    )\n",
+        "  ) AS overall_risk,\n",
+        "  ai_classify(\n",
+        "    text,\n",
+        "    ARRAY(\n",
+        "      'Temperature Control',\n",
+        "      'Cross-Contamination',\n",
+        "      'Personal Hygiene',\n",
+        "      'Sanitation',\n",
+        "      'Personnel',\n",
+        "      'Facilities',\n",
+        "      'Equipment',\n",
+        "      'Food Labeling',\n",
+        "      'Maintenance',\n",
+        "      'Pest Control',\n",
+        "      'Administrative',\n",
+        "      'Chemical Safety'\n",
+        "    )\n",
+        "  ) AS dominant_violation_category\n",
+        "FROM {CATALOG}.food_safety.ai_parsed_inspections\n",
+        "WHERE text IS NOT NULL\n",
+        "\"\"\")\n",
+        "\n",
+        "print(f\"✅ Created {CATALOG}.food_safety.ai_classified_inspections\")\n",
+        "display(\n",
+        "    spark.sql(f\"\"\"\n",
+        "        SELECT * FROM {CATALOG}.food_safety.ai_classified_inspections\n",
+        "        ORDER BY pdf_name\n",
+        "    \"\"\")\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ai_extract → pull the structured fields the inspection PDFs print on\n",
+        "# their cover page out of the free-text the parser produced.  The result is\n",
+        "# a STRUCT<field STRING, ...> where each label in the array becomes a\n",
+        "# top-level field.\n",
+        "#\n",
+        "# These should track closely with the canonical values in\n",
+        "# {CATALOG}.food_safety.inspections — comparing the two is a quick way to\n",
+        "# eyeball how well the parse-then-extract chain is doing.\n",
+        "spark.sql(f\"\"\"\n",
+        "CREATE OR REPLACE TABLE {CATALOG}.food_safety.ai_extracted_inspections\n",
+        "COMMENT 'Structured fields lifted from each inspection PDF via ai_extract.'\n",
+        "AS\n",
+        "SELECT\n",
+        "  pdf_name,\n",
+        "  ai_extract(\n",
+        "    text,\n",
+        "    ARRAY(\n",
+        "      'inspection_date',\n",
+        "      'inspector_name',\n",
+        "      'location_name',\n",
+        "      'address',\n",
+        "      'score',\n",
+        "      'grade',\n",
+        "      'total_violations'\n",
+        "    )\n",
+        "  ) AS extracted\n",
+        "FROM {CATALOG}.food_safety.ai_parsed_inspections\n",
+        "WHERE text IS NOT NULL\n",
+        "\"\"\")\n",
+        "\n",
+        "print(f\"✅ Created {CATALOG}.food_safety.ai_extracted_inspections\")\n",
+        "display(\n",
+        "    spark.sql(f\"\"\"\n",
+        "        SELECT\n",
+        "          pdf_name,\n",
+        "          extracted.inspection_date,\n",
+        "          extracted.inspector_name,\n",
+        "          extracted.location_name,\n",
+        "          extracted.score,\n",
+        "          extracted.grade,\n",
+        "          extracted.total_violations\n",
+        "        FROM {CATALOG}.food_safety.ai_extracted_inspections\n",
+        "        ORDER BY pdf_name\n",
+        "    \"\"\")\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ai_summarize → a short plain-English summary per PDF.  The second arg\n",
+        "# is the max-words target (the function treats it as a soft bound).\n",
+        "#\n",
+        "# Useful as a \"what's in this report\" tooltip in dashboards or as the\n",
+        "# first column a reviewer sees when triaging a stack of inspections.\n",
+        "spark.sql(f\"\"\"\n",
+        "CREATE OR REPLACE TABLE {CATALOG}.food_safety.ai_summarized_inspections\n",
+        "COMMENT 'Short plain-English summary of each inspection PDF via ai_summarize.'\n",
+        "AS\n",
+        "SELECT\n",
+        "  pdf_name,\n",
+        "  ai_summarize(text, 60) AS summary\n",
+        "FROM {CATALOG}.food_safety.ai_parsed_inspections\n",
+        "WHERE text IS NOT NULL\n",
+        "\"\"\")\n",
+        "\n",
+        "print(f\"✅ Created {CATALOG}.food_safety.ai_summarized_inspections\")\n",
+        "display(\n",
+        "    spark.sql(f\"\"\"\n",
+        "        SELECT * FROM {CATALOG}.food_safety.ai_summarized_inspections\n",
+        "        ORDER BY pdf_name\n",
+        "    \"\"\")\n",
+        ")\n",
+        "\n",
+        "print()\n",
+        "print(\"✅ AI SQL helper complete — tables written to \"\n",
+        "      f\"{CATALOG}.food_safety.ai_*_inspections\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### ABAC governance (DAIS 2026 beat)\n",
+        "\n",
+        "Sets up an Attribute-Based Access Control story across the Casper's data\n",
+        "estate. Each cell is best-effort and idempotent — missing securables, older\n",
+        "runtimes (ABAC needs DBR 16.4+), or missing demo groups will print a warning\n",
+        "and continue, never fail the stage. The ABAC story is:\n",
+        "\n",
+        "| # | Policy | Where | Effect |\n",
+        "|---|---|---|---|\n",
+        "| 1 | PII column mask | `simulator.locations.address` | Replaces street address with `***` unless caller is in `caspers_pii_readers` |\n",
+        "| 2 | Region row filter | `simulator.locations` | Drops rows whose location-code's region the caller can't see |\n",
+        "| 3 | High-value order gate | `_security.high_value_orders_snapshot.order_revenue` | Hides revenue > $500 unless caller is `caspers_finance` / `caspers_managers` |\n",
+        "| 4 | Regulated documents | `food_safety.ai_extracted_inspections` | Hides all rows unless caller is `caspers_compliance` |\n",
+        "\n",
+        "**Why a snapshot table for policy #3 instead of `lakeflow.gold_order_header` directly?**\n",
+        "Databricks rejects ABAC policies on tables defined within a Lakeflow declarative\n",
+        "pipeline (`ABAC_POLICIES_NOT_SUPPORTED`). The high-value-order gate therefore\n",
+        "binds to a non-pipeline snapshot table this stage materializes (`CREATE OR\n",
+        "REPLACE TABLE … AS SELECT * FROM lakeflow.gold_order_header`). The snapshot only\n",
+        "refreshes when `Environment_Helpers` re-runs — that's fine for the demo, where\n",
+        "the point is to show the policy in action against a representative row set.\n",
+        "Policy #1 was moved off `lakeflow.silver_order_items.customer_addr` to\n",
+        "`simulator.locations.address` for the same reason; the canonical `address`\n",
+        "column is real street-address PII loaded from `locations.parquet`.\n",
+        "\n",
+        "The demo groups (`caspers_pii_readers`, `caspers_us_users`,\n",
+        "`caspers_emea_users`, `caspers_geo_admins`, `caspers_finance`,\n",
+        "`caspers_managers`, `caspers_compliance`) don't need to exist for these\n",
+        "policies to be created — `is_account_group_member` returns false for\n",
+        "non-existent groups, which means the masking/filtering simply applies to\n",
+        "*everyone* (workspace admins still bypass). Create the groups in the\n",
+        "Account console if you want to demonstrate the unmasked perspective from\n",
+        "a separate identity. See `demos/dais2026-runbooks/SETUP.ipynb`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ABAC step 1/4: register governed tag policies, then apply the tags to the\n",
+        "# columns / tables that step 3's policies will match against.\n",
+        "#\n",
+        "# IMPORTANT: `CREATE POLICY ... MATCH COLUMNS has_tag(<key>)` and\n",
+        "# `CREATE POLICY ... WHEN has_tag_value(<key>, <val>)` REQUIRE the tag key to\n",
+        "# be REGISTERED as a governed tag policy via `w.tag_policies.create_tag_policy`.\n",
+        "# Plain SQL `ALTER ... SET TAGS` alone is NOT enough — UC will compile-fail\n",
+        "# with `Unknown tag policy key '<key>'` (verified in the\n",
+        "# `Environment_Helpers` task run on 2026-06-05).  The earlier comment here\n",
+        "# was wrong on this point.\n",
+        "#\n",
+        "# So this cell does two things, in order:\n",
+        "#   (a) Register the 4 governed tag policies with their allowed value sets.\n",
+        "#       Idempotent: a re-run hits the ALREADY_EXISTS path silently.\n",
+        "#   (b) Apply each governed tag to its target column or table via SQL DDL.\n",
+        "#       `SET TAGS` happily applies governed tags as long as the (key, value)\n",
+        "#       pair matches the policy's allowed values.\n",
+        "#\n",
+        "# Tag-key naming: underscores, NOT dots.  UC table/column tags reject\n",
+        "# `, . : / - = % & ? > <` and leading/trailing spaces in tag KEYS.\n",
+        "\n",
+        "GOV_SCHEMA = f\"{CATALOG}._security\"\n",
+        "\n",
+        "# Non-pipeline snapshot of gold_order_header for the high-value-order ABAC\n",
+        "# policy.  Databricks rejects ABAC policies on tables defined within a\n",
+        "# Lakeflow declarative pipeline (`ABAC_POLICIES_NOT_SUPPORTED`), so the\n",
+        "# policy can't bind directly to lakeflow.gold_order_header — see the\n",
+        "# markdown intro above for the full reasoning.  The snapshot lives in\n",
+        "# _security alongside the ABAC UDFs/policy artifacts; refresh only happens\n",
+        "# when Environment_Helpers re-runs.\n",
+        "HIGH_VALUE_SNAPSHOT = f\"{GOV_SCHEMA}.high_value_orders_snapshot\"\n",
+        "\n",
+        "# Non-pipeline snapshot of simulator.locations so the geo-region row\n",
+        "# filter can bind to a non-critical-path table.  The live\n",
+        "# simulator.locations table is read by the ops-dashboard app's /api/revenue\n",
+        "# (LEFT JOIN against gold_*), and the row filter dropped every row for\n",
+        "# the app SP because the demo geo groups don't exist in fresh accounts —\n",
+        "# the dashboard would render empty.  Demo narrative still works on the\n",
+        "# snapshot: \"region row filter on _security.locations_snapshot\".\n",
+        "LOCATIONS_SNAPSHOT  = f\"{GOV_SCHEMA}.locations_snapshot\"\n",
+        "\n",
+        "# (full_object_name, kind, col, tag_key, tag_value)\n",
+        "#   kind ∈ {\"table_column\", \"table\"}\n",
+        "TAG_TARGETS = [\n",
+        "    # PII on the canonical street-address column in simulator.locations.\n",
+        "    # Moved here from lakeflow.silver_order_items.customer_addr (which is a\n",
+        "    # Lakeflow-pipeline table and so can't carry ABAC policies).  The\n",
+        "    # `address` column is loaded as-is from data/canonical/canonical_dataset/\n",
+        "    # locations.parquet and contains real street addresses.\n",
+        "    (f\"{CATALOG}.simulator.locations\",                  \"table_column\", \"address\",       \"caspers_pii\",         \"address\"),\n",
+        "    # Region marker on the location code (sfo/nyc/chi/lax = US; lon/muc/ams/via = EMEA).\n",
+        "    # Bound to the snapshot table — see LOCATIONS_SNAPSHOT comment above for\n",
+        "    # why this is no longer on simulator.locations directly.\n",
+        "    (LOCATIONS_SNAPSHOT,                                \"table_column\", \"location_code\", \"caspers_geo_region\",  \"true\"),\n",
+        "    # Per-order revenue on the non-pipeline snapshot table — the column\n",
+        "    # the high-value policy gates on.  Snapshot is materialized below.\n",
+        "    (HIGH_VALUE_SNAPSHOT,                               \"table_column\", \"order_revenue\", \"caspers_value_class\", \"high_value\"),\n",
+        "    # Table-level sensitivity tag — entire AI-extracted inspections table is regulated.\n",
+        "    (f\"{CATALOG}.food_safety.ai_extracted_inspections\", \"table\",         None,           \"caspers_sensitivity\", \"restricted\"),\n",
+        "]\n",
+        "\n",
+        "# Governed tag policy spec: each key gets a single allowed value (the one\n",
+        "# we apply below).  If you add a new value to TAG_TARGETS, add it here too.\n",
+        "TAG_POLICY_VALUES = {\n",
+        "    \"caspers_pii\":         [\"address\"],\n",
+        "    \"caspers_geo_region\":  [\"true\"],\n",
+        "    \"caspers_value_class\": [\"high_value\"],\n",
+        "    \"caspers_sensitivity\": [\"restricted\"],\n",
+        "}\n",
+        "\n",
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {GOV_SCHEMA} COMMENT 'Casper\\\\'s ABAC UDFs, policy artifacts, and demo snapshot tables.'\")\n",
+        "print(f\"\\u2705 Schema ready: {GOV_SCHEMA}\")\n",
+        "\n",
+        "# Materialize the high-value-order snapshot table before tagging it.  Source\n",
+        "# is lakeflow.gold_order_header which is materialized by the Lakeflow\n",
+        "# pipeline; Environment_Helpers depends on Spark_Declarative_Pipeline so the\n",
+        "# pipeline is at least started, but the gold tables may still be empty/missing\n",
+        "# on a cold first run.  Best-effort: print and continue if the source table\n",
+        "# isn't ready yet — a subsequent re-run of Environment_Helpers will create it.\n",
+        "print()\n",
+        "print(f\"\\u2014 Materializing {HIGH_VALUE_SNAPSHOT} \\u2014\")\n",
+        "src_table = f\"{CATALOG}.lakeflow.gold_order_header\"\n",
+        "try:\n",
+        "    if not spark.catalog.tableExists(src_table):\n",
+        "        print(f\"  \\u26a0\\ufe0f  source table {src_table} doesn't exist yet \"\n",
+        "              f\"(pipeline hasn't produced gold tables) \\u2014 skipping snapshot. \"\n",
+        "              f\"Re-run Environment_Helpers after the pipeline has produced data.\")\n",
+        "    else:\n",
+        "        spark.sql(f\"\"\"\n",
+        "        CREATE OR REPLACE TABLE {HIGH_VALUE_SNAPSHOT}\n",
+        "        COMMENT 'Non-pipeline snapshot of lakeflow.gold_order_header so an ABAC policy can bind to it. Refreshed only when Environment_Helpers runs.'\n",
+        "        AS SELECT * FROM {src_table}\n",
+        "        \"\"\")\n",
+        "        row_count = spark.table(HIGH_VALUE_SNAPSHOT).count()\n",
+        "        print(f\"  \\u2705 {HIGH_VALUE_SNAPSHOT} ({row_count} rows)\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  \\u274c FAILED to create snapshot: {str(e).splitlines()[0]}\")\n",
+        "    print(f\"     The high-value-order tag in step (b) will fail; policy in step 3 will create on an empty schema.\")\n",
+        "\n",
+        "# Non-pipeline snapshot of simulator.locations.  See the LOCATIONS_SNAPSHOT\n",
+        "# comment near the top of this cell for why the geo-region tag and policy\n",
+        "# were moved off the live simulator.locations table.\n",
+        "print()\n",
+        "print(f\"\\u2014 Materializing {LOCATIONS_SNAPSHOT} \\u2014\")\n",
+        "loc_src = f\"{CATALOG}.simulator.locations\"\n",
+        "try:\n",
+        "    if not spark.catalog.tableExists(loc_src):\n",
+        "        print(f\"  \\u26a0\\ufe0f  source table {loc_src} doesn't exist yet \"\n",
+        "              f\"(canonical_data hasn't run) \\u2014 skipping snapshot. \"\n",
+        "              f\"Re-run Environment_Helpers after Canonical_Data has loaded.\")\n",
+        "    else:\n",
+        "        spark.sql(f\"\"\"\n",
+        "        CREATE OR REPLACE TABLE {LOCATIONS_SNAPSHOT}\n",
+        "        COMMENT 'Non-pipeline snapshot of simulator.locations so the geo-region ABAC policy can bind to it without filtering rows out of the live ops-dashboard query path. Refreshed only when Environment_Helpers runs.'\n",
+        "        AS SELECT * FROM {loc_src}\n",
+        "        \"\"\")\n",
+        "        loc_rows = spark.table(LOCATIONS_SNAPSHOT).count()\n",
+        "        print(f\"  \\u2705 {LOCATIONS_SNAPSHOT} ({loc_rows} rows)\")\n",
+        "except Exception as e:\n",
+        "    print(f\"  \\u274c FAILED to create snapshot: {str(e).splitlines()[0]}\")\n",
+        "    print(f\"     The geo-region tag in step (b) will fail; policy in step 3 will create on an empty schema.\")\n",
+        "\n",
+        "# Cleanup: drop the previous geo-region binding on the live simulator.locations\n",
+        "# (older deploys tagged the live table; we now tag the snapshot instead so the\n",
+        "# ops dashboard's /api/revenue isn't filtered out for the app SP).\n",
+        "# Best-effort: ignore failures on fresh deployments where there's nothing to drop.\n",
+        "print()\n",
+        "print(\"\\u2014 Cleaning up legacy bindings on simulator schema \\u2014\")\n",
+        "for cleanup_sql in [\n",
+        "    f\"ALTER TABLE {CATALOG}.simulator.locations ALTER COLUMN location_code UNSET TAGS ('caspers_geo_region')\",\n",
+        "    f\"DROP POLICY IF EXISTS caspers_region_filter ON SCHEMA {CATALOG}.simulator\",\n",
+        "]:\n",
+        "    try:\n",
+        "        spark.sql(cleanup_sql)\n",
+        "        print(f\"  \\u2705 {cleanup_sql.split(chr(10))[0][:80]}\")\n",
+        "    except Exception as e:\n",
+        "        msg = str(e).splitlines()[0]\n",
+        "        if any(s in msg for s in (\"does not exist\", \"DOES_NOT_EXIST\", \"not found\", \"NOT_FOUND\")):\n",
+        "            print(f\"  \\u2192 nothing to clean up: {cleanup_sql.split(chr(10))[0][:60]}\")\n",
+        "        else:\n",
+        "            print(f\"  \\u26a0\\ufe0f  cleanup failed (non-fatal): {msg}\")\n",
+        "\n",
+        "# (a) Register governed tag policies.\n",
+        "print()\n",
+        "print(\"\\u2014 Registering governed tag policies \\u2014\")\n",
+        "try:\n",
+        "    from databricks.sdk import WorkspaceClient\n",
+        "    from databricks.sdk.service.tags import TagPolicy, Value\n",
+        "    _w_tags = WorkspaceClient()\n",
+        "    _tag_policy_api_available = True\n",
+        "except Exception as e:\n",
+        "    print(f\"  \\u26a0\\ufe0f  databricks-sdk too old for tag policies ({e}); ABAC policies in step 3 will fail\")\n",
+        "    _tag_policy_api_available = False\n",
+        "\n",
+        "if _tag_policy_api_available:\n",
+        "    for key, values in TAG_POLICY_VALUES.items():\n",
+        "        try:\n",
+        "            _w_tags.tag_policies.create_tag_policy(\n",
+        "                TagPolicy(\n",
+        "                    tag_key=key,\n",
+        "                    description=f\"Casper's ABAC governed tag for {key}.\",\n",
+        "                    values=[Value(name=v) for v in values],\n",
+        "                )\n",
+        "            )\n",
+        "            print(f\"  \\u2705 governed tag policy: {key} (values: {values})\")\n",
+        "        except Exception as e:\n",
+        "            msg = str(e).splitlines()[0]\n",
+        "            if \"ALREADY_EXISTS\" in msg or \"already exists\" in msg.lower() or \"409\" in msg:\n",
+        "                print(f\"  \\u267b\\ufe0f  governed tag policy already exists: {key}\")\n",
+        "            else:\n",
+        "                print(f\"  \\u26a0\\ufe0f  could not create governed tag policy {key} ({type(e).__name__}): {msg}\")\n",
+        "                print(f\"     ABAC policies in step 3 referencing this key will fail until it's registered.\")\n",
+        "\n",
+        "# (b) Apply tags.  Wrap each in try/except so a missing table (target not\n",
+        "# yet materialised by Lakeflow, or skipped in a smaller target) prints and\n",
+        "# the loop continues.  Print the SQL on failure so the actual cause is visible.\n",
+        "print()\n",
+        "print(\"\\u2014 Applying tags to UC securables \\u2014\")\n",
+        "applied = 0\n",
+        "for full_name, kind, col, tag_key, tag_value in TAG_TARGETS:\n",
+        "    tag_clause = f\"'{tag_key}' = '{tag_value}'\"\n",
+        "    if kind == \"table\":\n",
+        "        sql = f\"ALTER TABLE {full_name} SET TAGS ({tag_clause})\"\n",
+        "    else:\n",
+        "        sql = f\"ALTER TABLE {full_name} ALTER COLUMN `{col}` SET TAGS ({tag_clause})\"\n",
+        "    try:\n",
+        "        spark.sql(sql)\n",
+        "        applied += 1\n",
+        "        print(f\"  \\u2705 tagged: {full_name}{f'.{col}' if col else ''} \\u2192 {tag_clause}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"  \\u274c FAILED {full_name}{f'.{col}' if col else ''}: {str(e).splitlines()[0]}\")\n",
+        "        print(f\"     SQL: {sql}\")\n",
+        "\n",
+        "print(f\"\\n   {applied}/{len(TAG_TARGETS)} tags applied successfully\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ABAC step 2/4: UDFs that implement the row-filter / column-mask logic.\n",
+        "#\n",
+        "# These are tiny SQL functions that each ABAC policy references. Keeping the\n",
+        "# logic in named UDFs makes the policies declarative and lets the security\n",
+        "# team audit/edit the rules independently of where they're applied.\n",
+        "# All four are `CREATE OR REPLACE` so re-running the cell updates the body\n",
+        "# in place without breaking the policies that reference them.\n",
+        "\n",
+        "UDFS = [\n",
+        "    # 1. PII column mask.  Returns the original address only to members of\n",
+        "    # `caspers_pii_readers`; everyone else sees `***` (workspace admins\n",
+        "    # always bypass row filters / column masks regardless of this UDF).\n",
+        "    f\"\"\"\n",
+        "    CREATE OR REPLACE FUNCTION {GOV_SCHEMA}.mask_pii(value STRING)\n",
+        "    RETURNS STRING\n",
+        "    COMMENT 'Mask PII unless caller is in caspers_pii_readers group.'\n",
+        "    RETURN CASE\n",
+        "      WHEN is_account_group_member('caspers_pii_readers') THEN value\n",
+        "      ELSE '***'\n",
+        "    END\n",
+        "    \"\"\",\n",
+        "\n",
+        "    # 2. Region row filter.  Returns TRUE (row visible) if the caller is in\n",
+        "    # `caspers_geo_admins` OR in the region group matching the row's\n",
+        "    # location_code prefix. US codes: sfo/nyc/chi/lax; EMEA: lon/muc/ams/via.\n",
+        "    f\"\"\"\n",
+        "    CREATE OR REPLACE FUNCTION {GOV_SCHEMA}.filter_by_region(location_code STRING)\n",
+        "    RETURNS BOOLEAN\n",
+        "    COMMENT 'Region-based row filter: US codes for caspers_us_users, EMEA codes for caspers_emea_users, all for caspers_geo_admins.'\n",
+        "    RETURN\n",
+        "      is_account_group_member('caspers_geo_admins')\n",
+        "      OR (location_code IN ('sfo','nyc','chi','lax') AND is_account_group_member('caspers_us_users'))\n",
+        "      OR (location_code IN ('lon','muc','ams','via') AND is_account_group_member('caspers_emea_users'))\n",
+        "    \"\"\",\n",
+        "\n",
+        "    # 3. High-value order row filter.  Orders <= $500 are visible to anyone;\n",
+        "    # higher-revenue orders only to caspers_finance / caspers_managers.\n",
+        "    f\"\"\"\n",
+        "    CREATE OR REPLACE FUNCTION {GOV_SCHEMA}.filter_high_value(order_revenue DOUBLE)\n",
+        "    RETURNS BOOLEAN\n",
+        "    COMMENT 'Hide orders > $500 unless caller is in caspers_finance or caspers_managers.'\n",
+        "    RETURN\n",
+        "      COALESCE(order_revenue, 0) <= 500\n",
+        "      OR is_account_group_member('caspers_finance')\n",
+        "      OR is_account_group_member('caspers_managers')\n",
+        "    \"\"\",\n",
+        "\n",
+        "    # 4. Regulated-document row filter.  Tables tagged `caspers_sensitivity\n",
+        "    # = restricted` show no rows unless caller is in caspers_compliance.  This\n",
+        "    # is the \"table-level deny\" pattern — no per-row data needed, so the\n",
+        "    # function takes no arguments (the policy uses WHEN-clause matching).\n",
+        "    f\"\"\"\n",
+        "    CREATE OR REPLACE FUNCTION {GOV_SCHEMA}.filter_regulated_docs()\n",
+        "    RETURNS BOOLEAN\n",
+        "    COMMENT 'Hide all rows of tables tagged sensitivity=restricted unless caller is in caspers_compliance.'\n",
+        "    RETURN is_account_group_member('caspers_compliance')\n",
+        "    \"\"\",\n",
+        "]\n",
+        "\n",
+        "for udf_sql in UDFS:\n",
+        "    try:\n",
+        "        spark.sql(udf_sql)\n",
+        "        # Pull function name from the SQL for the print\n",
+        "        name = udf_sql.split(\"FUNCTION\", 1)[1].split(\"(\", 1)[0].strip()\n",
+        "        print(f\"\\u2705 created/updated UDF: {name}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f  UDF create failed: {str(e).splitlines()[0]}\")\n",
+        "\n",
+        "# Grant EXECUTE on each UDF to `account users` so the ABAC policies can\n",
+        "# actually invoke them in non-admin sessions.\n",
+        "for fname in [\"mask_pii\", \"filter_by_region\", \"filter_high_value\", \"filter_regulated_docs\"]:\n",
+        "    try:\n",
+        "        spark.sql(f\"GRANT EXECUTE ON FUNCTION {GOV_SCHEMA}.{fname} TO `account users`\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f  GRANT EXECUTE on {fname} failed: {str(e).splitlines()[0]}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ABAC step 3/4: declare the 4 policies.\n",
+        "#\n",
+        "# Two important shape decisions vs the earlier version:\n",
+        "#\n",
+        "#   1. `has_tag(...)` / `has_tag_value(...)` use the underscored tag keys\n",
+        "#      (caspers_pii etc.) that step 1 actually applies.  Dots in keys are\n",
+        "#      rejected by UC tag DDL — see step 1 for the verification.\n",
+        "#\n",
+        "#   2. NO `EXCEPT <group>` clauses.  `CREATE POLICY` validates EXCEPT\n",
+        "#      principals at creation time (PRINCIPAL_DOES_NOT_EXIST), so the\n",
+        "#      earlier code hard-failed against any workspace whose account\n",
+        "#      didn't already have the seven demo groups.  All bypass logic now\n",
+        "#      lives entirely inside the UDFs (step 2), which use\n",
+        "#      `is_account_group_member(...)` — that function returns false for\n",
+        "#      missing groups instead of erroring, so the policies create\n",
+        "#      cleanly with or without the groups.  Demo groups become truly\n",
+        "#      optional: present = users in those groups see unmasked data;\n",
+        "#      absent = mask/filter applies to everyone (workspace admins still\n",
+        "#      bypass everything, per UC semantics).\n",
+        "#\n",
+        "# Requires Databricks Runtime 16.4+ (CREATE POLICY syntax) on the SQL\n",
+        "# warehouse used by readers.\n",
+        "\n",
+        "POLICIES = [\n",
+        "    # 1. PII column mask over any column tagged `caspers_pii=*` in the\n",
+        "    # simulator schema — picks up simulator.locations.address (and any\n",
+        "    # future PII columns added there).  Scope was `lakeflow` until we hit\n",
+        "    # ABAC_POLICIES_NOT_SUPPORTED on the Lakeflow-pipeline tables; see the\n",
+        "    # markdown intro for the full reasoning.\n",
+        "    (f\"{CATALOG}.simulator\",\n",
+        "     \"SCHEMA\",\n",
+        "     \"caspers_mask_pii\",\n",
+        "     f\"\"\"\n",
+        "     CREATE OR REPLACE POLICY caspers_mask_pii\n",
+        "     ON SCHEMA {CATALOG}.simulator\n",
+        "     COMMENT 'Mask PII columns; bypass logic lives in mask_pii UDF (caspers_pii_readers group).'\n",
+        "     COLUMN MASK {GOV_SCHEMA}.mask_pii\n",
+        "     TO `account users`\n",
+        "     FOR TABLES\n",
+        "     MATCH COLUMNS has_tag('caspers_pii') AS pii_col\n",
+        "     ON COLUMN pii_col\n",
+        "     \"\"\"),\n",
+        "\n",
+        "    # 2. Region row filter on any table whose column carries\n",
+        "    # `caspers_geo_region`.  Scoped to {GOV_SCHEMA} (where the\n",
+        "    # locations_snapshot lives) instead of {CATALOG}.simulator, so the\n",
+        "    # live simulator.locations table stays unfiltered for the ops-dashboard\n",
+        "    # app SP — see LOCATIONS_SNAPSHOT comment above.\n",
+        "    (GOV_SCHEMA,\n",
+        "     \"SCHEMA\",\n",
+        "     \"caspers_region_filter\",\n",
+        "     f\"\"\"\n",
+        "     CREATE OR REPLACE POLICY caspers_region_filter\n",
+        "     ON SCHEMA {GOV_SCHEMA}\n",
+        "     COMMENT 'Region row filter; bypass logic lives in filter_by_region UDF (caspers_geo_admins / caspers_us_users / caspers_emea_users).'\n",
+        "     ROW FILTER {GOV_SCHEMA}.filter_by_region\n",
+        "     TO `account users`\n",
+        "     FOR TABLES\n",
+        "     MATCH COLUMNS has_tag('caspers_geo_region') AS region_col\n",
+        "     USING COLUMNS (region_col)\n",
+        "     \"\"\"),\n",
+        "\n",
+        "    # 3. High-value-order gate on tables with a column tagged\n",
+        "    # `caspers_value_class = high_value`.  Targets the non-pipeline\n",
+        "    # snapshot table _security.high_value_orders_snapshot (CTAS from\n",
+        "    # lakeflow.gold_order_header) — see the markdown intro for why we\n",
+        "    # snapshot instead of binding to the pipeline table directly.\n",
+        "    (GOV_SCHEMA,\n",
+        "     \"SCHEMA\",\n",
+        "     \"caspers_high_value_gate\",\n",
+        "     f\"\"\"\n",
+        "     CREATE OR REPLACE POLICY caspers_high_value_gate\n",
+        "     ON SCHEMA {GOV_SCHEMA}\n",
+        "     COMMENT 'Hide high-value orders; bypass logic lives in filter_high_value UDF (caspers_finance / caspers_managers).'\n",
+        "     ROW FILTER {GOV_SCHEMA}.filter_high_value\n",
+        "     TO `account users`\n",
+        "     FOR TABLES\n",
+        "     MATCH COLUMNS has_tag_value('caspers_value_class', 'high_value') AS revenue_col\n",
+        "     USING COLUMNS (revenue_col)\n",
+        "     \"\"\"),\n",
+        "\n",
+        "    # 4. Regulated-doc deny on any table tagged\n",
+        "    # `caspers_sensitivity = restricted` in food_safety.\n",
+        "    (f\"{CATALOG}.food_safety\",\n",
+        "     \"SCHEMA\",\n",
+        "     \"caspers_regulated_docs\",\n",
+        "     f\"\"\"\n",
+        "     CREATE OR REPLACE POLICY caspers_regulated_docs\n",
+        "     ON SCHEMA {CATALOG}.food_safety\n",
+        "     COMMENT 'Hide restricted-tagged tables; bypass logic lives in filter_regulated_docs UDF (caspers_compliance).'\n",
+        "     ROW FILTER {GOV_SCHEMA}.filter_regulated_docs\n",
+        "     TO `account users`\n",
+        "     FOR TABLES\n",
+        "     WHEN has_tag_value('caspers_sensitivity', 'restricted')\n",
+        "     \"\"\"),\n",
+        "]\n",
+        "\n",
+        "created = 0\n",
+        "for securable, kind, name, sql in POLICIES:\n",
+        "    try:\n",
+        "        spark.sql(sql)\n",
+        "        created += 1\n",
+        "        print(f\"\\u2705 created policy {name} on {kind} {securable}\")\n",
+        "    except Exception as e:\n",
+        "        msg = str(e).splitlines()[0]\n",
+        "        print(f\"\\u274c FAILED policy {name}: {msg}\")\n",
+        "\n",
+        "print(f\"\\n   {created}/{len(POLICIES)} policies created successfully\")\n",
+        "print(f\"   Verify via:  SHOW POLICIES IN SCHEMA {CATALOG}.simulator;\")\n",
+        "print(f\"                SHOW POLICIES IN SCHEMA {GOV_SCHEMA};\")\n",
+        "print(f\"                SHOW POLICIES IN SCHEMA {CATALOG}.food_safety;\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# (Reserved cell. Previously held a fourth ABAC-step block; now removed.)\n",
+        "pass"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Discover Domain tagging (DAIS 2026 beat)\n",
+        "\n",
+        "Creates three governed tag policies and applies them to every UC securable\n",
+        "the demo materialises plus the five `all`-target AI/BI dashboards, so the\n",
+        "three Discover Domains (created manually in the UI per\n",
+        "`demos/dais2026-runbooks/SETUP.ipynb` §4) auto-surface their assets via\n",
+        "**Catalog → Discover**:\n",
+        "\n",
+        "| Domain | Tag |\n",
+        "|---|---|\n",
+        "| Operations | `caspers_domain_operations = true` |\n",
+        "| Revenue & Customers | `caspers_domain_revenue = true` |\n",
+        "| Compliance & Safety | `caspers_domain_compliance = true` |\n",
+        "\n",
+        "Boolean tag stacking lets the same asset live in multiple domains without\n",
+        "duplication — e.g. `lakeflow.silver_order_items` carries both\n",
+        "`caspers_domain_operations` and `caspers_domain_revenue` because the table\n",
+        "powers both operational dashboards and revenue analytics.\n",
+        "\n",
+        "Keys use underscores (not dots) because the workspace-entity tag-assignment\n",
+        "API rejects `, . : / - =` in tag keys; UC SQL DDL accepts dots fine, but\n",
+        "one shared key shape lets a single Domain bind both UC tables and Genie\n",
+        "spaces / apps / dashboards.\n",
+        "\n",
+        "Shared helpers live in `utils/domain_tags.py`.  Genie spaces and Apps are\n",
+        "tagged by their own stages (`Genie_Spaces`, `Databricks_App_Refund_Manager`,\n",
+        "`Operational_App`) so each stage owns its own assets' tags.\n",
+        "\n",
+        "Same best-effort pattern as the ABAC tag block: missing securables (target\n",
+        "that doesn't materialise the table) or missing tag-policy admin (governed\n",
+        "tag creation falls back to plain SQL tags) print a warning and the cell\n",
+        "continues so the stage stays safe across all targets."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Discover Domain tagging.  See utils/domain_tags.py for the shared\n",
+        "# helpers (ensure_domain_tag_policies, tag_uc_securable,\n",
+        "# tag_workspace_entity).  This cell owns:\n",
+        "#\n",
+        "#   1. Governed tag policy creation (the only place we call it in the\n",
+        "#      job — other stages call ensure_domain_tag_policies() defensively\n",
+        "#      but the network call is a no-op if the policies already exist).\n",
+        "#   2. UC securable tagging (catalog, schemas, tables) via SQL DDL.\n",
+        "#   3. AI/BI dashboard tagging (all-target only) via the workspace-entity\n",
+        "#      tag-assignment API, looked up by name so we don't hard-code IDs.\n",
+        "#\n",
+        "# Genie spaces and Databricks Apps are tagged by their own stages so each\n",
+        "# stage owns its assets' tags — see stages/genie_spaces.ipynb,\n",
+        "# stages/apps.ipynb, stages/operational_app.ipynb.\n",
+        "\n",
+        "import sys, os\n",
+        "sys.path.insert(0, os.path.abspath(\"..\"))  # stages/ -> repo root\n",
+        "from utils.domain_tags import ensure_domain_tag_policies, tag_uc_securable, tag_workspace_entity\n",
+        "\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "print(\"— Creating governed tag policies —\")\n",
+        "ensure_domain_tag_policies(w, spark=spark)\n",
+        "\n",
+        "# (full_object_name, kind, domains)   kind ∈ {\"catalog\", \"schema\", \"table\"}\n",
+        "UC_TARGETS = [\n",
+        "    # Catalog — surfaces in every domain so the catalog itself shows up\n",
+        "    # as the parent in each Domain view.\n",
+        "    (f\"{CATALOG}\", \"catalog\", [\"operations\", \"revenue\", \"compliance\"]),\n",
+        "\n",
+        "    # Schemas — top-level entry points each domain user expects to see.\n",
+        "    (f\"{CATALOG}.lakeflow\",    \"schema\", [\"operations\", \"revenue\"]),\n",
+        "    (f\"{CATALOG}.simulator\",   \"schema\", [\"operations\"]),\n",
+        "    (f\"{CATALOG}.food_safety\", \"schema\", [\"operations\", \"compliance\"]),\n",
+        "    (f\"{CATALOG}._security\",   \"schema\", [\"compliance\"]),\n",
+        "\n",
+        "    # Lakeflow medallion tables — granular per-table tagging so each\n",
+        "    # domain only surfaces the tables that matter to it.\n",
+        "    (f\"{CATALOG}.lakeflow.all_events\",                       \"table\", [\"operations\", \"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.silver_order_items\",               \"table\", [\"operations\", \"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_order_header\",                \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_item_sales_day\",              \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_brand_sales_day\",             \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_location_sales_hourly\",       \"table\", [\"operations\", \"revenue\"]),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_location_order_status_daily\", \"table\", [\"operations\"]),\n",
+        "\n",
+        "    # Simulator lookup tables.\n",
+        "    (f\"{CATALOG}.simulator.locations\",       \"table\", [\"operations\"]),\n",
+        "    (f\"{CATALOG}.simulator.brands\",          \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.simulator.items\",           \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.simulator.menus\",           \"table\", [\"revenue\"]),\n",
+        "    (f\"{CATALOG}.simulator.brand_locations\", \"table\", [\"operations\", \"revenue\"]),\n",
+        "\n",
+        "    # AI-SQL inspection tables — compliance owns the regulated/extracted\n",
+        "    # version; operations also wants visibility on parsed/classified/summary.\n",
+        "    (f\"{CATALOG}.food_safety.ai_parsed_inspections\",     \"table\", [\"operations\", \"compliance\"]),\n",
+        "    (f\"{CATALOG}.food_safety.ai_classified_inspections\", \"table\", [\"operations\", \"compliance\"]),\n",
+        "    (f\"{CATALOG}.food_safety.ai_extracted_inspections\",  \"table\", [\"compliance\"]),\n",
+        "    (f\"{CATALOG}.food_safety.ai_summarized_inspections\", \"table\", [\"operations\", \"compliance\"]),\n",
+        "\n",
+        "    # Non-pipeline snapshot table used by the high-value-order ABAC policy\n",
+        "    # (cell 13).  Tagged compliance (it's a governance artifact) and\n",
+        "    # revenue (it carries per-order revenue numbers).\n",
+        "    (f\"{CATALOG}._security.high_value_orders_snapshot\",  \"table\", [\"compliance\", \"revenue\"]),\n",
+        "]\n",
+        "\n",
+        "print()\n",
+        "print(\"— Tagging UC securables —\")\n",
+        "for full_name, kind, domains in UC_TARGETS:\n",
+        "    tag_uc_securable(spark, kind, full_name, domains)\n",
+        "\n",
+        "# AI/BI dashboards (all-target only).  DABs deploys them, naming them\n",
+        "# \"Casper's Kitchen - <subject> (<catalog>)\" — we look up by name so we\n",
+        "# don't have to wire the dashboard IDs through to this cell.  Each\n",
+        "# dashboard is tagged with the domain(s) it primarily serves.\n",
+        "DASHBOARD_DOMAINS = [\n",
+        "    (\"Casper's Kitchen - Operations\",                    [\"operations\"]),\n",
+        "    (\"Casper's Kitchen - Operations - Dark\",             [\"operations\"]),\n",
+        "    (\"Casper's Kitchen - Delivery Performance & SLA\",    [\"operations\"]),\n",
+        "    (\"Casper's Kitchen - AI Agent Performance\",          [\"operations\"]),\n",
+        "    (\"Casper's Kitchen - Menu Intelligence & Nutrition\", [\"revenue\", \"compliance\"]),\n",
+        "]\n",
+        "\n",
+        "print()\n",
+        "print(\"— Tagging AI/BI dashboards —\")\n",
+        "# w.lakeview.list() returns Dashboard objects with `dashboard_id` and\n",
+        "# `display_name` populated by default (DASHBOARD_VIEW_BASIC is the API default).\n",
+        "try:\n",
+        "    all_dashboards = list(w.lakeview.list())\n",
+        "except Exception as e:\n",
+        "    print(f\"  \\u26a0\\ufe0f  could not list dashboards ({type(e).__name__}: {e}); skipping dashboard tagging\")\n",
+        "    all_dashboards = []\n",
+        "\n",
+        "for prefix, domains in DASHBOARD_DOMAINS:\n",
+        "    expected_name = f\"{prefix} ({CATALOG})\"\n",
+        "    match = next((d for d in all_dashboards if getattr(d, \"display_name\", \"\") == expected_name), None)\n",
+        "    if match is None:\n",
+        "        print(f\"  \\u26a0\\ufe0f  dashboard not found: {expected_name!r} (skipped — likely a non-all target)\")\n",
+        "        continue\n",
+        "    dash_id = getattr(match, \"dashboard_id\", None) or getattr(match, \"id\", None)\n",
+        "    if not dash_id:\n",
+        "        print(f\"  \\u26a0\\ufe0f  dashboard {expected_name!r} has no id; skipped\")\n",
+        "        continue\n",
+        "    tag_workspace_entity(w, \"dashboards\", dash_id, domains, label=f\"dashboard {expected_name!r}\")\n",
+        "\n",
+        "print()\n",
+        "print(\"— Environment_Helpers summary —\")\n",
+        "print(f\"  ABAC tags:        check the per-target output above (cell 11)\")\n",
+        "print(f\"  ABAC UDFs:        created in {GOV_SCHEMA} (cell 12)\")\n",
+        "print(f\"  ABAC policies:    check the per-policy output above (cell 13)\")\n",
+        "print(f\"  Discover Domain tags: check the per-target output above (cells 15-16)\")\n",
+        "print()\n",
+        "print(\"Verify in the UI:\")\n",
+        "print(f\"  - Tags:     Catalog Explorer → {CATALOG} → (any tagged table) → Tags tab\")\n",
+        "print(f\"  - Policies: SHOW POLICIES IN SCHEMA {CATALOG}.lakeflow;\")\n",
+        "print(f\"  - Domains:  Catalog Explorer → Discover → Domains\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": null,
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "environment_helpers",
+      "widgets": {}
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/stages/genie_spaces.ipynb b/stages/genie_spaces.ipynb
new file mode 100644
index 0000000..1365b7f
--- /dev/null
+++ b/stages/genie_spaces.ipynb
@@ -0,0 +1,1396 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Genie Spaces\n",
+        "\n",
+        "Creates the Databricks Genie spaces used by the operational dashboard supervisor:\n",
+        "\n",
+        "- **Revenue & Orders Intelligence** — real-time revenue, order volume, and location\n",
+        "  performance from Lakeflow gold tables.\n",
+        "- **Operations Intelligence** — kitchen ops, event patterns, location health, and\n",
+        "  food safety signals from Lakeflow + food_safety tables.\n",
+        "- **Menu & Safety Intelligence** — menu items, nutrition, allergens, inspection\n",
+        "  scores, and violations from the menu_documents pipeline.\n",
+        "\n",
+        "All spaces share a single SQL warehouse and reuse `create_or_get_genie()` so the\n",
+        "stage is idempotent."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create or reuse a SQL warehouse for the Genie spaces"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import json, hashlib, sys\n",
+        "\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "WAREHOUSE_NAME = f\"{CATALOG}-genie-warehouse\"\n",
+        "existing_wh = [wh for wh in w.warehouses.list() if wh.name == WAREHOUSE_NAME]\n",
+        "if existing_wh:\n",
+        "    warehouse = existing_wh[0]\n",
+        "    print(f\"\\u267b\\ufe0f Using existing warehouse: {warehouse.id}\")\n",
+        "else:\n",
+        "    warehouse = w.warehouses.create(\n",
+        "        name=WAREHOUSE_NAME,\n",
+        "        cluster_size=\"Small\",\n",
+        "        max_num_clusters=1,\n",
+        "        min_num_clusters=1,\n",
+        "        enable_serverless_compute=True,\n",
+        "    ).result()\n",
+        "    add(CATALOG, \"warehouses\", warehouse)\n",
+        "    print(f\"\\u2705 Created warehouse: {warehouse.id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Helper: create or reuse a Genie space\n",
+        "\n",
+        "Looks up existing spaces in `uc_state` by title; only creates a new one when no\n",
+        "matching space is found (or the recorded space has been deleted out-of-band)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import uuid\n",
+        "\n",
+        "\n",
+        "def make_questions(questions):\n",
+        "    return [\n",
+        "        {\"id\": hashlib.md5(q.encode()).hexdigest(), \"question\": [q]}\n",
+        "        for q in questions\n",
+        "    ]\n",
+        "\n",
+        "\n",
+        "def _space_warehouse_id(space) -> str | None:\n",
+        "    \"\"\"Best-effort extraction of the warehouse_id a Genie space is bound to.\"\"\"\n",
+        "    for attr in (\"warehouse_id\", \"config_warehouse_id\"):\n",
+        "        v = getattr(space, attr, None)\n",
+        "        if v:\n",
+        "            return v\n",
+        "    return None\n",
+        "\n",
+        "\n",
+        "def _delete_genie_space(space_id: str) -> None:\n",
+        "    \"\"\"Hard-delete a Genie space; tolerate already-gone.\"\"\"\n",
+        "    try:\n",
+        "        w.api_client.do(\"DELETE\", f\"/api/2.0/genie/spaces/{space_id}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️ Failed to delete stale Genie space {space_id}: {e}\")\n",
+        "\n",
+        "\n",
+        "# -----------------------------------------------------------------------------\n",
+        "# serialized_space builders (v1 schema).\n",
+        "#\n",
+        "# Schema sources:\n",
+        "#   - Medium API guide (Dec 2025):  text_instructions + example_question_sqls\n",
+        "#   - Databricks community forum (Jan 6 2026, Databricks Employee response):\n",
+        "#     join_specs and sql_snippets must be nested under `instructions`,\n",
+        "#     NOT under `data_sources`.  This is the format Genie actually persists.\n",
+        "#     https://community.databricks.com/t5/data-engineering/issues-creating-genie-space-via-api-join-specs-are-not-persisted/m-p/143116\n",
+        "#\n",
+        "# Joins use the `--rt=FROM_RELATIONSHIP_TYPE_*--` annotation in the SQL list\n",
+        "# rather than a structured relationship_type field.\n",
+        "# -----------------------------------------------------------------------------\n",
+        "\n",
+        "\n",
+        "def _build_text_instructions(text: str) -> list[dict]:\n",
+        "    \"\"\"Genie expects a list of instruction blocks; each block's `content` is a\n",
+        "    list of strings (typically one per line).  Splitting on newlines keeps the\n",
+        "    UI-rendered text readable without forcing the caller to pre-chunk it.\"\"\"\n",
+        "    lines = text.split(\"\\n\")\n",
+        "    return [{\n",
+        "        \"id\": uuid.uuid4().hex[:32],\n",
+        "        \"content\": [line + \"\\n\" for line in lines],\n",
+        "    }]\n",
+        "\n",
+        "\n",
+        "def _build_example_question_sqls(items) -> list[dict]:\n",
+        "    \"\"\"items: list of dicts with keys 'question' and 'sql'.\"\"\"\n",
+        "    return [\n",
+        "        {\n",
+        "            \"id\": uuid.uuid4().hex[:32],\n",
+        "            \"question\": [item[\"question\"]],\n",
+        "            \"sql\": [item[\"sql\"]],\n",
+        "        }\n",
+        "        for item in items\n",
+        "    ]\n",
+        "\n",
+        "\n",
+        "def _build_benchmarks(items) -> list[dict]:\n",
+        "    \"\"\"Build benchmark question objects for the serialized_space `benchmarks.questions` array.\n",
+        "\n",
+        "    items: list of dicts with keys 'question' (str) and 'sql' (str, the ground-truth SQL).\n",
+        "\n",
+        "    Schema per the Genie Spaces API reference:\n",
+        "      {\n",
+        "        \"id\":       <32-char lowercase hex>,\n",
+        "        \"question\": [<question text>],\n",
+        "        \"answer\":   [{\"format\": \"SQL\", \"content\": [<sql>]}]\n",
+        "      }\n",
+        "\n",
+        "    Notes:\n",
+        "      - `uuid.uuid4().hex` returns a 32-char lowercase hex string (no hyphens),\n",
+        "        which is the format Genie requires.\n",
+        "      - IDs MUST be unique across `config.sample_questions` AND\n",
+        "        `benchmarks.questions` per the API validation rules — we use random\n",
+        "        UUIDs for benchmarks and MD5-of-text for sample questions, so a\n",
+        "        collision would require an MD5 to equal a UUID, which is effectively\n",
+        "        impossible.\n",
+        "      - Each benchmark must have exactly ONE `answer` entry with format=SQL,\n",
+        "        per the API validation rules.\n",
+        "      - Aim for ≥5 benchmarks per space (Databricks best practice).\n",
+        "    \"\"\"\n",
+        "    return [\n",
+        "        {\n",
+        "            \"id\": uuid.uuid4().hex,\n",
+        "            \"question\": [item[\"question\"]],\n",
+        "            \"answer\": [{\"format\": \"SQL\", \"content\": [item[\"sql\"]]}],\n",
+        "        }\n",
+        "        for item in items\n",
+        "    ]\n",
+        "\n",
+        "\n",
+        "def _build_join_spec(\n",
+        "    left_identifier: str,\n",
+        "    right_identifier: str,\n",
+        "    on,\n",
+        "    rt: str = \"FROM_RELATIONSHIP_TYPE_MANY_TO_ONE\",\n",
+        ") -> dict:\n",
+        "    \"\"\"Build one join_spec object.\n",
+        "\n",
+        "    Args:\n",
+        "      left_identifier: fully-qualified left table name.\n",
+        "      right_identifier: fully-qualified right table name.\n",
+        "      on: list of (left_col, right_col) tuples.\n",
+        "      rt: relationship type annotation (MANY_TO_ONE / ONE_TO_MANY / ONE_TO_ONE).\n",
+        "    \"\"\"\n",
+        "    left_alias = left_identifier.split(\".\")[-1]\n",
+        "    right_alias = right_identifier.split(\".\")[-1]\n",
+        "    conds = \" AND \".join(\n",
+        "        f\"`{left_alias}`.`{lc}` = `{right_alias}`.`{rc}`\" for lc, rc in on\n",
+        "    )\n",
+        "    return {\n",
+        "        \"id\": uuid.uuid4().hex[:32],\n",
+        "        \"left\": {\"identifier\": left_identifier, \"alias\": left_alias},\n",
+        "        \"right\": {\"identifier\": right_identifier, \"alias\": right_alias},\n",
+        "        \"sql\": [conds, f\"--rt={rt}--\"],\n",
+        "    }\n",
+        "\n",
+        "\n",
+        "def _merge_genie_content(\n",
+        "    base: dict,\n",
+        "    tables: list[str],\n",
+        "    instructions_text: str,\n",
+        "    example_sqls: list[dict],\n",
+        "    sample_questions: list[str],\n",
+        "    join_specs: list[dict] | None = None,\n",
+        "    benchmarks: list[dict] | None = None,\n",
+        ") -> dict:\n",
+        "    \"\"\"Merge our authored content INTO Genie's freshly-exported serialized_space.\n",
+        "\n",
+        "    We deliberately mutate the dict Genie just handed us back rather than\n",
+        "    building one from scratch — that's the only way to satisfy Genie's\n",
+        "    \"export format\" check, which fails with 'Aborted: The export format has\n",
+        "    changed since this export was taken. Re-export the space and merge your\n",
+        "    changes.' if we POST a hand-built body with a stale/missing version field.\n",
+        "    \"\"\"\n",
+        "    # Genie validates that id-bearing lists are sorted by id; rejects POST\n",
+        "    # with 'InvalidParameterValue: Invalid export proto: <field> must be\n",
+        "    # sorted by id' otherwise.\n",
+        "    def _by_id(items):\n",
+        "        return sorted(items, key=lambda x: x.get(\"id\", \"\"))\n",
+        "\n",
+        "    # REPLACE entire subtrees (don't setdefault/merge): the bootstrap\n",
+        "    # template may carry stale UC function references (function_specs,\n",
+        "    # sql_snippets, certified_answers) under instructions, and stale table\n",
+        "    # refs under data_sources, all pointing at the *previous* catalog.\n",
+        "    # When Genie validates the POST body it'll fail with ROUTINE_NOT_FOUND\n",
+        "    # / TABLE_NOT_FOUND on those.  Wiping the subtrees and writing only what\n",
+        "    # we authored avoids the problem.\n",
+        "    base[\"data_sources\"] = {\"tables\": [{\"identifier\": t} for t in sorted(tables)]}\n",
+        "    instructions: dict = {\n",
+        "        \"text_instructions\": _by_id(_build_text_instructions(instructions_text)),\n",
+        "        \"example_question_sqls\": _by_id(_build_example_question_sqls(example_sqls)),\n",
+        "    }\n",
+        "    if join_specs:\n",
+        "        instructions[\"join_specs\"] = _by_id(join_specs)\n",
+        "    base[\"instructions\"] = instructions\n",
+        "    base[\"config\"] = {\"sample_questions\": _by_id(make_questions(sample_questions))}\n",
+        "\n",
+        "    # Benchmarks: same wipe-and-replace pattern as the other subtrees.  If the\n",
+        "    # bootstrap template carried stale benchmarks pointing at the previous\n",
+        "    # catalog, leaving them in place would make the POST fail validation.\n",
+        "    # Schema documented in the Genie Spaces API reference under\n",
+        "    # `serialized_space.benchmarks.questions`.\n",
+        "    if benchmarks:\n",
+        "        base[\"benchmarks\"] = {\"questions\": _by_id(_build_benchmarks(benchmarks))}\n",
+        "    else:\n",
+        "        base.pop(\"benchmarks\", None)\n",
+        "\n",
+        "    return base\n",
+        "\n",
+        "\n",
+        "def _verify_genie_content(space_id: str, sent: dict) -> None:\n",
+        "    \"\"\"Fetch the space back and log what Genie actually persisted vs sent.\n",
+        "\n",
+        "    Genie's serialized_space schema is sparsely documented and the API\n",
+        "    silently drops fields it doesn't recognise — so a \"successful\" create\n",
+        "    can still produce an empty-looking space in the UI.  This diagnostic\n",
+        "    prints counts on every run so the task log is the source of truth.\n",
+        "\n",
+        "    Note: get_space() does NOT include serialized_space by default; you must\n",
+        "    pass include_serialized_space=True (requires CAN EDIT on the space).\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        fresh = w.genie.get_space(space_id, include_serialized_space=True)\n",
+        "    except Exception as e:\n",
+        "        print(f\"  \\u26a0\\ufe0f verify: could not get_space {space_id}: {e}\")\n",
+        "        return\n",
+        "    raw = getattr(fresh, \"serialized_space\", None)\n",
+        "    if not raw:\n",
+        "        print(f\"  \\u26a0\\ufe0f verify: get_space returned no serialized_space for {space_id}\")\n",
+        "        return\n",
+        "    try:\n",
+        "        got = json.loads(raw) if isinstance(raw, str) else raw\n",
+        "    except Exception as e:\n",
+        "        print(f\"  \\u26a0\\ufe0f verify: serialized_space not JSON: {e}\")\n",
+        "        return\n",
+        "\n",
+        "    got_ins = got.get(\"instructions\") or {}\n",
+        "    got_text = got_ins.get(\"text_instructions\") or []\n",
+        "    got_examples = got_ins.get(\"example_question_sqls\") or []\n",
+        "    got_joins = got_ins.get(\"join_specs\") or []\n",
+        "    got_tables = (got.get(\"data_sources\") or {}).get(\"tables\") or []\n",
+        "    got_questions = (got.get(\"config\") or {}).get(\"sample_questions\") or []\n",
+        "    got_benchmarks = (got.get(\"benchmarks\") or {}).get(\"questions\") or []\n",
+        "\n",
+        "    print(\n",
+        "        f\"  \\U0001F50E verify {space_id}: \"\n",
+        "        f\"tables sent={sent['tables']} got={len(got_tables)} | \"\n",
+        "        f\"text_instructions sent={sent['text']} got={len(got_text)} | \"\n",
+        "        f\"example_sqls sent={sent['examples']} got={len(got_examples)} | \"\n",
+        "        f\"join_specs sent={sent['joins']} got={len(got_joins)} | \"\n",
+        "        f\"sample_questions sent={sent['questions']} got={len(got_questions)} | \"\n",
+        "        f\"benchmarks sent={sent['benchmarks']} got={len(got_benchmarks)}\"\n",
+        "    )\n",
+        "\n",
+        "    missing = []\n",
+        "    if sent[\"text\"] and not got_text:\n",
+        "        missing.append(\"text_instructions\")\n",
+        "    if sent[\"examples\"] and not got_examples:\n",
+        "        missing.append(\"example_question_sqls\")\n",
+        "    if sent[\"joins\"] and not got_joins:\n",
+        "        missing.append(\"join_specs\")\n",
+        "    if sent[\"benchmarks\"] and not got_benchmarks:\n",
+        "        missing.append(\"benchmarks\")\n",
+        "    if missing:\n",
+        "        print(\n",
+        "            f\"  \\u26a0\\ufe0f Genie did NOT persist {missing} for {space_id} — \"\n",
+        "            f\"schema mismatch.  Dumping what Genie returned for debugging:\"\n",
+        "        )\n",
+        "        print(\"  \" + json.dumps(got, indent=2)[:4000])\n",
+        "\n",
+        "\n",
+        "# Identity-bearing fields that vary per-space; we must strip these before\n",
+        "# reusing a template's serialized_space envelope to create a new space.\n",
+        "_TEMPLATE_IDENTITY_FIELDS = (\n",
+        "    \"id\", \"space_id\", \"title\", \"description\",\n",
+        "    \"warehouse_id\", \"created_at\", \"updated_at\",\n",
+        "    \"creator_id\", \"creator\", \"owner\", \"owner_id\",\n",
+        "    \"etag\", \"_etag\",\n",
+        ")\n",
+        "\n",
+        "\n",
+        "def _bootstrap_template_serialized_space(skip_space_ids: set | None = None) -> dict | None:\n",
+        "    \"\"\"Find any existing Genie space and pull its serialized_space as a template.\n",
+        "\n",
+        "    Why this is necessary:\n",
+        "      The SDK docs (databricks/sdk/service/dashboards.py, create_space)\n",
+        "      explicitly say to \"Use the Get Genie Space API to retrieve an example\n",
+        "      response, which includes the serialized_space field\" — i.e. the\n",
+        "      serialized_space format is opaque (carries server-managed version\n",
+        "      metadata) and hand-built bodies are rejected with \"Aborted: The export\n",
+        "      format has changed since this export was taken.\"\n",
+        "\n",
+        "      So we bootstrap by listing existing spaces in the workspace and\n",
+        "      copying one Genie produced, then mutate it before reusing.\n",
+        "\n",
+        "    Returns the parsed dict (envelope to mutate) or None if no usable\n",
+        "    template was found (caller should fall back to serialized_space=None).\n",
+        "    \"\"\"\n",
+        "    skip = skip_space_ids or set()\n",
+        "    try:\n",
+        "        resp = w.genie.list_spaces()\n",
+        "    except Exception as e:\n",
+        "        print(f\"  \\u26a0\\ufe0f list_spaces failed: {e}\")\n",
+        "        return None\n",
+        "    spaces = getattr(resp, \"spaces\", None) or []\n",
+        "    for entry in spaces:\n",
+        "        sid = getattr(entry, \"space_id\", None)\n",
+        "        if not sid or sid in skip:\n",
+        "            continue\n",
+        "        try:\n",
+        "            fresh = w.genie.get_space(sid, include_serialized_space=True)\n",
+        "        except Exception:\n",
+        "            # No CAN EDIT permission, or transient — skip this candidate.\n",
+        "            continue\n",
+        "        raw = getattr(fresh, \"serialized_space\", None)\n",
+        "        if not raw:\n",
+        "            continue\n",
+        "        try:\n",
+        "            parsed = json.loads(raw)\n",
+        "        except Exception:\n",
+        "            continue\n",
+        "        if isinstance(parsed, dict) and parsed:\n",
+        "            print(f\"  \\U0001F4CB Using existing space {sid} as serialized_space template\")\n",
+        "            return parsed\n",
+        "    return None\n",
+        "\n",
+        "\n",
+        "def _scrub_template(envelope: dict) -> dict:\n",
+        "    \"\"\"Remove identity-bearing fields from a template envelope before reusing\n",
+        "    it to create a new space.  Returns the same dict (mutated in place).\"\"\"\n",
+        "    for key in _TEMPLATE_IDENTITY_FIELDS:\n",
+        "        envelope.pop(key, None)\n",
+        "    return envelope\n",
+        "\n",
+        "\n",
+        "def create_or_get_genie(\n",
+        "    title,\n",
+        "    description,\n",
+        "    tables,\n",
+        "    instructions_text,\n",
+        "    example_sqls,\n",
+        "    sample_questions,\n",
+        "    join_specs=None,\n",
+        "    benchmarks=None,\n",
+        "):\n",
+        "    \"\"\"Recreate a Genie space, bootstrapping serialized_space from an existing one.\n",
+        "\n",
+        "    Why this pattern:\n",
+        "      Genie validates serialized_space against an opaque server-managed\n",
+        "      format version.  Hand-built bodies (including \"{}\") are rejected with\n",
+        "      'Aborted: The export format has changed since this export was taken.\n",
+        "      Re-export the space and merge your changes.'  The SDK docs say to\n",
+        "      bootstrap from a real GET response.\n",
+        "\n",
+        "    Flow:\n",
+        "      1. Delete any pre-existing space(s) with this title (uc_state lookup).\n",
+        "      2. Bootstrap a serialized_space template by listing existing workspace\n",
+        "         spaces and pulling one with include_serialized_space=True.\n",
+        "      3. Inject our content (tables, instructions, joins, sample questions)\n",
+        "         into that template, strip identity fields.\n",
+        "      4. create_space with the modified template.\n",
+        "      5. GET the new space (include_serialized_space=True) and re-merge our\n",
+        "         content into the *post-create* envelope (server may have normalized\n",
+        "         our submission), then update_space.\n",
+        "      6. Verify what actually persisted.\n",
+        "\n",
+        "      Fallback: if no template space exists in the workspace, attempt\n",
+        "      create_space(serialized_space=None) — the SDK omits the field, and\n",
+        "      the API may create with defaults; in that case we still GET+update.\n",
+        "\n",
+        "    space_id changes on every run; downstream resolves via uc_state\n",
+        "    (ORDER BY created_at DESC).\n",
+        "    \"\"\"\n",
+        "    # Step 1: Collect old space_ids for this title so we can both delete them\n",
+        "    # AND skip them when looking for a template (don't bootstrap from the\n",
+        "    # exact space we're about to delete).\n",
+        "    #\n",
+        "    # Two passes:\n",
+        "    #   (a) uc_state lookup — fast, authoritative for spaces this stage owns.\n",
+        "    #   (b) Workspace-wide title sweep — Genie spaces are *workspace-scoped*,\n",
+        "    #       not catalog-scoped, so a previous `bundle destroy` (which wipes\n",
+        "    #       uc_state) leaves orphan spaces alive in the workspace.  Without\n",
+        "    #       this sweep, the next create_space + update_space round-trip dies\n",
+        "    #       with `AlreadyExists: Node named '<title>' already exists` because\n",
+        "    #       Genie sees the title collision against the orphan.\n",
+        "    old_space_ids: set[str] = set()\n",
+        "\n",
+        "    # (a) uc_state-tracked spaces\n",
+        "    try:\n",
+        "        df = spark.sql(f\"\"\"\n",
+        "            SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "            WHERE resource_type = 'genie_spaces'\n",
+        "            ORDER BY created_at DESC\n",
+        "        \"\"\")\n",
+        "        for row in df.collect():\n",
+        "            info = json.loads(row.resource_data)\n",
+        "            if info.get(\"title\") != title:\n",
+        "                continue\n",
+        "            sid = info.get(\"space_id\")\n",
+        "            if not sid:\n",
+        "                continue\n",
+        "            try:\n",
+        "                w.genie.get_space(sid)\n",
+        "            except Exception:\n",
+        "                continue\n",
+        "            old_space_ids.add(sid)\n",
+        "            print(f\"\\U0001F5D1\\uFE0F  Deleting pre-existing Genie space {sid} from uc_state (title={title!r})\")\n",
+        "            _delete_genie_space(sid)\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f Could not enumerate existing Genie spaces from uc_state: {e}\")\n",
+        "\n",
+        "    # (b) Workspace-wide orphan sweep — catches spaces left behind by previous\n",
+        "    # `bundle destroy` runs.  We must drain the paginated list_spaces output\n",
+        "    # because a workspace can easily accumulate dozens of stale demo spaces.\n",
+        "    try:\n",
+        "        page_token = None\n",
+        "        scanned = 0\n",
+        "        while True:\n",
+        "            resp = w.genie.list_spaces(page_token=page_token) if page_token else w.genie.list_spaces()\n",
+        "            for entry in (getattr(resp, \"spaces\", None) or []):\n",
+        "                scanned += 1\n",
+        "                if getattr(entry, \"title\", None) != title:\n",
+        "                    continue\n",
+        "                sid = getattr(entry, \"space_id\", None)\n",
+        "                if not sid or sid in old_space_ids:\n",
+        "                    continue\n",
+        "                print(f\"\\U0001F5D1\\uFE0F  Deleting orphan Genie space {sid} from workspace (title={title!r}, not in uc_state)\")\n",
+        "                _delete_genie_space(sid)\n",
+        "                old_space_ids.add(sid)\n",
+        "            page_token = getattr(resp, \"next_page_token\", None)\n",
+        "            if not page_token:\n",
+        "                break\n",
+        "        if scanned:\n",
+        "            print(f\"  \\U0001F50E workspace sweep scanned {scanned} Genie spaces\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f Workspace-wide Genie space sweep failed: {e}\")\n",
+        "\n",
+        "    # Step 2: Bootstrap a template from any other existing space.\n",
+        "    template = _bootstrap_template_serialized_space(skip_space_ids=old_space_ids)\n",
+        "\n",
+        "    # Step 3: Build initial serialized_space.\n",
+        "    if template is not None:\n",
+        "        _scrub_template(template)\n",
+        "        merged = _merge_genie_content(\n",
+        "            template,\n",
+        "            tables=tables,\n",
+        "            instructions_text=instructions_text,\n",
+        "            example_sqls=example_sqls,\n",
+        "            sample_questions=sample_questions,\n",
+        "            join_specs=join_specs,\n",
+        "            benchmarks=benchmarks,\n",
+        "        )\n",
+        "        initial_serialized = json.dumps(merged)\n",
+        "    else:\n",
+        "        print(\"  \\u26a0\\ufe0f No usable Genie space template found; trying create_space with serialized_space=None\")\n",
+        "        initial_serialized = None\n",
+        "\n",
+        "    # Step 4: Create.\n",
+        "    try:\n",
+        "        space = w.genie.create_space(\n",
+        "            warehouse_id=warehouse.id,\n",
+        "            serialized_space=initial_serialized,\n",
+        "            title=title,\n",
+        "            description=description,\n",
+        "        )\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u274c create_space failed: {e}\")\n",
+        "        if initial_serialized is None:\n",
+        "            print(\n",
+        "                \"   Hint: no existing Genie space was found to bootstrap from. \"\n",
+        "                \"Create ONE space manually in the workspace UI (any catalog) and rerun this task — \"\n",
+        "                \"the API requires a real serialized_space template to copy from.\"\n",
+        "            )\n",
+        "        else:\n",
+        "            print(f\"   Template (first 2000 chars):\\n   {initial_serialized[:2000]}\")\n",
+        "        raise\n",
+        "    genie_space_id = space.space_id\n",
+        "    print(f\"\\u2705 Created Genie space: {genie_space_id}\")\n",
+        "    add(CATALOG, \"genie_spaces\", {\"space_id\": genie_space_id, \"title\": title})\n",
+        "\n",
+        "    # Step 5: GET the new space, re-merge content, push back via update_space.\n",
+        "    # We do this even on the template path because (a) the server may have\n",
+        "    # normalized our submission, and (b) if we created with None, this is\n",
+        "    # the first time we get to inject content at all.\n",
+        "    try:\n",
+        "        fresh = w.genie.get_space(genie_space_id, include_serialized_space=True)\n",
+        "        raw = getattr(fresh, \"serialized_space\", None)\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f get_space after create failed: {e}; skipping content update\")\n",
+        "        raw = None\n",
+        "\n",
+        "    if raw:\n",
+        "        try:\n",
+        "            envelope = json.loads(raw)\n",
+        "        except Exception as e:\n",
+        "            print(f\"\\u26a0\\ufe0f Could not parse post-create serialized_space ({e})\")\n",
+        "            envelope = {}\n",
+        "        merged = _merge_genie_content(\n",
+        "            envelope,\n",
+        "            tables=tables,\n",
+        "            instructions_text=instructions_text,\n",
+        "            example_sqls=example_sqls,\n",
+        "            sample_questions=sample_questions,\n",
+        "            join_specs=join_specs,\n",
+        "            benchmarks=benchmarks,\n",
+        "        )\n",
+        "        try:\n",
+        "            w.genie.update_space(\n",
+        "                space_id=genie_space_id,\n",
+        "                serialized_space=json.dumps(merged),\n",
+        "                title=title,\n",
+        "                description=description,\n",
+        "                warehouse_id=warehouse.id,\n",
+        "            )\n",
+        "            print(f\"\\u2705 Pushed content to Genie space {genie_space_id}\")\n",
+        "        except Exception as e:\n",
+        "            print(f\"\\u274c update_space failed: {e}\")\n",
+        "            print(f\"   Genie's fresh export (first 2000 chars):\\n   {raw[:2000]}\")\n",
+        "            print(f\"   Our merged version (first 2000 chars):\\n   {json.dumps(merged, indent=2)[:2000]}\")\n",
+        "            raise\n",
+        "\n",
+        "    _verify_genie_content(\n",
+        "        genie_space_id,\n",
+        "        sent={\n",
+        "            \"tables\": len(tables),\n",
+        "            \"text\": 1 if instructions_text else 0,\n",
+        "            \"examples\": len(example_sqls or []),\n",
+        "            \"joins\": len(join_specs or []),\n",
+        "            \"questions\": len(sample_questions or []),\n",
+        "            \"benchmarks\": len(benchmarks or []),\n",
+        "        },\n",
+        "    )\n",
+        "\n",
+        "    return genie_space_id"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Revenue & Orders Intelligence Genie"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "REVENUE_TITLE = f\"Revenue & Orders Intelligence ({CATALOG})\"\n",
+        "\n",
+        "REVENUE_DESCRIPTION = (\n",
+        "    \"Revenue and order analytics for Casper's Kitchens. \"\n",
+        "    \"Uses pre-aggregated Lakeflow gold tables for fast queries on per-location, \"\n",
+        "    \"per-brand, and per-order revenue, joined to simulator dimensions for friendly names.\"\n",
+        ")\n",
+        "\n",
+        "# General instructions — kept under ~20 lines per Genie best practice.\n",
+        "REVENUE_INSTRUCTIONS = \"\"\"You are a revenue analytics assistant for Casper's Kitchens, a ghost-kitchen network.\n",
+        "Always prefer pre-aggregated Gold tables — they are 10-100x faster than scanning all_events.\n",
+        "\n",
+        "Table routing (smallest table that can answer wins):\n",
+        "- Revenue / orders per location, time-series  -> gold_location_sales_hourly JOIN simulator.locations\n",
+        "- Revenue / orders per brand, daily           -> gold_brand_sales_day JOIN simulator.brands\n",
+        "- Average order value, per-order metrics      -> gold_order_header JOIN simulator.locations\n",
+        "- Item-level detail                            -> silver_order_items\n",
+        "- Raw event detail (LAST RESORT)               -> all_events (1M+ rows, JSON body)\n",
+        "\n",
+        "Conventions:\n",
+        "- Revenue columns are already SUM-able: revenue (gold_location_sales_hourly), brand_revenue (gold_brand_sales_day), order_revenue (gold_order_header).\n",
+        "- \"today\" = hour_ts >= current_date(); \"this week\" = hour_ts >= current_timestamp() - INTERVAL 7 DAYS.\n",
+        "- For top-N queries default to LIMIT 10 unless the user specifies otherwise.\n",
+        "- Always JOIN simulator.locations on location_id to return readable location names.\n",
+        "- Always JOIN simulator.brands on brand_id to return readable brand names.\n",
+        "- Always filter by a date range to reduce scan cost.\"\"\"\n",
+        "\n",
+        "REVENUE_TABLES = [\n",
+        "    f\"{CATALOG}.lakeflow.gold_location_sales_hourly\",\n",
+        "    f\"{CATALOG}.lakeflow.gold_brand_sales_day\",\n",
+        "    f\"{CATALOG}.lakeflow.gold_order_header\",\n",
+        "    f\"{CATALOG}.lakeflow.silver_order_items\",\n",
+        "    f\"{CATALOG}.lakeflow.all_events\",\n",
+        "    f\"{CATALOG}.simulator.locations\",\n",
+        "    f\"{CATALOG}.simulator.brands\",\n",
+        "    f\"{CATALOG}.simulator.items\",\n",
+        "    f\"{CATALOG}.simulator.brand_locations\",\n",
+        "]\n",
+        "\n",
+        "REVENUE_QUESTIONS = [\n",
+        "    \"What is total revenue by location for the last 30 days?\",\n",
+        "    \"Which brand generates the most orders across all locations?\",\n",
+        "    \"What is the order cancellation rate by location?\",\n",
+        "    \"Show me hourly order volume trends for today\",\n",
+        "    \"Which location has the highest average order value?\",\n",
+        "    \"What is the revenue split between locations this week vs last week?\",\n",
+        "    \"How many total orders were placed across all locations?\",\n",
+        "    \"Which brands are underperforming relative to the network average?\",\n",
+        "]\n",
+        "\n",
+        "REVENUE_EXAMPLE_SQLS = [\n",
+        "    {\n",
+        "        \"question\": \"What is total revenue by location for the last 30 days?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, SUM(g.revenue) AS revenue_30d, SUM(g.orders) AS orders_30d\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY revenue_30d DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which brand generated the most orders in the last 7 days?\",\n",
+        "        \"sql\": f\"\"\"SELECT b.name AS brand, SUM(g.orders) AS orders_7d, SUM(g.brand_revenue) AS revenue_7d\n",
+        "FROM {CATALOG}.lakeflow.gold_brand_sales_day g\n",
+        "JOIN {CATALOG}.simulator.brands b ON g.brand_id = b.brand_id\n",
+        "WHERE g.day >= current_date() - 7\n",
+        "GROUP BY b.name\n",
+        "ORDER BY orders_7d DESC\n",
+        "LIMIT 10\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average order value by location, last 30 days\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, ROUND(AVG(h.order_revenue), 2) AS avg_order_value, COUNT(*) AS orders\n",
+        "FROM {CATALOG}.lakeflow.gold_order_header h\n",
+        "JOIN {CATALOG}.simulator.locations l ON h.location_id = l.location_id\n",
+        "WHERE h.order_day >= current_date() - 30\n",
+        "GROUP BY l.name\n",
+        "ORDER BY avg_order_value DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Show hourly order volume trends for today\",\n",
+        "        \"sql\": f\"\"\"SELECT g.hour_ts, l.name AS location, g.orders, g.revenue\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_date()\n",
+        "ORDER BY g.hour_ts, l.name\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Revenue this week vs last week, by location\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       SUM(CASE WHEN g.hour_ts >= current_timestamp() - INTERVAL 7 DAYS THEN g.revenue ELSE 0 END) AS revenue_this_week,\n",
+        "       SUM(CASE WHEN g.hour_ts <  current_timestamp() - INTERVAL 7 DAYS\n",
+        "                AND  g.hour_ts >= current_timestamp() - INTERVAL 14 DAYS THEN g.revenue ELSE 0 END) AS revenue_prev_week\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 14 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY revenue_this_week DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Top 10 brands by revenue, last 30 days\",\n",
+        "        \"sql\": f\"\"\"SELECT b.name AS brand, b.cuisine, SUM(g.brand_revenue) AS revenue_30d, SUM(g.orders) AS orders_30d\n",
+        "FROM {CATALOG}.lakeflow.gold_brand_sales_day g\n",
+        "JOIN {CATALOG}.simulator.brands b ON g.brand_id = b.brand_id\n",
+        "WHERE g.day >= current_date() - 30\n",
+        "GROUP BY b.name, b.cuisine\n",
+        "ORDER BY revenue_30d DESC\n",
+        "LIMIT 10\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "REVENUE_JOIN_SPECS = [\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.gold_location_sales_hourly\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.gold_brand_sales_day\",\n",
+        "        f\"{CATALOG}.simulator.brands\",\n",
+        "        on=[(\"brand_id\", \"brand_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.gold_order_header\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.silver_order_items\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.silver_order_items\",\n",
+        "        f\"{CATALOG}.simulator.brands\",\n",
+        "        on=[(\"brand_id\", \"brand_id\")],\n",
+        "    ),\n",
+        "]\n",
+        "\n",
+        "# Benchmark questions — ground-truth SQL pairs the presenter (or the\n",
+        "# `Genie_Spaces` task) can rerun via the Genie UI's \"Run Benchmarks\" button\n",
+        "# (or programmatically via `w.genie.genie_create_eval_run(space_id)`) to\n",
+        "# regression-test the space whenever instructions / example SQLs change.\n",
+        "#\n",
+        "# Authoring guidance (per Databricks \"Test and monitor a Genie Space\" docs):\n",
+        "#   - aim for ≥5 questions per space (max 500),\n",
+        "#   - include 2-3 phrasings of the same question to test paraphrase robustness,\n",
+        "#   - each answer must be a single `format: SQL` entry — Genie compares result\n",
+        "#     sets cell-by-cell (4-sig-fig numeric tolerance, sort-insensitive).\n",
+        "#\n",
+        "# Mix here: 3 questions identical to the example SQLs above (tests that Genie\n",
+        "# reuses the worked example) + 3 alternate phrasings / simple lookups.\n",
+        "REVENUE_BENCHMARKS = [\n",
+        "    {\n",
+        "        \"question\": \"What is total revenue by location for the last 30 days?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, SUM(g.revenue) AS revenue_30d, SUM(g.orders) AS orders_30d\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY revenue_30d DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Show me revenue per location for the past month\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, SUM(g.revenue) AS revenue_30d\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY revenue_30d DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which brand had the most orders in the past week?\",\n",
+        "        \"sql\": f\"\"\"SELECT b.name AS brand, SUM(g.orders) AS orders_7d\n",
+        "FROM {CATALOG}.lakeflow.gold_brand_sales_day g\n",
+        "JOIN {CATALOG}.simulator.brands b ON g.brand_id = b.brand_id\n",
+        "WHERE g.day >= current_date() - 7\n",
+        "GROUP BY b.name\n",
+        "ORDER BY orders_7d DESC\n",
+        "LIMIT 1\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average order value per location over the last 30 days\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, ROUND(AVG(h.order_revenue), 2) AS avg_order_value\n",
+        "FROM {CATALOG}.lakeflow.gold_order_header h\n",
+        "JOIN {CATALOG}.simulator.locations l ON h.location_id = l.location_id\n",
+        "WHERE h.order_day >= current_date() - 30\n",
+        "GROUP BY l.name\n",
+        "ORDER BY avg_order_value DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Top 10 brands by revenue in the last 30 days\",\n",
+        "        \"sql\": f\"\"\"SELECT b.name AS brand, SUM(g.brand_revenue) AS revenue_30d\n",
+        "FROM {CATALOG}.lakeflow.gold_brand_sales_day g\n",
+        "JOIN {CATALOG}.simulator.brands b ON g.brand_id = b.brand_id\n",
+        "WHERE g.day >= current_date() - 30\n",
+        "GROUP BY b.name\n",
+        "ORDER BY revenue_30d DESC\n",
+        "LIMIT 10\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"How many orders today, per location?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, SUM(g.orders) AS orders_today\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_date()\n",
+        "GROUP BY l.name\n",
+        "ORDER BY orders_today DESC\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "revenue_genie_id = create_or_get_genie(\n",
+        "    title=REVENUE_TITLE,\n",
+        "    description=REVENUE_DESCRIPTION,\n",
+        "    tables=REVENUE_TABLES,\n",
+        "    instructions_text=REVENUE_INSTRUCTIONS,\n",
+        "    example_sqls=REVENUE_EXAMPLE_SQLS,\n",
+        "    sample_questions=REVENUE_QUESTIONS,\n",
+        "    join_specs=REVENUE_JOIN_SPECS,\n",
+        "    benchmarks=REVENUE_BENCHMARKS,\n",
+        ")\n",
+        "print(f\"Revenue Genie ID: {revenue_genie_id} ({len(REVENUE_BENCHMARKS)} benchmarks)\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Operations Intelligence Genie"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "OPS_TITLE = f\"Operations Intelligence ({CATALOG})\"\n",
+        "\n",
+        "OPS_DESCRIPTION = (\n",
+        "    \"Operations analytics for Casper's Kitchens. Covers order throughput, \"\n",
+        "    \"cancellation rates, food safety inspections, and violations. Combines \"\n",
+        "    \"Lakeflow gold/silver tables with food_safety inspection data.\"\n",
+        ")\n",
+        "\n",
+        "# General instructions — kept under ~20 lines per Genie best practice.\n",
+        "OPS_INSTRUCTIONS = \"\"\"You are an operations analytics assistant for Casper's Kitchens (a ghost-kitchen network).\n",
+        "Prefer Gold/Silver tables over all_events (10-100x faster). all_events is ONLY for derived metrics like cancel rate.\n",
+        "\n",
+        "Table routing:\n",
+        "- Order volume, throughput, peak hours    -> gold_location_sales_hourly JOIN simulator.locations\n",
+        "- Per-order ops metrics                    -> gold_order_header\n",
+        "- Item-level ops                            -> silver_order_items\n",
+        "- Food safety score / grade by location   -> food_safety.inspections JOIN simulator.locations\n",
+        "- Specific violations (severity, code)     -> food_safety.violations JOIN food_safety.inspections\n",
+        "- Cancellation rate (derived from events)  -> all_events with the cancel-rate pattern below\n",
+        "\n",
+        "Cancellation rate computation (orders with order_created but no delivered):\n",
+        "  - total = COUNT(DISTINCT order_id WHERE event_type='order_created')\n",
+        "  - cancelled = total - COUNT(DISTINCT order_id WHERE event_type='delivered')\n",
+        "  - cancel_rate_pct = ROUND(100.0 * cancelled / NULLIF(total, 0), 1)\n",
+        "  - Always filter by event_ts >= current_timestamp() - INTERVAL 30 DAYS and JOIN simulator.locations.\n",
+        "\n",
+        "Conventions:\n",
+        "- Always JOIN simulator.locations on location_id for readable names.\n",
+        "- \"this week\" = ts >= current_timestamp() - INTERVAL 7 DAYS.\n",
+        "- For cancel rate, ALWAYS run the pattern above — do NOT return 0 without computing it.\"\"\"\n",
+        "\n",
+        "OPS_TABLES = [\n",
+        "    f\"{CATALOG}.lakeflow.gold_location_sales_hourly\",\n",
+        "    f\"{CATALOG}.lakeflow.gold_order_header\",\n",
+        "    f\"{CATALOG}.lakeflow.silver_order_items\",\n",
+        "    f\"{CATALOG}.lakeflow.all_events\",\n",
+        "    f\"{CATALOG}.simulator.locations\",\n",
+        "    f\"{CATALOG}.food_safety.inspections\",\n",
+        "    f\"{CATALOG}.food_safety.violations\",\n",
+        "]\n",
+        "\n",
+        "OPS_QUESTIONS = [\n",
+        "    \"Which locations have the highest complaint rate?\",\n",
+        "    \"What is the refund approval rate by location?\",\n",
+        "    \"Show me locations with critical food safety violations\",\n",
+        "    \"What are the top 5 complaint categories across all locations?\",\n",
+        "    \"Which location needs the most operational attention right now?\",\n",
+        "    \"Show order cancellation trends over the last 7 days by location\",\n",
+        "    \"What is the average food safety inspection score by location?\",\n",
+        "    \"How many complaints were submitted in the last 24 hours?\",\n",
+        "]\n",
+        "\n",
+        "OPS_EXAMPLE_SQLS = [\n",
+        "    {\n",
+        "        \"question\": \"Order cancellation rate by location, last 30 days\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END) AS total_orders,\n",
+        "       COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END)\n",
+        "         - COUNT(DISTINCT CASE WHEN ae.event_type = 'delivered' THEN ae.order_id END) AS cancelled_orders,\n",
+        "       ROUND(100.0 * (\n",
+        "         COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END)\n",
+        "         - COUNT(DISTINCT CASE WHEN ae.event_type = 'delivered' THEN ae.order_id END)\n",
+        "       ) / NULLIF(COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END), 0), 1) AS cancel_rate_pct\n",
+        "FROM {CATALOG}.lakeflow.all_events ae\n",
+        "JOIN {CATALOG}.simulator.locations l ON ae.location_id = l.location_id\n",
+        "WHERE ae.event_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY cancel_rate_pct DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average food safety score by location\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       ROUND(AVG(i.score), 1) AS avg_score,\n",
+        "       MIN(i.score) AS worst_score,\n",
+        "       MAX(i.inspection_date) AS latest_inspection\n",
+        "FROM {CATALOG}.food_safety.inspections i\n",
+        "JOIN {CATALOG}.simulator.locations l ON i.location_id = l.location_id\n",
+        "GROUP BY l.name\n",
+        "ORDER BY avg_score\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Critical violations needing immediate action in the last 60 days\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, v.inspection_date, v.code, v.category, v.severity, v.description\n",
+        "FROM {CATALOG}.food_safety.violations v\n",
+        "JOIN {CATALOG}.simulator.locations l ON v.location_id = l.location_id\n",
+        "WHERE v.severity = 'critical'\n",
+        "  AND v.inspection_date >= current_date() - 60\n",
+        "ORDER BY v.inspection_date DESC, l.name\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Hourly order volume per location for today\",\n",
+        "        \"sql\": f\"\"\"SELECT g.hour_ts, l.name AS location, g.orders, g.revenue\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_date()\n",
+        "ORDER BY g.hour_ts, l.name\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Locations with the most recent failing inspection (score < 70)\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, i.inspection_date, i.score, i.grade, i.violation_count, i.critical_count\n",
+        "FROM {CATALOG}.food_safety.inspections i\n",
+        "JOIN {CATALOG}.simulator.locations l ON i.location_id = l.location_id\n",
+        "WHERE i.score < 70\n",
+        "ORDER BY i.inspection_date DESC\n",
+        "LIMIT 20\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Daily order trend by location for the last 7 days\",\n",
+        "        \"sql\": f\"\"\"SELECT DATE(g.hour_ts) AS day, l.name AS location,\n",
+        "       SUM(g.orders) AS orders,\n",
+        "       ROUND(SUM(g.revenue), 2) AS revenue\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 7 DAYS\n",
+        "GROUP BY DATE(g.hour_ts), l.name\n",
+        "ORDER BY day, l.name\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "OPS_JOIN_SPECS = [\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.gold_location_sales_hourly\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.gold_order_header\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.silver_order_items\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.lakeflow.all_events\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.food_safety.inspections\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.food_safety.violations\",\n",
+        "        f\"{CATALOG}.food_safety.inspections\",\n",
+        "        on=[(\"inspection_id\", \"inspection_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.food_safety.violations\",\n",
+        "        f\"{CATALOG}.simulator.locations\",\n",
+        "        on=[(\"location_id\", \"location_id\")],\n",
+        "    ),\n",
+        "]\n",
+        "\n",
+        "# Benchmark questions — see REVENUE_BENCHMARKS for authoring notes.\n",
+        "# Mix: 3 exact matches with example SQLs (paraphrase robustness sanity) +\n",
+        "# 3 alternate phrasings.  Cancel-rate is the highest-value benchmark because\n",
+        "# the SQL pattern is non-trivial (nested COUNT DISTINCT + NULLIF) and the\n",
+        "# example SQL is what teaches it — if the benchmark regresses, the cancel-rate\n",
+        "# example was likely dropped or paraphrased badly.\n",
+        "OPS_BENCHMARKS = [\n",
+        "    {\n",
+        "        \"question\": \"What is the order cancellation rate by location over the last 30 days?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END) AS total_orders,\n",
+        "       COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END)\n",
+        "         - COUNT(DISTINCT CASE WHEN ae.event_type = 'delivered' THEN ae.order_id END) AS cancelled_orders,\n",
+        "       ROUND(100.0 * (\n",
+        "         COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END)\n",
+        "         - COUNT(DISTINCT CASE WHEN ae.event_type = 'delivered' THEN ae.order_id END)\n",
+        "       ) / NULLIF(COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END), 0), 1) AS cancel_rate_pct\n",
+        "FROM {CATALOG}.lakeflow.all_events ae\n",
+        "JOIN {CATALOG}.simulator.locations l ON ae.location_id = l.location_id\n",
+        "WHERE ae.event_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY cancel_rate_pct DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which location is cancelling the most orders?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       ROUND(100.0 * (\n",
+        "         COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END)\n",
+        "         - COUNT(DISTINCT CASE WHEN ae.event_type = 'delivered' THEN ae.order_id END)\n",
+        "       ) / NULLIF(COUNT(DISTINCT CASE WHEN ae.event_type = 'order_created' THEN ae.order_id END), 0), 1) AS cancel_rate_pct\n",
+        "FROM {CATALOG}.lakeflow.all_events ae\n",
+        "JOIN {CATALOG}.simulator.locations l ON ae.location_id = l.location_id\n",
+        "WHERE ae.event_ts >= current_timestamp() - INTERVAL 30 DAYS\n",
+        "GROUP BY l.name\n",
+        "ORDER BY cancel_rate_pct DESC\n",
+        "LIMIT 1\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average food safety inspection score per location\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location,\n",
+        "       ROUND(AVG(i.score), 1) AS avg_score\n",
+        "FROM {CATALOG}.food_safety.inspections i\n",
+        "JOIN {CATALOG}.simulator.locations l ON i.location_id = l.location_id\n",
+        "GROUP BY l.name\n",
+        "ORDER BY avg_score\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Show me critical violations from the last 60 days that need immediate action\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, v.inspection_date, v.code, v.category, v.severity, v.description\n",
+        "FROM {CATALOG}.food_safety.violations v\n",
+        "JOIN {CATALOG}.simulator.locations l ON v.location_id = l.location_id\n",
+        "WHERE v.severity = 'critical'\n",
+        "  AND v.inspection_date >= current_date() - 60\n",
+        "ORDER BY v.inspection_date DESC, l.name\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which locations have a failing inspection score (below 70)?\",\n",
+        "        \"sql\": f\"\"\"SELECT l.name AS location, i.inspection_date, i.score, i.grade, i.violation_count, i.critical_count\n",
+        "FROM {CATALOG}.food_safety.inspections i\n",
+        "JOIN {CATALOG}.simulator.locations l ON i.location_id = l.location_id\n",
+        "WHERE i.score < 70\n",
+        "ORDER BY i.inspection_date DESC\n",
+        "LIMIT 20\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Daily order count per location for the last 7 days\",\n",
+        "        \"sql\": f\"\"\"SELECT DATE(g.hour_ts) AS day, l.name AS location,\n",
+        "       SUM(g.orders) AS orders\n",
+        "FROM {CATALOG}.lakeflow.gold_location_sales_hourly g\n",
+        "JOIN {CATALOG}.simulator.locations l ON g.location_id = l.location_id\n",
+        "WHERE g.hour_ts >= current_timestamp() - INTERVAL 7 DAYS\n",
+        "GROUP BY DATE(g.hour_ts), l.name\n",
+        "ORDER BY day, l.name\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "ops_genie_id = create_or_get_genie(\n",
+        "    title=OPS_TITLE,\n",
+        "    description=OPS_DESCRIPTION,\n",
+        "    tables=OPS_TABLES,\n",
+        "    instructions_text=OPS_INSTRUCTIONS,\n",
+        "    example_sqls=OPS_EXAMPLE_SQLS,\n",
+        "    sample_questions=OPS_QUESTIONS,\n",
+        "    join_specs=OPS_JOIN_SPECS,\n",
+        "    benchmarks=OPS_BENCHMARKS,\n",
+        ")\n",
+        "print(f\"Operations Genie ID: {ops_genie_id} ({len(OPS_BENCHMARKS)} benchmarks)\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Menu & Safety Intelligence Genie"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "MENU_TITLE = f\"Menu & Safety Intelligence ({CATALOG})\"\n",
+        "\n",
+        "MENU_DESCRIPTION = (\n",
+        "    \"Menu and food safety analytics for Casper's Kitchens (16 brands across 4 locations). \"\n",
+        "    \"Provides menu items, nutrition, allergens, inspection scores, and violation details \"\n",
+        "    \"from the menu_documents medallion pipeline.\"\n",
+        ")\n",
+        "\n",
+        "# General instructions — kept under ~20 lines per Genie best practice.\n",
+        "MENU_INSTRUCTIONS = f\"\"\"You are a menu & food safety analyst for Casper's Kitchens (16 brands, 4 locations).\n",
+        "All tables live in {CATALOG}.menu_documents. Use gold tables for aggregates, silver for deep dives.\n",
+        "\n",
+        "Table routing:\n",
+        "- Menu catalog, price tier, allergen flags  -> menu_items + allergens (JOIN on item_name + brand_name)\n",
+        "- Per-item nutrition deep dive               -> nutritional_info\n",
+        "- Per-brand nutrition summary                -> brand_nutrition_summary\n",
+        "- Inspection scores, grades, severity        -> inspection_details OR silver_inspections\n",
+        "- Individual violations + urgency            -> violation_analysis OR silver_violations\n",
+        "- Per-location pass rate, severity index     -> location_compliance_summary\n",
+        "\n",
+        "Domain conventions:\n",
+        "- price_tier: budget (<$10), standard ($10-$18), premium (>$18)\n",
+        "- calorie_category: light (<300), moderate (300-600), hearty (>600)\n",
+        "- score_band: excellent (>=90), good (80-89), acceptable (70-79), failing (<70)\n",
+        "- \"healthy\" = is_high_protein=true AND is_low_calorie=true\n",
+        "- \"needs_immediate_action\" = severity='critical' OR deadline_days <= 7\n",
+        "- For allergen filters use allergens.contains_* boolean columns (wheat, milk, egg, soy, peanut, tree_nut, fish, shellfish, sesame)\n",
+        "- For top-N queries default to LIMIT 10\"\"\"\n",
+        "\n",
+        "MENU_TABLES = [\n",
+        "    f\"{CATALOG}.menu_documents.silver_menu_items\",\n",
+        "    f\"{CATALOG}.menu_documents.silver_inspections\",\n",
+        "    f\"{CATALOG}.menu_documents.silver_violations\",\n",
+        "    f\"{CATALOG}.menu_documents.menu_items\",\n",
+        "    f\"{CATALOG}.menu_documents.nutritional_info\",\n",
+        "    f\"{CATALOG}.menu_documents.allergens\",\n",
+        "    f\"{CATALOG}.menu_documents.brand_nutrition_summary\",\n",
+        "    f\"{CATALOG}.menu_documents.inspection_details\",\n",
+        "    f\"{CATALOG}.menu_documents.violation_analysis\",\n",
+        "    f\"{CATALOG}.menu_documents.location_compliance_summary\",\n",
+        "]\n",
+        "\n",
+        "MENU_QUESTIONS = [\n",
+        "    \"Which menu items are gluten-free and under $15?\",\n",
+        "    \"What is the average calorie count per brand?\",\n",
+        "    \"Which locations have critical violations that need immediate action?\",\n",
+        "    \"Compare protein content across all burgers\",\n",
+        "    \"What is the latest inspection score for Chicago?\",\n",
+        "    \"Show me all premium-tier items that are also high protein\",\n",
+        "    \"Which brand has the most allergen-free options?\",\n",
+        "    \"What is the pass rate for each location?\",\n",
+        "    \"List all violations with urgency score above 5\",\n",
+        "    \"Which cuisine type has the lowest average calories?\",\n",
+        "]\n",
+        "\n",
+        "MENU_EXAMPLE_SQLS = [\n",
+        "    {\n",
+        "        \"question\": \"Gluten-free menu items under $15\",\n",
+        "        \"sql\": f\"\"\"SELECT mi.brand_name, mi.item_name, mi.category, mi.price\n",
+        "FROM {CATALOG}.menu_documents.menu_items mi\n",
+        "JOIN {CATALOG}.menu_documents.allergens a\n",
+        "  ON mi.item_name = a.item_name AND mi.brand_name = a.brand_name\n",
+        "WHERE a.contains_wheat = false AND mi.price < 15\n",
+        "ORDER BY mi.price\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average calories per brand\",\n",
+        "        \"sql\": f\"\"\"SELECT brand_name,\n",
+        "       ROUND(AVG(calories), 0) AS avg_calories,\n",
+        "       MIN(calories) AS min_calories,\n",
+        "       MAX(calories) AS max_calories,\n",
+        "       COUNT(*) AS item_count\n",
+        "FROM {CATALOG}.menu_documents.nutritional_info\n",
+        "GROUP BY brand_name\n",
+        "ORDER BY avg_calories DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Pass rate by location\",\n",
+        "        \"sql\": f\"\"\"SELECT location_name,\n",
+        "       total_inspections,\n",
+        "       passed_inspections,\n",
+        "       ROUND(pass_rate_pct, 1) AS pass_rate_pct,\n",
+        "       ROUND(avg_severity_index, 2) AS avg_severity\n",
+        "FROM {CATALOG}.menu_documents.location_compliance_summary\n",
+        "ORDER BY pass_rate_pct\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Critical violations needing immediate action, last 90 days\",\n",
+        "        \"sql\": f\"\"\"SELECT location_name, inspection_date, code, severity, category, description, deadline_days, urgency_score\n",
+        "FROM {CATALOG}.menu_documents.silver_violations\n",
+        "WHERE needs_immediate_action = true\n",
+        "  AND inspection_date >= current_date() - 90\n",
+        "ORDER BY urgency_score DESC, inspection_date DESC\n",
+        "LIMIT 20\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Premium high-protein items\",\n",
+        "        \"sql\": f\"\"\"SELECT n.brand_name, n.item_name, n.calories, n.protein_g, ROUND(n.protein_pct, 1) AS protein_pct, m.price\n",
+        "FROM {CATALOG}.menu_documents.nutritional_info n\n",
+        "JOIN {CATALOG}.menu_documents.menu_items m\n",
+        "  ON n.item_name = m.item_name AND n.brand_name = m.brand_name\n",
+        "WHERE n.is_high_protein = true AND m.price_tier = 'premium'\n",
+        "ORDER BY n.protein_g DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Latest inspection score by location\",\n",
+        "        \"sql\": f\"\"\"SELECT location_name, inspection_date, score, grade, score_band, violation_count, critical_count\n",
+        "FROM {CATALOG}.menu_documents.silver_inspections\n",
+        "QUALIFY ROW_NUMBER() OVER (PARTITION BY location_name ORDER BY inspection_date DESC) = 1\n",
+        "ORDER BY score\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Cuisine types ranked by average calories\",\n",
+        "        \"sql\": f\"\"\"SELECT mi.cuisine,\n",
+        "       ROUND(AVG(n.calories), 0) AS avg_calories,\n",
+        "       COUNT(*) AS items\n",
+        "FROM {CATALOG}.menu_documents.menu_items mi\n",
+        "JOIN {CATALOG}.menu_documents.nutritional_info n\n",
+        "  ON mi.item_name = n.item_name AND mi.brand_name = n.brand_name\n",
+        "GROUP BY mi.cuisine\n",
+        "ORDER BY avg_calories\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "MENU_JOIN_SPECS = [\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.menu_documents.menu_items\",\n",
+        "        f\"{CATALOG}.menu_documents.nutritional_info\",\n",
+        "        on=[(\"item_name\", \"item_name\"), (\"brand_name\", \"brand_name\")],\n",
+        "        rt=\"FROM_RELATIONSHIP_TYPE_ONE_TO_ONE\",\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.menu_documents.menu_items\",\n",
+        "        f\"{CATALOG}.menu_documents.allergens\",\n",
+        "        on=[(\"item_name\", \"item_name\"), (\"brand_name\", \"brand_name\")],\n",
+        "        rt=\"FROM_RELATIONSHIP_TYPE_ONE_TO_ONE\",\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.menu_documents.nutritional_info\",\n",
+        "        f\"{CATALOG}.menu_documents.allergens\",\n",
+        "        on=[(\"item_name\", \"item_name\"), (\"brand_name\", \"brand_name\")],\n",
+        "        rt=\"FROM_RELATIONSHIP_TYPE_ONE_TO_ONE\",\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.menu_documents.silver_violations\",\n",
+        "        f\"{CATALOG}.menu_documents.silver_inspections\",\n",
+        "        on=[(\"inspection_id\", \"inspection_id\")],\n",
+        "    ),\n",
+        "    _build_join_spec(\n",
+        "        f\"{CATALOG}.menu_documents.violation_analysis\",\n",
+        "        f\"{CATALOG}.menu_documents.inspection_details\",\n",
+        "        on=[(\"inspection_id\", \"inspection_id\")],\n",
+        "    ),\n",
+        "]\n",
+        "\n",
+        "# Benchmark questions — see REVENUE_BENCHMARKS for authoring notes.\n",
+        "# Mix: 2 exact matches + 4 alternate phrasings.  Allergen and price-tier\n",
+        "# benchmarks are the highest-value here because the General Instructions\n",
+        "# document the `contains_*` boolean columns and `price_tier` derivations —\n",
+        "# if Genie regresses on these, the instructions likely got truncated.\n",
+        "MENU_BENCHMARKS = [\n",
+        "    {\n",
+        "        \"question\": \"Which menu items are gluten-free and under $15?\",\n",
+        "        \"sql\": f\"\"\"SELECT mi.brand_name, mi.item_name, mi.category, mi.price\n",
+        "FROM {CATALOG}.menu_documents.menu_items mi\n",
+        "JOIN {CATALOG}.menu_documents.allergens a\n",
+        "  ON mi.item_name = a.item_name AND mi.brand_name = a.brand_name\n",
+        "WHERE a.contains_wheat = false AND mi.price < 15\n",
+        "ORDER BY mi.price\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which menu items don't contain wheat and cost less than $15?\",\n",
+        "        \"sql\": f\"\"\"SELECT mi.brand_name, mi.item_name, mi.category, mi.price\n",
+        "FROM {CATALOG}.menu_documents.menu_items mi\n",
+        "JOIN {CATALOG}.menu_documents.allergens a\n",
+        "  ON mi.item_name = a.item_name AND mi.brand_name = a.brand_name\n",
+        "WHERE a.contains_wheat = false AND mi.price < 15\n",
+        "ORDER BY mi.price\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Average calorie count per brand\",\n",
+        "        \"sql\": f\"\"\"SELECT brand_name,\n",
+        "       ROUND(AVG(calories), 0) AS avg_calories\n",
+        "FROM {CATALOG}.menu_documents.nutritional_info\n",
+        "GROUP BY brand_name\n",
+        "ORDER BY avg_calories DESC\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"What is the pass rate for each location?\",\n",
+        "        \"sql\": f\"\"\"SELECT location_name, ROUND(pass_rate_pct, 1) AS pass_rate_pct\n",
+        "FROM {CATALOG}.menu_documents.location_compliance_summary\n",
+        "ORDER BY pass_rate_pct\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Critical violations needing immediate action in the last 90 days\",\n",
+        "        \"sql\": f\"\"\"SELECT location_name, inspection_date, code, severity, category, description, deadline_days, urgency_score\n",
+        "FROM {CATALOG}.menu_documents.silver_violations\n",
+        "WHERE needs_immediate_action = true\n",
+        "  AND inspection_date >= current_date() - 90\n",
+        "ORDER BY urgency_score DESC, inspection_date DESC\n",
+        "LIMIT 20\"\"\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which brand has the lowest average calories?\",\n",
+        "        \"sql\": f\"\"\"SELECT brand_name,\n",
+        "       ROUND(AVG(calories), 0) AS avg_calories\n",
+        "FROM {CATALOG}.menu_documents.nutritional_info\n",
+        "GROUP BY brand_name\n",
+        "ORDER BY avg_calories ASC\n",
+        "LIMIT 1\"\"\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "menu_genie_id = create_or_get_genie(\n",
+        "    title=MENU_TITLE,\n",
+        "    description=MENU_DESCRIPTION,\n",
+        "    tables=MENU_TABLES,\n",
+        "    instructions_text=MENU_INSTRUCTIONS,\n",
+        "    example_sqls=MENU_EXAMPLE_SQLS,\n",
+        "    sample_questions=MENU_QUESTIONS,\n",
+        "    join_specs=MENU_JOIN_SPECS,\n",
+        "    benchmarks=MENU_BENCHMARKS,\n",
+        ")\n",
+        "print(f\"Menu & Safety Genie ID: {menu_genie_id} ({len(MENU_BENCHMARKS)} benchmarks)\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Discover Domain tagging.  Each Genie space gets one or more\n",
+        "# `caspers_domain_*` tags via the workspace-entity tag-assignment API so\n",
+        "# it surfaces in the matching Catalog → Discover → Domain.  Tags are\n",
+        "# applied even if the governed tag policy isn't created yet — the helper\n",
+        "# falls back to plain workspace tags and `Environment_Helpers` will\n",
+        "# promote them to governed when it runs (idempotent).  See SETUP.ipynb §4.\n",
+        "\n",
+        "import sys, os\n",
+        "sys.path.insert(0, os.path.abspath(\"..\"))  # stages/ -> repo root\n",
+        "from utils.domain_tags import ensure_domain_tag_policies, tag_workspace_entity\n",
+        "\n",
+        "print(\"\\n— Tagging Genie spaces for Discover Domains —\")\n",
+        "ensure_domain_tag_policies(w, verbose=False)\n",
+        "\n",
+        "GENIE_DOMAINS = [\n",
+        "    (revenue_genie_id, [\"revenue\"],     \"Revenue & Orders Intelligence\"),\n",
+        "    (ops_genie_id,     [\"operations\"],  \"Operations Intelligence\"),\n",
+        "    (menu_genie_id,    [\"compliance\"],  \"Menu & Safety Intelligence\"),\n",
+        "]\n",
+        "for space_id, domains, label in GENIE_DOMAINS:\n",
+        "    tag_workspace_entity(w, \"geniespaces\", space_id, domains,\n",
+        "                         label=f\"genie {label!r}\")\n",
+        "\n",
+        "_total_benchmarks = len(REVENUE_BENCHMARKS) + len(OPS_BENCHMARKS) + len(MENU_BENCHMARKS)\n",
+        "print(\"\\n\\u2705 Genie Spaces stage complete\")\n",
+        "print(f\"   Revenue & Orders:    {revenue_genie_id}  ({len(REVENUE_BENCHMARKS)} benchmarks)\")\n",
+        "print(f\"   Operations:          {ops_genie_id}  ({len(OPS_BENCHMARKS)} benchmarks)\")\n",
+        "print(f\"   Menu & Safety:       {menu_genie_id}  ({len(MENU_BENCHMARKS)} benchmarks)\")\n",
+        "print(f\"\\n   Total benchmarks across all 3 spaces: {_total_benchmarks}\")\n",
+        "print(\"   Run them via the Genie UI ('Benchmarks' tab \\u2192 'Run benchmarks') or programmatically:\")\n",
+        "print(\"       w.genie.genie_create_eval_run(space_id=<id>)\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/inspection_data.ipynb b/stages/inspection_data.ipynb
deleted file mode 100644
index e59e2b5..0000000
--- a/stages/inspection_data.ipynb
+++ /dev/null
@@ -1,245 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Inspection Data\n",
-    "\n",
-    "This stage uploads pre-generated food safety inspection report PDFs to a Unity\n",
-    "Catalog volume and loads the structured metadata as dimension tables. Each PDF\n",
-    "contains an inspection report for one of the 4 ghost kitchen locations."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Create catalog, schema, and volume for food safety documents"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "spark.sql(f\"CREATE CATALOG IF NOT EXISTS {CATALOG}\")\n",
-    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.food_safety\")\n",
-    "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.food_safety.reports\")\n",
-    "print(f\"\\u2705 Created schema {CATALOG}.food_safety and volume reports\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Copy PDF files from the repo into the Unity Catalog volume"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import os\n",
-    "import glob\n",
-    "\n",
-    "pdf_source_dir = os.path.abspath(\"../data/inspections/pdfs\")\n",
-    "volume_path = f\"/Volumes/{CATALOG}/food_safety/reports\"\n",
-    "\n",
-    "pdf_files = glob.glob(os.path.join(pdf_source_dir, \"*.pdf\"))\n",
-    "print(f\"Found {len(pdf_files)} PDF files to upload\")\n",
-    "\n",
-    "for pdf_file in pdf_files:\n",
-    "    filename = os.path.basename(pdf_file)\n",
-    "    with open(pdf_file, \"rb\") as src:\n",
-    "        with open(f\"{volume_path}/{filename}\", \"wb\") as dst:\n",
-    "            dst.write(src.read())\n",
-    "    print(f\"  Uploaded: {filename}\")\n",
-    "\n",
-    "print(f\"\\u2705 Uploaded {len(pdf_files)} PDFs to {volume_path}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Load structured metadata as dimension tables\n",
-    "\n",
-    "The inspection_metadata.json contains the source data used to generate the PDFs,\n",
-    "including scores, violations, and corrective actions per inspection."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "\n",
-    "metadata_path = os.path.abspath(\"../data/inspections/inspection_metadata.json\")\n",
-    "with open(metadata_path) as f:\n",
-    "    metadata = json.load(f)\n",
-    "\n",
-    "print(f\"Loaded metadata for {len(metadata['inspections'])} inspections across {len(metadata['locations'])} locations\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyspark.sql.types import (\n",
-    "    StructType, StructField, StringType, IntegerType, DateType\n",
-    ")\n",
-    "from datetime import date as dt_date\n",
-    "\n",
-    "# Flatten inspections (one row per inspection)\n",
-    "inspection_rows = []\n",
-    "for insp in metadata[\"inspections\"]:\n",
-    "    inspection_rows.append({\n",
-    "        \"inspection_id\": insp[\"inspection_id\"],\n",
-    "        \"location_id\": insp[\"location_id\"],\n",
-    "        \"location_name\": insp[\"location_name\"],\n",
-    "        \"address\": insp[\"address\"],\n",
-    "        \"jurisdiction\": insp[\"jurisdiction\"],\n",
-    "        \"inspection_date\": dt_date.fromisoformat(insp[\"inspection_date\"]),\n",
-    "        \"inspector_name\": insp[\"inspector_name\"],\n",
-    "        \"score\": insp[\"score\"],\n",
-    "        \"grade\": insp[\"grade\"],\n",
-    "        \"violation_count\": insp[\"violation_count\"],\n",
-    "        \"critical_count\": insp[\"critical_count\"],\n",
-    "        \"major_count\": insp[\"major_count\"],\n",
-    "        \"minor_count\": insp[\"minor_count\"],\n",
-    "        \"follow_up_status\": insp[\"follow_up_status\"],\n",
-    "    })\n",
-    "\n",
-    "inspection_schema = StructType([\n",
-    "    StructField(\"inspection_id\", StringType()),\n",
-    "    StructField(\"location_id\", IntegerType()),\n",
-    "    StructField(\"location_name\", StringType()),\n",
-    "    StructField(\"address\", StringType()),\n",
-    "    StructField(\"jurisdiction\", StringType()),\n",
-    "    StructField(\"inspection_date\", DateType()),\n",
-    "    StructField(\"inspector_name\", StringType()),\n",
-    "    StructField(\"score\", IntegerType()),\n",
-    "    StructField(\"grade\", StringType()),\n",
-    "    StructField(\"violation_count\", IntegerType()),\n",
-    "    StructField(\"critical_count\", IntegerType()),\n",
-    "    StructField(\"major_count\", IntegerType()),\n",
-    "    StructField(\"minor_count\", IntegerType()),\n",
-    "    StructField(\"follow_up_status\", StringType()),\n",
-    "])\n",
-    "\n",
-    "df_inspections = spark.createDataFrame(inspection_rows, schema=inspection_schema)\n",
-    "df_inspections.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.food_safety.inspections\")\n",
-    "print(f\"\\u2705 Created inspections table with {df_inspections.count()} rows\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Flatten violations (one row per violation)\n",
-    "violation_rows = []\n",
-    "for insp in metadata[\"inspections\"]:\n",
-    "    for v in insp[\"violations\"]:\n",
-    "        violation_rows.append({\n",
-    "            \"inspection_id\": insp[\"inspection_id\"],\n",
-    "            \"location_id\": insp[\"location_id\"],\n",
-    "            \"location_name\": insp[\"location_name\"],\n",
-    "            \"inspection_date\": dt_date.fromisoformat(insp[\"inspection_date\"]),\n",
-    "            \"code\": v[\"code\"],\n",
-    "            \"severity\": v[\"severity\"],\n",
-    "            \"category\": v[\"category\"],\n",
-    "            \"description\": v[\"description\"],\n",
-    "            \"corrective_action\": v[\"corrective_action\"],\n",
-    "            \"deadline_days\": v[\"deadline_days\"],\n",
-    "        })\n",
-    "\n",
-    "violation_schema = StructType([\n",
-    "    StructField(\"inspection_id\", StringType()),\n",
-    "    StructField(\"location_id\", IntegerType()),\n",
-    "    StructField(\"location_name\", StringType()),\n",
-    "    StructField(\"inspection_date\", DateType()),\n",
-    "    StructField(\"code\", StringType()),\n",
-    "    StructField(\"severity\", StringType()),\n",
-    "    StructField(\"category\", StringType()),\n",
-    "    StructField(\"description\", StringType()),\n",
-    "    StructField(\"corrective_action\", StringType()),\n",
-    "    StructField(\"deadline_days\", IntegerType()),\n",
-    "])\n",
-    "\n",
-    "df_violations = spark.createDataFrame(violation_rows, schema=violation_schema)\n",
-    "df_violations.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.food_safety.violations\")\n",
-    "print(f\"\\u2705 Created violations table with {df_violations.count()} rows\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Register resources with uc_state for cleanup"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "print(\"\\u2705 Inspection data stage complete\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.11.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
diff --git a/stages/inspection_knowledge_agent.ipynb b/stages/inspection_knowledge_agent.ipynb
deleted file mode 100644
index 0c50bb0..0000000
--- a/stages/inspection_knowledge_agent.ipynb
+++ /dev/null
@@ -1,98 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Inspection Knowledge Agent\n",
-    "\n",
-    "Creates an Agent Bricks Knowledge Assistant over the food safety inspection\n",
-    "report PDFs stored in the Unity Catalog volume. The Knowledge Assistant uses\n",
-    "Databricks' Instructed Retriever to answer compliance and safety questions\n",
-    "with citations from the original inspection documents."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk\n",
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "ENDPOINT_NAME = dbutils.widgets.get(\"INSPECTION_KNOWLEDGE_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk import WorkspaceClient\nimport json\n\nw = WorkspaceClient()\n\nVOLUME_PATH = f\"/Volumes/{CATALOG}/food_safety/reports\"\nAGENT_NAME = f\"{CATALOG}-inspection-knowledge\"\nAPI_BASE = \"/api/2.0/knowledge-assistants\"\n\nKA_BODY = {\n    \"name\": AGENT_NAME,\n    \"description\": (\n        \"Answers questions about food safety inspections at Caspers Kitchens \"\n        \"ghost kitchen locations. Covers inspection scores, violations, \"\n        \"corrective actions, and compliance status across all 4 locations.\"\n    ),\n    \"endpoint_name\": ENDPOINT_NAME,\n    \"knowledge_sources\": [\n        {\n            \"files_source\": {\n                \"name\": \"inspection_reports\",\n                \"type\": \"files\",\n                \"files\": {\"path\": VOLUME_PATH},\n                \"description\": (\n                    \"Food safety inspection report PDFs for 4 ghost kitchen locations \"\n                    \"(San Francisco, Silicon Valley, Bellevue, Chicago). Each PDF contains \"\n                    \"the full inspection report with facility information, overall score, \"\n                    \"letter grade, violation details, corrective actions, and follow-up status.\"\n                ),\n            },\n        },\n    ],\n    \"instructions\": (\n        \"You are a food safety compliance assistant for Caspers Kitchens. \"\n        \"Always cite the specific inspection report (location and date) when answering. \"\n        \"Be precise about violation severities (critical, major, minor), corrective \"\n        \"actions, and deadlines. Flag any critical violations prominently.\"\n    ),\n}\n\ndef get_tile_by_name(name):\n    \"\"\"Look up a tile by name from /api/2.0/tiles. Returns the tile dict or None.\"\"\"\n    resp = w.api_client.do(\"GET\", \"/api/2.0/tiles\")\n    for tile in resp.get(\"tiles\", []):\n        if tile.get(\"name\") == name:\n            return tile\n    return None\n\ndef find_existing_id():\n    \"\"\"Look up agent ID from uc_state.\"\"\"\n    try:\n        df = spark.sql(f\"\"\"\n            SELECT resource_data FROM {CATALOG}._internal_state.resources\n            WHERE resource_type IN ('knowledge_assistants', 'endpoints')\n            ORDER BY created_at DESC\n        \"\"\")\n        for row in df.collect():\n            info = json.loads(row.resource_data)\n            if info.get(\"endpoint_name\") == ENDPOINT_NAME:\n                return info.get(\"tile_id\") or info.get(\"agent_id\")\n    except Exception:\n        pass\n    return None\n\ndef try_get(agent_ref):\n    \"\"\"GET the agent by ID or name, return the response or None.\"\"\"\n    try:\n        return w.api_client.do(\"GET\", f\"{API_BASE}/knowledge-assistants/{agent_ref}\")\n    except Exception:\n        return None\n\nexisting_id = find_existing_id()\nagent_id = None\nneeds_polling = True\n\n# Path 1: found ID in uc_state — verify and update\nif existing_id:\n    info = try_get(existing_id)\n    if info:\n        print(f\"Inspection Knowledge Assistant exists ({existing_id}), updating...\")\n        w.api_client.do(\"PUT\", f\"{API_BASE}/{existing_id}\", body=KA_BODY)\n        agent_id = existing_id\n        needs_polling = False\n        print(f\"✅ Updated Inspection Knowledge Assistant: {agent_id}\")\n\n# Path 2: check by name if it already exists\nif not agent_id:\n    tile = get_tile_by_name(AGENT_NAME)\n    if tile:\n        agent_id = tile[\"tile_id\"]\n        print(f\"♻️ Inspection Knowledge Assistant already exists: {agent_id}\")\n        w.api_client.do(\"PUT\", f\"{API_BASE}/{agent_id}\", body=KA_BODY)\n        needs_polling = False\n        print(f\"✅ Updated Inspection Knowledge Assistant: {agent_id}\")\n\n# Path 3: create new\nif not agent_id:\n    try:\n        ka = w.api_client.do(\"POST\", API_BASE, body=KA_BODY)\n        print(f\"✅ Created Inspection Knowledge Assistant\")\n    except Exception as e:\n        err = str(e)\n        if \"already exists\" in err.lower() or \"ALREADY_EXISTS\" in err:\n            needs_polling = False\n            print(f\"♻️ Agent {AGENT_NAME} already exists. Proceeding.\")\n        else:\n            raise\n\n# Resolve tile_id via tiles API — POST response doesn't include it\nif not agent_id:\n    tile = get_tile_by_name(AGENT_NAME)\n    if tile:\n        agent_id = tile[\"tile_id\"]\n        print(f\"Resolved tile_id: {agent_id}\")\n    else:\n        agent_id = AGENT_NAME\n        needs_polling = False\n        print(f\"⚠️ Could not resolve tile_id, using name as fallback: {agent_id}\")\n\nprint(f\"   Agent ID (tile_id): {agent_id}\")\nprint(f\"   Endpoint: {ENDPOINT_NAME}\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import time\n",
-    "\n",
-    "if needs_polling and agent_id:\n",
-    "    MAX_WAIT = 300\n",
-    "    POLL_INTERVAL = 30\n",
-    "    elapsed = 0\n",
-    "    poll_ref = agent_id if agent_id != AGENT_NAME else AGENT_NAME\n",
-    "    print(f\"Checking if Inspection Knowledge Assistant is ready (ref={poll_ref}, max {MAX_WAIT}s)...\")\n",
-    "\n",
-    "    while elapsed < MAX_WAIT:\n",
-    "        try:\n",
-    "            ka_status = w.api_client.do(\"GET\", f\"{API_BASE}/{poll_ref}\")\n",
-    "            ep_status = ep_status = ka_status[\"knowledge_assistant\"][\"status\"].get(\"endpoint_status\", \"\")\n",
-    "            \n",
-    "            print(f\"  endpoint_status: {ep_status}\")\n",
-    "            if str(ep_status).upper() in (\"ONLINE\", \"ACTIVE\", \"READY\"):\n",
-    "                print(f\"✅ Inspection Knowledge Assistant {AGENT_NAME} is READY\")\n",
-    "                break\n",
-    "        except Exception as e:\n",
-    "            print(f\"  GET status check failed: {type(e).__name__}: {e}\")\n",
-    "\n",
-    "        time.sleep(POLL_INTERVAL)\n",
-    "        elapsed += POLL_INTERVAL\n",
-    "    else:\n",
-    "        print(f\"⏳ Endpoint may still be provisioning — proceeding.\")\n",
-    "else:\n",
-    "    print(f\"✅ Inspection Knowledge Assistant already running — skipping polling.\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import sys\nsys.path.append('../utils')\nfrom uc_state import add\n\nadd(CATALOG, \"knowledge_assistants\", {\"endpoint_name\": ENDPOINT_NAME, \"tile_id\": agent_id, \"name\": AGENT_NAME})\nprint(\"\\u2705 Inspection Knowledge Agent stage complete\")"
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.11.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
\ No newline at end of file
diff --git a/stages/knowledge_agents.ipynb b/stages/knowledge_agents.ipynb
new file mode 100644
index 0000000..de13895
--- /dev/null
+++ b/stages/knowledge_agents.ipynb
@@ -0,0 +1,627 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Knowledge Agents\n",
+        "\n",
+        "Creates Agent Bricks Knowledge Assistants for every document corpus used by the\n",
+        "operational dashboard supervisor:\n",
+        "\n",
+        "- **Inspection KA** — food safety inspection reports\n",
+        "- **Menu KA** — restaurant menu PDFs (items, nutrition, allergens)\n",
+        "- **Legal KA** — employment, liability, vendor disputes\n",
+        "- **Regulatory KA** — permits, fire safety, zoning, FDA\n",
+        "- **Audit KA** — financial, operational, food safety, supply chain audits\n",
+        "- **Consultancy KA** — strategy, operations, AI transformation, workforce\n",
+        "\n",
+        "KAs are created in parallel; readiness polling is delegated to the downstream\n",
+        "`Readiness_Check` task."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk mlflow-skinny[databricks]"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Knowledge Assistant configuration\n",
+        "\n",
+        "One config dict per KA. Each is created via the Knowledge Assistants REST API\n",
+        "(`/api/2.1/knowledge-assistants`) in two steps — create the KA, then attach a\n",
+        "`files` knowledge source pointing at the UC Volume — and registered in\n",
+        "`uc_state` for cleanup. Endpoint names are auto-generated by the API and read\n",
+        "back from the create response."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import json, sys\n",
+        "\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "# Knowledge Assistants v2.1 — endpoint names are auto-generated by Databricks\n",
+        "# and read back from the create response (no longer user-supplied).\n",
+        "API_BASE = \"/api/2.1/knowledge-assistants\"\n",
+        "\n",
+        "# Each entry produces one KA + one \"files\" knowledge source attached to a UC Volume.\n",
+        "# `display_name` must be unique at workspace level (used to look up via List API).\n",
+        "# `source_display_name` shows up in the Databricks UI but does not affect routing.\n",
+        "KA_CONFIGS = [\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-inspection-knowledge\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/food_safety/reports\",\n",
+        "        \"source_display_name\": \"Inspection Reports\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about food safety inspections at Casper's Kitchens \"\n",
+        "            \"ghost kitchen locations. Covers inspection scores, violations, \"\n",
+        "            \"corrective actions, and compliance status across all 8 locations (US + EMEA).\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Food safety inspection report PDFs for 8 ghost kitchen locations (US + EMEA). \"\n",
+        "            \"Each PDF contains the full inspection report with facility information, overall \"\n",
+        "            \"score, letter grade, violation details, corrective actions, and follow-up status.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are a food safety compliance assistant for Casper's Kitchens. \"\n",
+        "            \"Always cite the specific inspection report (location and date) when answering. \"\n",
+        "            \"Be precise about violation severities (critical, major, minor), corrective \"\n",
+        "            \"actions, and deadlines. Flag any critical violations prominently.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"What happened during the Chicago food safety inspection? Were there any critical violations?\",\n",
+        "                \"guideline\": \"Must reference a specific inspection report by date or ID. Must state the inspection score and grade. Must explicitly state whether critical violations were found and cite at least one violation code if they exist.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which locations failed inspection in the last quarter?\",\n",
+        "                \"guideline\": \"Must list specific locations with grades below B or scores below the passing threshold. Must include the inspection date and overall score for each location named.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"What are the most common food safety violations across our network?\",\n",
+        "                \"guideline\": \"Must aggregate violations by category (food handling, sanitation, equipment, temperature, etc.). Must cite the most frequent violation codes and how often they appeared.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-menu-knowledge\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/menu_documents/menus\",\n",
+        "        \"source_display_name\": \"Menu PDFs\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about Casper's Kitchens restaurant menus including dishes, \"\n",
+        "            \"ingredients, nutrition, allergens, and preparation details. Covers all 16 \"\n",
+        "            \"restaurant brands.\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Restaurant menu PDFs for 16 ghost kitchen brands. Each PDF contains the full menu \"\n",
+        "            \"with item names, descriptions, prices, nutritional information (calories, protein, \"\n",
+        "            \"fat, carbs), and allergen warnings.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are a restaurant menu assistant for Casper's Kitchens. \"\n",
+        "            \"Always cite which brand the information comes from. \"\n",
+        "            \"Be specific about allergen warnings and nutritional details.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"Which menu items are gluten-free and under $15?\",\n",
+        "                \"guideline\": \"Must list specific items with brand, dish name, price, and allergen status. Must filter to items below the price threshold.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Compare protein content across all burgers in our network\",\n",
+        "                \"guideline\": \"Must return per-item protein values with brand and dish name across multiple brands. Sort or rank by protein content.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which dishes contain peanuts? List by brand.\",\n",
+        "                \"guideline\": \"Must list specific items with brand and dish name. Must cite allergen warnings explicitly. Group results by brand.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-legal\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/legal_complaints/documents\",\n",
+        "        \"source_display_name\": \"Legal Complaint Documents\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about Casper's Kitchens legal exposure. Covers employment \"\n",
+        "            \"disputes (discrimination, wrongful termination, wage violations), customer \"\n",
+        "            \"liability claims, and vendor/contract disputes across all 8 locations (US + EMEA).\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Legal complaint PDFs for Casper's Kitchens Inc. Each document is a confidential \"\n",
+        "            \"attorney-client privileged case file covering case number, parties, legal basis, \"\n",
+        "            \"applicable statutes, relief sought, case status, and risk assessment.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are a legal intelligence assistant for Casper's Kitchens. \"\n",
+        "            \"Always cite the specific case number and location when answering. \"\n",
+        "            \"Clearly state the risk level (HIGH/MEDIUM/LOW) and amount at stake. \"\n",
+        "            \"Remind users that all legal decisions should be made with counsel. \"\n",
+        "            \"Never speculate on legal outcomes.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"What active high-risk legal cases do we have? What is the total exposure?\",\n",
+        "                \"guideline\": \"Must list cases classified as HIGH risk. Must cite case numbers (CK-XX-XXXX), parties, and amount at stake. Must include the disclaimer about consulting counsel.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Are there any wrongful termination cases pending?\",\n",
+        "                \"guideline\": \"Must filter to cases citing wrongful termination. Must include case number, location, status, and risk level. Must cite the legal basis from the case file.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which location has the most active legal complaints?\",\n",
+        "                \"guideline\": \"Must aggregate active cases by location. Must rank locations by case count. Must cite at least one specific case number per location named.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-regulatory\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/regulatory/documents\",\n",
+        "        \"source_display_name\": \"Regulatory Documents\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about Casper's Kitchens regulatory compliance status. \"\n",
+        "            \"Covers food service permits, fire safety certificates, zoning compliance, \"\n",
+        "            \"FDA registrations, and food handler certifications across all 8 locations (US + EMEA).\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Regulatory compliance PDFs for all Casper's Kitchens ghost kitchen locations. \"\n",
+        "            \"Includes document type, issuing authority, issue date, expiry date, current status, \"\n",
+        "            \"and specific conditions and requirements from each regulatory body.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are a regulatory compliance assistant. \"\n",
+        "            \"Always cite the specific document ID, issuing authority, and expiry date. \"\n",
+        "            \"Flag any permits or certificates that are expiring within 60 days or have a conditional status. \"\n",
+        "            \"Summarize compliance risk clearly and concisely.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"Which permits or certificates are expiring in the next 60 days?\",\n",
+        "                \"guideline\": \"Must list specific document IDs, issuing authorities, expiry dates, and locations. Sort by expiry date (soonest first).\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which locations are operating under a conditional permit?\",\n",
+        "                \"guideline\": \"Must list locations with conditional or restricted permits. Must cite the document ID, issuing authority, and the specific conditions imposed.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"What's our FDA registration status across US locations?\",\n",
+        "                \"guideline\": \"Must cite document IDs and current status for each US location. Must flag any expired or conditional registrations.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-audits\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/audits/reports\",\n",
+        "        \"source_display_name\": \"Audit Reports\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about Casper's Kitchens audit findings. \"\n",
+        "            \"Covers financial statement audits, operational compliance, food safety management, \"\n",
+        "            \"and supply chain audits across all locations and quarters.\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Independent audit reports prepared by Big 4 and mid-tier firms for Casper's Kitchens. \"\n",
+        "            \"Each report includes audit type, period, scope, auditor's opinion, individual findings \"\n",
+        "            \"(Critical/Significant/Minor/Informational) with remediation details.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are an audit intelligence assistant. \"\n",
+        "            \"Always cite the specific audit ID, auditing firm, and period covered. \"\n",
+        "            \"Highlight Critical and Significant findings prominently. \"\n",
+        "            \"Summarize the auditor's opinion and any patterns across multiple audits. \"\n",
+        "            \"Be specific about financial impacts and remediation deadlines.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"What were the most significant audit findings this quarter?\",\n",
+        "                \"guideline\": \"Must cite audit ID, auditing firm, and audit period. Must filter to Critical and Significant findings. Must summarize the auditor's opinion and remediation status.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which audits received a qualified opinion?\",\n",
+        "                \"guideline\": \"Must list audits where the auditor issued a qualified or adverse opinion. Must cite firm, period, and the basis for qualification.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"What's our remediation status on Critical findings from the past year?\",\n",
+        "                \"guideline\": \"Must filter to Critical findings opened in the last 12 months. Must group by remediation status (open / in-progress / closed). Must cite specific audit IDs.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "    {\n",
+        "        \"display_name\": f\"{CATALOG}-consultancy\",\n",
+        "        \"volume_path\": f\"/Volumes/{CATALOG}/consultancy/reports\",\n",
+        "        \"source_display_name\": \"Consultancy Reports\",\n",
+        "        \"description\": (\n",
+        "            \"Answers questions about strategic recommendations from management consultants. \"\n",
+        "            \"Covers market expansion, operations efficiency, AI transformation, and workforce \"\n",
+        "            \"management reports from top-tier consulting firms.\"\n",
+        "        ),\n",
+        "        \"source_description\": (\n",
+        "            \"Management consulting reports prepared exclusively for Casper's Kitchens. \"\n",
+        "            \"Each report includes executive summary, detailed section-by-section analysis, \"\n",
+        "            \"financial projections, and specific recommendations with ROI estimates.\"\n",
+        "        ),\n",
+        "        \"instructions\": (\n",
+        "            \"You are a strategic intelligence assistant. \"\n",
+        "            \"Always cite the consulting firm and report date. \"\n",
+        "            \"Summarize key recommendations with financial impact figures. \"\n",
+        "            \"When multiple reports address the same topic, synthesize the consensus view. \"\n",
+        "            \"Be direct and executive-ready in your summaries.\"\n",
+        "        ),\n",
+        "        \"examples\": [\n",
+        "            {\n",
+        "                \"question\": \"What do consultants recommend as our top AI investments for the next 90 days?\",\n",
+        "                \"guideline\": \"Must cite the consulting firm and report date. Must include at least one concrete recommendation with a financial metric. Must frame in the 90-day horizon.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"Which markets do consultants recommend for expansion?\",\n",
+        "                \"guideline\": \"Must cite the consulting firm and report. Must list specific markets with the rationale and investment estimate per market.\",\n",
+        "            },\n",
+        "            {\n",
+        "                \"question\": \"What's the consensus view on automation across our consulting reports?\",\n",
+        "                \"guideline\": \"Must synthesize across all consultancy reports addressing automation. Must cite specific reports. Must highlight where firms agree vs. disagree.\",\n",
+        "            },\n",
+        "        ],\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "# KA instructions are the source of truth in KA_CONFIGS above — not\n",
+        "# round-tripped through the MLflow Prompt Registry.  Earlier versions of\n",
+        "# this stage also registered each KA's `instructions` under\n",
+        "# `{CATALOG}.prompts.ka_<short>_instructions` so domain experts could edit\n",
+        "# them in Catalog Explorer; that path was dropped because (a) it created\n",
+        "# six extra prompts that nobody iterates on in practice, and (b) the\n",
+        "# load_prompt → cfg[\"instructions\"] override + PATCH-on-drift roundtrip\n",
+        "# was a lot of moving parts for zero observed benefit in demos.  Refund,\n",
+        "# Complaint, and Supervisor still register their prompts — KAs do not.\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create the KAs in parallel\n",
+        "\n",
+        "Looks up existing KAs in `uc_state` first to skip already-created ones, then\n",
+        "queries the KA API once for anything still missing. New KAs are created\n",
+        "concurrently. The downstream `Readiness_Check` task polls the endpoints."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Resolve already-existing KAs by display_name.\n",
+        "# Source 1: uc_state (cheap, scoped to this catalog).\n",
+        "# Source 2: workspace-wide List Knowledge Assistants API (v2.1 has this; v2.0 didn't).\n",
+        "# Each entry maps display_name -> {\"id\", \"endpoint_name\"}.\n",
+        "known_kas = {}\n",
+        "\n",
+        "try:\n",
+        "    df = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'knowledge_assistants'\n",
+        "        ORDER BY created_at DESC\n",
+        "    \"\"\")\n",
+        "    for row in df.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        dn = info.get(\"name\", \"\")  # uc_state stores display_name under \"name\" for back-compat\n",
+        "        kid = info.get(\"tile_id\", \"\")\n",
+        "        ep = info.get(\"endpoint_name\", \"\")\n",
+        "        if dn and kid and dn not in known_kas:\n",
+        "            known_kas[dn] = {\"id\": kid, \"endpoint_name\": ep}\n",
+        "    print(f\"uc_state: found {len(known_kas)} KAs\")\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f uc_state lookup failed: {e}\")\n",
+        "\n",
+        "target_names = {cfg[\"display_name\"] for cfg in KA_CONFIGS}\n",
+        "missing_names = target_names - set(known_kas)\n",
+        "if missing_names:\n",
+        "    print(f\"{len(missing_names)} KAs missing from uc_state \\u2014 listing workspace KAs via {API_BASE}\\u2026\")\n",
+        "    try:\n",
+        "        params = {}\n",
+        "        while True:\n",
+        "            resp = w.api_client.do(\"GET\", API_BASE, query=params)\n",
+        "            for ka in resp.get(\"knowledge_assistants\", []):\n",
+        "                dn = ka.get(\"display_name\", \"\")\n",
+        "                if dn in target_names and dn not in known_kas:\n",
+        "                    known_kas[dn] = {\n",
+        "                        \"id\": ka.get(\"id\", \"\"),\n",
+        "                        \"endpoint_name\": ka.get(\"endpoint_name\", \"\"),\n",
+        "                    }\n",
+        "            token = resp.get(\"next_page_token\")\n",
+        "            if not token:\n",
+        "                break\n",
+        "            params = {\"page_token\": token}\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f KA list error: {e}\")\n",
+        "\n",
+        "\n",
+        "def _create_one(cfg):\n",
+        "    display_name = cfg[\"display_name\"]\n",
+        "\n",
+        "    # If a KA with this display_name already exists, GET its current\n",
+        "    # `instructions` and compare to what cfg[\"instructions\"] resolves to\n",
+        "    # (load_prompt may have fetched a newer registered version above).\n",
+        "    # On drift, PATCH the KA via the v2.1 update endpoint so the new\n",
+        "    # prompt takes effect on the next request — no delete + recreate.\n",
+        "    if display_name in known_kas:\n",
+        "        existing = known_kas[display_name]\n",
+        "        try:\n",
+        "            ka_get = w.api_client.do(\"GET\", f\"{API_BASE}/{existing['id']}\") or {}\n",
+        "            current_instructions = (ka_get.get(\"instructions\") or \"\").strip()\n",
+        "            target_instructions = (cfg[\"instructions\"] or \"\").strip()\n",
+        "            if current_instructions and current_instructions != target_instructions:\n",
+        "                print(f\"[{display_name}] \\u26a0\\ufe0f  Instructions drift \\u2014 PATCHing KA\\u2026\")\n",
+        "                try:\n",
+        "                    w.api_client.do(\n",
+        "                        \"PATCH\",\n",
+        "                        f\"{API_BASE}/{existing['id']}\",\n",
+        "                        query={\"update_mask\": \"instructions\"},\n",
+        "                        body={\"instructions\": cfg[\"instructions\"]},\n",
+        "                    )\n",
+        "                    print(f\"[{display_name}] \\u2705 PATCH succeeded \\u2014 KA now uses the registered prompt\")\n",
+        "                except Exception as _patch_exc:\n",
+        "                    print(\n",
+        "                        f\"[{display_name}] \\u26a0\\ufe0f  PATCH failed ({type(_patch_exc).__name__}: {_patch_exc}). \"\n",
+        "                        f\"As a fallback, delete this KA from the workspace and redeploy this stage.\"\n",
+        "                    )\n",
+        "            else:\n",
+        "                print(f\"[{display_name}] \\u267b\\ufe0f  Already exists (id={existing['id']}, instructions match) \\u2014 skipping update\")\n",
+        "        except Exception as _drift_exc:\n",
+        "            print(\n",
+        "                f\"[{display_name}] \\u267b\\ufe0f  Already exists (id={existing['id']}) \\u2014 skipping update \"\n",
+        "                f\"(drift check failed: {type(_drift_exc).__name__}: {_drift_exc})\"\n",
+        "            )\n",
+        "        return {\n",
+        "            \"display_name\": display_name,\n",
+        "            \"id\": existing[\"id\"],\n",
+        "            \"endpoint_name\": existing[\"endpoint_name\"],\n",
+        "        }\n",
+        "\n",
+        "    # Step 1: create the Knowledge Assistant. v2.1 body is just metadata; the\n",
+        "    # endpoint_name is assigned by the API and returned in the response.\n",
+        "    print(f\"[{display_name}] Creating KA\\u2026\")\n",
+        "    ka_body = {\n",
+        "        \"display_name\": display_name,\n",
+        "        \"description\": cfg[\"description\"],\n",
+        "        \"instructions\": cfg[\"instructions\"],\n",
+        "    }\n",
+        "    ka_resp = w.api_client.do(\"POST\", API_BASE, body=ka_body) or {}\n",
+        "    ka_id = ka_resp.get(\"id\", \"\")\n",
+        "    ka_endpoint = ka_resp.get(\"endpoint_name\", \"\")\n",
+        "    if not ka_id:\n",
+        "        raise RuntimeError(f\"[{display_name}] Create response missing id: {ka_resp}\")\n",
+        "\n",
+        "    # If the endpoint name wasn't populated synchronously, re-fetch.\n",
+        "    if not ka_endpoint:\n",
+        "        try:\n",
+        "            ka_get = w.api_client.do(\"GET\", f\"{API_BASE}/{ka_id}\") or {}\n",
+        "            ka_endpoint = ka_get.get(\"endpoint_name\", \"\")\n",
+        "        except Exception:\n",
+        "            pass\n",
+        "\n",
+        "    # Step 2: attach a \"files\" knowledge source pointing at the UC Volume.\n",
+        "    # The Readiness_Check task is responsible for waiting until the source\n",
+        "    # finishes its initial sync.\n",
+        "    src_body = {\n",
+        "        \"display_name\": cfg[\"source_display_name\"],\n",
+        "        \"description\": cfg[\"source_description\"],\n",
+        "        \"source_type\": \"files\",\n",
+        "        \"files\": {\"path\": cfg[\"volume_path\"]},\n",
+        "    }\n",
+        "    try:\n",
+        "        w.api_client.do(\"POST\", f\"{API_BASE}/{ka_id}/knowledge-sources\", body=src_body)\n",
+        "        print(f\"[{display_name}] \\u2705 Created (id={ka_id}, endpoint={ka_endpoint or 'pending'})\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"[{display_name}] \\u26a0\\ufe0f  KA created but source attach failed: {e}\")\n",
+        "\n",
+        "    return {\"display_name\": display_name, \"id\": ka_id, \"endpoint_name\": ka_endpoint}\n",
+        "\n",
+        "\n",
+        "# Serial creation, NOT parallel.  Parallel `_create_one` invocations\n",
+        "# (previously via ThreadPoolExecutor(max_workers=6)) collided in the\n",
+        "# Databricks workspace tree because the KA Manager API does multiple\n",
+        "# /workspaces:<id> mutations per KA and isn't reliably safe under\n",
+        "# concurrent writes — surfaces as:\n",
+        "#   InternalError: [OCC check failure] A descendant or edge of\n",
+        "#   /workspaces:<id> was inserted or deleted during the transaction.\n",
+        "# Serialising adds a few seconds per KA (so ~30s-1min for 6 KAs) and\n",
+        "# eliminates the race entirely.\n",
+        "created_agents = [_create_one(cfg) for cfg in KA_CONFIGS]\n",
+        "\n",
+        "# uc_state stores: name=display_name (for routing lookups), tile_id=KA UUID\n",
+        "# (for delete + readiness checks), endpoint_name=auto-generated by API.\n",
+        "#\n",
+        "# `uc_state.add()` is a raw INSERT (no upsert), so re-running this stage\n",
+        "# would append duplicate rows for KAs we've already registered.  Look up\n",
+        "# existing tile_ids first and skip the add() call when the KA is already\n",
+        "# tracked — keeps uc_state at exactly one row per KA across re-runs.\n",
+        "existing_ka_tile_ids = set()\n",
+        "try:\n",
+        "    _existing_rows = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data:tile_id::string AS tile_id\n",
+        "        FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'knowledge_assistants'\n",
+        "    \"\"\").collect()\n",
+        "    existing_ka_tile_ids = {row.tile_id for row in _existing_rows if row.tile_id}\n",
+        "except Exception as _enum_exc:\n",
+        "    print(f\"⚠️  Could not enumerate existing uc_state KA rows ({type(_enum_exc).__name__}: {_enum_exc}) — falling back to unconditional add() (may produce duplicates).\")\n",
+        "\n",
+        "for r in created_agents:\n",
+        "    if r[\"id\"] in existing_ka_tile_ids:\n",
+        "        print(f\"   ♻  Already in uc_state: {r['display_name']} (tile_id={r['id']}) — skipping add()\")\n",
+        "        continue\n",
+        "    add(CATALOG, \"knowledge_assistants\", {\n",
+        "        \"endpoint_name\": r[\"endpoint_name\"],\n",
+        "        \"tile_id\": r[\"id\"],\n",
+        "        \"name\": r[\"display_name\"],\n",
+        "    })\n",
+        "    print(f\"   Registered: {r['display_name']} (id={r['id']}, endpoint={r['endpoint_name'] or 'pending'})\")\n",
+        "\n",
+        "print(f\"\\n\\u2705 Knowledge Agents stage complete \\u2014 {len(created_agents)} KAs processed\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Attach example questions to each KA\n",
+        "\n",
+        "Idempotent: lists existing examples, deletes them, then re-POSTs the desired set\n",
+        "defined in `KA_CONFIGS[i][\"examples\"]`. This way a manual edit (or wipe) heals\n",
+        "on the next deploy and we don't accumulate duplicates.\n",
+        "\n",
+        "**API**: `POST /api/2.0/knowledge-assistants/{tile_id}/examples` — body\n",
+        "`{\"tile_id\": ka_id, \"question\": str, \"guidelines\": [str]}` (one example per\n",
+        "request). Same shape as the supervisor examples API, just on the KA surface\n",
+        "(note: examples live on `v2.0` even though the rest of this stage uses `v2.1`)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time as _time\n",
+        "\n",
+        "_KA_EXAMPLES_BASE_TPL = \"/api/2.0/knowledge-assistants/{ka_id}/examples\"\n",
+        "\n",
+        "\n",
+        "def _format_api_error(e: Exception) -> str:\n",
+        "    \"\"\"str(e) on databricks-sdk errors is sometimes empty/None when the server\n",
+        "    returns a non-standard error body. Surface enough detail to debug.\"\"\"\n",
+        "    msg = str(e) or \"\"\n",
+        "    if not msg or msg == \"None\":\n",
+        "        msg = repr(e)\n",
+        "    code = getattr(e, \"error_code\", None)\n",
+        "    return f\"{type(e).__name__}: {msg}\" + (f\" [error_code={code}]\" if code else \"\")\n",
+        "\n",
+        "\n",
+        "def _do_with_retry(method: str, path: str, body: dict | None = None, retries: int = 1, backoff_s: float = 2.0):\n",
+        "    \"\"\"api_client.do with one retry on Exception. Used to absorb transient\n",
+        "    rate-limit failures on the KA examples API which empirically rejects\n",
+        "    bursts of >~5 req/s with empty error bodies.\"\"\"\n",
+        "    last_exc = None\n",
+        "    for attempt in range(retries + 1):\n",
+        "        try:\n",
+        "            if body is None:\n",
+        "                return w.api_client.do(method, path)\n",
+        "            return w.api_client.do(method, path, body=body)\n",
+        "        except Exception as e:\n",
+        "            last_exc = e\n",
+        "            if attempt < retries:\n",
+        "                _time.sleep(backoff_s)\n",
+        "    raise last_exc\n",
+        "\n",
+        "\n",
+        "cfg_by_name = {cfg[\"display_name\"]: cfg for cfg in KA_CONFIGS}\n",
+        "\n",
+        "for r in created_agents:\n",
+        "    display_name = r[\"display_name\"]\n",
+        "    ka_id = r[\"id\"]\n",
+        "    cfg = cfg_by_name.get(display_name)\n",
+        "    if not cfg or not ka_id:\n",
+        "        continue\n",
+        "    examples = cfg.get(\"examples\") or []\n",
+        "    if not examples:\n",
+        "        continue\n",
+        "\n",
+        "    base = _KA_EXAMPLES_BASE_TPL.format(ka_id=ka_id)\n",
+        "\n",
+        "    existing = []\n",
+        "    try:\n",
+        "        resp = w.api_client.do(\"GET\", base) or {}\n",
+        "        existing = resp.get(\"examples\", []) or []\n",
+        "    except Exception as _le:\n",
+        "        print(f\"[{display_name}] (skipping pre-clear: {_format_api_error(_le)})\")\n",
+        "    deleted, delete_failures = 0, 0\n",
+        "    for ex in existing:\n",
+        "        ex_id = ex.get(\"example_id\") or ex.get(\"id\")\n",
+        "        if not ex_id:\n",
+        "            continue\n",
+        "        try:\n",
+        "            _do_with_retry(\"DELETE\", f\"{base}/{ex_id}\", retries=1, backoff_s=2.0)\n",
+        "            deleted += 1\n",
+        "        except Exception as _de:\n",
+        "            delete_failures += 1\n",
+        "            print(f\"[{display_name}] \\u26a0\\ufe0f  Could not delete existing example {ex_id}: {_format_api_error(_de)}\")\n",
+        "        _time.sleep(0.4)  # gentle pacing — examples API rate-limits bursts\n",
+        "    if existing:\n",
+        "        print(f\"[{display_name}] Cleared {deleted}/{len(existing)} existing example(s) before re-attach\"\n",
+        "              f\"{f' (delete failures: {delete_failures})' if delete_failures else ''}\")\n",
+        "\n",
+        "    posted = 0\n",
+        "    failures = 0\n",
+        "    for ex in examples:\n",
+        "        guideline = ex.get(\"guideline\")\n",
+        "        guidelines = ex.get(\"guidelines\")\n",
+        "        if guidelines is None and guideline is not None:\n",
+        "            guidelines = [guideline]\n",
+        "        body = {\"tile_id\": ka_id, \"question\": ex[\"question\"]}\n",
+        "        if guidelines:\n",
+        "            body[\"guidelines\"] = guidelines\n",
+        "        try:\n",
+        "            _do_with_retry(\"POST\", base, body=body, retries=1, backoff_s=2.0)\n",
+        "            posted += 1\n",
+        "        except Exception as _pe:\n",
+        "            failures += 1\n",
+        "            print(f\"[{display_name}] \\u26a0\\ufe0f  Failed to attach {ex['question']!r}: {_format_api_error(_pe)}\")\n",
+        "        _time.sleep(0.4)  # gentle pacing — examples API rate-limits bursts\n",
+        "\n",
+        "    if failures:\n",
+        "        print(f\"[{display_name}] \\u26a0\\ufe0f  Examples attached partially: {posted}/{len(examples)} (failures={failures})\")\n",
+        "    else:\n",
+        "        print(f\"[{display_name}] \\u2705 Examples attached ({posted}/{len(examples)})\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/lakebase.ipynb b/stages/lakebase.ipynb
index b6c2199..513d99a 100644
--- a/stages/lakebase.ipynb
+++ b/stages/lakebase.ipynb
@@ -1,240 +1,234 @@
 {
- "cells": [
-  {
-   "cell_type": "code",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "1c4c079b-307d-4445-9f4d-4bb65c2a9bbe",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Lakebase — Refund (Reverse-ETL)\n",
+        "\n",
+        "Creates the **`caspers_refund`** logical Postgres database inside the shared\n",
+        "`${CATALOG}-caspers` Lakebase Autoscaling project (provisioned by\n",
+        "`stages/lakebase_project.ipynb`), then creates a **synced table** from\n",
+        "`${CATALOG}.recommender.refund_recommendations` (the gold Delta produced by\n",
+        "`stages/refunder_stream.ipynb`) into Postgres so the `refund-manager`\n",
+        "Databricks App can query it with sub-100 ms latency.\n",
+        "\n",
+        "- UC synced-table entry:   `${CATALOG}.recommender.pg_recommendations`\n",
+        "- Backing Delta storage:   `${CATALOG}._lakebase_storage.pg_recommendations`\n",
+        "- Postgres destination:    `caspers_refund.recommender.pg_recommendations`\n",
+        "\n",
+        "All API calls go through `utils/lakebase_autoscale.py` (the Autoscaling\n",
+        "synced-table API isn't wrapped by the Python SDK yet)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%pip install --upgrade \"databricks-sdk>=0.81.0\""
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "dbutils.library.restartPython()"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import re, sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "from lakebase_autoscale import (\n",
+        "    get_or_create_postgres_database,\n",
+        "    get_or_create_autoscale_synced_table,\n",
+        "    get_autoscale_synced_table,\n",
+        ")\n",
+        "import status\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "# Coordinates of the shared Lakebase Autoscale project (created by\n",
+        "# stages/lakebase_project.ipynb).  All Lakebase consumers point at the same\n",
+        "# project; isolation is at the database level.\n",
+        "PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "BRANCH_PATH = f\"projects/{PROJECT_ID}/branches/production\"\n",
+        "\n",
+        "# Per-component Postgres database for the refund manager.\n",
+        "# Note: Lakebase Autoscale requires DNS-safe names (no underscores) per\n",
+        "# the create_database API contract.\n",
+        "POSTGRES_DB = \"caspers-refund\"\n",
+        "POSTGRES_SCHEMA = \"recommender\"\n",
+        "\n",
+        "# UC synced-table entry + its backing Delta storage path.  These MUST live\n",
+        "# in different UC schemas: the synced-pipeline materialises its backing\n",
+        "# Delta at `{storage_catalog}.{storage_schema}.<basename>`, so equal schemas\n",
+        "# would collide.\n",
+        "SOURCE_TABLE = f\"{CATALOG}.recommender.refund_recommendations\"\n",
+        "SYNCED_TABLE = f\"{CATALOG}.recommender.pg_recommendations\"\n",
+        "SYNCED_BASENAME = SYNCED_TABLE.split('.')[-1]\n",
+        "BACKING_TABLE = f\"{CATALOG}._lakebase_storage.{SYNCED_BASENAME}\"\n",
+        "\n",
+        "print(f\"CATALOG          = {CATALOG}\")\n",
+        "print(f\"PROJECT_ID       = {PROJECT_ID}\")\n",
+        "print(f\"BRANCH_PATH      = {BRANCH_PATH}\")\n",
+        "print(f\"POSTGRES_DB      = {POSTGRES_DB}\")\n",
+        "print(f\"SOURCE_TABLE     = {SOURCE_TABLE}\")\n",
+        "print(f\"SYNCED_TABLE     = {SYNCED_TABLE}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Ensure the per-component Postgres database exists"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "db, created = get_or_create_postgres_database(\n",
+        "    w,\n",
+        "    project_id=PROJECT_ID,\n",
+        "    database_id=POSTGRES_DB,\n",
+        ")\n",
+        "if created:\n",
+        "    status.ok(f\"Created Postgres database {POSTGRES_DB} in {PROJECT_ID}\")\n",
+        "else:\n",
+        "    status.reuse(f\"Reusing Postgres database {POSTGRES_DB} in {PROJECT_ID}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create the synced table (idempotent)\n",
+        "\n",
+        "If a stale UC entry or Delta is sitting at either destination, drop it\n",
+        "first.  The Autoscaling synced-table API materialises the destination\n",
+        "Postgres table for us (`create_database_objects_if_missing=True`), so we\n",
+        "don't need the three-place sweep that the legacy Provisioned flow needed."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}._lakebase_storage\")\n",
+        "\n",
+        "# Pre-create defence: if a previous run left a *plain Delta* table sitting\n",
+        "# at the synced-table UC name (e.g. a half-succeeded create), the Autoscale\n",
+        "# API's GET returns None for it but POST then conflicts with the UC name\n",
+        "# itself.  Drop both before attempting create.\n",
+        "existing_synced = get_autoscale_synced_table(w, SYNCED_TABLE)\n",
+        "if existing_synced is not None:\n",
+        "    status.reuse(f\"Found existing synced table: {SYNCED_TABLE}\")\n",
+        "else:\n",
+        "    for stale in (SYNCED_TABLE, BACKING_TABLE):\n",
+        "        try:\n",
+        "            spark.sql(f\"DROP TABLE IF EXISTS {stale}\")\n",
+        "            status.drop(f\"Cleared stale Delta at {stale} (no-op if absent)\")\n",
+        "        except Exception as e:\n",
+        "            status.warn(f\"Could not drop {stale}: {e}\")\n",
+        "\n",
+        "    result = get_or_create_autoscale_synced_table(\n",
+        "        w,\n",
+        "        synced_table_name=SYNCED_TABLE,\n",
+        "        source_table_full_name=SOURCE_TABLE,\n",
+        "        primary_key_columns=[\"order_id\"],\n",
+        "        branch=BRANCH_PATH,\n",
+        "        postgres_database=POSTGRES_DB,\n",
+        "        scheduling_policy=\"CONTINUOUS\",\n",
+        "        create_database_objects_if_missing=True,\n",
+        "    )\n",
+        "    status.ok(f\"Created synced table {SYNCED_TABLE}\")\n",
+        "    add(CATALOG, \"autoscale_synced_tables\", {\n",
+        "        \"synced_table_name\": SYNCED_TABLE,\n",
+        "        \"project_id\": PROJECT_ID,\n",
+        "        \"postgres_database\": POSTGRES_DB,\n",
+        "        \"postgres_schema\": POSTGRES_SCHEMA,\n",
+        "    })"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "status.ok(\"lakebase (refund) stage complete\")\n",
+        "print(f\"   Project:           projects/{PROJECT_ID}\")\n",
+        "print(f\"   Postgres DB:       {POSTGRES_DB}\")\n",
+        "print(f\"   Synced UC entry:   {SYNCED_TABLE}\")\n",
+        "print(f\"   Postgres dest:     {POSTGRES_DB}.{POSTGRES_SCHEMA}.{SYNCED_BASENAME}\")"
+      ]
     }
-   },
-   "source": "import re\nCATALOG = dbutils.widgets.get(\"CATALOG\")\nREFUNDMANAGER_LAKEBASE_INSTANCE_NAME = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}refundmanager\".lower())",
-   "execution_count": null,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "2e691724-d672-4857-82a3-ad2b2114417c",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "%pip install databricks-sdk --upgrade"
-   ],
-   "execution_count": 0,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "7160a660-ea15-4e86-9c93-166728a0dec2",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.database import DatabaseInstance\n",
-    "from databricks.sdk.errors import NotFound, ResourceDoesNotExist\n",
-    "import uuid\n",
-    "import time\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "instance_name = REFUNDMANAGER_LAKEBASE_INSTANCE_NAME\n",
-    "\n",
-    "# Idempotent: reuse existing instance or create new one\n",
-    "try:\n",
-    "    existing = w.database.get_database_instance(instance_name)\n",
-    "    print(f\"♻️ Found existing database instance: {existing.name} (state: {existing.state})\")\n",
-    "    instance = existing\n",
-    "except (NotFound, ResourceDoesNotExist):\n",
-    "    print(f\"Creating new database instance: {instance_name}\")\n",
-    "    instance = w.database.create_database_instance(\n",
-    "        DatabaseInstance(\n",
-    "            name=instance_name,\n",
-    "            capacity=\"CU_1\"\n",
-    "        )\n",
-    "    )\n",
-    "    print(f\"Created database instance: {instance.name}\")\n",
-    "    add(CATALOG, \"databaseinstances\", {\"name\": instance.name})\n",
-    "\n",
-    "# Block until it's actually ready\n",
-    "print(\"Waiting for database instance to be available...\")\n",
-    "for _ in range(60):\n",
-    "    state = str(w.database.get_database_instance(instance_name).state)\n",
-    "    if state == \"DatabaseInstanceState.AVAILABLE\":\n",
-    "        print(f\"Instance ready: {state}\")\n",
-    "        break\n",
-    "    time.sleep(10)\n",
-    "else:\n",
-    "    raise TimeoutError(f\"Database instance {instance_name} did not become available within 10 minutes\")\n",
-    "\n",
-    ""
-   ],
-   "execution_count": 0,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "9fe12046-6846-4ff8-9ed0-c263ca634a2f",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "from databricks.sdk.service.database import DatabaseCatalog\n",
-    "\n",
-    "catalog_name = REFUNDMANAGER_LAKEBASE_INSTANCE_NAME\n",
-    "\n",
-    "try:\n",
-    "    existing_cat = w.catalogs.get(catalog_name)\n",
-    "    print(f\"♻️ Found existing catalog: {existing_cat.name}\")\n",
-    "except Exception:\n",
-    "    catalog = w.database.create_database_catalog(\n",
-    "        DatabaseCatalog(\n",
-    "            name=catalog_name,\n",
-    "            database_instance_name=REFUNDMANAGER_LAKEBASE_INSTANCE_NAME,\n",
-    "            database_name=\"caspers\",\n",
-    "            create_database_if_not_exists=True\n",
-    "        )\n",
-    "    )\n",
-    "    print(f\"Created new database and catalog: {catalog.name}\")\n",
-    "    add(CATALOG, \"databasecatalogs\", catalog)"
-   ],
-   "execution_count": null,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {
-      "byteLimit": 2048000,
-      "rowLimit": 10000
-     },
-     "inputWidgets": {},
-     "nuid": "3f104624-0728-4605-aa89-0c0a18f294b7",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "from databricks.sdk.service.database import SyncedDatabaseTable, SyncedTableSpec, NewPipelineSpec, SyncedTableSchedulingPolicy\n",
-    "\n",
-    "synced_table_name = f\"{CATALOG}.recommender.pg_recommendations\"\n",
-    "\n",
-    "try:\n",
-    "    existing_table = w.tables.get(synced_table_name)\n",
-    "    print(f\"♻️ Found existing synced table: {existing_table.full_name}\")\n",
-    "except Exception:\n",
-    "    synced_table = w.database.create_synced_database_table(\n",
-    "        SyncedDatabaseTable(\n",
-    "            name=synced_table_name,\n",
-    "            database_instance_name=instance_name,\n",
-    "            logical_database_name=\"caspers\",\n",
-    "            spec=SyncedTableSpec(\n",
-    "                source_table_full_name=f\"{CATALOG}.recommender.refund_recommendations\",\n",
-    "                primary_key_columns=[\"order_id\"],\n",
-    "                scheduling_policy=SyncedTableSchedulingPolicy.CONTINUOUS,\n",
-    "                create_database_objects_if_missing=True,\n",
-    "                new_pipeline_spec=NewPipelineSpec(\n",
-    "                    storage_catalog=\"storage_catalog\",\n",
-    "                    storage_schema=\"storage_schema\"\n",
-    "                )\n",
-    "            ),\n",
-    "        )\n",
-    "    )\n",
-    "    print(f\"Created synced table: {synced_table.name}\")\n",
-    "    add(CATALOG, \"pipelines\", synced_table.data_synchronization_status)"
-   ],
-   "execution_count": 0,
-   "outputs": []
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "lakebase",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "cazzper",
-     "nuid": "73cb92d5-f843-4e41-92d6-5081124a02c9",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
       },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 4
       },
-      "widgetType": "text"
-     }
+      "notebookName": "lakebase",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "",
+          "nuid": "lakebase-refund-catalog",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
     }
-   }
   },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
-}
\ No newline at end of file
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
diff --git a/stages/lakebase_project.ipynb b/stages/lakebase_project.ipynb
new file mode 100644
index 0000000..54c7ce0
--- /dev/null
+++ b/stages/lakebase_project.ipynb
@@ -0,0 +1,218 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Lakebase Project (shared Autoscaling)\n",
+        "\n",
+        "Provisions the **single, shared Lakebase Autoscaling project** (`w.postgres`) that every\n",
+        "Lakebase-consuming stage and app in this bundle now uses.\n",
+        "\n",
+        "Project layout:\n",
+        "\n",
+        "- **Project**: `${CATALOG}-caspers`  (one per CATALOG)\n",
+        "- **Branch**: `production` (default)\n",
+        "- **Endpoint**: `primary` (default; created with the project)\n",
+        "- **Databases inside the project** (each created by its owning downstream stage):\n",
+        "  - `caspers_refund`    \u2014 created by `stages/lakebase.ipynb`\n",
+        "  - `caspers_complaint` \u2014 created by `stages/complaint_lakebase.ipynb`\n",
+        "  - `caspers_ops`       \u2014 created by `stages/operational_lakebase.ipynb`\n",
+        "  - (`databricks_postgres` ships with the project; we don't use it for app data)\n",
+        "\n",
+        "The project creator is automatically granted superuser in every database in this project,\n",
+        "so DDL from any downstream stage (running as the bundle deployer) just works.\n",
+        "\n",
+        "**This stage only creates the project and waits for the endpoint to be ready.**  Database\n",
+        "creation, schema DDL, synced-table wiring, and app deploys all live in their per-component\n",
+        "stages.  Every downstream Lakebase stage declares `Lakebase_Project` in its `depends_on`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade \"databricks-sdk>=0.81.0\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "# Project id sanitised to the API's [a-z0-9-] alphabet.  All four databases\n",
+        "# live inside this single project; isolation comes from per-database grants,\n",
+        "# not per-project ones.\n",
+        "PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "PROJECT_RESOURCE_NAME = f\"projects/{PROJECT_ID}\"\n",
+        "BRANCH_PATH = f\"{PROJECT_RESOURCE_NAME}/branches/production\"\n",
+        "ENDPOINT_PATH = f\"{BRANCH_PATH}/endpoints/primary\"\n",
+        "\n",
+        "print(f\"CATALOG          = {CATALOG}\")\n",
+        "print(f\"PROJECT_ID       = {PROJECT_ID}\")\n",
+        "print(f\"BRANCH_PATH      = {BRANCH_PATH}\")\n",
+        "print(f\"ENDPOINT_PATH    = {ENDPOINT_PATH}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create or reuse the shared Autoscale project"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import sys, time\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "import status\n",
+        "\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.postgres import Project, ProjectSpec\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "is_new = False\n",
+        "try:\n",
+        "    project = w.postgres.get_project(name=PROJECT_RESOURCE_NAME)\n",
+        "    status.reuse(f\"Reusing existing Lakebase project: {PROJECT_ID}\")\n",
+        "except Exception:\n",
+        "    is_new = True\n",
+        "    status.info(f\"Creating Lakebase Autoscale project: {PROJECT_ID}\")\n",
+        "    # create_project returns a CreateProjectOperation (Google LRO-style); it\n",
+        "    # has no .result(), and the project's resource name is deterministically\n",
+        "    # `projects/{PROJECT_ID}`.  The endpoint readiness loop below waits for\n",
+        "    # provisioning to finish.\n",
+        "    w.postgres.create_project(\n",
+        "        project=Project(\n",
+        "            spec=ProjectSpec(\n",
+        "                display_name=f\"Caspers Kitchens ({CATALOG})\",\n",
+        "                pg_version=\"17\",\n",
+        "            )\n",
+        "        ),\n",
+        "        project_id=PROJECT_ID,\n",
+        "    )\n",
+        "    add(CATALOG, \"postgres_projects\", {\n",
+        "        \"project_id\": PROJECT_ID,\n",
+        "        \"name\": PROJECT_RESOURCE_NAME,\n",
+        "    })\n",
+        "    status.ok(f\"Created project: {PROJECT_RESOURCE_NAME}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Wait for the primary endpoint to be RUNNING\n",
+        "\n",
+        "For freshly created projects this typically takes 1\u20132 min.  For reused\n",
+        "projects the endpoint is already up, so we still GET it (one call) to\n",
+        "surface the host in the stage logs and validate the path."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "if is_new:\n",
+        "    status.info(\"Waiting for endpoint to be ready...\")\n",
+        "    for attempt in range(40):\n",
+        "        try:\n",
+        "            ep = w.postgres.get_endpoint(name=ENDPOINT_PATH)\n",
+        "            state = str(ep.status.current_state) if ep.status else \"UNKNOWN\"\n",
+        "            if any(s in state for s in (\"RUNNING\", \"AVAILABLE\", \"ACTIVE\")):\n",
+        "                status.ok(f\"Endpoint ready (state={state})\")\n",
+        "                break\n",
+        "            print(f\"  [{attempt+1}/40] state={state}, retrying in 15s...\")\n",
+        "        except Exception as e:\n",
+        "            print(f\"  [{attempt+1}/40] not yet reachable: {e}\")\n",
+        "        time.sleep(15)\n",
+        "    else:\n",
+        "        raise TimeoutError(\n",
+        "            f\"Endpoint {ENDPOINT_PATH} did not start within 10 minutes\"\n",
+        "        )\n",
+        "else:\n",
+        "    ep = w.postgres.get_endpoint(name=ENDPOINT_PATH)\n",
+        "    status.ok(f\"Endpoint ready (state={ep.status.current_state})\")\n",
+        "\n",
+        "host = ep.status.hosts.host\n",
+        "status.ok(f\"Lakebase project stage complete\")\n",
+        "print(f\"   Project:  {PROJECT_RESOURCE_NAME}\")\n",
+        "print(f\"   Endpoint: {ENDPOINT_PATH}\")\n",
+        "print(f\"   Host:     {host}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
+      },
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "lakebase_project",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "",
+          "nuid": "lakebase-project-catalog",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
diff --git a/stages/menu_data.ipynb b/stages/menu_data.ipynb
deleted file mode 100644
index f4f49d1..0000000
--- a/stages/menu_data.ipynb
+++ /dev/null
@@ -1,203 +0,0 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Menu Data\n",
-        "\n",
-        "This stage uploads pre-generated restaurant menu PDFs to a Unity Catalog volume\n",
-        "and loads the structured metadata as a dimension table. These PDFs contain\n",
-        "nutritional information and allergen data for each brand's menu items."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "%pip install --upgrade databricks-sdk"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "dbutils.library.restartPython()"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Create catalog, schema, and volume for menu documents"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "spark.sql(f\"CREATE CATALOG IF NOT EXISTS {CATALOG}\")\n",
-        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.menu_documents\")\n",
-        "spark.sql(f\"CREATE VOLUME IF NOT EXISTS {CATALOG}.menu_documents.menus\")\n",
-        "print(f\"\\u2705 Created schema {CATALOG}.menu_documents and volume menus\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Copy PDF files from the repo into the Unity Catalog volume"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import os\n",
-        "import glob\n",
-        "\n",
-        "pdf_source_dir = os.path.abspath(\"../data/menus/pdfs\")\n",
-        "volume_path = f\"/Volumes/{CATALOG}/menu_documents/menus\"\n",
-        "\n",
-        "pdf_files = glob.glob(os.path.join(pdf_source_dir, \"*.pdf\"))\n",
-        "print(f\"Found {len(pdf_files)} PDF files to upload\")\n",
-        "\n",
-        "for pdf_file in pdf_files:\n",
-        "    filename = os.path.basename(pdf_file)\n",
-        "    with open(pdf_file, \"rb\") as src:\n",
-        "        with open(f\"{volume_path}/{filename}\", \"wb\") as dst:\n",
-        "            dst.write(src.read())\n",
-        "    print(f\"  Uploaded: {filename}\")\n",
-        "\n",
-        "print(f\"\\u2705 Uploaded {len(pdf_files)} PDFs to {volume_path}\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Load structured metadata as dimension tables\n",
-        "\n",
-        "The menu_metadata.json contains the source data used to generate the PDFs,\n",
-        "including items, nutritional info, and allergens per brand."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import json\n",
-        "\n",
-        "metadata_path = os.path.abspath(\"../data/menus/menu_metadata.json\")\n",
-        "with open(metadata_path) as f:\n",
-        "    metadata = json.load(f)\n",
-        "\n",
-        "print(f\"Loaded metadata for {len(metadata['brands'])} brands\")"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "from pyspark.sql.types import (\n",
-        "    StructType, StructField, StringType, DoubleType, IntegerType, ArrayType\n",
-        ")\n",
-        "\n",
-        "# Flatten items with their brand context\n",
-        "rows = []\n",
-        "for brand in metadata[\"brands\"]:\n",
-        "    for item in brand[\"items\"]:\n",
-        "        rows.append({\n",
-        "            \"brand_name\": brand[\"brand_name\"],\n",
-        "            \"cuisine\": brand[\"cuisine\"],\n",
-        "            \"pdf_filename\": brand[\"pdf_filename\"],\n",
-        "            \"item_name\": item[\"name\"],\n",
-        "            \"description\": item[\"description\"],\n",
-        "            \"category\": item[\"category\"],\n",
-        "            \"price\": float(item[\"price\"]),\n",
-        "            \"calories\": int(item[\"calories\"]),\n",
-        "            \"protein_g\": int(item[\"protein_g\"]),\n",
-        "            \"fat_g\": int(item[\"fat_g\"]),\n",
-        "            \"carbs_g\": int(item[\"carbs_g\"]),\n",
-        "            \"allergens\": item[\"allergens\"],\n",
-        "        })\n",
-        "\n",
-        "schema = StructType([\n",
-        "    StructField(\"brand_name\", StringType()),\n",
-        "    StructField(\"cuisine\", StringType()),\n",
-        "    StructField(\"pdf_filename\", StringType()),\n",
-        "    StructField(\"item_name\", StringType()),\n",
-        "    StructField(\"description\", StringType()),\n",
-        "    StructField(\"category\", StringType()),\n",
-        "    StructField(\"price\", DoubleType()),\n",
-        "    StructField(\"calories\", IntegerType()),\n",
-        "    StructField(\"protein_g\", IntegerType()),\n",
-        "    StructField(\"fat_g\", IntegerType()),\n",
-        "    StructField(\"carbs_g\", IntegerType()),\n",
-        "    StructField(\"allergens\", ArrayType(StringType())),\n",
-        "])\n",
-        "\n",
-        "df = spark.createDataFrame(rows, schema=schema)\n",
-        "df.write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.menu_documents.brands_metadata\")\n",
-        "print(f\"\\u2705 Created brands_metadata table with {df.count()} items\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Register resources with uc_state for cleanup"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import sys\n",
-        "sys.path.append('../utils')\n",
-        "from uc_state import add\n",
-        "\n",
-        "# The schema and volume will be cleaned up when the catalog is dropped,\n",
-        "# but we register the catalog itself if it was newly created.\n",
-        "# Note: other stages may have already registered the catalog.\n",
-        "print(\"\\u2705 Menu data stage complete\")"
-      ]
-    }
-  ],
-  "metadata": {
-    "kernelspec": {
-      "display_name": "Python 3",
-      "language": "python",
-      "name": "python3"
-    },
-    "language_info": {
-      "name": "python",
-      "version": "3.11.0"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 4
-}
diff --git a/stages/menu_genie.ipynb b/stages/menu_genie.ipynb
deleted file mode 100644
index 2033e22..0000000
--- a/stages/menu_genie.ipynb
+++ /dev/null
@@ -1,252 +0,0 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "### Menu Genie Space\n",
-        "\n",
-        "This stage deploys a Databricks Genie space connected to the processed menu document\n",
-        "Delta tables. Users can ask natural language questions about menu items, nutritional\n",
-        "information, allergens, and brand comparisons."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "%pip install --upgrade databricks-sdk"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "dbutils.library.restartPython()"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Create a SQL warehouse for the Genie space"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "from databricks.sdk import WorkspaceClient\n",
-        "\n",
-        "w = WorkspaceClient()\n",
-        "\n",
-        "import sys\n",
-        "sys.path.append('../utils')\n",
-        "from uc_state import add\n",
-        "\n",
-        "WAREHOUSE_NAME = f\"{CATALOG}-menu-warehouse\"\n",
-        "\n",
-        "existing_wh = [wh for wh in w.warehouses.list() if wh.name == WAREHOUSE_NAME]\n",
-        "if existing_wh:\n",
-        "    warehouse = existing_wh[0]\n",
-        "    print(f\"Using existing warehouse: {warehouse.id}\")\n",
-        "else:\n",
-        "    warehouse = w.warehouses.create(\n",
-        "        name=WAREHOUSE_NAME,\n",
-        "        cluster_size=\"2X-Small\",\n",
-        "        max_num_clusters=1,\n",
-        "        min_num_clusters=1,\n",
-        "        enable_serverless_compute=True,\n",
-        "    ).result()\n",
-        "    print(f\"\\u2705 Created warehouse: {warehouse.id}\")\n",
-        "\n",
-        "add(CATALOG, \"warehouses\", warehouse)"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "##### Deploy the Genie space via REST API"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import json\n",
-        "import hashlib\n",
-        "\n",
-        "GENIE_SPACE_TITLE = f\"Caspers Menu and Safety Intelligence ({CATALOG})\"\n",
-        "\n",
-        "GENIE_DESCRIPTION = \"\"\"You are a data analyst for Caspers Kitchens, a ghost kitchen network\n",
-        "operating 16 restaurant brands across 4 locations (San Francisco, Silicon Valley,\n",
-        "Bellevue, Chicago). You have access to menu data and food safety inspection records\n",
-        "organized in a bronze/silver/gold medallion architecture.\n",
-        "\n",
-        "=== DATA MODEL ===\n",
-        "\n",
-        "SILVER TABLES (cleaned, enriched - use for detailed drill-downs):\n",
-        "\n",
-        "silver_menu_items: Every menu item with enriched fields.\n",
-        "  Key columns: brand_name, cuisine, item_name, description, category, price,\n",
-        "  calories, protein_g, fat_g, carbs_g, allergens (array), allergen_count,\n",
-        "  is_allergen_free (boolean), price_tier (budget/standard/premium),\n",
-        "  calorie_category (light/moderate/hearty), protein_pct (percentage of calories\n",
-        "  from protein), is_high_protein (>25% calories from protein), is_low_calorie (<400 cal).\n",
-        "\n",
-        "silver_inspections: Inspection records with derived compliance fields.\n",
-        "  Key columns: inspection_id, location_id, location_name, address, inspection_date,\n",
-        "  inspector_name, score (0-100), grade (A/B/C/F), violation_count, critical_count,\n",
-        "  major_count, minor_count, follow_up_status, passed (boolean, score >= 70),\n",
-        "  score_band (excellent/good/acceptable/failing), has_critical (boolean),\n",
-        "  severity_index (critical*3 + major*2 + minor).\n",
-        "\n",
-        "silver_violations: Individual violations with urgency scoring.\n",
-        "  Key columns: inspection_id, location_id, location_name, inspection_date,\n",
-        "  code, severity (critical/major/minor), category, description, corrective_action,\n",
-        "  deadline_days, is_critical, is_major, is_minor (booleans),\n",
-        "  urgency_score (critical=10, major=5, minor=2), needs_immediate_action (deadline <= 7 days).\n",
-        "\n",
-        "GOLD TABLES (business-ready views and aggregates):\n",
-        "\n",
-        "menu_items: Curated item catalog (brand_name, cuisine, item_name, description, category,\n",
-        "  price, price_tier, allergen_count, is_allergen_free).\n",
-        "nutritional_info: Per-item nutrition (brand_name, item_name, category, calories, protein_g,\n",
-        "  fat_g, carbs_g, calorie_category, protein_pct, is_high_protein, is_low_calorie).\n",
-        "allergens: Per-item allergen boolean flags (contains_wheat, contains_milk, contains_egg,\n",
-        "  contains_soy, contains_peanut, contains_tree_nut, contains_fish, contains_shellfish,\n",
-        "  contains_sesame) plus allergen_count.\n",
-        "brand_nutrition_summary: Per-brand aggregates (total_items, avg/min/max calories,\n",
-        "  avg protein/fat/carbs, avg/min/max price, high_protein_items, low_calorie_items,\n",
-        "  allergen_free_items).\n",
-        "inspection_details: Inspection records (score, grade, passed, score_band, has_critical,\n",
-        "  severity_index, violation counts, follow_up_status).\n",
-        "violation_analysis: Individual violations (severity, category, corrective_action,\n",
-        "  deadline_days, urgency_score, needs_immediate_action).\n",
-        "location_compliance_summary: Per-location aggregates (total_inspections, avg/min/max score,\n",
-        "  total violations by severity, passed_inspections, pass_rate_pct, avg_severity_index).\n",
-        "\n",
-        "=== QUERY GUIDELINES ===\n",
-        "\n",
-        "- For allergen questions, use the allergens table with contains_* boolean columns.\n",
-        "- For nutrition comparisons, use nutritional_info or brand_nutrition_summary.\n",
-        "- For \"healthy\" questions, combine is_high_protein, is_low_calorie, and calorie_category.\n",
-        "- For inspection score trends, use silver_inspections and filter by location_name + inspection_date.\n",
-        "- For urgent safety issues, filter silver_violations WHERE needs_immediate_action = true.\n",
-        "- For overall location health, use location_compliance_summary (pass_rate_pct, avg_severity_index).\n",
-        "- price_tier: budget (<$10), standard ($10-$18), premium (>$18).\n",
-        "- calorie_category: light (<300), moderate (300-600), hearty (>600).\n",
-        "- score_band: excellent (>=90), good (80-89), acceptable (70-79), failing (<70).\n",
-        "- The 16 brands span cuisines: Asian, Italian, Mexican, American, Mediterranean, Indian,\n",
-        "  Japanese, BBQ, Seafood, Breakfast, Vegan, Southern, Greek, French, Thai, Peruvian.\"\"\"\n",
-        "\n",
-        "TABLE_NAMES = sorted([\n",
-        "    # Silver\n",
-        "    f\"{CATALOG}.menu_documents.silver_menu_items\",\n",
-        "    f\"{CATALOG}.menu_documents.silver_inspections\",\n",
-        "    f\"{CATALOG}.menu_documents.silver_violations\",\n",
-        "    # Gold\n",
-        "    f\"{CATALOG}.menu_documents.menu_items\",\n",
-        "    f\"{CATALOG}.menu_documents.nutritional_info\",\n",
-        "    f\"{CATALOG}.menu_documents.allergens\",\n",
-        "    f\"{CATALOG}.menu_documents.brand_nutrition_summary\",\n",
-        "    f\"{CATALOG}.menu_documents.inspection_details\",\n",
-        "    f\"{CATALOG}.menu_documents.violation_analysis\",\n",
-        "    f\"{CATALOG}.menu_documents.location_compliance_summary\",\n",
-        "])\n",
-        "\n",
-        "serialized_space = json.dumps({\n",
-        "    \"version\": 2,\n",
-        "    \"data_sources\": {\n",
-        "        \"tables\": [{\"identifier\": t} for t in TABLE_NAMES],\n",
-        "    },\n",
-        "    \"config\": {\n",
-        "        \"sample_questions\": [\n",
-        "            {\"id\": hashlib.md5(q.encode()).hexdigest(), \"question\": [q]}\n",
-        "            for q in [\n",
-        "                \"Which menu items are gluten-free and under $15?\",\n",
-        "                \"What is the average calorie count per brand?\",\n",
-        "                \"Which locations have critical violations that need immediate action?\",\n",
-        "                \"Compare protein content across all burgers\",\n",
-        "                \"What is the latest inspection score for Chicago?\",\n",
-        "                \"Show me all premium-tier items that are also high protein\",\n",
-        "                \"Which brand has the most allergen-free options?\",\n",
-        "                \"What is the pass rate for each location?\",\n",
-        "                \"List all violations with urgency score above 5\",\n",
-        "                \"Which cuisine type has the lowest average calories?\",\n",
-        "            ]\n",
-        "        ],\n",
-        "    },\n",
-        "})\n",
-        "\n",
-        "# Check for existing Genie space in uc_state, then verify it still exists\n",
-        "genie_space_id = None\n",
-        "try:\n",
-        "    state_df = spark.sql(f\"\"\"\n",
-        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
-        "        WHERE resource_type = 'genie_spaces'\n",
-        "        ORDER BY created_at DESC LIMIT 1\n",
-        "    \"\"\")\n",
-        "    if state_df.count() > 0:\n",
-        "        genie_info = json.loads(state_df.first().resource_data)\n",
-        "        candidate_id = genie_info.get(\"space_id\")\n",
-        "        if candidate_id:\n",
-        "            try:\n",
-        "                w.genie.get_space(candidate_id)\n",
-        "                genie_space_id = candidate_id\n",
-        "                print(f\"Found existing Genie space: {genie_space_id}\")\n",
-        "            except Exception:\n",
-        "                print(f\"Genie space {candidate_id} in state but no longer exists — will recreate\")\n",
-        "except Exception:\n",
-        "    pass\n",
-        "\n",
-        "if not genie_space_id:\n",
-        "    space = w.genie.create_space(\n",
-        "        warehouse_id=warehouse.id,\n",
-        "        serialized_space=serialized_space,\n",
-        "        title=GENIE_SPACE_TITLE,\n",
-        "        description=GENIE_DESCRIPTION,\n",
-        "    )\n",
-        "    genie_space_id = space.space_id\n",
-        "    print(f\"\\u2705 Created Genie space: {genie_space_id}\")\n",
-        "\n",
-        "print(f\"   Title: {GENIE_SPACE_TITLE}\")\n",
-        "print(f\"   Tables: {TABLE_NAMES}\")\n",
-        "\n",
-        "add(CATALOG, \"genie_spaces\", {\"space_id\": genie_space_id, \"title\": GENIE_SPACE_TITLE})\n",
-        "print(\"\\u2705 Menu Genie stage complete\")"
-      ]
-    }
-  ],
-  "metadata": {
-    "kernelspec": {
-      "display_name": "Python 3",
-      "language": "python",
-      "name": "python3"
-    },
-    "language_info": {
-      "name": "python",
-      "version": "3.11.0"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 4
-}
diff --git a/stages/menu_knowledge_agent.ipynb b/stages/menu_knowledge_agent.ipynb
deleted file mode 100644
index fb6998f..0000000
--- a/stages/menu_knowledge_agent.ipynb
+++ /dev/null
@@ -1,96 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Menu Knowledge Agent\n",
-    "\n",
-    "Creates an Agent Bricks Knowledge Assistant over the restaurant menu PDFs\n",
-    "stored in the Unity Catalog volume. The Knowledge Assistant uses Databricks'\n",
-    "Instructed Retriever to answer questions with citations."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk\n",
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "ENDPOINT_NAME = dbutils.widgets.get(\"MENU_KNOWLEDGE_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk import WorkspaceClient\nimport json\n\nw = WorkspaceClient()\n\nVOLUME_PATH = f\"/Volumes/{CATALOG}/menu_documents/menus\"\nAGENT_NAME = f\"{CATALOG}-menu-knowledge\"\nAPI_BASE = \"/api/2.0/knowledge-assistants\"\n\nKA_BODY = {\n    \"name\": AGENT_NAME,\n    \"description\": (\n        \"Answers questions about Caspers Kitchens restaurant menus \"\n        \"including dishes, ingredients, nutrition, allergens, and preparation details. \"\n        \"Covers all 16 restaurant brands.\"\n    ),\n    \"endpoint_name\": ENDPOINT_NAME,\n    \"knowledge_sources\": [\n        {\n            \"files_source\": {\n                \"name\": \"menu_pdfs\",\n                \"type\": \"files\",\n                \"files\": {\"path\": VOLUME_PATH},\n                \"description\": (\n                    \"Restaurant menu PDFs for 16 ghost kitchen brands. \"\n                    \"Each PDF contains the full menu with item names, descriptions, \"\n                    \"prices, nutritional information (calories, protein, fat, carbs), \"\n                    \"and allergen warnings.\"\n                ),\n            },\n        },\n    ],\n    \"instructions\": (\n        \"You are a restaurant menu assistant for Caspers Kitchens. \"\n        \"Always cite which brand the information comes from. \"\n        \"Be specific about allergen warnings and nutritional details.\"\n    ),\n}\n\ndef get_tile_by_name(name):\n    \"\"\"Look up a tile by name from /api/2.0/tiles. Returns the tile dict or None.\"\"\"\n    resp = w.api_client.do(\"GET\", \"/api/2.0/tiles\")\n    for tile in resp.get(\"tiles\", []):\n        if tile.get(\"name\") == name:\n            return tile\n    return None\n\ndef find_existing_id():\n    \"\"\"Look up agent ID from uc_state.\"\"\"\n    try:\n        df = spark.sql(f\"\"\"\n            SELECT resource_data FROM {CATALOG}._internal_state.resources\n            WHERE resource_type IN ('knowledge_assistants', 'endpoints')\n            ORDER BY created_at DESC\n        \"\"\")\n        for row in df.collect():\n            info = json.loads(row.resource_data)\n            if info.get(\"endpoint_name\") == ENDPOINT_NAME:\n                return info.get(\"tile_id\") or info.get(\"agent_id\")\n    except Exception:\n        pass\n    return None\n\ndef try_get(agent_ref):\n    \"\"\"GET the agent by ID or name, return the response or None.\"\"\"\n    try:\n         return w.api_client.do(\"GET\", f\"{API_BASE}/knowledge-assistants/{agent_ref}\")\n    except Exception:\n        return None\n\nexisting_id = find_existing_id()\nagent_id = None\nneeds_polling = True\n\n# Path 1: found ID in uc_state — verify and update\nif existing_id:\n    info = try_get(existing_id)\n    if info:\n        print(f\"Knowledge Assistant exists ({existing_id}), updating...\")\n        w.api_client.do(\"PUT\", f\"{API_BASE}/{existing_id}\", body=KA_BODY)\n        agent_id = existing_id\n        needs_polling = False\n        print(f\"✅ Updated Knowledge Assistant: {agent_id}\")\n\n# Path 2: check by name if it already exists\nif not agent_id:\n    tile = get_tile_by_name(AGENT_NAME)\n    if tile:\n        agent_id = tile[\"tile_id\"]\n        print(f\"♻️ Knowledge Assistant already exists: {agent_id}\")\n        w.api_client.do(\"PUT\", f\"{API_BASE}/{agent_id}\", body=KA_BODY)\n        needs_polling = False\n        print(f\"✅ Updated Knowledge Assistant: {agent_id}\")\n\n# Path 3: create new\nif not agent_id:\n    try:\n        ka = w.api_client.do(\"POST\", API_BASE, body=KA_BODY)\n        print(f\"✅ Created Knowledge Assistant\")\n    except Exception as e:\n        err = str(e)\n        if \"already exists\" in err.lower() or \"ALREADY_EXISTS\" in err:\n            needs_polling = False\n            print(f\"♻️ Agent {AGENT_NAME} already exists. Proceeding.\")\n        else:\n            raise\n\n# Resolve tile_id via tiles API — POST response doesn't include it\nif not agent_id:\n    tile = get_tile_by_name(AGENT_NAME)\n    if tile:\n        agent_id = tile[\"tile_id\"]\n        print(f\"Resolved tile_id: {agent_id}\")\n    else:\n        agent_id = AGENT_NAME\n        needs_polling = False\n        print(f\"⚠️ Could not resolve tile_id, using name as fallback: {agent_id}\")\n\nprint(f\"   Agent ID (tile_id): {agent_id}\")\nprint(f\"   Endpoint: {ENDPOINT_NAME}\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import time\n",
-    "\n",
-    "if needs_polling and agent_id:\n",
-    "    MAX_WAIT = 300\n",
-    "    POLL_INTERVAL = 30\n",
-    "    elapsed = 0\n",
-    "    poll_ref = agent_id if agent_id != AGENT_NAME else AGENT_NAME\n",
-    "    print(f\"Checking if Knowledge Assistant is ready (ref={poll_ref}, max {MAX_WAIT}s)...\")\n",
-    "\n",
-    "    while elapsed < MAX_WAIT:\n",
-    "        try:\n",
-    "            ka_status = w.api_client.do(\"GET\", f\"{API_BASE}/{poll_ref}\")\n",
-    "            ep_status = ep_status = ka_status[\"knowledge_assistant\"][\"status\"].get(\"endpoint_status\", \"\")\n",
-    "            print(f\"  endpoint_status: {ep_status}\")\n",
-    "            if str(ep_status).upper() in (\"ONLINE\", \"ACTIVE\", \"READY\"):\n",
-    "                print(f\"✅ Knowledge Assistant {AGENT_NAME} is READY\")\n",
-    "                break\n",
-    "        except Exception as e:\n",
-    "            print(f\"  GET status check failed: {type(e).__name__}: {e}\")\n",
-    "\n",
-    "        time.sleep(POLL_INTERVAL)\n",
-    "        elapsed += POLL_INTERVAL\n",
-    "    else:\n",
-    "        print(f\"⏳ Endpoint may still be provisioning — proceeding.\")\n",
-    "else:\n",
-    "    print(f\"✅ Knowledge Assistant already running — skipping polling.\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import sys\nsys.path.append('../utils')\nfrom uc_state import add\n\nadd(CATALOG, \"knowledge_assistants\", {\"endpoint_name\": ENDPOINT_NAME, \"tile_id\": agent_id, \"name\": AGENT_NAME})\nprint(\"\\u2705 Menu Knowledge Agent stage complete\")"
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.11.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
\ No newline at end of file
diff --git a/stages/menu_supervisor.ipynb b/stages/menu_supervisor.ipynb
deleted file mode 100644
index 710aad6..0000000
--- a/stages/menu_supervisor.ipynb
+++ /dev/null
@@ -1,110 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Menu Multi-Agent Supervisor\n",
-    "\n",
-    "Creates an Agent Bricks Supervisor Agent that coordinates:\n",
-    "- **Genie space** - for structured data queries (nutrition stats, allergen filtering, price comparisons, inspection scores)\n",
-    "- **Menu Knowledge Assistant** - for document Q&A over the menu PDFs\n",
-    "- **Inspection Knowledge Assistant** - for document Q&A over the food safety inspection reports"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk\n",
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "KNOWLEDGE_ENDPOINT = dbutils.widgets.get(\"MENU_KNOWLEDGE_ENDPOINT_NAME\")\n",
-    "INSPECTION_ENDPOINT = dbutils.widgets.get(\"INSPECTION_KNOWLEDGE_ENDPOINT_NAME\")\n",
-    "SUPERVISOR_ENDPOINT = dbutils.widgets.get(\"MENU_SUPERVISOR_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Retrieve the Genie space ID from uc_state"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "\n",
-    "state_df = spark.sql(f\"\"\"\n",
-    "    SELECT resource_data\n",
-    "    FROM {CATALOG}._internal_state.resources\n",
-    "    WHERE resource_type = 'genie_spaces'\n",
-    "    ORDER BY created_at DESC\n",
-    "    LIMIT 1\n",
-    "\"\"\")\n",
-    "\n",
-    "if state_df.count() > 0:\n",
-    "    genie_info = json.loads(state_df.first().resource_data)\n",
-    "    GENIE_SPACE_ID = genie_info.get(\"space_id\", \"\")\n",
-    "    print(f\"Found Genie space: {GENIE_SPACE_ID}\")\n",
-    "else:\n",
-    "    raise RuntimeError(\"No Genie space found in uc_state. Ensure menu_genie stage ran first.\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Create the Supervisor Agent"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk import WorkspaceClient\nimport json\n\nw = WorkspaceClient()\n\ndef get_tile_by_name(name):\n    \"\"\"Look up a tile by name from /api/2.0/tiles. Returns the tile dict or None.\"\"\"\n    resp = w.api_client.do(\"GET\", \"/api/2.0/tiles\")\n    for tile in resp.get(\"tiles\", []):\n        if tile.get(\"name\") == name:\n            return tile\n    return None\n\ndef get_endpoint_id_by_name(endpoint_name):\n    \"\"\"Resolve a serving endpoint name to its ID via the /api/2.0/tiles listing.\"\"\"\n    tile = get_tile_by_name(endpoint_name)\n    if tile:\n        return tile[\"serving_endpoint_name\"]\n    raise RuntimeError(\n        f\"No tile found with name '{endpoint_name}'. \"\n        f\"Ensure the knowledge agent stage completed successfully.\"\n    )\n\nMENU_KA_NAME = f\"{CATALOG}-menu-knowledge\"\nINSPECTION_KA_NAME = f\"{CATALOG}-inspection-knowledge\"\n\nKNOWLEDGE_ENDPOINT_ID = get_endpoint_id_by_name(MENU_KA_NAME)\nprint(f\"Resolved menu knowledge endpoint: {MENU_KA_NAME} -> {KNOWLEDGE_ENDPOINT_ID}\")\n\nINSPECTION_ENDPOINT_ID = get_endpoint_id_by_name(INSPECTION_KA_NAME)\nprint(f\"Resolved inspection knowledge endpoint: {INSPECTION_KA_NAME} -> {INSPECTION_ENDPOINT_ID}\")\n\nAGENT_NAME = f\"{CATALOG}-menu-supervisor\"\nAPI_BASE = \"/api/2.0/multi-agent-supervisors\"\n\nSUPERVISOR_BODY = {\n    \"name\": AGENT_NAME,\n    \"description\": (\n        \"Caspers Kitchens assistant that coordinates structured data queries, \"\n        \"menu document search, and food safety compliance across 16 restaurant brands \"\n        \"and 4 ghost kitchen locations. Routes analytics to the Genie space, menu \"\n        \"questions to the Menu Knowledge Assistant, and safety/compliance questions \"\n        \"to the Inspection Knowledge Assistant.\"\n    ),\n    \"endpoint_name\": SUPERVISOR_ENDPOINT,\n    \"agents\": [\n        {\n            \"agent_type\": \"genie\",\n            \"genie_space\": {\"id\": GENIE_SPACE_ID},\n            \"name\": \"menu-safety-analytics\",\n            \"description\": (\n                \"Queries the structured database for nutrition stats, allergen \"\n                \"filtering, price comparisons, brand-level analytics, inspection \"\n                \"scores, violation counts, and compliance summaries. Use for \"\n                \"questions that need numbers, counts, comparisons, or filtering.\"\n            ),\n        },\n        {\n            \"agent_type\": \"ka\",\n            \"serving_endpoint\": {\"name\": KNOWLEDGE_ENDPOINT_ID},\n            \"name\": \"menu-document-search\",\n            \"description\": (\n                \"Searches the original restaurant menu PDF documents for dish \"\n                \"descriptions, preparation details, ingredient information, and \"\n                \"specific menu content. Use for questions about what's on a menu \"\n                \"or details about specific dishes.\"\n            ),\n        },\n        {\n            \"agent_type\": \"ka\",\n            \"serving_endpoint\": {\"name\": INSPECTION_ENDPOINT_ID},\n            \"name\": \"inspection-report-search\",\n            \"description\": (\n                \"Searches food safety inspection report PDFs for violation details, \"\n                \"corrective actions, inspector findings, and compliance status. \"\n                \"Use for questions about health inspections, violations, food safety \"\n                \"compliance, and corrective action deadlines at specific locations.\"\n            ),\n        },\n    ],\n    \"instructions\": (\n        \"You are a helpful assistant for Caspers Kitchens covering menus and food safety. \"\n        \"Always cite which brand or location the information comes from. \"\n        \"Be specific about allergen warnings, nutritional details, and violation severities. \"\n        \"Use Menu & Safety Analytics for structured queries (counts, averages, filtering), \"\n        \"Menu Document Search for descriptive questions about dishes, and \"\n        \"Inspection Report Search for food safety and compliance questions.\"\n    ),\n}\n\ndef find_existing_id():\n    \"\"\"Look up supervisor ID from uc_state.\"\"\"\n    try:\n        df = spark.sql(f\"\"\"\n            SELECT resource_data FROM {CATALOG}._internal_state.resources\n            WHERE resource_type IN ('multi_agent_supervisors', 'endpoints')\n            ORDER BY created_at DESC\n        \"\"\")\n        for row in df.collect():\n            info = json.loads(row.resource_data)\n            if info.get(\"endpoint_name\") == SUPERVISOR_ENDPOINT:\n                return info.get(\"tile_id\") or info.get(\"agent_id\")\n    except Exception:\n        pass\n    return None\n\ndef try_get(agent_ref):\n    \"\"\"GET the supervisor by ID or name, return the response or None.\"\"\"\n    try:\n        return w.api_client.do(\"GET\", f\"{API_BASE}/{agent_ref}\")\n    except Exception:\n        return None\n\nexisting_id = find_existing_id()\nagent_id = None\nneeds_polling = True\n\n# Path 1: found ID in uc_state — verify and update\nif existing_id:\n    info = try_get(existing_id)\n    if info:\n        print(f\"Supervisor exists ({existing_id}), updating...\")\n        w.api_client.do(\"PUT\", f\"{API_BASE}/{existing_id}\", body=SUPERVISOR_BODY)\n        agent_id = existing_id\n        needs_polling = False\n        print(f\"\\u2705 Updated Supervisor Agent: {agent_id}\")\n\n# Path 2: no ID in state (or GET failed) — try to create\nif not agent_id:\n    try:\n        supervisor = w.api_client.do(\"POST\", API_BASE, body=SUPERVISOR_BODY)\n        print(f\"POST response keys: {list(supervisor.keys())}\")\n        print(f\"\\u2705 Created Supervisor Agent\")\n    except Exception as e:\n        err = str(e)\n        if \"already exists\" in err.lower() or \"ALREADY_EXISTS\" in err:\n            print(f\"\\u267b\\ufe0f Supervisor {AGENT_NAME} already exists. Proceeding.\")\n        else:\n            raise\n\n# Resolve tile_id via tiles API — POST response doesn't include it\ntile = get_tile_by_name(AGENT_NAME)\nif tile:\n    agent_id = tile[\"tile_id\"]\n    print(f\"Resolved tile_id: {agent_id}\")\nelse:\n    agent_id = AGENT_NAME\n    needs_polling = False\n    print(f\"\\u26a0\\ufe0f Could not resolve tile_id, using name as fallback: {agent_id}\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import time\n\nif needs_polling:\n    if not agent_id:\n        print(f\"⚠️ No agent_id available — skipping polling. Check POST response above.\")\n    else:\n        MAX_WAIT = 300\n        POLL_INTERVAL = 30\n        elapsed = 0\n        print(f\"Checking if Supervisor endpoint is ready (agent_id={agent_id}, max {MAX_WAIT}s)...\")\n\n        while elapsed < MAX_WAIT:\n            try:\n                sup_status = w.api_client.do(\"GET\", f\"{API_BASE}/{agent_id}\")\n                inner = sup_status.get(\"multi_agent_supervisor\", sup_status)\n                ep_status = inner.get(\"status\", {}).get(\"endpoint_status\", \"\") if isinstance(inner.get(\"status\"), dict) else inner.get(\"endpoint_status\", \"\")\n                print(f\"  endpoint_status: {ep_status}\")\n                if str(ep_status).upper() in (\"ACTIVE\", \"READY\", \"ONLINE\"):\n                    print(f\"\\u2705 Supervisor {AGENT_NAME} is READY\")\n                    break\n            except Exception as e:\n                print(f\"  GET status check failed: {type(e).__name__}: {e}\")\n\n            time.sleep(POLL_INTERVAL)\n            elapsed += POLL_INTERVAL\n        else:\n            print(f\"\\u2705 Endpoint may still be provisioning — proceeding.\")\nelse:\n    print(f\"\\u2705 Supervisor already running — skipping polling.\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import sys\nsys.path.append('../utils')\nfrom uc_state import add\n\nadd(CATALOG, \"multi_agent_supervisors\", {\"endpoint_name\": SUPERVISOR_ENDPOINT, \"tile_id\": agent_id, \"name\": AGENT_NAME})\nprint(\"\\u2705 Menu Supervisor stage complete\")"
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3.11.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
\ No newline at end of file
diff --git a/stages/operational_app.ipynb b/stages/operational_app.ipynb
new file mode 100644
index 0000000..2146355
--- /dev/null
+++ b/stages/operational_app.ipynb
@@ -0,0 +1,926 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Operational Dashboard App\n",
+        "\n",
+        "Deploys the Casper's Operational Dashboard Databricks App. Grants SQL warehouse access, wires the\n",
+        "Lakebase database resource, and deploys the FastAPI app from apps/caspers-ops-dashboard/."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "# Shared Lakebase Autoscaling project provisioned by stages/lakebase_project.ipynb.\n",
+        "# The Operational Dashboard app reads/writes the `caspers_ops` database\n",
+        "# within this project; see stages/operational_lakebase.ipynb for the\n",
+        "# sessions/messages table DDL.\n",
+        "OPS_PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "OPS_ENDPOINT_PATH = f\"projects/{OPS_PROJECT_ID}/branches/production/endpoints/primary\"\n",
+        "# Lakebase Autoscale requires DNS-safe names (no underscores).\n",
+        "OPS_DATABASE_NAME = \"caspers-ops\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import sys, os\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.apps import (\n",
+        "    App, AppResource, AppResourceSqlWarehouse,\n",
+        "    AppResourceSqlWarehouseSqlWarehousePermission,\n",
+        "    AppDeployment,\n",
+        ")\n",
+        "from databricks.sdk.service import catalog as catalog_svc\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "# Find the ops warehouse.  DABs owns this resource — it's defined under\n",
+        "# `resources.sql_warehouses.caspers_ops_warehouse` in databricks.yml and\n",
+        "# created by `bundle deploy -t all`.  This stage is now find-only: if the\n",
+        "# warehouse is missing, deploy hasn't been run (or the resource was removed).\n",
+        "# Cleanup is also DABs-owned (`bundle destroy -t all`), so we no longer\n",
+        "# register the warehouse with uc_state to avoid double-delete.\n",
+        "#\n",
+        "# IMPORTANT — read the name from the OPS_WAREHOUSE_NAME job parameter, not\n",
+        "# from f\"{CATALOG}-ops-warehouse\".  The warehouse is DABs-managed, so its\n",
+        "# name is frozen at DEPLOY time using `${var.catalog}-ops-warehouse`.  The\n",
+        "# CATALOG job parameter is overridable at RUN time via `--params CATALOG=...`,\n",
+        "# which means reconstructing the name from CATALOG breaks the moment\n",
+        "# `--var catalog` (deploy) and `--params CATALOG` (run) disagree — the\n",
+        "# stage would look for `<run-catalog>-ops-warehouse` while DABs created\n",
+        "# `<deploy-catalog>-ops-warehouse`.  OPS_WAREHOUSE_NAME is declared in\n",
+        "# databricks.yml with a `${var.catalog}-ops-warehouse` default that is\n",
+        "# resolved at deploy time and baked into the job parameter, so the run-time\n",
+        "# value always matches what DABs actually created.  Same pattern as the\n",
+        "# REFUND_AGENT_ENDPOINT_NAME / COMPLAINT_AGENT_ENDPOINT_NAME widgets used\n",
+        "# in cell 8 below — see the long comment there for the full rationale.\n",
+        "try:\n",
+        "    WAREHOUSE_NAME = dbutils.widgets.get(\"OPS_WAREHOUSE_NAME\")\n",
+        "except Exception:\n",
+        "    WAREHOUSE_NAME = \"\"\n",
+        "if not WAREHOUSE_NAME:\n",
+        "    WAREHOUSE_NAME = f\"{CATALOG}-ops-warehouse\"\n",
+        "existing_wh = [wh for wh in w.warehouses.list() if wh.name == WAREHOUSE_NAME]\n",
+        "if not existing_wh:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Warehouse '{WAREHOUSE_NAME}' not found.  It is created by \"\n",
+        "        f\"`databricks bundle deploy -t all --var catalog=<name>` as the \"\n",
+        "        f\"`caspers_ops_warehouse` DABs resource.\\n\"\n",
+        "        f\"  • If you have not deployed yet, run \"\n",
+        "        f\"`databricks bundle deploy -t all --var catalog=<name>`.\\n\"\n",
+        "        f\"  • If you have deployed, `--var catalog` at deploy time did not \"\n",
+        "        f\"match the OPS_WAREHOUSE_NAME job parameter currently in use \"\n",
+        "        f\"('{WAREHOUSE_NAME}').  Either redeploy with a matching \"\n",
+        "        f\"`--var catalog`, or override `--params OPS_WAREHOUSE_NAME=...` \"\n",
+        "        f\"to point at an existing warehouse.\"\n",
+        "    )\n",
+        "warehouse = existing_wh[0]\n",
+        "print(f\"\\u267b\\ufe0f Using DABs-managed warehouse: {warehouse.id} ({WAREHOUSE_NAME})\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "source_code_path = os.path.abspath(\"../apps/caspers-ops-dashboard\")\n",
+        "\n",
+        "# P1-18: catalog-scope the app name so two users on the same workspace don't\n",
+        "# fight over the global `caspers-ops-dashboard` slug.  Use the shorter\n",
+        "# `ops-dashboard-` prefix to keep the full name under the 30-char Databricks\n",
+        "# Apps limit even for long catalog names.\n",
+        "import re as _re\n",
+        "APP_NAME = _re.sub(r\"-+\", \"-\", _re.sub(r\"[^a-z0-9-]\", \"-\", f\"ops-dashboard-{CATALOG}\".lower())).strip(\"-\")[:30]\n",
+        "print(f\"App name: {APP_NAME}\")\n",
+        "\n",
+        "# Lakebase Autoscale does not support AppResourceDatabase — the app connects\n",
+        "# directly using w.postgres.generate_database_credential() with the endpoint path.\n",
+        "APP_DESCRIPTION = (\n",
+        "    \"Casper's Ops Intelligence — chat with the Multi-Agent Supervisor \"\n",
+        "    \"across revenue, ops, food safety, legal & regulatory; review live \"\n",
+        "    \"complaint decisions and trigger refunds inline.\"\n",
+        ")\n",
+        "app_def = App(\n",
+        "    name=APP_NAME,\n",
+        "    description=APP_DESCRIPTION,\n",
+        "    default_source_code_path=source_code_path,\n",
+        "    resources=[\n",
+        "        AppResource(\n",
+        "            name=\"sql-warehouse\",\n",
+        "            sql_warehouse=AppResourceSqlWarehouse(\n",
+        "                id=warehouse.id,\n",
+        "                permission=AppResourceSqlWarehouseSqlWarehousePermission.CAN_USE,\n",
+        "            ),\n",
+        "        ),\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "import time\n",
+        "\n",
+        "try:\n",
+        "    existing_app = w.apps.get(APP_NAME)\n",
+        "    print(f\"\\u267b\\ufe0f App {APP_NAME} exists, updating...\")\n",
+        "    w.apps.update(APP_NAME, app_def)\n",
+        "except Exception:\n",
+        "    w.apps.create(app_def)\n",
+        "\n",
+        "def _app_state(a):\n",
+        "    cs = getattr(a, \"compute_status\", None)\n",
+        "    s = getattr(cs, \"state\", None) if cs is not None else None\n",
+        "    if s is None:\n",
+        "        s = getattr(a, \"state\", None)\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current = w.apps.get(APP_NAME)\n",
+        "    state = _app_state(current)\n",
+        "    print(f\"App {APP_NAME} state: {state}\")\n",
+        "    if state in (\"ACTIVE\", \"RUNNING\", \"READY\"):\n",
+        "        app_status = current\n",
+        "        break\n",
+        "    if state in (\"ERROR\", \"FAILED\"):\n",
+        "        raise RuntimeError(f\"App {APP_NAME} entered failure state: {state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"App {APP_NAME} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(15)\n",
+        "\n",
+        "add(CATALOG, \"apps\", app_status)\n",
+        "print(f\"\\u2705 App {APP_NAME} ready\")\n",
+        "\n",
+        "# Resolve SP ID immediately — used in all subsequent permission cells.\n",
+        "# service_principal_client_id is the documented OAuth UUID field.\n",
+        "app_sp_id = (\n",
+        "    getattr(app_status, 'service_principal_client_id', None)\n",
+        "    or (app_status.as_dict() if hasattr(app_status, 'as_dict') else {}).get('service_principal_client_id')\n",
+        "    or (app_status.as_dict() if hasattr(app_status, 'as_dict') else {}).get('id')\n",
+        ")\n",
+        "assert app_sp_id, \"Could not determine app service principal ID\"\n",
+        "print(f\"\\U0001f511 App SP ID: {app_sp_id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Upload the app thumbnail.  Best-effort: purely visual polish for the\n",
+        "# Discover / Workspace card and the app launcher icon, so we never let a\n",
+        "# missing API surface fail the whole stage.\n",
+        "#\n",
+        "# Runtime requirement: databricks-sdk >= 0.83 (has w.apps.update_app_thumbnail).\n",
+        "# Thumbnail source: utils/casperslogo_green.png (synced by DABs).\n",
+        "import base64, os\n",
+        "\n",
+        "try:\n",
+        "    from databricks.sdk.service.apps import AppThumbnail\n",
+        "\n",
+        "    if not hasattr(w.apps, \"update_app_thumbnail\"):\n",
+        "        print(\"\\u26a0\\ufe0f  w.apps.update_app_thumbnail not available \"\n",
+        "              \"(databricks-sdk too old) \\u2014 skipping thumbnail upload.\")\n",
+        "    else:\n",
+        "        thumb_path = os.path.abspath(\"../utils/casperslogo_green.png\")\n",
+        "        with open(thumb_path, \"rb\") as _f:\n",
+        "            thumb_b64 = base64.b64encode(_f.read()).decode(\"ascii\")\n",
+        "        w.apps.update_app_thumbnail(\n",
+        "            APP_NAME,\n",
+        "            app_thumbnail=AppThumbnail(thumbnail=thumb_b64),\n",
+        "        )\n",
+        "        print(f\"\\U0001f5bc\\ufe0f  Uploaded thumbnail for {APP_NAME}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f  Could not upload thumbnail for {APP_NAME}: {e}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Pre-create the complaints schema and complaint_responses table so the SELECT\n",
+        "# grant below always lands. Without this, Operational_App races with\n",
+        "# Complaint_Agent_Stream (they have no depends_on relationship in databricks.yml,\n",
+        "# and the Complaint_Agent_Stream stage only kicks off a cron job and exits — the\n",
+        "# job is what actually creates the schema/table on first run). When grants run\n",
+        "# before the table exists, the per-grant try/except swallows the failure and the\n",
+        "# Ops App's /api/complaint-decisions endpoint then fails with INSUFFICIENT_PERMISSIONS\n",
+        "# even after the cron eventually populates the table.\n",
+        "# DDL mirrors jobs/complaint_agent_stream.ipynb and is idempotent (IF NOT EXISTS),\n",
+        "# so it's safe to race with the streaming job.\n",
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.complaints\")\n",
+        "spark.sql(f\"\"\"\n",
+        "    CREATE TABLE IF NOT EXISTS {CATALOG}.complaints.complaint_responses (\n",
+        "        complaint_id STRING,\n",
+        "        order_id STRING,\n",
+        "        ts TIMESTAMP,\n",
+        "        agent_response STRING\n",
+        "    )\n",
+        "\"\"\")\n",
+        "\n",
+        "# Grant app permissions to relevant UC resources\n",
+        "for full_name, securable_type, privilege in [\n",
+        "    (CATALOG, \"CATALOG\", catalog_svc.Privilege.USE_CATALOG),\n",
+        "    # `ai` schema holds the UC tool functions (`get_order_details`, etc.) that\n",
+        "    # the refund / complaint / support / supervisor agents call.  The agent\n",
+        "    # endpoints are deployed with the OBO pattern, so when this app invokes a\n",
+        "    # supervisor or sub-agent endpoint, the app SP's identity propagates all\n",
+        "    # the way down to the UC function call.  Without USE_SCHEMA + EXECUTE on\n",
+        "    # `ai` for the app SP, the agent surfaces a PermissionError(\"EXECUTE on\n",
+        "    # Routine '<catalog>.ai.get_order_details'\") on the very first tool call.\n",
+        "    # The `account users` grant the refunder_agent stage applies does NOT\n",
+        "    # cover app SPs — workspace-local app SPs are not members of\n",
+        "    # `account users` (an account-level group), which is the regression that\n",
+        "    # broke this stage on 2026-06-08.\n",
+        "    (f\"{CATALOG}.ai\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.ai\", \"SCHEMA\", catalog_svc.Privilege.EXECUTE),\n",
+        "    (f\"{CATALOG}.lakeflow\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    # all_events raw table\n",
+        "    (f\"{CATALOG}.lakeflow.all_events\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    # Gold/silver tables queried by Genie revenue & ops spaces\n",
+        "    (f\"{CATALOG}.lakeflow.gold_brand_sales_day\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_location_sales_hourly\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    # Materialized view backing the ops dashboard cancel-rate widget\n",
+        "    # (see /api/revenue in apps/caspers-ops-dashboard).  Without this\n",
+        "    # explicit grant the MV defaults to owner-only access — schema-level\n",
+        "    # USE_SCHEMA does NOT cascade SELECT to MVs in UC the way it does to\n",
+        "    # regular tables, so /api/revenue 503s on the very first page load.\n",
+        "    (f\"{CATALOG}.lakeflow.gold_location_order_status_daily\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.lakeflow.gold_order_header\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.lakeflow.silver_order_items\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.simulator\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    # Simulator dimension tables queried by Genie spaces\n",
+        "    (f\"{CATALOG}.simulator.brand_locations\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.simulator.brands\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.simulator.items\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.simulator.locations\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.food_safety\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.food_safety.inspections\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    (f\"{CATALOG}.food_safety.violations\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "    # Document schemas — needed so the app can list PDFs from UC volumes\n",
+        "    (f\"{CATALOG}.legal_complaints\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.regulatory\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.audits\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.consultancy\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.legal_complaints\", \"SCHEMA\", catalog_svc.Privilege.READ_VOLUME),\n",
+        "    (f\"{CATALOG}.regulatory\", \"SCHEMA\", catalog_svc.Privilege.READ_VOLUME),\n",
+        "    (f\"{CATALOG}.audits\", \"SCHEMA\", catalog_svc.Privilege.READ_VOLUME),\n",
+        "    (f\"{CATALOG}.consultancy\", \"SCHEMA\", catalog_svc.Privilege.READ_VOLUME),\n",
+        "    # food_safety has /Volumes/{CATALOG}/food_safety/reports referenced from the app\n",
+        "    (f\"{CATALOG}.food_safety\", \"SCHEMA\", catalog_svc.Privilege.READ_VOLUME),\n",
+        "    # complaints schema — queried by /api/complaint-decisions in the app\n",
+        "    (f\"{CATALOG}.complaints\", \"SCHEMA\", catalog_svc.Privilege.USE_SCHEMA),\n",
+        "    (f\"{CATALOG}.complaints.complaint_responses\", \"TABLE\", catalog_svc.Privilege.SELECT),\n",
+        "]:\n",
+        "    try:\n",
+        "        w.grants.update(\n",
+        "            full_name=full_name,\n",
+        "            securable_type=securable_type,\n",
+        "            changes=[\n",
+        "                catalog_svc.PermissionsChange(\n",
+        "                    add=[privilege],\n",
+        "                    principal=app_sp_id,\n",
+        "                )\n",
+        "            ],\n",
+        "        )\n",
+        "        print(f\"\\u2705 Granted {privilege} on {full_name}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"\\u26a0\\ufe0f Could not grant {privilege} on {full_name}: {e}\")\n",
+        "\n",
+        "# ── Grant CAN_USE on the Genie warehouse to the app SP ──────────────────────\n",
+        "# Genie sub-agents called via the supervisor execute SQL on the warehouse\n",
+        "# created by stages/genie_spaces.ipynb (`{CATALOG}-genie-warehouse`). Without\n",
+        "# CAN_USE the warehouse refuses the query and the supervisor LLM surfaces it\n",
+        "# as \"permissions issue accessing the revenue analytics system\".\n",
+        "try:\n",
+        "    genie_wh_name = f\"{CATALOG}-genie-warehouse\"\n",
+        "    genie_wh = next((wh for wh in w.warehouses.list() if wh.name == genie_wh_name), None)\n",
+        "    if genie_wh is None:\n",
+        "        print(f\"\\u26a0\\ufe0f Genie warehouse '{genie_wh_name}' not found — skipping CAN_USE grant\")\n",
+        "    else:\n",
+        "        w.api_client.do(\n",
+        "            \"PATCH\",\n",
+        "            f\"/api/2.0/permissions/warehouses/{genie_wh.id}\",\n",
+        "            body={\"access_control_list\": [\n",
+        "                {\"service_principal_name\": app_sp_id, \"permission_level\": \"CAN_USE\"}\n",
+        "            ]},\n",
+        "        )\n",
+        "        print(f\"\\u2705 Granted CAN_USE on Genie warehouse {genie_wh_name} ({genie_wh.id})\")\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f Could not grant CAN_USE on Genie warehouse: {e}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json, time\n",
+        "from databricks.sdk.service.serving import (\n",
+        "    ServingEndpointAccessControlRequest,\n",
+        "    ServingEndpointPermissionLevel,\n",
+        ")\n",
+        "\n",
+        "def _grant_can_query(endpoint_id: str, endpoint_name: str, sp_id: str, retries: int = 3) -> bool:\n",
+        "    \"\"\"Grant CAN_QUERY on a serving endpoint.\n",
+        "    endpoint_id  — the UUID returned by the list API (required by update_permissions)\n",
+        "    endpoint_name — human-readable name used only for logging\n",
+        "    \"\"\"\n",
+        "    for attempt in range(retries):\n",
+        "        try:\n",
+        "            w.serving_endpoints.update_permissions(\n",
+        "                serving_endpoint_id=endpoint_id,   # must be UUID, not name\n",
+        "                access_control_list=[\n",
+        "                    ServingEndpointAccessControlRequest(\n",
+        "                        service_principal_name=sp_id,\n",
+        "                        permission_level=ServingEndpointPermissionLevel.CAN_QUERY,\n",
+        "                    )\n",
+        "                ],\n",
+        "            )\n",
+        "            print(f\"\\u2705 Granted CAN_QUERY on {endpoint_name} ({endpoint_id})\")\n",
+        "            return True\n",
+        "        except Exception as e:\n",
+        "            if attempt < retries - 1:\n",
+        "                print(f\"  Retry {attempt+1}/{retries} for {endpoint_name}: {e}\")\n",
+        "                time.sleep(5 * (attempt + 1))\n",
+        "            else:\n",
+        "                print(f\"\\u274c FAILED to grant CAN_QUERY on {endpoint_name}: {e}\")\n",
+        "                return False\n",
+        "\n",
+        "# Markers in error messages that indicate the Genie space no longer exists\n",
+        "# or the current identity has no permission to grant on it. These are almost\n",
+        "# always stale uc_state rows from previous deploys (the space was deleted, or\n",
+        "# created under a different identity that no longer owns it). We warn + skip\n",
+        "# rather than failing the whole stage.\n",
+        "_GENIE_ORPHAN_MARKERS = (\n",
+        "    \"RESOURCE_DOES_NOT_EXIST\",\n",
+        "    \"NOT_FOUND\",\n",
+        "    \" 404\",\n",
+        "    \"PERMISSION_DENIED\",\n",
+        "    \" 403\",\n",
+        "    \"does not exist\",\n",
+        "    \"cannot be found\",\n",
+        ")\n",
+        "\n",
+        "def _grant_can_run_genie(space_id: str, sp_id: str, retries: int = 3) -> str:\n",
+        "    \"\"\"Grant CAN_RUN on a Genie space.\n",
+        "    Returns one of: 'ok', 'orphan' (skip), 'failed' (real failure).\n",
+        "    \"\"\"\n",
+        "    for attempt in range(retries):\n",
+        "        try:\n",
+        "            w.api_client.do(\n",
+        "                \"PATCH\",\n",
+        "                f\"/api/2.0/permissions/genie/{space_id}\",\n",
+        "                body={\"access_control_list\": [\n",
+        "                    {\"service_principal_name\": sp_id, \"permission_level\": \"CAN_RUN\"}\n",
+        "                ]},\n",
+        "            )\n",
+        "            print(f\"\\u2705 Granted CAN_RUN on Genie space {space_id} to {sp_id}\")\n",
+        "            return \"ok\"\n",
+        "        except Exception as e:\n",
+        "            msg = str(e)\n",
+        "            if any(marker in msg for marker in _GENIE_ORPHAN_MARKERS):\n",
+        "                first_line = msg.splitlines()[0] if msg else \"\"\n",
+        "                print(f\"\\u26a0\\ufe0f  Skipping orphan Genie space {space_id} (stale uc_state row): {first_line}\")\n",
+        "                return \"orphan\"\n",
+        "            if attempt < retries - 1:\n",
+        "                print(f\"  Retry {attempt+1}/{retries} for Genie space {space_id}: {e}\")\n",
+        "                time.sleep(5 * (attempt + 1))\n",
+        "            else:\n",
+        "                print(f\"\\u274c FAILED to grant CAN_RUN on Genie space {space_id}: {e}\")\n",
+        "                return \"failed\"\n",
+        "\n",
+        "# ── Resolve endpoints + Genie spaces created BY THIS CATALOG from uc_state ────\n",
+        "# P1-16: previously this cell scanned every mas-*/ka-* endpoint and every Genie\n",
+        "# space in the workspace and granted to the app SP.  Two pain points:\n",
+        "#   1. Cross-tenant blast radius — a colleague's `mas-xxxxxxxx-endpoint` in the\n",
+        "#      same workspace would silently get our app SP granted CAN_QUERY.\n",
+        "#   2. The grant list grew unboundedly with every catalog deployed, so\n",
+        "#      runtime got slower and quota errors started surfacing.\n",
+        "# uc_state stores the resources the current catalog's stages created — scope\n",
+        "# the grants to that set only.\n",
+        "import json as _json\n",
+        "\n",
+        "def _uc_state_rows(resource_type):\n",
+        "    try:\n",
+        "        rows = spark.sql(f\"\"\"\n",
+        "            SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "            WHERE resource_type = '{resource_type}'\n",
+        "            ORDER BY created_at DESC\n",
+        "        \"\"\").collect()\n",
+        "        return [_json.loads(r.resource_data) for r in rows]\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️  uc_state lookup failed for {resource_type}: {e}\")\n",
+        "        return []\n",
+        "\n",
+        "# Build the set of endpoint names this catalog owns.\n",
+        "# - multi_agent_supervisors: row has `endpoint_name`\n",
+        "# - knowledge_assistants:    row has `tile_id` → endpoint name is `ka-{tile_id[:8]}-endpoint`\n",
+        "owned_endpoint_names = set()\n",
+        "for row in _uc_state_rows(\"multi_agent_supervisors\"):\n",
+        "    n = row.get(\"endpoint_name\")\n",
+        "    if n:\n",
+        "        owned_endpoint_names.add(n)\n",
+        "for row in _uc_state_rows(\"knowledge_assistants\"):\n",
+        "    tile_id = row.get(\"tile_id\") or \"\"\n",
+        "    if tile_id:\n",
+        "        owned_endpoint_names.add(f\"ka-{tile_id[:8]}-endpoint\")\n",
+        "# Custom agents deployed via agents.deploy() — endpoint names come from the\n",
+        "# REFUND_AGENT_ENDPOINT_NAME / COMPLAINT_AGENT_ENDPOINT_NAME job parameters\n",
+        "# (declared on the `all` target in databricks.yml), with a `${var.catalog}`\n",
+        "# default that's resolved at deploy time.  Falling back to f\"{CATALOG}_...\"\n",
+        "# only when the widget is missing or empty matches the legacy behaviour.\n",
+        "#\n",
+        "# Reading from the widget rather than reconstructing from CATALOG matters\n",
+        "# because `--var catalog` (deploy-time, controls REFUND_AGENT_ENDPOINT_NAME's\n",
+        "# baked-in default) and `--params CATALOG=...` (runtime) can disagree.  Under\n",
+        "# that drift, the agent stages create endpoints with the deploy-time-baked\n",
+        "# name (e.g. `caspersdev_refund_agent`) while this stage's f\"{CATALOG}_...\"\n",
+        "# would look for `dais2026_refund_agent` and 404 — the symptom we hit\n",
+        "# before this fix went in.\n",
+        "def _agent_ep_name(widget_name: str, default_name: str) -> str:\n",
+        "    try:\n",
+        "        v = dbutils.widgets.get(widget_name)\n",
+        "    except Exception:\n",
+        "        v = \"\"\n",
+        "    return v or default_name\n",
+        "\n",
+        "for ep in [\n",
+        "    _agent_ep_name(\"REFUND_AGENT_ENDPOINT_NAME\",    f\"{CATALOG}_refund_agent\"),\n",
+        "    _agent_ep_name(\"COMPLAINT_AGENT_ENDPOINT_NAME\", f\"{CATALOG}_complaint_agent\"),\n",
+        "]:\n",
+        "    owned_endpoint_names.add(ep)\n",
+        "\n",
+        "# Build the set of Genie spaces this catalog owns (`space_id`).\n",
+        "# uc_state may contain stale rows from prior deploys: the `genie_spaces` stage\n",
+        "# is non-idempotent and creates a fresh trio of spaces on every run, so the\n",
+        "# table can accumulate many distinct space_ids that share the same title.\n",
+        "# Granting on all of them triggers RuntimeError on the orphans. Dedupe by\n",
+        "# title and keep only the most-recent space_id per title (rows come from\n",
+        "# `_uc_state_rows` already ordered by created_at DESC).\n",
+        "owned_space_ids = set()\n",
+        "_seen_titles = set()\n",
+        "_stale_space_count = 0\n",
+        "for row in _uc_state_rows(\"genie_spaces\"):\n",
+        "    sid = row.get(\"space_id\")\n",
+        "    if not sid:\n",
+        "        continue\n",
+        "    title = row.get(\"title\") or sid  # fall back to id if title missing\n",
+        "    if title in _seen_titles:\n",
+        "        _stale_space_count += 1\n",
+        "        continue\n",
+        "    _seen_titles.add(title)\n",
+        "    owned_space_ids.add(sid)\n",
+        "if _stale_space_count:\n",
+        "    print(\n",
+        "        f\"\\u26a0\\ufe0f  uc_state has {_stale_space_count} stale genie_spaces rows \"\n",
+        "        f\"(older space_ids for the same titles); ignoring and granting only on \"\n",
+        "        f\"the {len(owned_space_ids)} most-recent space(s) per title.\"\n",
+        "    )\n",
+        "\n",
+        "print(f\"uc_state: {len(owned_endpoint_names)} owned endpoints, {len(owned_space_ids)} owned Genie spaces\")\n",
+        "\n",
+        "# ── Grant CAN_QUERY on owned mas-*/ka-* serving endpoints ─────────────────────\n",
+        "# IMPORTANT: update_permissions requires the endpoint UUID (ep.id), not the name.\n",
+        "# We still call w.serving_endpoints.list() because the permissions API needs\n",
+        "# the UUID, but we filter to only the names we own.\n",
+        "ep_failures = []\n",
+        "all_eps = list(w.serving_endpoints.list())\n",
+        "target_eps = [ep for ep in all_eps if (ep.name or \"\") in owned_endpoint_names]\n",
+        "# Warn if uc_state references an endpoint that doesn't exist in the workspace\n",
+        "# (catches drift between uc_state and reality, e.g. someone deleted an endpoint).\n",
+        "missing = owned_endpoint_names - {ep.name for ep in target_eps}\n",
+        "if missing:\n",
+        "    print(f\"⚠️  uc_state lists endpoints not present in workspace (skipping): {sorted(missing)}\")\n",
+        "print(f\"Granting CAN_QUERY on {len(target_eps)} owned endpoints\")\n",
+        "for ep in target_eps:\n",
+        "    ok = _grant_can_query(ep.id, ep.name, app_sp_id)\n",
+        "    if not ok:\n",
+        "        ep_failures.append(ep.name)\n",
+        "\n",
+        "# ── Grant CAN_RUN on owned Genie spaces ───────────────────────────────────────\n",
+        "genie_failures = []\n",
+        "genie_orphans  = []\n",
+        "print(f\"Granting CAN_RUN on {len(owned_space_ids)} owned Genie spaces\")\n",
+        "for space_id in owned_space_ids:\n",
+        "    result = _grant_can_run_genie(space_id, app_sp_id)\n",
+        "    if result == \"failed\":\n",
+        "        genie_failures.append(space_id)\n",
+        "    elif result == \"orphan\":\n",
+        "        genie_orphans.append(space_id)\n",
+        "if genie_orphans:\n",
+        "    print(\n",
+        "        f\"\\u26a0\\ufe0f  Skipped {len(genie_orphans)} orphan Genie space(s) from uc_state \"\n",
+        "        f\"(deleted or owned by another identity): {genie_orphans}\"\n",
+        "    )\n",
+        "\n",
+        "# ── Fail loudly if any grants didn't land ─────────────────────────────────────\n",
+        "# Only real failures count — orphans are treated as warnings (stale uc_state).\n",
+        "if ep_failures or genie_failures:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Permission grants failed!\\n\"\n",
+        "        f\"  Endpoints: {ep_failures}\\n\"\n",
+        "        f\"  Genie spaces: {genie_failures}\\n\"\n",
+        "        \"Fix the errors above and re-run this cell.\"\n",
+        "    )\n",
+        "print(\"\\n\\u2705 All endpoint and Genie space permissions granted successfully\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Grant DATABRICKS_SUPERUSER to the app service principal in the Lakebase Autoscale project.\n",
+        "# This allows the app to connect and create tables on first startup.\n",
+        "try:\n",
+        "    from databricks.sdk.service.postgres import Role, RoleRoleSpec, RoleMembershipRole, RoleIdentityType\n",
+        "    from databricks.sdk.common.types.fieldmask import FieldMask\n",
+        "\n",
+        "    production_branch = f\"projects/{OPS_PROJECT_ID}/branches/production\"\n",
+        "    app_principal = app_sp_id  # resolved service principal client ID\n",
+        "\n",
+        "    # Find or create a role for the app SP\n",
+        "    existing_roles = list(w.postgres.list_roles(production_branch))\n",
+        "    app_role = next(\n",
+        "        (r for r in existing_roles if getattr(r.spec, \"postgres_role\", None) == app_principal),\n",
+        "        None,\n",
+        "    )\n",
+        "\n",
+        "    if app_role:\n",
+        "        app_role.spec = RoleRoleSpec(\n",
+        "            identity_type=RoleIdentityType.SERVICE_PRINCIPAL,\n",
+        "            postgres_role=app_principal,\n",
+        "            membership_roles=[RoleMembershipRole.DATABRICKS_SUPERUSER],\n",
+        "        )\n",
+        "        w.postgres.update_role(\n",
+        "            name=app_role.name,\n",
+        "            role=app_role,\n",
+        "            update_mask=FieldMask(field_mask=[\"spec.membership_roles\"]),\n",
+        "        )\n",
+        "        print(f\"\\u2705 Updated app role to DATABRICKS_SUPERUSER\")\n",
+        "    else:\n",
+        "        try:\n",
+        "            new_role = w.postgres.create_role(\n",
+        "                parent=production_branch,\n",
+        "                role=Role(\n",
+        "                    spec=RoleRoleSpec(\n",
+        "                        identity_type=RoleIdentityType.SERVICE_PRINCIPAL,\n",
+        "                        postgres_role=app_principal,\n",
+        "                        membership_roles=[RoleMembershipRole.DATABRICKS_SUPERUSER],\n",
+        "                    ),\n",
+        "                ),\n",
+        "            )\n",
+        "            print(f\"\\u2705 Created DATABRICKS_SUPERUSER role for app SP: {app_principal}\")\n",
+        "        except Exception as _ce:\n",
+        "            # Idempotent path: if the server says the role already exists,\n",
+        "            # the list_roles() match above didn't recognise it (most likely\n",
+        "            # because spec.postgres_role on the returned role isn't exactly\n",
+        "            # equal to the SP client_id we used to filter).  The role is\n",
+        "            # already configured for our SP, so treat as success.\n",
+        "            _msg = str(_ce).lower()\n",
+        "            if \"already exists\" in _msg:\n",
+        "                print(f\"\\u267b DATABRICKS_SUPERUSER role for app SP {app_principal} already exists \\u2014 skipping create\")\n",
+        "            else:\n",
+        "                raise\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f Could not grant Lakebase role to app SP: {e}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Write app.yaml — assembles all resource IDs from uc_state before deploy"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json as _json, re as _re, os as _os\n",
+        "\n",
+        "def _latest_from_uc_state(resource_type, key):\n",
+        "    try:\n",
+        "        df = spark.sql(f\"\"\"\n",
+        "            SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "            WHERE resource_type = '{resource_type}'\n",
+        "            ORDER BY created_at DESC\n",
+        "        \"\"\")\n",
+        "        for row in df.collect():\n",
+        "            val = _json.loads(row.resource_data).get(key, \"\")\n",
+        "            if val:\n",
+        "                return val\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️ uc_state lookup failed for {resource_type}/{key}: {e}\")\n",
+        "    return \"\"\n",
+        "\n",
+        "def _ka_tile_id(ka_name):\n",
+        "    try:\n",
+        "        df = spark.sql(f\"\"\"\n",
+        "            SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "            WHERE resource_type = 'knowledge_assistants'\n",
+        "            ORDER BY created_at DESC\n",
+        "        \"\"\")\n",
+        "        for row in df.collect():\n",
+        "            info = _json.loads(row.resource_data)\n",
+        "            if info.get(\"name\") == ka_name:\n",
+        "                return info.get(\"tile_id\", \"\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️ Could not read KA tile {ka_name}: {e}\")\n",
+        "    return \"\"\n",
+        "\n",
+        "# Supervisor\n",
+        "supervisor_endpoint = _latest_from_uc_state(\"multi_agent_supervisors\", \"endpoint_name\")\n",
+        "supervisor_tile_id  = _latest_from_uc_state(\"multi_agent_supervisors\", \"tile_id\")\n",
+        "\n",
+        "supervisor_mlflow_experiment_id = \"\"\n",
+        "if supervisor_tile_id:\n",
+        "    try:\n",
+        "        _tile = w.api_client.do(\"GET\", f\"/api/2.0/tiles/{supervisor_tile_id}\")\n",
+        "        supervisor_mlflow_experiment_id = str(_tile.get(\"mlflow_experiment_id\") or \"\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"⚠️ Could not fetch mlflow_experiment_id from tile: {e}\")\n",
+        "\n",
+        "# Genie spaces (titles must match stages/genie_spaces.ipynb)\n",
+        "_revenue_title = f\"Revenue & Orders Intelligence ({CATALOG})\"\n",
+        "_ops_title     = f\"Operations Intelligence ({CATALOG})\"\n",
+        "_menu_title    = f\"Menu & Safety Intelligence ({CATALOG})\"\n",
+        "genie_revenue_id = genie_ops_id = genie_menu_id = \"\"\n",
+        "try:\n",
+        "    df = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'genie_spaces'\n",
+        "        ORDER BY created_at DESC\n",
+        "    \"\"\")\n",
+        "    for row in df.collect():\n",
+        "        info = _json.loads(row.resource_data)\n",
+        "        title = info.get(\"title\")\n",
+        "        if title == _revenue_title and not genie_revenue_id:\n",
+        "            genie_revenue_id = info.get(\"space_id\", \"\")\n",
+        "        elif title == _ops_title and not genie_ops_id:\n",
+        "            genie_ops_id = info.get(\"space_id\", \"\")\n",
+        "        elif title == _menu_title and not genie_menu_id:\n",
+        "            genie_menu_id = info.get(\"space_id\", \"\")\n",
+        "except Exception as e:\n",
+        "    print(f\"⚠️ Could not read genie IDs: {e}\")\n",
+        "\n",
+        "# KA tile IDs (one per Knowledge Assistant created by stages/knowledge_agents.ipynb)\n",
+        "ka_inspection  = _ka_tile_id(f\"{CATALOG}-inspection-knowledge\")\n",
+        "ka_menu        = _ka_tile_id(f\"{CATALOG}-menu-knowledge\")\n",
+        "ka_legal       = _ka_tile_id(f\"{CATALOG}-legal\")\n",
+        "ka_regulatory  = _ka_tile_id(f\"{CATALOG}-regulatory\")\n",
+        "ka_audits      = _ka_tile_id(f\"{CATALOG}-audits\")\n",
+        "ka_consultancy = _ka_tile_id(f\"{CATALOG}-consultancy\")\n",
+        "\n",
+        "# Operations dashboard embedded in the app's opt-in \"Ops Dashboard\" tab.\n",
+        "# We publish TWO variants — light + dark — because Databricks embedded\n",
+        "# dashboards always render their `light` theme slot (the `?theme=` URL\n",
+        "# param is ignored).  The dark variant bakes dark-palette tokens into\n",
+        "# the `light` slot so the iframe renders with dark colors.  The frontend\n",
+        "# swaps the iframe src when the user toggles the theme.  The Revenue\n",
+        "# card on the always-visible main view stays on Chart.js because the\n",
+        "# embed's other limitations (separate workspace login on first view,\n",
+        "# fixed canvas width) were deal-breakers for an always-visible panel.\n",
+        "ops_dashboard_id       = \"\"   # light variant — default, used by app's light theme\n",
+        "ops_dashboard_id_dark  = \"\"   # dark variant — used when app theme is dark\n",
+        "ops_dashboard_page     = \"\"\n",
+        "_dash_titles = {\n",
+        "    \"light\": f\"Casper's Kitchen - Operations ({CATALOG})\",\n",
+        "    \"dark\":  f\"Casper's Kitchen - Operations - Dark ({CATALOG})\",\n",
+        "}\n",
+        "try:\n",
+        "    _by_title = {(_d.display_name or \"\"): _d for _d in w.lakeview.list()}\n",
+        "    for _variant, _title in _dash_titles.items():\n",
+        "        _d = _by_title.get(_title)\n",
+        "        if not _d:\n",
+        "            print(f\"⚠️ Dashboard '{_title}' not found via lakeview.list()\")\n",
+        "            continue\n",
+        "        _id = _d.dashboard_id or \"\"\n",
+        "        if _variant == \"light\":\n",
+        "            ops_dashboard_id = _id\n",
+        "        else:\n",
+        "            ops_dashboard_id_dark = _id\n",
+        "        try:\n",
+        "            # embed_credentials=True so the iframe runs as the dashboard\n",
+        "            # owner — query execution doesn't require the viewer to\n",
+        "            # authenticate to cloud.databricks.com separately.\n",
+        "            w.lakeview.publish(dashboard_id=_id, embed_credentials=True)\n",
+        "            print(f\"✅ Ops dashboard ({_variant}) (re-)published: {_id}\")\n",
+        "        except Exception as _pe:\n",
+        "            # ALREADY_PUBLISHED and similar racy states are fine.\n",
+        "            print(f\"⚠️ Could not (re-)publish {_variant} dashboard {_id}: {_pe}\")\n",
+        "except Exception as _e:\n",
+        "    print(f\"⚠️ Could not look up ops dashboards: {_e}\")\n",
+        "\n",
+        "# Lakebase endpoint path — deterministic from CATALOG, points at the\n",
+        "# shared Autoscaling project (`<CATALOG>-caspers`) created by\n",
+        "# stages/lakebase_project.ipynb.  Reuses OPS_PROJECT_ID computed at the top\n",
+        "# of this notebook.\n",
+        "lakebase_endpoint_path = OPS_ENDPOINT_PATH\n",
+        "\n",
+        "# Custom agent endpoints — read from the job parameters (REFUND_AGENT_ENDPOINT_NAME\n",
+        "# / COMPLAINT_AGENT_ENDPOINT_NAME), declared on the `all` target with a\n",
+        "# `${var.catalog}` default resolved at deploy time.  Falling back to\n",
+        "# f\"{CATALOG}_...\" only when the widget is missing or empty matches legacy\n",
+        "# behaviour.  See cell 8 above for the full rationale — using CATALOG to\n",
+        "# reconstruct the name breaks when --var catalog (deploy-time) disagrees\n",
+        "# with --params CATALOG (run-time), since the agent stages bake the\n",
+        "# deploy-time-resolved value into the actual endpoint and this stage would\n",
+        "# 404 looking for the run-time value.\n",
+        "def _agent_ep_name(widget_name: str, default_name: str) -> str:\n",
+        "    try:\n",
+        "        v = dbutils.widgets.get(widget_name)\n",
+        "    except Exception:\n",
+        "        v = \"\"\n",
+        "    return v or default_name\n",
+        "\n",
+        "refund_agent_endpoint    = _agent_ep_name(\"REFUND_AGENT_ENDPOINT_NAME\",    f\"{CATALOG}_refund_agent\")\n",
+        "complaint_agent_endpoint = _agent_ep_name(\"COMPLAINT_AGENT_ENDPOINT_NAME\", f\"{CATALOG}_complaint_agent\")\n",
+        "\n",
+        "# Refund Manager app URL — look up by name, empty string if not yet deployed\n",
+        "refund_manager_app_name = _re.sub(r'-+', '-', _re.sub(r'[^a-z0-9-]', '-', f'refundmanager-{CATALOG}'.lower())).strip('-')[:30]\n",
+        "try:\n",
+        "    _rm_app = w.apps.get(refund_manager_app_name)\n",
+        "    refund_manager_app_url = getattr(_rm_app, 'url', '') or ''\n",
+        "    print(f'Refund Manager app: {refund_manager_app_url}')\n",
+        "except Exception:\n",
+        "    refund_manager_app_url = ''\n",
+        "    print(f'Refund Manager app not found ({refund_manager_app_name}) — REFUND_MANAGER_APP_URL will be empty')\n",
+        "\n",
+        "app_yaml_path = _os.path.abspath(\"../apps/caspers-ops-dashboard/app.yaml\")\n",
+        "app_yaml_contents = f\"\"\"command:\n",
+        "  - uvicorn\n",
+        "  - app.main:app\n",
+        "env:\n",
+        "  - name: LAKEBASE_ENDPOINT_PATH\n",
+        "    value: '{lakebase_endpoint_path}'\n",
+        "  - name: LAKEBASE_DATABASE_NAME\n",
+        "    value: '{OPS_DATABASE_NAME}'\n",
+        "  - name: DATABRICKS_CATALOG\n",
+        "    value: '{CATALOG}'\n",
+        "  - name: SUPERVISOR_ENDPOINT\n",
+        "    value: '{supervisor_endpoint}'\n",
+        "  - name: SUPERVISOR_TILE_ID\n",
+        "    value: '{supervisor_tile_id}'\n",
+        "  - name: SUPERVISOR_MLFLOW_EXPERIMENT_ID\n",
+        "    value: '{supervisor_mlflow_experiment_id}'\n",
+        "  - name: GENIE_ID_REVENUE\n",
+        "    value: '{genie_revenue_id}'\n",
+        "  - name: GENIE_ID_OPS\n",
+        "    value: '{genie_ops_id}'\n",
+        "  - name: GENIE_ID_MENU\n",
+        "    value: '{genie_menu_id}'\n",
+        "  - name: KA_ID_INSPECTION\n",
+        "    value: '{ka_inspection}'\n",
+        "  - name: KA_ID_MENU\n",
+        "    value: '{ka_menu}'\n",
+        "  - name: KA_ID_LEGAL\n",
+        "    value: '{ka_legal}'\n",
+        "  - name: KA_ID_REGULATORY\n",
+        "    value: '{ka_regulatory}'\n",
+        "  - name: KA_ID_AUDITS\n",
+        "    value: '{ka_audits}'\n",
+        "  - name: KA_ID_CONSULTANCY\n",
+        "    value: '{ka_consultancy}'\n",
+        "  - name: DATABRICKS_WAREHOUSE_ID\n",
+        "    value: '{warehouse.id}'\n",
+        "  - name: OPS_DASHBOARD_ID\n",
+        "    value: '{ops_dashboard_id}'\n",
+        "  - name: OPS_DASHBOARD_ID_DARK\n",
+        "    value: '{ops_dashboard_id_dark}'\n",
+        "  - name: OPS_DASHBOARD_PAGE\n",
+        "    value: '{ops_dashboard_page}'\n",
+        "  - name: REFUND_AGENT_ENDPOINT\n",
+        "    value: '{refund_agent_endpoint}'\n",
+        "  - name: COMPLAINT_AGENT_ENDPOINT\n",
+        "    value: '{complaint_agent_endpoint}'\n",
+        "  - name: REFUND_MANAGER_APP_URL\n",
+        "    value: '{refund_manager_app_url}'\n",
+        "\"\"\"\n",
+        "with open(app_yaml_path, \"w\") as _f:\n",
+        "    _f.write(app_yaml_contents)\n",
+        "\n",
+        "print(f\"✅ Wrote app.yaml to {app_yaml_path}\")\n",
+        "print(f\"   Supervisor endpoint:  {supervisor_endpoint}\")\n",
+        "print(f\"   Supervisor tile:      {supervisor_tile_id}\")\n",
+        "print(f\"   MLflow experiment:    {supervisor_mlflow_experiment_id}\")\n",
+        "print(f\"   Lakebase endpoint:    {lakebase_endpoint_path}\")\n",
+        "print(f\"   Revenue Genie:        {genie_revenue_id}\")\n",
+        "print(f\"   Ops Genie:            {genie_ops_id}\")\n",
+        "print(f\"   Menu Genie:           {genie_menu_id}\")\n",
+        "print(f\"   KA Inspection:        {ka_inspection}\")\n",
+        "print(f\"   KA Menu:              {ka_menu}\")\n",
+        "print(f\"   KA Legal:             {ka_legal}\")\n",
+        "print(f\"   KA Regulatory:        {ka_regulatory}\")\n",
+        "print(f\"   KA Audits:            {ka_audits}\")\n",
+        "print(f\"   KA Consultancy:       {ka_consultancy}\")\n",
+        "print(f\"   Warehouse:            {warehouse.id}\")\n",
+        "print(f\"   Ops Dashboard (light):{ops_dashboard_id}\")\n",
+        "print(f\"   Ops Dashboard (dark): {ops_dashboard_id_dark}\")\n",
+        "print(f\"   Ops Dashboard page:   {ops_dashboard_page or '(default landing page)'}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time\n",
+        "\n",
+        "deployment = w.apps.deploy(\n",
+        "    app_name=app_status.name,\n",
+        "    app_deployment=AppDeployment(source_code_path=source_code_path),\n",
+        ")\n",
+        "\n",
+        "def _deploy_state(d):\n",
+        "    st = getattr(d, \"status\", None)\n",
+        "    s = getattr(st, \"state\", None) if st is not None else None\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current_dep = w.apps.get_deployment(app_name=app_status.name, deployment_id=deployment.deployment_id)\n",
+        "    state = _deploy_state(current_dep)\n",
+        "    print(f\"Deployment state: {state}\")\n",
+        "    if state == \"SUCCEEDED\":\n",
+        "        deployment_status = current_dep\n",
+        "        break\n",
+        "    if state in (\"FAILED\", \"STOPPED\"):\n",
+        "        raise RuntimeError(f\"Deployment failed for {app_status.name}: state={state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"Deployment for {app_status.name} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(10)\n",
+        "\n",
+        "print(f\"\\u2705 Operational Dashboard deployed\")\n",
+        "print(f\"   URL: {app_status.url if hasattr(app_status, 'url') else 'Check Databricks Apps UI'}\")\n",
+        "\n",
+        "# Discover Domain tagging.  The Operational Dashboard is the operator's\n",
+        "# single pane of glass over the orchestrated agents — pure operations\n",
+        "# domain.  Genie spaces, KAs, dashboards used inside the app each carry\n",
+        "# their own tags so they ALSO surface in their respective domains.  See\n",
+        "# SETUP.ipynb §4 for the manual one-time Domain creation step.\n",
+        "import sys as _sys, os as _os\n",
+        "_sys.path.insert(0, _os.path.abspath(\"..\"))  # stages/ -> repo root\n",
+        "from utils.domain_tags import ensure_domain_tag_policies, tag_workspace_entity\n",
+        "print(\"\\n— Tagging operational dashboard app for Discover Domains —\")\n",
+        "ensure_domain_tag_policies(w, verbose=False)\n",
+        "tag_workspace_entity(w, \"apps\", app_status.name, [\"operations\"],\n",
+        "                     label=f\"app {app_status.name!r}\")\n",
+        "\n",
+        "display(deployment_status)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/operational_evaluation.ipynb b/stages/operational_evaluation.ipynb
new file mode 100644
index 0000000..f10825e
--- /dev/null
+++ b/stages/operational_evaluation.ipynb
@@ -0,0 +1,1465 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Operational Supervisor — Evaluation\n",
+    "\n",
+    "Standalone evaluation task for the deployed Operational Supervisor and all 6\n",
+    "Knowledge Assistants. Runs after `Readiness_Check` in the `all` target pipeline\n",
+    "so endpoints are up before we hit them.\n",
+    "\n",
+    "This notebook demonstrates how to evaluate the Casper's Kitchens Operational Supervisor using **MLflow GenAI evaluation**. It covers:\n",
+    "\n",
+    "1. **Evaluation datasets** \u2014 curated questions with behavioral guidelines (data-agnostic, so they survive simulator updates)\n",
+    "2. **LLM-as-judge scorers** \u2014 built-in `Guidelines` and `Safety` judges + custom `routing_accuracy` and `cites_specific_data` scorers\n",
+    "3. **Running evaluation** \u2014 `mlflow.genai.evaluate()` against the live MAS endpoint\n",
+    "4. **Trace-derived datasets** \u2014 how to harvest production traces and turn them into a labelled eval set\n",
+    "\n",
+    "The Operational Supervisor routes questions across 7 sub-agents:\n",
+    "```\n",
+    "Operational Supervisor (MAS)\n",
+    "  \u251c\u2500\u2500 Revenue Analytics Genie    \u2192 lakeflow + simulator Delta tables\n",
+    "  \u251c\u2500\u2500 Operations Intelligence Genie \u2192 food_safety + all_events tables\n",
+    "  \u251c\u2500\u2500 Inspection Reports KA      \u2192 food safety PDF reports\n",
+    "  \u251c\u2500\u2500 Legal Complaints KA        \u2192 litigation case file PDFs\n",
+    "  \u251c\u2500\u2500 Regulatory Documents KA    \u2192 permits & certifications PDFs\n",
+    "  \u251c\u2500\u2500 Audit Findings KA          \u2192 financial / operational audit PDFs\n",
+    "  \u2514\u2500\u2500 Consultancy Strategy KA    \u2192 management consulting report PDFs\n",
+    "```\n",
+    "\n",
+    "> **Demo tip:** Run cells 1\u20135 before the live demo. Results will be ready to show in the MLflow Experiments UI during Part 3 of the demo script."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "%pip install --upgrade mlflow databricks-sdk 'mlflow[databricks]'\n",
+    "dbutils.library.restartPython()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# (intentionally empty \u2014 was a temporary guidelines-shape diagnostic; bug\n",
+    "# was located in the build cell below, so the diagnostic is no longer needed.\n",
+    "# Safe to skip this cell.)\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Configuration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "import os\n",
+    "import sys\n",
+    "sys.path.append(\"../../utils\")\n",
+    "\n",
+    "# Bump MLflow client-side HTTP timeouts before any deploy/judge calls.\n",
+    "#  \u2022 MLFLOW_DEPLOYMENT_PREDICT_TIMEOUT (default 120s): single supervisor predict.\n",
+    "#    Multi-domain board-deck questions can take 3\u20135 minutes when the supervisor\n",
+    "#    fans out to several sub-agents.\n",
+    "#  \u2022 MLFLOW_HTTP_REQUEST_TIMEOUT (default 120s): used by the LLM-judge calls\n",
+    "#    inside Safety / ExpectationsGuidelines / Guidelines scorers.\n",
+    "#  \u2022 MLFLOW_DEPLOYMENT_PREDICT_TOTAL_TIMEOUT (default 600s): total retry budget;\n",
+    "#    must be \u2265 predict timeout.\n",
+    "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TIMEOUT\", \"600\")\n",
+    "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TOTAL_TIMEOUT\", \"900\")\n",
+    "os.environ.setdefault(\"MLFLOW_HTTP_REQUEST_TIMEOUT\", \"600\")\n",
+    "\n",
+    "from databricks.sdk import WorkspaceClient\n",
+    "\n",
+    "try:\n",
+    "    CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+    "except Exception:\n",
+    "    CATALOG = \"caspersdev\"\n",
+    "\n",
+    "_w = WorkspaceClient()\n",
+    "_supervisor_tile_name = f\"{CATALOG}-operational-supervisor\"\n",
+    "_current_user = spark.sql(\"SELECT current_user()\").collect()[0][0]\n",
+    "\n",
+    "\n",
+    "def _resolve_supervisor_endpoint(tile_name: str) -> str:\n",
+    "    \"\"\"Return the serving endpoint name for the named supervisor.\n",
+    "\n",
+    "    Uses the v2.1 SupervisorAgents list API. The legacy v2.0 path\n",
+    "    /api/2.0/multi-agent-supervisors only supports per-resource ops\n",
+    "    (POST/GET-by-id/PATCH/DELETE) \u2014 listing on it returns 'No API found'.\n",
+    "    \"\"\"\n",
+    "    # Primary: v2.1 supervisor-agents list API. Items are flat dicts \u2014\n",
+    "    # `display_name` is the user-facing name; `name` is the resource path.\n",
+    "    try:\n",
+    "        params = {}\n",
+    "        while True:\n",
+    "            resp = _w.api_client.do(\"GET\", \"/api/2.1/supervisor-agents\", query=params)\n",
+    "            for sa in resp.get(\"supervisor_agents\", []):\n",
+    "                if sa.get(\"display_name\") == tile_name or sa.get(\"name\") == tile_name:\n",
+    "                    ep = sa.get(\"endpoint_name\", \"\")\n",
+    "                    if ep:\n",
+    "                        return ep\n",
+    "            token = resp.get(\"next_page_token\")\n",
+    "            if not token:\n",
+    "                break\n",
+    "            params = {\"page_token\": token}\n",
+    "    except Exception as e:\n",
+    "        print(f\"\u26a0\ufe0f  /api/2.1/supervisor-agents lookup failed: {e}\")\n",
+    "\n",
+    "    # Fallback: generic tiles API\n",
+    "    try:\n",
+    "        params = {}\n",
+    "        while True:\n",
+    "            resp = _w.api_client.do(\"GET\", \"/api/2.0/tiles\", query=params)\n",
+    "            for tile in resp.get(\"tiles\", []):\n",
+    "                if tile.get(\"name\") == tile_name:\n",
+    "                    ep = tile.get(\"serving_endpoint_name\", \"\")\n",
+    "                    if ep:\n",
+    "                        return ep\n",
+    "            token = resp.get(\"next_page_token\")\n",
+    "            if not token:\n",
+    "                break\n",
+    "            params = {\"page_token\": token}\n",
+    "    except Exception as e:\n",
+    "        print(f\"\u26a0\ufe0f  Tiles API fallback failed: {e}\")\n",
+    "\n",
+    "    return \"\"\n",
+    "\n",
+    "\n",
+    "SUPERVISOR_ENDPOINT = _resolve_supervisor_endpoint(_supervisor_tile_name)\n",
+    "if not SUPERVISOR_ENDPOINT:\n",
+    "    raise ValueError(\n",
+    "        f\"Could not resolve supervisor endpoint for tile '{_supervisor_tile_name}'. \"\n",
+    "        \"Make sure the Operational Supervisor stage has been deployed for this catalog.\"\n",
+    "    )\n",
+    "\n",
+    "print(f\"Catalog:             {CATALOG}\")\n",
+    "print(f\"Supervisor endpoint: {SUPERVISOR_ENDPOINT}\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import mlflow\n",
+    "import mlflow.genai\n",
+    "import pandas as pd\n",
+    "import json\n",
+    "\n",
+    "from mlflow.deployments import get_deploy_client as _gdc\n",
+    "_deploy_client = _gdc(\"databricks\")\n",
+    "\n",
+    "# Each Agent Bricks Multi-Agent Supervisor gets a managed MLflow experiment under\n",
+    "# /Users/{user}/{mas_id}-dev-experiment.  This is THE default experiment for the\n",
+    "# supervisor \u2014 eval runs and production traces both land here.  No /Serving/\n",
+    "# companion exists for managed agent endpoints; the path below is the only place\n",
+    "# to look for supervisor activity.\n",
+    "_mas_id = SUPERVISOR_ENDPOINT.replace(\"-endpoint\", \"\")\n",
+    "EVAL_EXPERIMENT_NAME = f\"/Users/{_current_user}/{_mas_id}-dev-experiment\"\n",
+    "\n",
+    "mlflow.set_experiment(EVAL_EXPERIMENT_NAME)\n",
+    "print(f\"Eval experiment: {EVAL_EXPERIMENT_NAME}\")\n",
+    "\n",
+    "w = _w\n",
+    "print(f\"MLflow version: {mlflow.__version__}\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Build the Supervisor Evaluation Dataset (UC-managed)\n",
+    "\n",
+    "Curated questions covering all supervisor sub-agents, with per-row `expectations.guidelines` for the `ExpectationsGuidelines` scorer.  Stored as a UC-managed `mlflow.genai.datasets` table at `{CATALOG}.evaluations.operational_supervisor_eval_dataset` so it has lineage, governance, and is reproducible across deploys.\n",
+    "\n",
+    "Built inline in this notebook \u2014 no separate setup task.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import json as _json\n",
+    "import mlflow.genai.datasets\n",
+    "\n",
+    "EVAL_RECORDS = [\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Which location has the highest order cancellation rate right now?\", \"expected_agent\": \"revenue\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"revenue\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must name exactly one specific location as having the highest rate \u2014 not a list.\",\n",
+    "                \"Must include a numeric cancellation rate (percentage).\",\n",
+    "                \"Must not say it cannot access the data or ask for clarification.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"How does revenue compare across our locations this week?\", \"expected_agent\": \"revenue\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"revenue\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must provide revenue figures or a ranking for multiple locations.\",\n",
+    "                \"Must reference the current week as the time period.\",\n",
+    "                \"Must not return a generic description without actual numbers.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Which brand is generating the most revenue right now?\", \"expected_agent\": \"revenue\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"revenue\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must name a specific brand (not a location).\",\n",
+    "                \"Must include a revenue figure or ranking.\",\n",
+    "                \"Must distinguish between brand-level and location-level performance.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Which location needs the most operational attention right now?\", \"expected_agent\": \"operations\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"operations\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must name one specific location with the highest risk.\",\n",
+    "                \"Must justify with at least two operational metrics (e.g. complaint rate, cancel rate, food safety).\",\n",
+    "                \"Must not give a generic answer \u2014 must reference actual data from the system.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"What happened during the Chicago food safety inspection? Were there critical violations?\", \"expected_agent\": \"inspection\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"inspection\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must reference a specific inspection report by date or ID.\",\n",
+    "                \"Must state the inspection score and/or grade.\",\n",
+    "                \"Must explicitly state whether critical violations were found.\",\n",
+    "                \"Must cite at least one specific violation if they exist.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Do we have any active high-risk legal cases? What is the total financial exposure?\", \"expected_agent\": \"legal\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"legal\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must confirm whether active cases exist \u2014 cannot hedge or say data is unavailable.\",\n",
+    "                \"Must cite at least one specific case number (format: CK-XX-XXXX).\",\n",
+    "                \"Must include a risk classification (HIGH / MEDIUM / LOW) for at least one case.\",\n",
+    "                \"Must state a financial exposure amount.\",\n",
+    "                \"Must include a reminder to involve legal counsel.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Which location has the most active legal cases?\", \"expected_agent\": \"legal\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"legal\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must name a specific location \u2014 not 'I don\\'t know' or a list of all locations.\",\n",
+    "                \"Must provide a count of active cases for at least the top location.\",\n",
+    "                \"Must distinguish active cases from settled or dismissed ones.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Are there any permits or regulatory certificates expiring in the next 60 days?\", \"expected_agent\": \"regulatory\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"regulatory\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must list specific document IDs or permit names \u2014 not generic descriptions.\",\n",
+    "                \"Must include expiry dates for each flagged document.\",\n",
+    "                \"Must specify which location each document applies to.\",\n",
+    "                \"If nothing is expiring, must say so explicitly with supporting evidence.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"What do our consultants recommend as the top AI investments for the next 90 days?\", \"expected_agent\": \"consultancy\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"consultancy\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must reference a specific consulting report or firm by name.\",\n",
+    "                \"Must include at least one concrete recommendation (not just \\'invest in AI\\').\",\n",
+    "                \"Must include a financial metric \u2014 ROI estimate, cost, or projected saving.\",\n",
+    "                \"Must frame the answer in the 90-day horizon.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"What were the most significant audit findings this quarter?\", \"expected_agent\": \"audits\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"audits\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must cite the auditing firm and the audit period covered.\",\n",
+    "                \"Must classify findings by severity (Critical / Significant / Minor / Informational).\",\n",
+    "                \"Must state remediation status for at least one finding.\",\n",
+    "                \"Must not conflate audit findings with food safety inspection findings.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "    {\n",
+    "        \"inputs\": {\"question\": \"Give me a board deck summary: revenue performance, top operational risk, legal exposure, and one strategic recommendation.\", \"expected_agent\": \"multi\"},\n",
+    "        \"expectations\": {\n",
+    "            \"expected_agent\": \"multi\",\n",
+    "            \"guidelines\": [\n",
+    "                \"Must explicitly address all four domains: revenue, operations, legal, and strategy.\",\n",
+    "                \"Must include at least one concrete number or data point per domain.\",\n",
+    "                \"Must not refuse or hedge on any of the four domains.\",\n",
+    "                \"Response must be structured \u2014 not a single unbroken paragraph.\",\n",
+    "            ],\n",
+    "        },\n",
+    "    },\n",
+    "]\n",
+    "\n",
+    "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.operational_supervisor_eval_dataset\"\n",
+    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.evaluations\")\n",
+    "\n",
+    "# Drop + recreate to avoid Arrow schema mismatches if a prior run wrote a\n",
+    "# different shape.  mlflow.genai.datasets is the source of truth from now on.\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {UC_DATASET_TABLE}\")\n",
+    "_ds = mlflow.genai.datasets.create_dataset(uc_table_name=UC_DATASET_TABLE)\n",
+    "\n",
+    "\n",
+    "# Pass EVAL_RECORDS to mlflow.genai.datasets natively.  An earlier revision of\n",
+    "# this notebook JSON-stringified every list-of-primitives field (including\n",
+    "# `expectations.guidelines`) on the assumption that Arrow + mlflow.genai.datasets\n",
+    "# couldn't round-trip ARRAY<STRING>.  That workaround actively caused the bug\n",
+    "# it claimed to avoid: mlflow.genai.datasets's schema treated\n",
+    "# `expectations.guidelines` as ARRAY<STRING>, received the JSON string we'd\n",
+    "# manufactured, and cast str \u2192 array by iterating characters.  Net effect:\n",
+    "# `guidelines` arrived in MLflow as one element per character (e.g.\n",
+    "# `[\"[\", \"\\\"\", \"M\", \"u\", \"s\", \"t\", \u2026]`) and the ExpectationsGuidelines judge\n",
+    "# scored against garbage.  The cell below now passes native lists; if\n",
+    "# mlflow.genai.datasets really can't store them, we tolerate the write failure\n",
+    "# and fall back to the in-memory EVAL_RECORDS (cell that loads EVAL_DATASET\n",
+    "# does the same).\n",
+    "_UC_WRITE_OK = False\n",
+    "try:\n",
+    "    _ds.merge_records(EVAL_RECORDS)\n",
+    "    _UC_WRITE_OK = True\n",
+    "    print(f\"\u2705 Built {UC_DATASET_TABLE} ({len(EVAL_RECORDS)} rows, native ARRAY<STRING>)\")\n",
+    "except Exception as _e:\n",
+    "    print(\n",
+    "        f\"\u26a0\ufe0f  Could not write {UC_DATASET_TABLE} natively: \"\n",
+    "        f\"{type(_e).__name__}: {_e}\\n\"\n",
+    "        \"    The UC table will be empty / partially populated, but eval still\\n\"\n",
+    "        \"    proceeds against the in-memory EVAL_RECORDS list in the next cells.\"\n",
+    "    )\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Define the `predict_fn`\n",
+    "\n",
+    "The predict function wraps the Operational Supervisor endpoint. MLflow calls it for each row in the evaluation dataset, unpacking the `inputs` dict as keyword arguments.\n",
+    "\n",
+    "The supervisor is a Multi-Agent Supervisor served at a Databricks Inference Endpoint \u2014 we query it exactly like any other chat model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "from mlflow.deployments import get_deploy_client as _get_deploy_client\n",
+    "\n",
+    "# mlflow.deployments client is the correct way to call endpoints inside\n",
+    "# mlflow.genai.evaluate() \u2014 it sends plain dicts without the SDK's\n",
+    "# object-serialisation layer that causes \"'dict' has no attribute 'as_dict'\".\n",
+    "_deploy_client = _get_deploy_client(\"databricks\")\n",
+    "\n",
+    "\n",
+    "def _extract_text(response: dict) -> str:\n",
+    "    \"\"\"\n",
+    "    Extract the assistant text from any known MAS response format:\n",
+    "    - Chat Completions: {\"choices\": [{\"message\": {\"content\": \"...\"}}]}\n",
+    "    - Responses API:    {\"output\": [{\"role\": \"assistant\", \"content\": \"...\" | [...]}]}\n",
+    "    - Agent final:      {\"final_response\": \"...\"}\n",
+    "    - Plain string:     \"...\"\n",
+    "    \"\"\"\n",
+    "    # Deploy client sometimes returns a JSON string instead of a parsed dict \u2014\n",
+    "    # try to parse it before treating it as plain text.\n",
+    "    if isinstance(response, str):\n",
+    "        try:\n",
+    "            response = json.loads(response)\n",
+    "        except (json.JSONDecodeError, ValueError):\n",
+    "            return response  # genuinely plain text\n",
+    "\n",
+    "    if not isinstance(response, dict):\n",
+    "        return str(response)\n",
+    "\n",
+    "    # {\"final_response\": \"...\"}\n",
+    "    if \"final_response\" in response:\n",
+    "        return str(response[\"final_response\"])\n",
+    "\n",
+    "    # Deploy client may wrap in {\"predictions\": [...] or {...}}\n",
+    "    preds = response.get(\"predictions\")\n",
+    "    if preds is not None:\n",
+    "        if isinstance(preds, list) and preds:\n",
+    "            return _extract_text(preds[0])\n",
+    "        if isinstance(preds, (dict, str)):\n",
+    "            return _extract_text(preds)\n",
+    "\n",
+    "    # Chat Completions format\n",
+    "    if \"choices\" in response:\n",
+    "        return response[\"choices\"][0][\"message\"][\"content\"]\n",
+    "\n",
+    "    # Responses API format\n",
+    "    output = response.get(\"output\", [])\n",
+    "    if isinstance(output, list):\n",
+    "        for item in output:\n",
+    "            if not isinstance(item, dict):\n",
+    "                continue\n",
+    "            if item.get(\"role\") == \"assistant\" or item.get(\"type\") == \"message\":\n",
+    "                content = item.get(\"content\", \"\")\n",
+    "                if isinstance(content, str):\n",
+    "                    return content\n",
+    "                if isinstance(content, list):\n",
+    "                    return \" \".join(\n",
+    "                        c.get(\"text\", c.get(\"value\", \"\"))\n",
+    "                        for c in content\n",
+    "                        if isinstance(c, dict)\n",
+    "                    )\n",
+    "    if isinstance(output, str):\n",
+    "        return output\n",
+    "\n",
+    "    print(f\"\\u26a0\\ufe0f  Unrecognised response format \\u2014 keys: {list(response.keys())}. Returning raw string.\")\n",
+    "    return str(response)\n",
+    "\n",
+    "\n",
+    "def predict_fn(question: str, expected_agent: str = None) -> str:\n",
+    "    \"\"\"\n",
+    "    Call the Operational Supervisor MAS and return its text response.\n",
+    "\n",
+    "    mlflow.genai.evaluate() calls this for each dataset row, unpacking the\n",
+    "    `inputs` dict as kwargs.  MAS endpoints use the agent-style `input` field\n",
+    "    and return either Chat Completions or Responses API format depending on\n",
+    "    the SDK version \u2014 _extract_text handles both.\n",
+    "\n",
+    "    Per-row exceptions are caught and returned as an error string so a single\n",
+    "    failed call does not abort the entire evaluation run.\n",
+    "    \"\"\"\n",
+    "    try:\n",
+    "        response = _deploy_client.predict(\n",
+    "            endpoint=SUPERVISOR_ENDPOINT,\n",
+    "            inputs={\"input\": [{\"role\": \"user\", \"content\": question}]},\n",
+    "        )\n",
+    "        return _extract_text(response)\n",
+    "    except Exception as e:\n",
+    "        print(f\"\u26a0\ufe0f  predict_fn error for question {question[:60]!r}: {e}\")\n",
+    "        return f\"[ERROR: {e}]\"\n",
+    "\n",
+    "\n",
+    "print(f\"\u2705 predict_fn defined \u2014 will call {SUPERVISOR_ENDPOINT}\")"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Load the Evaluation Dataset from Unity Catalog\n",
+    "\n",
+    "The curated supervisor eval dataset lives in Unity Catalog at `{CATALOG}.evaluations.operational_supervisor_eval_dataset`, built by the previous cell. Reading it back from UC keeps the rest of the notebook independent of the in-memory `EVAL_RECORDS` variable, so eval runs always use the governed source of truth.\n",
+    "\n",
+    "A good evaluation dataset for a multi-agent supervisor tests **agent behavior**, not specific data values.\n",
+    "\n",
+    "Data changes \u2014 the simulator updates, new locations get added, legal cases resolve. Hard-coding \"Chicago has the highest cancellation rate at 11\u201312%\" would make the eval brittle and wrong the moment the data shifts.\n",
+    "\n",
+    "Instead, each record defines **behavioral guidelines**: criteria that should hold true regardless of what the current data says:\n",
+    "- Did the agent route to the right sub-agent domain?\n",
+    "- Did it return a structured, data-backed response (numbers, dates, IDs)?\n",
+    "- Did it avoid vague hedging (\"I cannot access...\")?\n",
+    "- Did it follow the expected response format for that question type?\n",
+    "\n",
+    "This also means we drop the `Correctness` scorer \u2014 that scorer compares outputs against a hardcoded `expected_response`, which is only appropriate when you have ground truth that doesn't change (like a fixed Q&A FAQ, not a live analytics system)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import copy as _copy\n",
+    "\n",
+    "# Use EVAL_RECORDS (in-memory, from the build cell) as the canonical eval\n",
+    "# data source, not a re-read of the UC table.  Reading back through\n",
+    "# spark.table -> toPandas -> json.loads was previously paired with the\n",
+    "# JSON-stringify workaround that mangled `expectations.guidelines` into a\n",
+    "# per-character ARRAY<STRING>; that's now removed.  We still want\n",
+    "# EVAL_DATASET to be a separate object the rest of the notebook can mutate\n",
+    "# (top-level `guidelines` lift below) without touching EVAL_RECORDS.\n",
+    "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.operational_supervisor_eval_dataset\"\n",
+    "EVAL_DATASET = [_copy.deepcopy(r) for r in EVAL_RECORDS]\n",
+    "\n",
+    "# Shape shim: EVAL_RECORDS stores guidelines under `expectations.guidelines`,\n",
+    "# but MLflow 3.x's ExpectationsGuidelines scorer (and cell 11's _eval_df\n",
+    "# construction) reads `guidelines` at the top level of each row.  Mirror it\n",
+    "# up so the rest of the notebook works unchanged.\n",
+    "for _rec in EVAL_DATASET:\n",
+    "    if \"guidelines\" not in _rec and isinstance(_rec.get(\"expectations\"), dict):\n",
+    "        _gl = _rec[\"expectations\"].get(\"guidelines\")\n",
+    "        if _gl is not None:\n",
+    "            _rec[\"guidelines\"] = _gl\n",
+    "\n",
+    "if not EVAL_DATASET:\n",
+    "    raise RuntimeError(\n",
+    "        \"EVAL_RECORDS is empty. Run the 'Build the Supervisor Evaluation \"\n",
+    "        \"Dataset' cell above before this one.\"\n",
+    "    )\n",
+    "\n",
+    "print(f\"Loaded {len(EVAL_DATASET)} eval rows from in-memory EVAL_RECORDS\")\n",
+    "\n",
+    "# Governance sanity check: confirm the UC table written by the build cell\n",
+    "# above also exists and has the expected row count (it's what mlflow.log_input\n",
+    "# below points at for lineage).  If the native write failed, this just warns \u2014\n",
+    "# eval still runs against the in-memory EVAL_DATASET.\n",
+    "try:\n",
+    "    _uc_rowcount = spark.table(UC_DATASET_TABLE).count()\n",
+    "    if _uc_rowcount == len(EVAL_DATASET):\n",
+    "        print(f\"   UC governance copy:  {UC_DATASET_TABLE} ({_uc_rowcount} rows) \u2713\")\n",
+    "    else:\n",
+    "        print(\n",
+    "            f\"\u26a0\ufe0f  UC governance copy:  {UC_DATASET_TABLE} has {_uc_rowcount} rows, \"\n",
+    "            f\"in-memory has {len(EVAL_DATASET)}.  Eval will use the in-memory copy.\"\n",
+    "        )\n",
+    "except Exception as _e:\n",
+    "    print(\n",
+    "        f\"\u26a0\ufe0f  UC governance copy:  {UC_DATASET_TABLE} not readable \"\n",
+    "        f\"({type(_e).__name__}: {_e}).  Eval will use the in-memory copy.\"\n",
+    "    )\n",
+    "\n",
+    "df = pd.DataFrame(EVAL_DATASET)\n",
+    "print(f\"Evaluation dataset: {len(df)} questions across \"\n",
+    "      f\"{df['expectations'].apply(lambda x: x['expected_agent']).nunique()} agent domains\")\n",
+    "df[[\"inputs\", \"guidelines\"]]\n",
+    ""
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Define Scorers\n",
+    "\n",
+    "| Scorer | Type | What it checks |\n",
+    "|---|---|---|\n",
+    "| `ExpectationsGuidelines()` | Built-in LLM judge | Per-row pass/fail criteria from `expectations.guidelines` |\n",
+    "| `RelevanceToQuery()` | Built-in LLM judge | Is the response directly relevant and responsive to the question asked? |\n",
+    "| `Safety()` | Built-in LLM judge | Does the response contain harmful or inappropriate content? |\n",
+    "| `routing_accuracy` | Custom `@scorer` | Does the response vocabulary match the expected sub-agent domain? |\n",
+    "| `cites_specific_data` | Custom `@scorer` | Does the response cite numbers/dates/IDs rather than hedge? |\n",
+    "\n",
+    "> **`ExpectationsGuidelines` vs `Guidelines`:** `Guidelines()` applies the *same* criteria to every row \u2014 useful for global rules like \"always respond in English\". `ExpectationsGuidelines()` reads `guidelines` from each row's `expectations` dict, so each question gets its own pass/fail criteria. Since every question here has different requirements, `ExpectationsGuidelines` is correct.\n",
+    ">\n",
+    "> **`RelevanceToQuery`:** LLM judge that evaluates whether the response actually answers the question asked \u2014 catches cases where the supervisor returns a response that passes safety and guideline checks but doesn't address what the operator asked.\n",
+    ">\n",
+    "> **No `Correctness` scorer.** Correctness compares against a hardcoded `expected_response`. For a live analytics system the data changes constantly \u2014 hardcoded gold answers become false failures after every simulator update. `ExpectationsGuidelines` + `cites_specific_data` cover the same intent without brittleness.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import re\n",
+    "try:\n",
+    "    from mlflow.genai.scorers import scorer, ExpectationsGuidelines, RelevanceToQuery, Safety, Guidelines\n",
+    "    _has_relevance = True\n",
+    "except ImportError:\n",
+    "    from mlflow.genai.scorers import scorer, ExpectationsGuidelines, Safety, Guidelines\n",
+    "    RelevanceToQuery = None\n",
+    "    _has_relevance = False\n",
+    "    print(\"\u26a0\ufe0f  RelevanceToQuery not available in this MLflow version \u2014 skipping\")\n",
+    "from mlflow.entities import Feedback\n",
+    "\n",
+    "# \u2500\u2500 Domain vocabulary signals \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "# Each sub-agent produces responses with characteristic vocabulary.\n",
+    "# We use this to infer routing without access to internal MAS trace data.\n",
+    "_AGENT_SIGNALS = {\n",
+    "    \"revenue\": [\"revenue\", \"cancellation rate\", \"order count\", \"orders placed\", \"sales\", \"avg order\", \"weekly\", \"total orders\"],\n",
+    "    \"operations\": [\"complaint rate\", \"kitchen\", \"operational\", \"throughput\", \"busiest\", \"food safety grade\", \"cancel rate\"],\n",
+    "    \"inspection\": [\"inspection report\", \"violation\", \"inspector\", \"corrective action\", \"grade\", \"score\", \"health permit\"],\n",
+    "    \"legal\": [\"case no\", \"ck-\", \"risk level\", \"amount at stake\", \"counsel\", \"litigation\", \"plaintiff\", \"high risk\"],\n",
+    "    \"regulatory\": [\"permit\", \"certificate\", \"expiry\", \"regulatory\", \"fda\", \"zoning\", \"issuing authority\"],\n",
+    "    \"audits\": [\"audit\", \"auditor\", \"finding\", \"pwc\", \"deloitte\", \"kpmg\", \"significant\", \"critical finding\"],\n",
+    "    \"consultancy\": [\"consultant\", \"roi\", \"recommend\", \"strategy\", \"mckinsey\", \"phase 1\", \"investment\"],\n",
+    "    \"multi\": [\"revenue\", \"legal\", \"audit\", \"operational\"],  # board summary \u2014 needs all domains\n",
+    "}\n",
+    "\n",
+    "\n",
+    "@scorer\n",
+    "def routing_accuracy(inputs: dict, outputs, expectations: dict = None) -> Feedback:\n",
+    "    \"\"\"\n",
+    "    Checks whether the MAS response contains vocabulary signals consistent\n",
+    "    with the expected sub-agent domain for this question.\n",
+    "    Returns a score from 0.0 (wrong domain) to 1.0 (clearly routed correctly).\n",
+    "    \"\"\"\n",
+    "    def _as_text(o):\n",
+    "        # Inlined so the registered/serialized scorer can resolve it at runtime.\n",
+    "        # Eval time hands us the string from predict_fn; prod monitoring hands us\n",
+    "        # the raw trace outputs (dict-shaped for the MAS endpoint).\n",
+    "        if o is None: return \"\"\n",
+    "        if isinstance(o, str): return o\n",
+    "        if isinstance(o, dict):\n",
+    "            v = o.get(\"final_response\")\n",
+    "            if isinstance(v, str): return v\n",
+    "            msgs = o.get(\"messages\")\n",
+    "            if isinstance(msgs, list):\n",
+    "                for m in reversed(msgs):\n",
+    "                    if isinstance(m, dict) and m.get(\"role\") == \"assistant\":\n",
+    "                        c = m.get(\"content\")\n",
+    "                        if isinstance(c, str): return c\n",
+    "            choices = o.get(\"choices\")\n",
+    "            if isinstance(choices, list) and choices:\n",
+    "                try:\n",
+    "                    c = choices[0][\"message\"][\"content\"]\n",
+    "                    if isinstance(c, str): return c\n",
+    "                except (KeyError, TypeError):\n",
+    "                    pass\n",
+    "            output = o.get(\"output\")\n",
+    "            if isinstance(output, str): return output\n",
+    "            if isinstance(output, list):\n",
+    "                parts = []\n",
+    "                for it in output:\n",
+    "                    if isinstance(it, dict):\n",
+    "                        c = it.get(\"content\")\n",
+    "                        if isinstance(c, str): parts.append(c)\n",
+    "                        elif isinstance(c, list):\n",
+    "                            for piece in c:\n",
+    "                                if isinstance(piece, dict):\n",
+    "                                    parts.append(piece.get(\"text\", piece.get(\"value\", \"\")) or \"\")\n",
+    "                if parts: return \" \".join(parts)\n",
+    "        return str(o)\n",
+    "    expected_agent = (inputs or {}).get(\"expected_agent\") or (expectations or {}).get(\"expected_agent\", \"\")\n",
+    "    response_lower = _as_text(outputs).lower()\n",
+    "\n",
+    "    if not expected_agent or expected_agent not in _AGENT_SIGNALS:\n",
+    "        return Feedback(value=None, rationale=\"No expected_agent specified \u2014 skipped\")\n",
+    "\n",
+    "    signals = _AGENT_SIGNALS[expected_agent]\n",
+    "\n",
+    "    if expected_agent == \"multi\":\n",
+    "        domains_present = sum(\n",
+    "            1 for domain_signals in _AGENT_SIGNALS.values()\n",
+    "            if any(s in response_lower for s in domain_signals)\n",
+    "        )\n",
+    "        score = min(1.0, domains_present / 4.0)\n",
+    "        rationale = f\"{domains_present} agent domains detected in board summary response\"\n",
+    "    else:\n",
+    "        matched = [s for s in signals if s in response_lower]\n",
+    "        score = min(1.0, len(matched) / max(2, len(signals) // 2))\n",
+    "        rationale = f\"Matched signals: {matched}\" if matched else \"No expected-agent signals detected in response\"\n",
+    "\n",
+    "    return Feedback(value=score, rationale=rationale)\n",
+    "\n",
+    "\n",
+    "@scorer\n",
+    "def cites_specific_data(inputs: dict, outputs, expectations: dict = None) -> Feedback:\n",
+    "    \"\"\"\n",
+    "    Checks whether the response cites concrete data points rather than\n",
+    "    giving vague or hedged answers. Operational responses must have numbers.\n",
+    "    \"\"\"\n",
+    "    import re  # imported inside the function so the registered/serialized scorer can resolve it at runtime\n",
+    "    def _as_text(o):\n",
+    "        # Inlined so the registered/serialized scorer can resolve it at runtime.\n",
+    "        # Eval time hands us the string from predict_fn; prod monitoring hands us\n",
+    "        # the raw trace outputs (dict-shaped for the MAS endpoint).\n",
+    "        if o is None: return \"\"\n",
+    "        if isinstance(o, str): return o\n",
+    "        if isinstance(o, dict):\n",
+    "            v = o.get(\"final_response\")\n",
+    "            if isinstance(v, str): return v\n",
+    "            msgs = o.get(\"messages\")\n",
+    "            if isinstance(msgs, list):\n",
+    "                for m in reversed(msgs):\n",
+    "                    if isinstance(m, dict) and m.get(\"role\") == \"assistant\":\n",
+    "                        c = m.get(\"content\")\n",
+    "                        if isinstance(c, str): return c\n",
+    "            choices = o.get(\"choices\")\n",
+    "            if isinstance(choices, list) and choices:\n",
+    "                try:\n",
+    "                    c = choices[0][\"message\"][\"content\"]\n",
+    "                    if isinstance(c, str): return c\n",
+    "                except (KeyError, TypeError):\n",
+    "                    pass\n",
+    "            output = o.get(\"output\")\n",
+    "            if isinstance(output, str): return output\n",
+    "            if isinstance(output, list):\n",
+    "                parts = []\n",
+    "                for it in output:\n",
+    "                    if isinstance(it, dict):\n",
+    "                        c = it.get(\"content\")\n",
+    "                        if isinstance(c, str): parts.append(c)\n",
+    "                        elif isinstance(c, list):\n",
+    "                            for piece in c:\n",
+    "                                if isinstance(piece, dict):\n",
+    "                                    parts.append(piece.get(\"text\", piece.get(\"value\", \"\")) or \"\")\n",
+    "                if parts: return \" \".join(parts)\n",
+    "        return str(o)\n",
+    "    response = _as_text(outputs)\n",
+    "\n",
+    "    patterns = [\n",
+    "        r'\\d+\\.?\\d*\\s*%',                        # percentages\n",
+    "        r'\\$\\s*[\\d,]+',                           # dollar amounts\n",
+    "        r'CK-\\d+-\\d+',                            # legal case numbers\n",
+    "        r'\\d{4}-\\d{2}-\\d{2}',                     # ISO dates\n",
+    "        r'\\b(?:score|grade)\\s*(?:of\\s*)?\\d+',     # inspection scores\n",
+    "        r'\\b\\d+x\\b',                              # ROI multiples (e.g. 3.2x)\n",
+    "        r'\\b\\d+\\s+(?:cases?|orders?|locations?|findings?)',  # count phrases\n",
+    "    ]\n",
+    "\n",
+    "    found = [pat for pat in patterns if re.search(pat, response, re.IGNORECASE)]\n",
+    "\n",
+    "    hedges = [\"i don't have access\", \"i cannot provide\", \"i'm unable\", \"consult your\", \"please check with\"]\n",
+    "    is_hedged = any(h in response.lower() for h in hedges)\n",
+    "\n",
+    "    if is_hedged and len(found) < 2:\n",
+    "        return Feedback(value=0.0, rationale=\"Response is hedged with no concrete data \u2014 agent likely failed to retrieve\")\n",
+    "\n",
+    "    score = min(1.0, len(found) / 3.0)\n",
+    "    return Feedback(value=score, rationale=f\"Data patterns found: {len(found)} types \u2014 {found}\")\n",
+    "\n",
+    "\n",
+    "print(\"Scorers defined:\")\n",
+    "print(\"  - ExpectationsGuidelines  (LLM judge: per-row pass/fail from expectations.guidelines)\")\n",
+    "print(\"  - RelevanceToQuery        (LLM judge: is the response directly relevant to the question?)\")\n",
+    "print(\"  - Safety                  (LLM judge: harmful/inappropriate content check)\")\n",
+    "print(\"  - Guidelines              (LLM judge: global guideline for trace-derived eval \u2014 trace eval only)\")\n",
+    "print(\"  - routing_accuracy        (custom: did MAS route to the right domain?)\")\n",
+    "print(\"  - cites_specific_data     (custom: does the answer contain concrete numbers?)\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Run Evaluation\n",
+    "\n",
+    "`mlflow.genai.evaluate()` calls `predict_fn` for each row, applies all scorers, and logs everything to the MLflow experiment as a named run.\n",
+    "\n",
+    "> This will make **10 calls** to the Operational Supervisor endpoint. Each call takes ~30\u2013120 seconds depending on agent routing. Expect total runtime of **5\u201315 minutes**."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Log the evaluation dataset to MLflow so it's visible in the Experiments UI.\n",
+    "# This makes the dataset a first-class artifact linked to the run \u2014 reviewers\n",
+    "# can see exactly which questions were used for evaluation without reading code.\n",
+    "# Log the UC table itself as the run's input dataset, so the run carries\n",
+    "# UC lineage to {CATALOG}.evaluations.operational_supervisor_eval_dataset\n",
+    "# (matches refund/complaint pattern). UC_DATASET_TABLE is defined in the\n",
+    "# \"Build the Evaluation Dataset\" cell above.\n",
+    "_mlflow_dataset = mlflow.data.from_spark(\n",
+    "    spark.table(UC_DATASET_TABLE),\n",
+    "    table_name=UC_DATASET_TABLE,\n",
+    ")\n",
+    "\n",
+    "# _mas_id is defined in cell 3 (e.g. \"mas-e693df14\")\n",
+    "_eval_run_name = f\"{_mas_id}-dev-experiment\"\n",
+    "\n",
+    "# Resolve the production supervisor_instructions prompt version so eval runs\n",
+    "# can be tagged with it.  Lets a failing scorer point at exactly which prompt\n",
+    "# revision regressed.  CATALOG is defined in cell 2.\n",
+    "import mlflow\n",
+    "import mlflow.genai\n",
+    "\n",
+    "# Required: without databricks-uc the registry client hits workspace MLflow,\n",
+    "# where 3-part names are opaque strings and load_prompt raises NotFound.\n",
+    "mlflow.set_registry_uri(\"databricks-uc\")\n",
+    "\n",
+    "SUPERVISOR_PROMPT_URI = f\"prompts:/{CATALOG}.prompts.supervisor_instructions@production\"\n",
+    "try:\n",
+    "    SUPERVISOR_PROMPT_VERSION = str(mlflow.genai.load_prompt(SUPERVISOR_PROMPT_URI).version)\n",
+    "    print(f\"  Resolved {SUPERVISOR_PROMPT_URI} -> v{SUPERVISOR_PROMPT_VERSION}\")\n",
+    "except Exception as _exc:\n",
+    "    SUPERVISOR_PROMPT_VERSION = \"unknown\"\n",
+    "    print(f\"  Could not resolve {SUPERVISOR_PROMPT_URI}: {type(_exc).__name__}: {_exc}\")\n",
+    "\n",
+    "with mlflow.start_run(run_name=_eval_run_name):\n",
+    "    mlflow.log_input(_mlflow_dataset, context=\"eval\")\n",
+    "    mlflow.log_param(\"prompt_uri\", SUPERVISOR_PROMPT_URI)\n",
+    "    mlflow.log_param(\"prompt_version\", SUPERVISOR_PROMPT_VERSION)\n",
+    "    results = mlflow.genai.evaluate(\n",
+    "        predict_fn=predict_fn,\n",
+    "        data=EVAL_DATASET,\n",
+    "        scorers=[\n",
+    "            ExpectationsGuidelines(),\n",
+    "            *([RelevanceToQuery()] if _has_relevance else []),\n",
+    "            Safety(),\n",
+    "            routing_accuracy,\n",
+    "            cites_specific_data,\n",
+    "        ],\n",
+    "    )\n",
+    "\n",
+    "print(\"\\n\u2705 Evaluation complete\")\n",
+    "# Diagnostics: inspect the results object so we know its shape\n",
+    "print(f\"results type: {type(results)}\")\n",
+    "print(f\"results.metrics: {getattr(results, 'metrics', 'N/A')}\")\n",
+    "_tables = getattr(results, 'tables', None)\n",
+    "if _tables is not None:\n",
+    "    if isinstance(_tables, dict):\n",
+    "        print(f\"results.tables keys: {list(_tables.keys())}\")\n",
+    "        for _k, _v in _tables.items():\n",
+    "            try:\n",
+    "                print(f\"  [{_k!r}] shape={_v.shape}, cols={_v.columns.tolist()}\")\n",
+    "            except Exception:\n",
+    "                print(f\"  [{_k!r}] type={type(_v)}\")\n",
+    "    else:\n",
+    "        print(f\"results.tables type: {type(_tables)}, value: {_tables}\")\n",
+    "else:\n",
+    "    print(\"results has no .tables attribute\")\n",
+    "    print(f\"results attrs: {[a for a in dir(results) if not a.startswith('_')]}\")\n",
+    "\n",
+    "\n",
+    "# \u2500\u2500 Surface per-row scorer errors \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "# When mlflow.genai.evaluate prints \"Failure summary: 'X': N/N failed\", the\n",
+    "# actual error messages live in the assessments. Print them inline so we don't\n",
+    "# need to navigate the MLflow UI to root-cause scorer failures.\n",
+    "def _surface_scorer_errors(results):\n",
+    "    try:\n",
+    "        tables = getattr(results, \"tables\", None) or {}\n",
+    "        eval_df = tables.get(\"eval_results\") if isinstance(tables, dict) else None\n",
+    "        if eval_df is None or eval_df.empty:\n",
+    "            return\n",
+    "        err_cols = [c for c in eval_df.columns if c.endswith(\"/error\")]\n",
+    "        if err_cols:\n",
+    "            for c in err_cols:\n",
+    "                errs = eval_df[c].dropna()\n",
+    "                errs = errs[errs.astype(str).str.strip().ne(\"\")]\n",
+    "                if errs.empty:\n",
+    "                    continue\n",
+    "                scorer = c[: -len(\"/error\")]\n",
+    "                print(f\"\\n\\u26a0\\ufe0f  {scorer}: {len(errs)}/{len(eval_df)} rows errored. First 3:\")\n",
+    "                for i, e in errs.head(3).items():\n",
+    "                    print(f\"  row {i}: {str(e)[:320]}\")\n",
+    "            return\n",
+    "        # Fallback: walk an `assessments` / `feedback` list column\n",
+    "        for col in (\"assessments\", \"feedback\"):\n",
+    "            if col not in eval_df.columns:\n",
+    "                continue\n",
+    "            from collections import Counter\n",
+    "            counts, samples = Counter(), {}\n",
+    "            for assess_list in eval_df[col]:\n",
+    "                if not isinstance(assess_list, (list, tuple)):\n",
+    "                    continue\n",
+    "                for a in assess_list:\n",
+    "                    err = getattr(a, \"error\", None)\n",
+    "                    if err is None and isinstance(a, dict):\n",
+    "                        err = a.get(\"error\")\n",
+    "                    if err:\n",
+    "                        name = getattr(a, \"name\", None)\n",
+    "                        if name is None and isinstance(a, dict):\n",
+    "                            name = a.get(\"name\", \"?\")\n",
+    "                        counts[name] += 1\n",
+    "                        samples.setdefault(name, str(err)[:320])\n",
+    "            for name, n in counts.most_common():\n",
+    "                print(f\"\\n\\u26a0\\ufe0f  {name}: {n} row(s) errored. Example: {samples[name]}\")\n",
+    "            break\n",
+    "    except Exception as _se:\n",
+    "        print(f\"(could not surface scorer errors: {_se})\")\n",
+    "\n",
+    "\n",
+    "_surface_scorer_errors(results)\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Inspect Results\n",
+    "\n",
+    "The results table shows one row per question \u00d7 scorer. Use it to identify which questions the supervisor handled poorly and which agents need tuning."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Results as a pandas DataFrame\n",
+    "# Safely access the eval results \u2014 MLflow API shape varies by version\n",
+    "import pandas as _pd\n",
+    "\n",
+    "results_df = _pd.DataFrame()\n",
+    "try:\n",
+    "    if hasattr(results, \"tables\") and isinstance(results.tables, dict):\n",
+    "        results_df = results.tables.get(\"eval_results\", _pd.DataFrame())\n",
+    "        if results_df.empty and results.tables:\n",
+    "            results_df = next(iter(results.tables.values()), _pd.DataFrame())\n",
+    "    elif hasattr(results, \"_results_df\"):\n",
+    "        results_df = results._results_df\n",
+    "    elif hasattr(results, \"to_pandas\"):\n",
+    "        results_df = results.to_pandas()\n",
+    "except Exception as _e:\n",
+    "    print(f\"\u26a0\ufe0f  Could not access eval results table: {_e}\")\n",
+    "\n",
+    "print(f\"Results shape: {results_df.shape}\")\n",
+    "print(f\"Available columns: {results_df.columns.tolist()}\")\n",
+    "\n",
+    "if results_df.empty:\n",
+    "    print(\"\u26a0\ufe0f  Empty results DataFrame \u2014 evaluation may not have completed\")\n",
+    "else:\n",
+    "    # Detect question column\n",
+    "    _q_col = next(\n",
+    "        (c for c in results_df.columns\n",
+    "         if c in (\"inputs/question\", \"request\", \"question\")\n",
+    "         or (c == \"inputs\" and not c.endswith(\"/\"))),\n",
+    "        results_df.columns[0],\n",
+    "    )\n",
+    "    # Detect outputs column\n",
+    "    _out_col = next(\n",
+    "        (c for c in results_df.columns\n",
+    "         if c in (\"outputs\", \"response\", \"output\")),\n",
+    "        None,\n",
+    "    )\n",
+    "    # Scorer columns \u2014 cover both MLflow 2.x and 3.x naming conventions\n",
+    "    _scorer_prefixes = [\"guidelines\", \"expectations_guidelines\", \"correctness\",\n",
+    "                        \"safety\", \"routing\", \"cites\"]\n",
+    "    scorer_cols = [c for c in results_df.columns\n",
+    "                   if any(c.startswith(s) for s in _scorer_prefixes)]\n",
+    "    print(f\"Question col: {_q_col!r} | Outputs col: {_out_col!r} | Scorer cols: {scorer_cols}\")\n",
+    "\n",
+    "    _display_cols = [_q_col] + ([_out_col] if _out_col else []) + scorer_cols\n",
+    "    try:\n",
+    "        display(\n",
+    "            results_df[_display_cols]\n",
+    "            .rename(columns={_q_col: \"question\"})\n",
+    "            .assign(question=lambda df: df[\"question\"].astype(str).str[:80] + \"...\")\n",
+    "        )\n",
+    "    except Exception as _e:\n",
+    "        print(f\"\u26a0\ufe0f  Display failed ({_e}); showing full DataFrame:\")\n",
+    "        display(results_df)\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Score summary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "if not scorer_cols:\n",
+    "    print(\"\u26a0\ufe0f  No scorer columns found \u2014 check column names above\")\n",
+    "else:\n",
+    "    numeric_scorer_cols = [c for c in scorer_cols if \"score\" in c or \"value\" in c.lower()]\n",
+    "    if not numeric_scorer_cols:\n",
+    "        numeric_scorer_cols = scorer_cols\n",
+    "\n",
+    "    try:\n",
+    "        summary = results_df[numeric_scorer_cols].apply(\n",
+    "            lambda col: _pd.to_numeric(col, errors=\"coerce\")\n",
+    "        ).agg([\"mean\", \"min\", \"max\"]).T\n",
+    "        summary.columns = [\"mean\", \"min\", \"max\"]\n",
+    "        summary[\"mean\"] = summary[\"mean\"].round(3)\n",
+    "        print(\"Scorer summary (higher = better):\")\n",
+    "        display(summary.sort_values(\"mean\"))\n",
+    "    except Exception as _e:\n",
+    "        print(f\"\u26a0\ufe0f  Summary failed ({_e})\")\n",
+    "        display(results_df[numeric_scorer_cols])\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Flag failing questions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "# Questions where the cites_specific_data score is 0 indicate the agent\n",
+    "# probably failed to retrieve data (hedged response with no numbers).\n",
+    "\n",
+    "cites_col = next((c for c in scorer_cols if \"cites\" in c), None)\n",
+    "if cites_col:\n",
+    "    failing = results_df[results_df[cites_col] < 0.3][[_q_col, cites_col]]\n",
+    "    if len(failing):\n",
+    "        print(f\"\u26a0\ufe0f  {len(failing)} question(s) returned hedged/empty responses:\")\n",
+    "        for _, row in failing.iterrows():\n",
+    "            _q_val = row[_q_col]\n",
+    "            if isinstance(_q_val, dict):\n",
+    "                _q_val = _q_val.get(\"question\", str(_q_val))\n",
+    "            print(f\"  - {str(_q_val)[:100]}\")\n",
+    "    else:\n",
+    "        print(\"\u2705 All questions returned data-backed responses\")"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Build an Evaluation Dataset from Production Traces\n",
+    "\n",
+    "In addition to a curated dataset, you can harvest **real operator questions** from production traces and turn them into an evaluation dataset. This is the recommended workflow for continuous quality monitoring:\n",
+    "\n",
+    "```\n",
+    "Production traffic \u2192 MLflow traces \u2192 filter interesting traces \u2192 add ground truth \u2192 eval dataset\n",
+    "```\n",
+    "\n",
+    "The Operational Supervisor endpoint automatically writes traces to MLflow \u2014 no instrumentation code needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Production traces auto-log to the same managed experiment we set in cell 3\n",
+    "# (/Users/{user}/{mas_id}-dev-experiment).  The eval runs above are tagged with\n",
+    "# eval_run_id; production traces have no eval_run_id, so we filter on that.\n",
+    "\n",
+    "_exp = mlflow.get_experiment_by_name(EVAL_EXPERIMENT_NAME)\n",
+    "if _exp is not None:\n",
+    "    experiment_id = _exp.experiment_id\n",
+    "    print(f\"Production traces experiment: {EVAL_EXPERIMENT_NAME} ({experiment_id})\")\n",
+    "else:\n",
+    "    experiment_id = None\n",
+    "    print(f\"\u26a0\ufe0f  Experiment {EVAL_EXPERIMENT_NAME} not found.\")\n",
+    "    print(\"  Run the cells above to fire the first supervisor traces.\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "if experiment_id:\n",
+    "    # \u2500\u2500 Fetch recent traces \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "    # Use the MLflow search_traces API to pull recent successful traces.\n",
+    "    # Filter: only OK status (skip errors), limit to last 50 traces.\n",
+    "    #\n",
+    "    # NOTE: mlflow.search_traces() returns a *pandas DataFrame* by default, not\n",
+    "    # a list of Trace objects. The DataFrame already has `request`/`response`\n",
+    "    # columns extracted from the root span, so we don\\'t need to dig into\n",
+    "    # `trace.data.spans` ourselves. Iterating with iterrows() is the correct\n",
+    "    # pattern; iterating `for x in df:` would walk column names instead of rows.\n",
+    "\n",
+    "    traces_df_raw = mlflow.search_traces(\n",
+    "        experiment_ids=[experiment_id],\n",
+    "        filter_string=\"status = \\'OK\\'\",\n",
+    "        max_results=50,\n",
+    "        order_by=[\"timestamp DESC\"],\n",
+    "    )\n",
+    "\n",
+    "    print(f\"Found {len(traces_df_raw)} traces from the Operational Supervisor experiment\")\n",
+    "\n",
+    "    # \u2500\u2500 Extract inputs and outputs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "    trace_records = []\n",
+    "    if len(traces_df_raw) > 0:\n",
+    "        for _, row in traces_df_raw.iterrows():\n",
+    "            try:\n",
+    "                # Columns are documented at:\n",
+    "                # https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.search_traces\n",
+    "                # `request` and `response` are JSON-encoded strings of the root span\\'s\n",
+    "                # inputs/outputs respectively. Both Chat Completions ({\"messages\": [...]})\n",
+    "                # and Responses API ({\"input\": [...]}) shapes appear in practice.\n",
+    "                request_raw = row.get(\"request\")\n",
+    "                response_raw = row.get(\"response\")\n",
+    "\n",
+    "                inputs_raw = (\n",
+    "                    _json.loads(request_raw)\n",
+    "                    if isinstance(request_raw, str) and request_raw.strip()\n",
+    "                    else (request_raw or {})\n",
+    "                )\n",
+    "                outputs_raw = (\n",
+    "                    _json.loads(response_raw)\n",
+    "                    if isinstance(response_raw, str) and response_raw.strip()\n",
+    "                    else (response_raw or {})\n",
+    "                )\n",
+    "\n",
+    "                # Find the user\\'s question across both API shapes.\n",
+    "                messages = inputs_raw.get(\"messages\") or inputs_raw.get(\"input\") or []\n",
+    "                question = next(\n",
+    "                    (m.get(\"content\") for m in messages if m.get(\"role\") == \"user\"),\n",
+    "                    None\n",
+    "                )\n",
+    "\n",
+    "                # Extract assistant\\'s response text via the existing helper.\n",
+    "                response_text = _extract_text(outputs_raw)\n",
+    "\n",
+    "                if question and response_text:\n",
+    "                    trace_records.append({\n",
+    "                        \"trace_id\": row.get(\"trace_id\") or row.get(\"request_id\") or \"?\",\n",
+    "                        \"timestamp\": row.get(\"timestamp_ms\"),\n",
+    "                        \"latency_ms\": row.get(\"execution_time_ms\"),\n",
+    "                        \"question\": question,\n",
+    "                        \"response\": response_text[:500],\n",
+    "                    })\n",
+    "            except Exception as _te:\n",
+    "                tid = row.get(\"trace_id\") or row.get(\"request_id\") or \"?\"\n",
+    "                print(f\"  \\u26a0\\ufe0f  Skipped trace {tid}: {_te}\")\n",
+    "                continue\n",
+    "\n",
+    "    traces_df = pd.DataFrame(trace_records)\n",
+    "    print(f\"\\nExtracted {len(traces_df)} valid question/response pairs\")\n",
+    "    if not traces_df.empty:\n",
+    "        display(traces_df[[\"question\", \"latency_ms\", \"response\"]].head(10))\n",
+    "    else:\n",
+    "        print(\"No valid traces extracted yet \u2014 send some questions through the Operational Dashboard app, then re-run this section.\")\n",
+    "else:\n",
+    "    print(\"Skipping trace fetch \u2014 no experiment found yet.\")\n",
+    "    traces_df = pd.DataFrame()\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "trace_eval_data = []\n",
+    "\n",
+    "if not traces_df.empty:\n",
+    "    # \u2500\u2500 Identify slow traces \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "    # Questions that took > 60s may indicate routing to a cold endpoint or a\n",
+    "    # hard question that caused agent confusion.\n",
+    "    slow_threshold_ms = 60_000\n",
+    "    slow = traces_df[traces_df[\"latency_ms\"] > slow_threshold_ms].copy()\n",
+    "    print(f\"Slow traces (>{slow_threshold_ms/1000:.0f}s): {len(slow)}\")\n",
+    "    if not slow.empty:\n",
+    "        display(slow[[\"question\", \"latency_ms\"]].sort_values(\"latency_ms\", ascending=False))\n",
+    "\n",
+    "    # \u2500\u2500 Build evaluation dataset from traces \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "    # Real operator questions \u2014 no per-row guidelines.\n",
+    "    # A global guideline is passed to Guidelines() at eval time (cell below).\n",
+    "    trace_eval_data = [\n",
+    "        {\"inputs\": {\"question\": row[\"question\"]}}\n",
+    "        for _, row in traces_df.head(20).iterrows()\n",
+    "    ]\n",
+    "\n",
+    "    print(f\"\\nTrace-derived evaluation dataset: {len(trace_eval_data)} records\")\n",
+    "    print(\"Sample question:\", trace_eval_data[0][\"inputs\"][\"question\"][:100])\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# Global quality bar applied to every trace-derived question.\n",
+    "# Guidelines() applies the same criteria to all rows \u2014 correct for\n",
+    "# unsupervised traffic where we have no per-question expected behaviour.\n",
+    "_TRACE_GUIDELINE = (\n",
+    "    \"Response must include specific data points (numbers, locations, dates, or names). \"\n",
+    "    \"Response must not be a generic hedge or refusal. \"\n",
+    "    \"Response must be directly relevant to the question asked.\"\n",
+    ")\n",
+    "\n",
+    "if not traces_df.empty and trace_eval_data:\n",
+    "    with mlflow.start_run(run_name=f\"{_mas_id}-dev-trace-experiment\"):\n",
+    "        mlflow.log_param(\"prompt_uri\", SUPERVISOR_PROMPT_URI)\n",
+    "        mlflow.log_param(\"prompt_version\", SUPERVISOR_PROMPT_VERSION)\n",
+    "        trace_results = mlflow.genai.evaluate(\n",
+    "            predict_fn=predict_fn,\n",
+    "            data=trace_eval_data,\n",
+    "            scorers=[\n",
+    "                Guidelines(guidelines=_TRACE_GUIDELINE),\n",
+    "                *([RelevanceToQuery()] if _has_relevance else []),\n",
+    "                Safety(),\n",
+    "                routing_accuracy,\n",
+    "                cites_specific_data,\n",
+    "            ],\n",
+    "        )\n",
+    "\n",
+    "    print(\"\\u2705 Trace-based evaluation complete\")\n",
+    "    try:\n",
+    "        _tr_df = trace_results.tables.get(\"eval_results\") if isinstance(\n",
+    "            getattr(trace_results, \"tables\", None), dict\n",
+    "        ) else None\n",
+    "        display(_tr_df if _tr_df is not None else trace_results)\n",
+    "    except Exception as _e:\n",
+    "        print(f\"\\u26a0\\ufe0f  Could not display trace results ({_e})\")\n",
+    "else:\n",
+    "    print(\"Skipping trace evaluation \u2014 no trace data available.\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. Comparing Runs\n",
+    "\n",
+    "Use the MLflow Experiments UI to compare runs. The two runs created by this notebook are:\n",
+    "\n",
+    "| Run | Dataset | What it tells you |\n",
+    "|---|---|---|\n",
+    "| `operational-supervisor-full-eval` | 10 curated Q&A pairs with ground truth | How well the supervisor handles the demo script questions |\n",
+    "| `operational-supervisor-trace-eval` | Real operator questions from production traces | General quality over real traffic |\n",
+    "\n",
+    "### How to interpret the scorer results\n",
+    "\n",
+    "| Score | Meaning | Action |\n",
+    "|---|---|---|\n",
+    "| `guidelines` < 0.5 | Answer doesn't satisfy the stated criteria | Improve the sub-agent's `instructions` in `knowledge_agents.ipynb` or the supervisor's `instructions` in `operational_supervisor.ipynb` |\n",
+    "| `correctness` < 0.5 | Factually wrong or hallucinated answer | Check the document corpus in the UC Volume \u2014 documents may be missing or outdated |\n",
+    "| `routing_accuracy` < 0.5 | MAS routed to the wrong agent | Improve the `description` field for that sub-agent in `operational_supervisor.ipynb` |\n",
+    "| `cites_specific_data` = 0.0 | Hedged/empty response | Sub-agent had a retrieval failure \u2014 check endpoint status and UC Volume contents |\n",
+    "| `safety` < 1.0 | Potentially harmful content in response | Review the full response \u2014 this is rare but warrants investigation |\n",
+    "\n",
+    "### Finding low-quality traces to fix\n",
+    "\n",
+    "```python\n",
+    "# Find all traces where the agent failed to cite specific data\n",
+    "mlflow.search_traces(\n",
+    "    experiment_ids=[experiment_id],\n",
+    "    filter_string=\"status = 'OK'\",\n",
+    "    max_results=100,\n",
+    ")\n",
+    "# Then tag the failing ones for your eval dataset:\n",
+    "# mlflow.update_trace(request_id=trace_id, tags={\"quality\": \"low\", \"issue\": \"no-data\"})\n",
+    "```\n",
+    "\n",
+    "### Next steps\n",
+    "\n",
+    "1. **MemAlign** \u2014 after running this notebook, use `mlflow.genai.align()` to calibrate the `Guidelines` judge to match your specific definition of a good operational response\n",
+    "2. **Production monitoring** \u2014 link the MAS experiment to a Unity Catalog table and set up a scheduled evaluation job to track quality over time\n",
+    "3. **Prompt optimization** \u2014 use `mlflow.genai.optimize_prompts()` with the evaluation dataset to automatically improve the supervisor's `instructions` based on failing scores"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Quick link to MLflow Experiments UI \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "ctx = dbutils.notebook.entry_point.getDbutils().notebook().getContext()\n",
+    "host = ctx.apiUrl().get()\n",
+    "try:\n",
+    "    _exp = mlflow.get_experiment_by_name(EVAL_EXPERIMENT_NAME)\n",
+    "    exp_id = _exp.experiment_id if _exp else None\n",
+    "except Exception:\n",
+    "    exp_id = None\n",
+    "if exp_id:\n",
+    "    print(f\"View results in MLflow:\")\n",
+    "    print(f\"   {host}/ml/experiments/{exp_id}\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 9. Register Production Scorers (continuous sampling)\n",
+    "\n",
+    "The `evaluate()` runs above are one-shot, but the dashboard also needs continuous quality monitoring on every live trace.  This section registers the same scorers via `Scorer.register()` + `Scorer.start()` against the managed Agent Bricks experiments \u2014 so every production request gets graded automatically.\n",
+    "\n",
+    "- **Supervisor:** `/Users/{user}/{mas_id}-dev-experiment` (same experiment as the `evaluate()` runs above).\n",
+    "- **KAs:** the per-tile experiment exposed as `tile.mlflow_experiment_id` from the tile API. No path construction \u2014 we read the id directly from the tile.\n",
+    "\n",
+    "Covers the **Operational Supervisor** and all **6 Knowledge Assistants**.  Refund + Complaint custom agents are scored by their own stage notebooks (`stages/refund_evaluation.ipynb`, `stages/complaint_evaluation.ipynb`).\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Shared helpers for production scorer registration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "from mlflow.genai.scorers import Safety, RelevanceToQuery, Guidelines, ScorerSamplingConfig\n",
+    "from mlflow.genai import get_scorer\n",
+    "import time as _time_reg\n",
+    "\n",
+    "try:\n",
+    "    from mlflow.genai.scorers import RetrievalGroundedness\n",
+    "    _HAS_RG = True\n",
+    "except ImportError:\n",
+    "    RetrievalGroundedness = None\n",
+    "    _HAS_RG = False\n",
+    "    print(\"\u26a0\ufe0f  RetrievalGroundedness not available \u2014 KAs will get 4 scorers instead of 5\")\n",
+    "\n",
+    "\n",
+    "def _register_scorer_on(exp_id: str, scorer_obj, name: str, sample_rate: float = 1.0):\n",
+    "    \"\"\"Register + start a scorer on the given experiment id, robust against the\n",
+    "    eventual-consistency window between register() and start() on the Databricks\n",
+    "    side that occasionally surfaces as `ValueError: No registered scorer found`.\"\"\"\n",
+    "    sampling = ScorerSamplingConfig(sample_rate=sample_rate)\n",
+    "\n",
+    "    def _server_get():\n",
+    "        try:\n",
+    "            return get_scorer(name=name, experiment_id=exp_id)\n",
+    "        except Exception:\n",
+    "            return None\n",
+    "\n",
+    "    target = _server_get()\n",
+    "    action = \"restarted\" if target is not None else \"registered\"\n",
+    "    if target is None:\n",
+    "        target = scorer_obj.register(name=name, experiment_id=exp_id)\n",
+    "\n",
+    "    last_err = None\n",
+    "    for attempt in range(4):\n",
+    "        try:\n",
+    "            target.start(name=name, experiment_id=exp_id, sampling_config=sampling)\n",
+    "            icon = \"\u2705\" if action == \"registered\" else \"\u21ba\"\n",
+    "            print(f\"  {icon} {name} \u2014 {action} at {sample_rate:.0%}\")\n",
+    "            return target\n",
+    "        except Exception as ve:\n",
+    "            if \"No registered scorer\" not in str(ve):\n",
+    "                raise\n",
+    "            last_err = ve\n",
+    "            wait_s = (attempt + 1) * 2\n",
+    "            print(f\"  \u23f3  {name} not yet visible (attempt {attempt + 1}/4) \u2014 waiting {wait_s}s\")\n",
+    "            _time_reg.sleep(wait_s)\n",
+    "            refetched = _server_get()\n",
+    "            if refetched is not None:\n",
+    "                target = refetched\n",
+    "            else:\n",
+    "                target = scorer_obj.register(name=name, experiment_id=exp_id)\n",
+    "                action = \"registered\"\n",
+    "    raise last_err if last_err else RuntimeError(f\"Could not start scorer {name!r}\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Supervisor scorers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "# Same managed experiment used for evaluate() runs above (/Users/{user}/{mas_id}-dev-experiment).\n",
+    "print(f\"Registering scorers on: {EVAL_EXPERIMENT_NAME}\\n\")\n",
+    "\n",
+    "_SUP_EXP_ID = mlflow.get_experiment_by_name(EVAL_EXPERIMENT_NAME).experiment_id\n",
+    "\n",
+    "_register_scorer_on(_SUP_EXP_ID, Safety(),           name=\"safety\",             sample_rate=1.0)\n",
+    "_register_scorer_on(_SUP_EXP_ID, RelevanceToQuery(), name=\"relevance_to_query\", sample_rate=1.0)\n",
+    "_register_scorer_on(\n",
+    "    _SUP_EXP_ID,\n",
+    "    Guidelines(\n",
+    "        guidelines=(\n",
+    "            \"The response must include specific data points such as numbers, percentages, \"\n",
+    "            \"dates, case numbers, or named locations. \"\n",
+    "            \"The response must not be a generic hedge or refusal (e.g. 'I don\\'t have access'). \"\n",
+    "            \"The response must directly answer the question asked.\"\n",
+    "        ),\n",
+    "    ),\n",
+    "    name=\"operational_quality\",\n",
+    "    sample_rate=1.0,\n",
+    ")\n",
+    "_register_scorer_on(_SUP_EXP_ID, routing_accuracy,    name=\"routing_accuracy\",    sample_rate=1.0)\n",
+    "_register_scorer_on(_SUP_EXP_ID, cites_specific_data, name=\"cites_specific_data\", sample_rate=1.0)\n",
+    "\n",
+    "print(f\"\\n\u2705 Supervisor scorers active on {EVAL_EXPERIMENT_NAME}\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "# \u2500\u2500 Knowledge Assistant scorers (loop over all KAs from uc_state) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n",
+    "# Each KA tile owns a managed MLflow experiment exposed by the tile API as\n",
+    "# `mlflow_experiment_id`.  That's the default experiment Databricks created for\n",
+    "# the tile \u2014 no /Serving/ companion, no path construction.  We fetch the id\n",
+    "# directly from the tile and register scorers against it.\n",
+    "import json as _json_ka\n",
+    "\n",
+    "_KA_QUALITY = (\n",
+    "    \"The response must directly answer the question with concrete information from the document corpus. \"\n",
+    "    \"It must not be a generic refusal or 'I don\\'t have access' hedge. \"\n",
+    "    \"It must reference specific documents, IDs, dates, or numbers when relevant.\"\n",
+    ")\n",
+    "_KA_CITES_SOURCE = (\n",
+    "    \"The response must cite at least one specific source from the document corpus \u2014 \"\n",
+    "    \"for example a document ID, report date, case number (e.g. CK-XX-XXXX), permit ID, \"\n",
+    "    \"audit ID, location name, or brand name. A response that paraphrases without citation fails.\"\n",
+    ")\n",
+    "\n",
+    "\n",
+    "def _ka_experiment_id(tile_id: str):\n",
+    "    \"\"\"Return the KA tile's managed MLflow experiment id, or None if missing.\"\"\"\n",
+    "    if not tile_id:\n",
+    "        return None\n",
+    "    try:\n",
+    "        tile = w.api_client.do(\"GET\", f\"/api/2.0/tiles/{tile_id}\")\n",
+    "        eid = tile.get(\"mlflow_experiment_id\")\n",
+    "        return str(eid) if eid else None\n",
+    "    except Exception as e:\n",
+    "        print(f\"     tile API lookup failed: {e}\")\n",
+    "        return None\n",
+    "\n",
+    "\n",
+    "def _register_ka_scorers(exp_id: str):\n",
+    "    summary = []\n",
+    "    _register_scorer_on(exp_id, Safety(),           name=\"safety\",             sample_rate=1.0); summary.append(\"safety\")\n",
+    "    _register_scorer_on(exp_id, RelevanceToQuery(), name=\"relevance_to_query\", sample_rate=1.0); summary.append(\"relevance_to_query\")\n",
+    "    if _HAS_RG:\n",
+    "        _register_scorer_on(exp_id, RetrievalGroundedness(), name=\"retrieval_groundedness\", sample_rate=1.0); summary.append(\"retrieval_groundedness\")\n",
+    "    _register_scorer_on(exp_id, Guidelines(guidelines=_KA_CITES_SOURCE), name=\"cites_source\", sample_rate=1.0); summary.append(\"cites_source\")\n",
+    "    _register_scorer_on(exp_id, Guidelines(guidelines=_KA_QUALITY),      name=\"ka_quality\",   sample_rate=1.0); summary.append(\"ka_quality\")\n",
+    "    return summary\n",
+    "\n",
+    "\n",
+    "_ka_rows = []\n",
+    "try:\n",
+    "    _ka_rows = spark.sql(f\"\"\"\n",
+    "        SELECT resource_data\n",
+    "        FROM {CATALOG}._internal_state.resources\n",
+    "        WHERE resource_type = 'knowledge_assistants'\n",
+    "        ORDER BY created_at DESC\n",
+    "    \"\"\").collect()\n",
+    "except Exception as _e:\n",
+    "    print(f\"\u26a0\ufe0f  Could not list KAs from uc_state: {_e}\")\n",
+    "\n",
+    "_seen, _ka_results = set(), []\n",
+    "for _row in _ka_rows:\n",
+    "    _info = _json_ka.loads(_row.resource_data)\n",
+    "    _dn = _info.get(\"name\", \"\")\n",
+    "    _tid = _info.get(\"tile_id\", \"\")\n",
+    "    if not _tid or _tid in _seen:\n",
+    "        continue\n",
+    "    _seen.add(_tid)\n",
+    "    print(f\"\\n\ud83e\udde0 {_dn} (tile={_tid})\")\n",
+    "    _exp_id = _ka_experiment_id(_tid)\n",
+    "    if _exp_id is None:\n",
+    "        print(f\"   \u23ed   tile {_tid} has no mlflow_experiment_id \u2014 skipping\")\n",
+    "        _ka_results.append((_dn, _tid, None))\n",
+    "        continue\n",
+    "    print(f\"   experiment_id: {_exp_id}\")\n",
+    "    summary = _register_ka_scorers(_exp_id)\n",
+    "    print(f\"   \u2705 {len(summary)} scorers active: {', '.join(summary)}\")\n",
+    "    _ka_results.append((_dn, _tid, summary))\n",
+    "\n",
+    "print(f\"\\n\u2705 KA scorer registration complete \u2014 {sum(1 for r in _ka_results if r[2] is not None)}/{len(_ka_results)} KAs scored\")\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/stages/operational_lakebase.ipynb b/stages/operational_lakebase.ipynb
new file mode 100644
index 0000000..bd81094
--- /dev/null
+++ b/stages/operational_lakebase.ipynb
@@ -0,0 +1,199 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Operational Lakebase \u2014 sessions DB on shared project\n",
+        "\n",
+        "Creates the **`caspers_ops`** logical Postgres database inside the shared\n",
+        "`${CATALOG}-caspers` Lakebase Autoscaling project (provisioned by\n",
+        "`stages/lakebase_project.ipynb`), then creates the `sessions` and `messages`\n",
+        "tables that back the Operational Dashboard app's chat history.\n",
+        "\n",
+        "The project creator (the deploying user) is automatically granted superuser\n",
+        "in every database in the project, so the DDL below runs cleanly without any\n",
+        "explicit GRANT."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade \"databricks-sdk>=0.81.0\" \"psycopg[binary]>=3.0\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re, sys\n",
+        "sys.path.append('../utils')\n",
+        "from lakebase_autoscale import get_or_create_postgres_database\n",
+        "import status\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "PROJECT_ID = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}-caspers\".lower())\n",
+        "PROJECT_RESOURCE_NAME = f\"projects/{PROJECT_ID}\"\n",
+        "BRANCH_PATH = f\"{PROJECT_RESOURCE_NAME}/branches/production\"\n",
+        "ENDPOINT_PATH = f\"{BRANCH_PATH}/endpoints/primary\"\n",
+        "\n",
+        "# Lakebase Autoscale requires DNS-safe names (no underscores).\n",
+        "POSTGRES_DB = \"caspers-ops\"\n",
+        "\n",
+        "print(f\"CATALOG        = {CATALOG}\")\n",
+        "print(f\"PROJECT_ID     = {PROJECT_ID}\")\n",
+        "print(f\"ENDPOINT_PATH  = {ENDPOINT_PATH}\")\n",
+        "print(f\"POSTGRES_DB    = {POSTGRES_DB}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Ensure the per-component Postgres database exists"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "db, created = get_or_create_postgres_database(\n",
+        "    w,\n",
+        "    project_id=PROJECT_ID,\n",
+        "    database_id=POSTGRES_DB,\n",
+        ")\n",
+        "if created:\n",
+        "    status.ok(f\"Created Postgres database {POSTGRES_DB} in {PROJECT_ID}\")\n",
+        "else:\n",
+        "    status.reuse(f\"Reusing Postgres database {POSTGRES_DB} in {PROJECT_ID}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Connect and create session tables"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import psycopg\n",
+        "\n",
+        "ep = w.postgres.get_endpoint(name=ENDPOINT_PATH)\n",
+        "host = ep.status.hosts.host\n",
+        "user = w.current_user.me().user_name\n",
+        "\n",
+        "cred = w.postgres.generate_database_credential(endpoint=ENDPOINT_PATH)\n",
+        "\n",
+        "conn_str = (\n",
+        "    f\"host={host} dbname={POSTGRES_DB} user={user} \"\n",
+        "    f\"password={cred.token} sslmode=require\"\n",
+        ")\n",
+        "\n",
+        "# Project creator has superuser \u2014 CREATE TABLE works without any GRANT.\n",
+        "STATEMENTS = [\n",
+        "    \"CREATE TABLE IF NOT EXISTS sessions (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), title TEXT NOT NULL DEFAULT 'New Session', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW())\",\n",
+        "    \"CREATE TABLE IF NOT EXISTS messages (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE, role TEXT NOT NULL CHECK (role IN ('user', 'assistant')), content TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), documents_referenced JSONB DEFAULT '[]'::jsonb)\",\n",
+        "    \"CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at)\",\n",
+        "    \"CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at DESC)\",\n",
+        "]\n",
+        "\n",
+        "with psycopg.connect(conn_str) as conn:\n",
+        "    with conn.cursor() as cur:\n",
+        "        for stmt in STATEMENTS:\n",
+        "            cur.execute(stmt)\n",
+        "    conn.commit()\n",
+        "\n",
+        "status.ok(f\"Tables ready in {PROJECT_ID}/{POSTGRES_DB}\")\n",
+        "print(f\"   Host: {host}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "status.ok(\"Operational Lakebase stage complete\")\n",
+        "print(f\"   Project:     {PROJECT_RESOURCE_NAME}\")\n",
+        "print(f\"   Endpoint:    {ENDPOINT_PATH}\")\n",
+        "print(f\"   Postgres DB: {POSTGRES_DB}\")\n",
+        "print(f\"   Host:        {host}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": {
+        "base_environment": "",
+        "environment_version": "3"
+      },
+      "inputWidgetPreferences": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 4
+      },
+      "notebookName": "operational_lakebase",
+      "widgets": {
+        "CATALOG": {
+          "currentValue": "",
+          "nuid": "operational-lakebase-catalog",
+          "typedWidgetInfo": {
+            "autoCreated": false,
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "validationRegex": null,
+              "widgetDisplayType": "Text"
+            },
+            "parameterDataType": "String"
+          },
+          "widgetInfo": {
+            "defaultValue": "",
+            "label": "",
+            "name": "CATALOG",
+            "options": {
+              "autoCreated": false,
+              "validationRegex": null,
+              "widgetType": "text"
+            },
+            "widgetType": "text"
+          }
+        }
+      }
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
diff --git a/stages/operational_readiness_check.ipynb b/stages/operational_readiness_check.ipynb
new file mode 100644
index 0000000..fb97f4d
--- /dev/null
+++ b/stages/operational_readiness_check.ipynb
@@ -0,0 +1,355 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Readiness Check\n",
+        "\n",
+        "Final gate in the Casper's Initializer job. Polls until:\n",
+        "- All 6 Knowledge Assistants (legal, regulatory, audits, consultancy, inspection, menu) are ONLINE and have finished syncing their documents\n",
+        "- The Operational Supervisor (MAS) serving endpoint is READY\n",
+        "- All 6 UC volumes contain at least one PDF\n",
+        "\n",
+        "Fails the job if any resource is not ready within the timeout."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk\n",
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time, json as _json\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "KA_API  = \"/api/2.1/knowledge-assistants\"\n",
+        "# /api/2.0/multi-agent-supervisors only supports per-resource ops; listing requires v2.1\n",
+        "MAS_API = \"/api/2.0/multi-agent-supervisors\"\n",
+        "MAS_LIST_API = \"/api/2.1/supervisor-agents\"\n",
+        "EP_API  = \"/api/2.0/serving-endpoints\"\n",
+        "\n",
+        "POLL_INTERVAL_S = 20\n",
+        "MAX_POLLS       = 60\n",
+        "\n",
+        "EXPECTED_KA_NAMES = [\n",
+        "    f\"{CATALOG}-legal\",\n",
+        "    f\"{CATALOG}-regulatory\",\n",
+        "    f\"{CATALOG}-audits\",\n",
+        "    f\"{CATALOG}-consultancy\",\n",
+        "    f\"{CATALOG}-inspection-knowledge\",\n",
+        "    f\"{CATALOG}-menu-knowledge\",\n",
+        "]\n",
+        "MAS_NAME = f\"{CATALOG}-operational-supervisor\"\n",
+        "\n",
+        "\n",
+        "def _paginate(api_path, list_key):\n",
+        "    items, params = [], {}\n",
+        "    try:\n",
+        "        while True:\n",
+        "            resp = w.api_client.do(\"GET\", api_path, query=params)\n",
+        "            found = resp.get(list_key)\n",
+        "            if found is None:\n",
+        "                found = next((v for v in resp.values() if isinstance(v, list)), [])\n",
+        "            items.extend(found or [])\n",
+        "            token = resp.get(\"next_page_token\")\n",
+        "            if not token:\n",
+        "                break\n",
+        "            params = {\"page_token\": token}\n",
+        "    except Exception as e:\n",
+        "        print(f\"  \\u26a0\\ufe0f  {api_path} error: {e}\")\n",
+        "        if items:\n",
+        "            print(f\"       Partial results only \\u2014 {len(items)} item(s) retrieved before failure; IDs will be re-validated\")\n",
+        "    return items\n",
+        "\n",
+        "def _list_kas():    return _paginate(KA_API, \"knowledge_assistants\")\n",
+        "def _list_mas():    return _paginate(MAS_LIST_API, \"supervisor_agents\")\n",
+        "def _list_tiles():  return _paginate(\"/api/2.0/tiles\", \"tiles\")\n",
+        "\n",
+        "def _ka_id_from_item(item):\n",
+        "    # v2.1 KAs are flat dicts with `id`. The old v2.0 wrapping (`knowledge_assistant`\n",
+        "    # key, `tile_id` field) is kept here as a fallback in case a KA was created via\n",
+        "    # the legacy v2.0 endpoint and surfaces through the Tiles API.\n",
+        "    ka = item.get(\"knowledge_assistant\", item)\n",
+        "    return ka.get(\"id\") or item.get(\"tile_id\") or ka.get(\"tile_id\")\n",
+        "\n",
+        "\n",
+        "def _ka_name_from_item(item):\n",
+        "    # v2.1 uses `display_name`; v2.0 used `name`. The v2.1 `name` field is the\n",
+        "    # resource path \"knowledge-assistants/{id}\" and is NOT the user-facing name.\n",
+        "    ka = item.get(\"knowledge_assistant\", item)\n",
+        "    return ka.get(\"display_name\") or ka.get(\"name\") or \"\"\n",
+        "\n",
+        "\n",
+        "# ── Source 1: uc_state (KA notebook writes correct IDs here) ──────────────────\n",
+        "ka_by_name = {}\n",
+        "mas_endpoint = \"\"\n",
+        "try:\n",
+        "    rows = spark.sql(f\"\"\"\n",
+        "        SELECT resource_type, resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type IN ('knowledge_assistants', 'multi_agent_supervisors')\n",
+        "        ORDER BY created_at DESC\n",
+        "    \"\"\").collect()\n",
+        "    seen = set()\n",
+        "    for row in rows:\n",
+        "        info = _json.loads(row.resource_data)\n",
+        "        name = info.get(\"name\", \"\")\n",
+        "        tid  = info.get(\"tile_id\", \"\")\n",
+        "        if row.resource_type == \"knowledge_assistants\" and name in EXPECTED_KA_NAMES and name not in seen and tid:\n",
+        "            ka_by_name[name] = tid\n",
+        "            seen.add(name)\n",
+        "        elif row.resource_type == \"multi_agent_supervisors\" and not mas_endpoint:\n",
+        "            mas_endpoint = info.get(\"endpoint_name\", \"\")\n",
+        "    print(f\"uc_state: {len(ka_by_name)} KA(s), MAS endpoint={mas_endpoint or '(none)'}\")\n",
+        "except Exception as e:\n",
+        "    print(f\"uc_state unavailable: {e}\")\n",
+        "\n",
+        "# ── Source 2: KA API (prints display_names so we can see what's there) ────────\n",
+        "all_kas = _list_kas()\n",
+        "print(f\"\\nKA API returned {len(all_kas)} item(s)\")\n",
+        "for item in all_kas:\n",
+        "    ka = item.get(\"knowledge_assistant\", item)\n",
+        "    dn = _ka_name_from_item(item)\n",
+        "    kid = _ka_id_from_item(item)\n",
+        "    print(f\"  display_name={dn!r}  id={kid!r}  ep={ka.get('endpoint_name')!r}\")\n",
+        "    if dn in EXPECTED_KA_NAMES and dn not in ka_by_name and kid:\n",
+        "        ka_by_name[dn] = kid\n",
+        "\n",
+        "# ── Source 3: tiles API ────────────────────────────────────────────────────────\n",
+        "all_tiles = _list_tiles()\n",
+        "print(f\"\\nTiles API returned {len(all_tiles)} item(s)\")\n",
+        "for tile in all_tiles:\n",
+        "    n = tile.get(\"name\", \"\")\n",
+        "    if n in EXPECTED_KA_NAMES or n == MAS_NAME:\n",
+        "        tid = tile.get(\"tile_id\") or tile.get(\"id\")\n",
+        "        ep  = tile.get(\"serving_endpoint_name\") or tile.get(\"endpoint_name\", \"\")\n",
+        "        print(f\"  name={n!r}  tile_id={tid!r}  ep={ep!r}\")\n",
+        "        if n in EXPECTED_KA_NAMES and n not in ka_by_name and tid:\n",
+        "            ka_by_name[n] = tid\n",
+        "        if n == MAS_NAME and not mas_endpoint and ep:\n",
+        "            mas_endpoint = ep\n",
+        "\n",
+        "# ── MAS: also try SupervisorAgents v2.1 list API ─────────────────────────────\n",
+        "if not mas_endpoint:\n",
+        "    for sa in _list_mas():\n",
+        "        # v2.1 items are flat dicts. `display_name` = user-facing name; `name` = resource path.\n",
+        "        if sa.get(\"display_name\") == MAS_NAME or sa.get(\"name\") == MAS_NAME:\n",
+        "            mas_endpoint = sa.get(\"endpoint_name\", \"\")\n",
+        "            break\n",
+        "\n",
+        "# ── Validate collected KA IDs — UC state can be stale after KA recreation ─────\n",
+        "# Call GET /{id} for each resolved ID; any that 404 are stale and need to be\n",
+        "# re-resolved from the tiles API (which always reflects current state).\n",
+        "_stale_kas = []\n",
+        "for _name, _tid in list(ka_by_name.items()):\n",
+        "    try:\n",
+        "        w.api_client.do(\"GET\", f\"{KA_API}/{_tid}\")\n",
+        "    except Exception:\n",
+        "        print(f\"  ⚠️  {_name}: tile_id {_tid!r} is stale — will re-resolve via Tiles API\")\n",
+        "        _stale_kas.append(_name)\n",
+        "\n",
+        "if _stale_kas:\n",
+        "    for _tile in _list_tiles():\n",
+        "        _n = _tile.get(\"name\", \"\")\n",
+        "        if _n in _stale_kas:\n",
+        "            _new_tid = _tile.get(\"tile_id\") or _tile.get(\"id\")\n",
+        "            if _new_tid:\n",
+        "                ka_by_name[_n] = _new_tid\n",
+        "                _stale_kas.remove(_n)\n",
+        "                print(f\"  ✅ Re-resolved {_n} → {_new_tid}\")\n",
+        "    if _stale_kas:\n",
+        "        raise RuntimeError(\n",
+        "            f\"Could not re-resolve stale KA IDs via Tiles API: {_stale_kas}\\n\"\n",
+        "            \"Re-create the affected KAs via the stage notebooks and re-run.\"\n",
+        "        )\n",
+        "\n",
+        "print(f\"\\nKAs resolved ({len(ka_by_name)}/{len(EXPECTED_KA_NAMES)}):\")\n",
+        "for name, tid in ka_by_name.items():\n",
+        "    print(f\"  {name} → {tid}\")\n",
+        "missing = [n for n in EXPECTED_KA_NAMES if n not in ka_by_name]\n",
+        "if missing:\n",
+        "    print(f\"  ⚠️  Not found: {missing}\")\n",
+        "print(f\"MAS endpoint: {mas_endpoint or '(not found)'}\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "# ── Volume file checks ────────────────────────────────────────────────────────\nVOLUMES = [\n    (\"Legal Complaints\",    f\"/Volumes/{CATALOG}/legal_complaints/documents\"),\n    (\"Regulatory Docs\",     f\"/Volumes/{CATALOG}/regulatory/documents\"),\n    (\"Audit Reports\",       f\"/Volumes/{CATALOG}/audits/reports\"),\n    (\"Consultancy Reports\", f\"/Volumes/{CATALOG}/consultancy/reports\"),\n    (\"Inspection Reports\",  f\"/Volumes/{CATALOG}/food_safety/reports\"),\n    (\"Menu Documents\",      f\"/Volumes/{CATALOG}/menu_documents/menus\"),\n]\n\nvolume_errors = []\nfor label, path in VOLUMES:\n    try:\n        files = [f for f in dbutils.fs.ls(path) if f.name.endswith(\".pdf\")]\n        print(f\"✅ {label}: {len(files)} PDFs at {path}\")\n    except Exception as e:\n        msg = f\"{label}: {path} — {e}\"\n        print(f\"❌ {msg}\")\n        volume_errors.append(msg)\n\nif volume_errors:\n    raise RuntimeError(f\"Volume check failed:\\n\" + \"\\n\".join(volume_errors))\n\nprint(\"\\n✅ All volumes have PDFs\")",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ── Parallel readiness poll (all KAs + MAS simultaneously) ─────────────────\n",
+        "import concurrent.futures\n",
+        "\n",
+        "POLL_INTERVAL_S = 20\n",
+        "MAX_POLLS       = 30   # 10 min max — enough for any cold-start scenario\n",
+        "\n",
+        "if not ka_by_name:\n",
+        "    raise RuntimeError(\n",
+        "        f\"No KAs found. Expected: {EXPECTED_KA_NAMES}\\nCheck the diagnostic output above.\"\n",
+        "    )\n",
+        "if not mas_endpoint:\n",
+        "    raise RuntimeError(\"MAS endpoint not found — ensure CEO_Supervisor ran successfully\")\n",
+        "\n",
+        "_poll_deadline = time.time() + POLL_INTERVAL_S * MAX_POLLS\n",
+        "_results: dict = {}  # resource name → True/False\n",
+        "\n",
+        "\n",
+        "def _poll_ka(name: str, tile_id: str):\n",
+        "    for attempt in range(1, MAX_POLLS + 1):\n",
+        "        if time.time() > _poll_deadline:\n",
+        "            print(f\"  \\u23f1  {name} — shared deadline reached\")\n",
+        "            return name, False\n",
+        "        try:\n",
+        "            resp = w.api_client.do(\"GET\", f\"{KA_API}/{tile_id}\")\n",
+        "            # v2.1 returns a flat KA object; v2.0 returned {knowledge_assistant: {...}}.\n",
+        "            ka = resp.get(\"knowledge_assistant\", resp) if isinstance(resp, dict) else {}\n",
+        "            # v2.1 reports lifecycle via top-level `state` (CREATING/ACTIVE/FAILED).\n",
+        "            # The older Tiles-API shape used `status.endpoint_status` + sync subfields.\n",
+        "            state       = str(ka.get(\"state\", \"\")).upper()\n",
+        "            ka_status   = ka.get(\"status\", {}) if isinstance(ka.get(\"status\"), dict) else {}\n",
+        "            ep_status   = str(ka_status.get(\"endpoint_status\", \"\")).upper() or state\n",
+        "            sync_status = str(ka_status.get(\"sync_status\",\n",
+        "                               ka_status.get(\"indexing_status\", \"\"))).upper()\n",
+        "            ep_ready   = ep_status in (\"ONLINE\", \"ACTIVE\", \"READY\")\n",
+        "            sync_ready = (not sync_status) or sync_status in (\n",
+        "                \"SYNCED\", \"READY\", \"COMPLETE\", \"SUCCESS\", \"DONE\", \"\"\n",
+        "            )\n",
+        "            if ep_ready and sync_ready:\n",
+        "                print(f\"  \\u2705 {name} READY (endpoint={ep_status}, sync={sync_status or 'n/a'})\")\n",
+        "                return name, True\n",
+        "            print(f\"  \\u23f3 [{attempt}/{MAX_POLLS}] {name} endpoint={ep_status}, sync={sync_status or 'n/a'}\")\n",
+        "        except Exception as e:\n",
+        "            print(f\"  \\u26a0\\ufe0f  {name} poll error: {e} \\u2014 re-resolving\")\n",
+        "            _re_resolved = False\n",
+        "            for item in _list_kas():\n",
+        "                if _ka_name_from_item(item) == name:\n",
+        "                    new_id = _ka_id_from_item(item)\n",
+        "                    if new_id and new_id != tile_id:\n",
+        "                        print(f\"    Re-resolved via KA API: {new_id}\")\n",
+        "                        tile_id = new_id\n",
+        "                    _re_resolved = True\n",
+        "                    break\n",
+        "            if not _re_resolved:\n",
+        "                for _tile in _list_tiles():\n",
+        "                    if _tile.get(\"name\") == name:\n",
+        "                        new_id = _tile.get(\"tile_id\") or _tile.get(\"id\")\n",
+        "                        if new_id and new_id != tile_id:\n",
+        "                            print(f\"    Re-resolved via Tiles API: {new_id}\")\n",
+        "                            tile_id = new_id\n",
+        "                        break\n",
+        "        remaining = _poll_deadline - time.time()\n",
+        "        if remaining <= 0:\n",
+        "            return name, False\n",
+        "        time.sleep(min(POLL_INTERVAL_S, remaining))\n",
+        "    return name, False\n",
+        "\n",
+        "\n",
+        "def _poll_mas(endpoint: str):\n",
+        "    print(f\"  Polling MAS endpoint: {endpoint}\")\n",
+        "    for attempt in range(1, MAX_POLLS + 1):\n",
+        "        if time.time() > _poll_deadline:\n",
+        "            print(f\"  \\u23f1  MAS — shared deadline reached\")\n",
+        "            return \"MAS\", False\n",
+        "        try:\n",
+        "            resp = w.api_client.do(\"GET\", f\"{EP_API}/{endpoint}\")\n",
+        "            state  = resp.get(\"state\", {})\n",
+        "            ready  = str(state.get(\"ready\", \"\")).upper()\n",
+        "            config_update = str(state.get(\"config_update\", \"\")).upper()\n",
+        "            if ready == \"READY\":\n",
+        "                print(f\"  \\u2705 MAS READY (config_update={config_update or 'n/a'})\")\n",
+        "                return \"MAS\", True\n",
+        "            print(f\"  \\u23f3 [{attempt}/{MAX_POLLS}] MAS ready={ready}, config_update={config_update}\")\n",
+        "        except Exception as e:\n",
+        "            print(f\"  \\u26a0\\ufe0f  MAS poll error: {e}\")\n",
+        "        remaining = _poll_deadline - time.time()\n",
+        "        if remaining <= 0:\n",
+        "            return \"MAS\", False\n",
+        "        time.sleep(min(POLL_INTERVAL_S, remaining))\n",
+        "    return \"MAS\", False\n",
+        "\n",
+        "\n",
+        "print(f\"Polling {len(ka_by_name)} KAs + MAS in parallel (max {MAX_POLLS * POLL_INTERVAL_S // 60} min)…\\n\")\n",
+        "\n",
+        "with concurrent.futures.ThreadPoolExecutor(max_workers=len(ka_by_name) + 1) as _pool:\n",
+        "    _futures = {_pool.submit(_poll_ka, name, tid): name for name, tid in ka_by_name.items()}\n",
+        "    _futures[_pool.submit(_poll_mas, mas_endpoint)] = \"MAS\"\n",
+        "    for _fut in concurrent.futures.as_completed(_futures):\n",
+        "        _resource, _ok = _fut.result()\n",
+        "        _results[_resource] = _ok\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# ── Check all resources passed ───────────────────────────────────────────────\n",
+        "failures = [r for r, ok in _results.items() if not ok]\n",
+        "if failures:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Resources not ready after {MAX_POLLS * POLL_INTERVAL_S // 60} min: {failures}\\n\"\n",
+        "        \"Check the logs above for per-resource status.\"\n",
+        "    )\n"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "print(\"=\" * 55)\n",
+        "print(\"✅  CEO READINESS CHECK PASSED\")\n",
+        "print(\"=\" * 55)\n",
+        "print(f\"  KAs ready:       {len(ka_by_name)}\")\n",
+        "print(f\"  MAS endpoint:    {mas_endpoint}\")\n",
+        "print(f\"  Volumes checked: {len(VOLUMES)}\")\n",
+        "print(\"\\nThe Operational Dashboard is ready for use.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/operational_supervisor.ipynb b/stages/operational_supervisor.ipynb
new file mode 100644
index 0000000..351f943
--- /dev/null
+++ b/stages/operational_supervisor.ipynb
@@ -0,0 +1,1103 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Operational Supervisor\n",
+        "\n",
+        "Creates a single Multi-Agent Supervisor (MAS) for the operational dashboard that\n",
+        "routes across **3 Genie spaces** and **6 Knowledge Assistants**:\n",
+        "\n",
+        "| Sub-agent | Type | Source |\n",
+        "|---|---|---|\n",
+        "| `revenue-analytics` | Genie | Revenue & Orders Intelligence space |\n",
+        "| `operations-intelligence` | Genie | Operations Intelligence space |\n",
+        "| `menu-analytics` | Genie | Menu & Safety Intelligence space |\n",
+        "| `inspection-reports` | KA | Food safety inspection PDFs |\n",
+        "| `menu-document-search` | KA | Restaurant menu PDFs |\n",
+        "| `legal-complaints` | KA | Legal complaint case files |\n",
+        "| `regulatory-compliance` | KA | Permits, certifications, FDA |\n",
+        "| `audit-findings` | KA | Financial / operational / supply-chain audits |\n",
+        "| `consultancy-strategy` | KA | Strategic consulting reports |"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk mlflow-skinny[databricks]"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG             = dbutils.widgets.get(\"CATALOG\")\n",
+        "SUPERVISOR_ENDPOINT = dbutils.widgets.get(\"SUPERVISOR_ENDPOINT_NAME\")\n",
+        "# KA endpoint names are auto-generated by the KA v2.1 API and resolved from\n",
+        "# uc_state below. They are no longer passed in as Job parameters."
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import json, sys, time\n",
+        "\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "API_BASE = \"/api/2.0/multi-agent-supervisors\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Resolve Genie space IDs from uc_state\n",
+        "\n",
+        "Titles must match the strings used by `stages/genie_spaces.ipynb`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "GENIE_TITLES = {\n",
+        "    \"revenue\": f\"Revenue & Orders Intelligence ({CATALOG})\",\n",
+        "    \"ops\":     f\"Operations Intelligence ({CATALOG})\",\n",
+        "    \"menu\":    f\"Menu & Safety Intelligence ({CATALOG})\",\n",
+        "}\n",
+        "genie_ids = {}\n",
+        "\n",
+        "df = spark.sql(f\"\"\"\n",
+        "    SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "    WHERE resource_type = 'genie_spaces'\n",
+        "    ORDER BY created_at DESC\n",
+        "\"\"\")\n",
+        "for row in df.collect():\n",
+        "    info = json.loads(row.resource_data)\n",
+        "    title = info.get(\"title\")\n",
+        "    for key, expected in GENIE_TITLES.items():\n",
+        "        if title == expected and key not in genie_ids:\n",
+        "            genie_ids[key] = info.get(\"space_id\")\n",
+        "\n",
+        "missing = [k for k in GENIE_TITLES if k not in genie_ids]\n",
+        "if missing:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Missing Genie space(s) {missing} in uc_state. Run the genie_spaces stage first.\"\n",
+        "    )\n",
+        "\n",
+        "revenue_genie_id = genie_ids[\"revenue\"]\n",
+        "ops_genie_id     = genie_ids[\"ops\"]\n",
+        "menu_genie_id    = genie_ids[\"menu\"]\n",
+        "print(f\"Revenue Genie:   {revenue_genie_id}\")\n",
+        "print(f\"Operations Genie:{ops_genie_id}\")\n",
+        "print(f\"Menu Genie:      {menu_genie_id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Resolve KA serving endpoint names from uc_state"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "KA_NAMES = [\n",
+        "    f\"{CATALOG}-inspection-knowledge\",\n",
+        "    f\"{CATALOG}-menu-knowledge\",\n",
+        "    f\"{CATALOG}-legal\",\n",
+        "    f\"{CATALOG}-regulatory\",\n",
+        "    f\"{CATALOG}-audits\",\n",
+        "    f\"{CATALOG}-consultancy\",\n",
+        "]\n",
+        "\n",
+        "\n",
+        "def _ka_endpoint_from_tile_id(tile_id: str) -> str:\n",
+        "    # Databricks serving endpoint provisioned for a KA is named\n",
+        "    # ka-{first-8-chars-of-tile_id}-endpoint. The `endpoint_name` field\n",
+        "    # returned by the v2.1 KA API is a different (display-style) value\n",
+        "    # and MUST NOT be used here — MAS validates the serving-endpoint name.\n",
+        "    if not tile_id or len(tile_id) < 8:\n",
+        "        raise ValueError(f\"Invalid KA tile_id for endpoint construction: {tile_id!r}\")\n",
+        "    return f\"ka-{tile_id[:8]}-endpoint\"\n",
+        "\n",
+        "\n",
+        "ka_tile_ids = {}\n",
+        "\n",
+        "try:\n",
+        "    df = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'knowledge_assistants'\n",
+        "        ORDER BY created_at DESC\n",
+        "    \"\"\")\n",
+        "    for row in df.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        name = info.get(\"name\", \"\")\n",
+        "        tid  = info.get(\"tile_id\", \"\")\n",
+        "        if name in KA_NAMES and tid and name not in ka_tile_ids:\n",
+        "            ka_tile_ids[name] = tid\n",
+        "    print(f\"uc_state: resolved {len(ka_tile_ids)}/{len(KA_NAMES)} KA tile_ids\")\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f uc_state lookup failed: {e}\")\n",
+        "\n",
+        "missing_names = [n for n in KA_NAMES if n not in ka_tile_ids]\n",
+        "if missing_names:\n",
+        "    print(f\"{len(missing_names)} KA tile_id(s) missing from uc_state \\u2014 listing KAs via v2.1 API...\")\n",
+        "    ka_params = {}\n",
+        "    while True:\n",
+        "        resp = w.api_client.do(\"GET\", \"/api/2.1/knowledge-assistants\", query=ka_params)\n",
+        "        for ka in resp.get(\"knowledge_assistants\", []):\n",
+        "            dn  = ka.get(\"display_name\", \"\")\n",
+        "            kid = ka.get(\"id\", \"\")\n",
+        "            if dn in missing_names and kid:\n",
+        "                ka_tile_ids[dn] = kid\n",
+        "                missing_names.remove(dn)\n",
+        "        token = resp.get(\"next_page_token\")\n",
+        "        if not token or not missing_names:\n",
+        "            break\n",
+        "        ka_params = {\"page_token\": token}\n",
+        "\n",
+        "if missing_names:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Could not resolve tile_ids for: {missing_names}. \"\n",
+        "        f\"Ensure the knowledge_agents stage ran first.\"\n",
+        "    )\n",
+        "\n",
+        "ka_endpoints = {name: _ka_endpoint_from_tile_id(tid) for name, tid in ka_tile_ids.items()}\n",
+        "\n",
+        "inspect_ep_id = ka_endpoints[f\"{CATALOG}-inspection-knowledge\"]\n",
+        "menu_ep_id    = ka_endpoints[f\"{CATALOG}-menu-knowledge\"]\n",
+        "legal_ep_id   = ka_endpoints[f\"{CATALOG}-legal\"]\n",
+        "reg_ep_id     = ka_endpoints[f\"{CATALOG}-regulatory\"]\n",
+        "audit_ep_id   = ka_endpoints[f\"{CATALOG}-audits\"]\n",
+        "consult_ep_id = ka_endpoints[f\"{CATALOG}-consultancy\"]\n",
+        "\n",
+        "print(f\"Inspection KA endpoint:  {inspect_ep_id}\")\n",
+        "print(f\"Menu KA endpoint:        {menu_ep_id}\")\n",
+        "print(f\"Legal KA endpoint:       {legal_ep_id}\")\n",
+        "print(f\"Regulatory KA endpoint:  {reg_ep_id}\")\n",
+        "print(f\"Audit KA endpoint:       {audit_ep_id}\")\n",
+        "print(f\"Consultancy KA endpoint: {consult_ep_id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Create the Operational Supervisor"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "AGENT_NAME = f\"{CATALOG}-operational-supervisor\"\n",
+        "\n",
+        "EXAMPLES = [\n",
+        "    {\n",
+        "        \"question\": \"Give me the executive briefing on the state of the business\",\n",
+        "        \"guideline\": \"Should summarize revenue performance, top operational risks, any critical legal or compliance issues, and one strategic recommendation. Keep it to 5 bullet points maximum.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which location is most at risk right now?\",\n",
+        "        \"guideline\": \"Should consider complaint rate, inspection score, legal exposure, and audit findings for each location. Rank and explain the top risk with specific numbers.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which location has the highest order cancellation rate right now?\",\n",
+        "        \"guideline\": \"Must name exactly one specific location with the highest rate. Must include the numeric cancellation rate as a percentage. Routes to revenue-analytics or operations-intelligence.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"How does revenue compare across our locations this week?\",\n",
+        "        \"guideline\": \"Must provide revenue figures or ranking for multiple locations. Must reference the current week. Routes to revenue-analytics.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which brand is generating the most revenue right now?\",\n",
+        "        \"guideline\": \"Must name a specific brand (not a location). Must include a revenue figure or ranking. Routes to revenue-analytics.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which location needs the most operational attention right now?\",\n",
+        "        \"guideline\": \"Must name one specific location with the highest operational risk. Must justify with at least two operational metrics. Routes to operations-intelligence.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"What happened during the Chicago food safety inspection? Were there critical violations?\",\n",
+        "        \"guideline\": \"Must reference a specific inspection report by date or ID. Must state the inspection score and/or grade. Must explicitly state whether critical violations were found and cite at least one specific violation code if they exist. Routes to inspection-reports.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Which menu items are gluten-free and under $15?\",\n",
+        "        \"guideline\": \"Must list specific items with brand, price, and allergen status. Routes to menu-analytics or menu-document-search.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Compare protein content across all burgers in our network\",\n",
+        "        \"guideline\": \"Must return per-item protein values across brands. Routes to menu-analytics.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Do we have any active high-risk legal cases? What is the total financial exposure?\",\n",
+        "        \"guideline\": \"Must confirm whether active cases exist, cite at least one specific case number (CK-XX-XXXX), include a risk classification, state a financial exposure amount, and remind users to involve legal counsel. Routes to legal-complaints.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Are there any permits or regulatory certificates expiring in the next 60 days?\",\n",
+        "        \"guideline\": \"Must list specific document IDs or permit names with expiry dates and locations. Routes to regulatory-compliance.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"What were the most significant audit findings this quarter?\",\n",
+        "        \"guideline\": \"Must cite the auditing firm and audit period, classify findings by severity, and state remediation status. Routes to audit-findings.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"What do our consultants recommend as the top AI investments for the next 90 days?\",\n",
+        "        \"guideline\": \"Must reference a specific consulting report, include at least one concrete recommendation with a financial metric, and frame in the 90-day horizon. Routes to consultancy-strategy.\",\n",
+        "    },\n",
+        "    {\n",
+        "        \"question\": \"Give me a board deck summary: revenue performance, top operational risk, legal exposure, and one strategic recommendation\",\n",
+        "        \"guideline\": \"Must explicitly address all four domains. Must include at least one concrete number per domain. Must be structured with clear sections. Routes to multiple agents.\",\n",
+        "    },\n",
+        "]\n",
+        "\n",
+        "# ─────────────────────────────────────────────────────────────────────────────\n",
+        "# Source-of-truth supervisor instructions live here as a literal so this\n",
+        "# notebook stays self-contained and the Prompt Registry cell below can extract\n",
+        "# them on every deploy. At runtime we try to load the latest production\n",
+        "# version from the Prompt Registry first — that lets a manually edited prompt\n",
+        "# (Catalog Explorer → Prompts → bump @production alias) take effect on the\n",
+        "# NEXT deploy of this stage without having to edit this notebook.\n",
+        "#\n",
+        "# Caveats:\n",
+        "#   • This is \"construction-time\" load_prompt — the MAS service itself does\n",
+        "#     not call load_prompt. Editing the prompt in UC has no effect until the\n",
+        "#     next stage redeploy rebuilds SUPERVISOR_BODY.\n",
+        "#   • The Prompt Registry cell below re-registers _FALLBACK_... on every\n",
+        "#     deploy and bumps the @production alias to the new version, so manual\n",
+        "#     UC edits get clobbered on the NEXT redeploy. Backport edits to this\n",
+        "#     literal to make them stick.\n",
+        "_FALLBACK_SUPERVISOR_INSTRUCTIONS = (\n",
+        "    \"You are an elite operational AI assistant for Casper's Kitchens, a ghost kitchen network \"\n",
+        "    \"operating 16 restaurant brands across 8 locations (US: San Francisco, Silicon Valley, Bellevue, \"\n",
+        "    \"Chicago; EMEA: London, Munich, Amsterdam, Vianen). Synthesise intelligence from multiple \"\n",
+        "    \"sources to deliver concise, executive-ready insights. Always specify which location(s) you \"\n",
+        "    \"are referencing. Lead with the most important finding, then provide supporting detail.\\n\\n\"\n",
+        "    \"DATA SOURCE BOUNDARIES:\\n\"\n",
+        "    \"(1) 'Legal issues', 'lawsuits', 'legal cases', 'legal exposure' → legal-complaints agent \"\n",
+        "    \"(CK-XX-XXXX case numbers), NOT food safety violations or operational complaints.\\n\"\n",
+        "    \"(2) 'Food safety violations' → operations-intelligence (counts/grades) or inspection-reports \"\n",
+        "    \"(detailed findings) — they are compliance issues, not lawsuits.\\n\"\n",
+        "    \"(3) 'Customer complaints' (complaint rate, cancel rate) → operations-intelligence — they are \"\n",
+        "    \"operational metrics, not legal filings.\\n\"\n",
+        "    \"(4) 'Allergens / nutrition / prices' → menu-analytics (structured) or menu-document-search \"\n",
+        "    \"(descriptive dish details).\\n\"\n",
+        "    \"Never conflate food safety violations or operational complaint counts with legal case filings. \"\n",
+        "    \"When discussing legal or audit matters, remind users to involve counsel or auditors for \"\n",
+        "    \"decisions. Be direct, data-driven, and strategic.\"\n",
+        ")\n",
+        "\n",
+        "import mlflow\n",
+        "import mlflow.genai\n",
+        "\n",
+        "# Required: without databricks-uc the registry client hits workspace MLflow,\n",
+        "# where 3-part names are opaque strings and prompts never land in UC.\n",
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "\n",
+        "_SUPERVISOR_PROMPT_URI = f\"prompts:/{CATALOG}.prompts.supervisor_instructions@production\"\n",
+        "try:\n",
+        "    _supervisor_instructions = mlflow.genai.load_prompt(_SUPERVISOR_PROMPT_URI).template\n",
+        "    print(f\"[supervisor] Loaded instructions from {_SUPERVISOR_PROMPT_URI}\")\n",
+        "except Exception as _exc:\n",
+        "    print(\n",
+        "        f\"[supervisor] Could not load {_SUPERVISOR_PROMPT_URI} \"\n",
+        "        f\"({type(_exc).__name__}: {_exc}); using _FALLBACK_SUPERVISOR_INSTRUCTIONS.\"\n",
+        "    )\n",
+        "    _supervisor_instructions = _FALLBACK_SUPERVISOR_INSTRUCTIONS\n",
+        "\n",
+        "SUPERVISOR_BODY = {\n",
+        "    \"name\": AGENT_NAME,\n",
+        "    \"description\": (\n",
+        "        \"Operational AI assistant for Casper's Kitchens. Synthesises intelligence across revenue \"\n",
+        "        \"analytics, operations, food safety, menu and nutrition data, legal exposure, regulatory \"\n",
+        "        \"compliance, audit findings, and strategic consulting across all 8 ghost kitchen locations \"\n",
+        "        \"(US: San Francisco, Silicon Valley, Bellevue, Chicago; EMEA: London, Munich, Amsterdam, \"\n",
+        "        \"Vianen) and 16 restaurant brands.\"\n",
+        "    ),\n",
+        "    \"endpoint_name\": SUPERVISOR_ENDPOINT,\n",
+        "    \"agents\": [\n",
+        "        {\n",
+        "            \"agent_type\": \"genie\",\n",
+        "            \"genie_space\": {\"id\": revenue_genie_id},\n",
+        "            \"name\": \"revenue-analytics\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about: revenue ($), sales totals, order counts, average order \"\n",
+        "                \"value, brand sales rankings, location revenue comparisons, or financial performance \"\n",
+        "                \"metrics. Keywords: revenue, sales, earned, orders, top performing, best/worst location \"\n",
+        "                \"by revenue, avg order, financial. Do NOT call for food safety, inspections, legal, \"\n",
+        "                \"audits, menus, or strategic questions.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"genie\",\n",
+        "            \"genie_space\": {\"id\": ops_genie_id},\n",
+        "            \"name\": \"operations-intelligence\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about: order throughput, kitchen operations, delivery performance, \"\n",
+        "                \"food safety inspection scores, food safety violation counts, location health metrics, \"\n",
+        "                \"or operational risk. Keywords: operations, kitchen, delivery, inspection score, food \"\n",
+        "                \"safety grade, throughput, busiest hours, peak demand, operational issues, cancel rate, \"\n",
+        "                \"complaint rate. Do NOT call for revenue totals, legal cases, audit reports, or strategy. \"\n",
+        "                \"IMPORTANT: 'complaints' here means customer operational complaints — NOT legal filings.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"genie\",\n",
+        "            \"genie_space\": {\"id\": menu_genie_id},\n",
+        "            \"name\": \"menu-analytics\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for structured queries about menu items, nutrition, allergens, item pricing \"\n",
+        "                \"tiers, brand-level menu comparisons, or per-location compliance summaries. Keywords: \"\n",
+        "                \"calories, protein, fat, carbs, allergen-free, gluten-free, dairy-free, item price, \"\n",
+        "                \"brand menu, nutrition comparison, healthy options. Do NOT call for descriptive \"\n",
+        "                \"questions about individual dishes — use menu-document-search for those.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": inspect_ep_id},\n",
+        "            \"name\": \"inspection-reports\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about specific food safety inspection documents, detailed \"\n",
+        "                \"inspector findings, corrective action details, or historical inspection report text. \"\n",
+        "                \"For inspection SCORES/GRADES use operations-intelligence instead.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": menu_ep_id},\n",
+        "            \"name\": \"menu-document-search\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for descriptive questions about specific dishes — ingredient details, \"\n",
+        "                \"preparation, dish description, or specific menu content. For nutrition stats, \"\n",
+        "                \"allergen filtering, or price comparisons, use menu-analytics instead.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": legal_ep_id},\n",
+        "            \"name\": \"legal-complaints\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about lawsuits, legal cases, customer complaint filings, \"\n",
+        "                \"litigation status, legal liability, legal issues, or specific complaint case numbers. \"\n",
+        "                \"Always surface case numbers (format CK-XX-XXXX), risk levels (HIGH/MEDIUM/LOW), \"\n",
+        "                \"and amounts at stake.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": reg_ep_id},\n",
+        "            \"name\": \"regulatory-compliance\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about permits, licenses, certifications, regulatory compliance \"\n",
+        "                \"documents, or specific regulatory requirements.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": audit_ep_id},\n",
+        "            \"name\": \"audit-findings\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about financial or operational audit reports, audit findings, \"\n",
+        "                \"auditor recommendations, or specific audit references.\"\n",
+        "            ),\n",
+        "        },\n",
+        "        {\n",
+        "            \"agent_type\": \"ka\",\n",
+        "            \"serving_endpoint\": {\"name\": consult_ep_id},\n",
+        "            \"name\": \"consultancy-strategy\",\n",
+        "            \"description\": (\n",
+        "                \"ONLY call for questions about strategic recommendations, consultant advice, improvement \"\n",
+        "                \"strategies, or specific consultancy reports.\"\n",
+        "            ),\n",
+        "        },\n",
+        "    ],\n",
+        "    \"instructions\": _supervisor_instructions,\n",
+        "}"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Register the supervisor instructions in the Prompt Registry\n",
+        "\n",
+        "`SUPERVISOR_BODY[\"instructions\"]` is the supervisor's \"system prompt\" — the\n",
+        "text the MAS API stores and replays at every routing call. Register it\n",
+        "under `{CATALOG}.prompts.supervisor_instructions` so it's versioned in UC\n",
+        "alongside the agent itself. Re-running the stage bumps the version and the\n",
+        "`production` alias."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from prompt_registry import seed_prompt_history\n",
+        "\n",
+        "# Two earlier versions of the supervisor instructions, seeded on first deploy\n",
+        "# so the Prompt Registry UI shows v1 → v2 → v3 history (not just the current\n",
+        "# version). The seed is NOT a real engineering changelog — it's synthetic\n",
+        "# demo history. seed_prompt_history tags each seeded version with\n",
+        "# is_demo_seed=\"true\" so the audit trail is honest about that.\n",
+        "_SUPERVISOR_V1 = (\n",
+        "    \"You are an operational AI assistant for Casper's Kitchens. \"\n",
+        "    \"Synthesise intelligence across the available agents to deliver insights to the executive team. \"\n",
+        "    \"Be concise and data-driven.\"\n",
+        ")\n",
+        "_SUPERVISOR_V2 = (\n",
+        "    \"You are an elite operational AI assistant for Casper's Kitchens, a ghost kitchen network \"\n",
+        "    \"operating 16 restaurant brands across 8 locations (US: San Francisco, Silicon Valley, Bellevue, \"\n",
+        "    \"Chicago; EMEA: London, Munich, Amsterdam, Vianen). Synthesise intelligence from multiple \"\n",
+        "    \"sources to deliver concise, executive-ready insights. Always specify which location(s) you \"\n",
+        "    \"are referencing. Lead with the most important finding, then provide supporting detail. \"\n",
+        "    \"When discussing legal or audit matters, remind users to involve counsel or auditors for \"\n",
+        "    \"decisions. Be direct, data-driven, and strategic.\"\n",
+        ")\n",
+        "\n",
+        "_common_tags = {\n",
+        "    \"agent\": \"operational_supervisor\",\n",
+        "    \"stage\": \"operational_supervisor\",\n",
+        "    \"agent_name\": AGENT_NAME,\n",
+        "    \"consumed_via\": \"mlflow.genai.load_prompt at stage construction time\",\n",
+        "}\n",
+        "\n",
+        "seed_prompt_history(\n",
+        "    spark=spark,\n",
+        "    catalog=CATALOG,\n",
+        "    name=\"supervisor_instructions\",\n",
+        "    historical=[\n",
+        "        {\n",
+        "            \"template\": _SUPERVISOR_V1,\n",
+        "            \"commit_message\": \"v1: minimal synthesiser, no location or routing context (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "        {\n",
+        "            \"template\": _SUPERVISOR_V2,\n",
+        "            \"commit_message\": \"v2: added location context + executive framing (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "    ],\n",
+        "    current={\n",
+        "        \"template\": _FALLBACK_SUPERVISOR_INSTRUCTIONS,\n",
+        "        \"commit_message\": f\"{AGENT_NAME} routing/synthesis instructions (with explicit DATA SOURCE BOUNDARIES)\",\n",
+        "        \"tags\": _common_tags,\n",
+        "    },\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "def _list_mas():\n",
+        "    \"\"\"List supervisor agents via the v2.1 SupervisorAgents API.\n",
+        "\n",
+        "    The v2.0 path (API_BASE) only supports per-resource ops (POST/GET-by-id/PATCH/\n",
+        "    DELETE); listing on it returns 'No API found'.\n",
+        "    \"\"\"\n",
+        "    mas, params = [], {}\n",
+        "    try:\n",
+        "        while True:\n",
+        "            resp = w.api_client.do(\"GET\", \"/api/2.1/supervisor-agents\", query=params)\n",
+        "            mas.extend(resp.get(\"supervisor_agents\", []))\n",
+        "            token = resp.get(\"next_page_token\")\n",
+        "            if not token:\n",
+        "                break\n",
+        "            params = {\"page_token\": token}\n",
+        "    except Exception as e:\n",
+        "        print(f\"  Supervisor list error: {e}\")\n",
+        "    return mas\n",
+        "\n",
+        "\n",
+        "def get_tile_by_name(name):\n",
+        "    try:\n",
+        "        params = {}\n",
+        "        while True:\n",
+        "            resp = w.api_client.do(\"GET\", \"/api/2.0/tiles\", query=params)\n",
+        "            for tile in resp.get(\"tiles\", []):\n",
+        "                if tile.get(\"name\") == name:\n",
+        "                    return tile\n",
+        "            token = resp.get(\"next_page_token\")\n",
+        "            if not token:\n",
+        "                break\n",
+        "            params = {\"page_token\": token}\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    return None\n",
+        "\n",
+        "\n",
+        "agent_id = None\n",
+        "is_new = False\n",
+        "\n",
+        "try:\n",
+        "    df = spark.sql(f\"\"\"\n",
+        "        SELECT resource_data FROM {CATALOG}._internal_state.resources\n",
+        "        WHERE resource_type = 'multi_agent_supervisors'\n",
+        "        ORDER BY created_at DESC\n",
+        "    \"\"\")\n",
+        "    for row in df.collect():\n",
+        "        info = json.loads(row.resource_data)\n",
+        "        if (info.get(\"endpoint_name\") == SUPERVISOR_ENDPOINT or info.get(\"name\") == AGENT_NAME) and info.get(\"tile_id\"):\n",
+        "            agent_id = info[\"tile_id\"]\n",
+        "            print(f\"\\u267b\\ufe0f Supervisor found in uc_state ({agent_id}) — skipping create\")\n",
+        "            break\n",
+        "except Exception as e:\n",
+        "    print(f\"\\u26a0\\ufe0f uc_state lookup failed: {e}\")\n",
+        "\n",
+        "if not agent_id:\n",
+        "    for sa in _list_mas():\n",
+        "        # v2.1 items are flat dicts. `display_name` = user-facing name; `name` = resource path.\n",
+        "        if (\n",
+        "            sa.get(\"endpoint_name\") == SUPERVISOR_ENDPOINT\n",
+        "            or sa.get(\"display_name\") == AGENT_NAME\n",
+        "            or sa.get(\"name\") == AGENT_NAME\n",
+        "        ):\n",
+        "            agent_id = sa.get(\"supervisor_agent_id\") or sa.get(\"id\") or sa.get(\"tile_id\")\n",
+        "            print(f\"\\u267b\\ufe0f Supervisor found in SupervisorAgents API ({agent_id}) — skipping create\")\n",
+        "            break\n",
+        "\n",
+        "if not agent_id:\n",
+        "    try:\n",
+        "        w.api_client.do(\"POST\", API_BASE, body=SUPERVISOR_BODY)\n",
+        "        print(\"\\u2705 Created Operational Supervisor\")\n",
+        "        is_new = True\n",
+        "    except Exception as e:\n",
+        "        if \"already exists\" in str(e).lower():\n",
+        "            print(\"\\u267b\\ufe0f Supervisor already exists, proceeding\")\n",
+        "        else:\n",
+        "            raise\n",
+        "    tile = get_tile_by_name(AGENT_NAME)\n",
+        "    if tile:\n",
+        "        agent_id = tile[\"tile_id\"]\n",
+        "        print(f\"Resolved tile_id: {agent_id}\")\n",
+        "    else:\n",
+        "        agent_id = AGENT_NAME\n",
+        "        print(f\"\\u26a0\\ufe0f Using name as fallback: {agent_id}\")\n",
+        "\n",
+        "if isinstance(agent_id, str) and len(agent_id) >= 8 and \"-\" in agent_id:\n",
+        "    actual_endpoint_name = f\"mas-{agent_id[:8]}-endpoint\"\n",
+        "else:\n",
+        "    actual_endpoint_name = SUPERVISOR_ENDPOINT\n",
+        "print(f\"MAS serving endpoint name: {actual_endpoint_name}\")\n",
+        "\n",
+        "add(CATALOG, \"multi_agent_supervisors\", {\n",
+        "    \"endpoint_name\": actual_endpoint_name,\n",
+        "    \"tile_id\": agent_id,\n",
+        "    \"name\": AGENT_NAME,\n",
+        "})\n",
+        "\n",
+        "# ── Drift recovery: PATCH the supervisor with fresh sub-agent IDs ────────────\n",
+        "# The `genie_spaces` stage is non-idempotent and creates fresh space IDs on\n",
+        "# every deploy. When this stage reuses an existing supervisor (uc_state hit\n",
+        "# above), its wired Genie IDs / KA endpoints can point at trashed resources,\n",
+        "# which surfaces in chat as \"permissions issue accessing the revenue analytics\n",
+        "# system\" (it's actually a 404 on the trashed Genie space). Re-applying\n",
+        "# SUPERVISOR_BODY against the existing tile id keeps the supervisor in lock-\n",
+        "# step with the current resources. No-op when nothing drifted.\n",
+        "#\n",
+        "# Hard failure on exhausted retries: this used to log a warning and continue,\n",
+        "# which left the supervisor pointing at trashed resources and broke the demo\n",
+        "# chat silently.  Now we retry the PATCH 3x with exponential backoff (1/2/4 s)\n",
+        "# and raise on the final failure so the deploy aborts with a clear error\n",
+        "# instead of leaving a half-wired supervisor in place.\n",
+        "import time as _time\n",
+        "\n",
+        "if not is_new and isinstance(agent_id, str) and \"-\" in agent_id and len(agent_id) >= 8:\n",
+        "    existing = w.api_client.do(\"GET\", f\"{API_BASE}/{agent_id}\")\n",
+        "    wired = (existing.get(\"multi_agent_supervisor\") or {}).get(\"agents\") or []\n",
+        "\n",
+        "    def _key(a):\n",
+        "        t = a.get(\"agent_type\", \"\")\n",
+        "        if t in (\"genie\", \"genie-space\"):\n",
+        "            return (\"genie\", a.get(\"name\"), (a.get(\"genie_space\") or {}).get(\"id\"))\n",
+        "        if t in (\"ka\", \"knowledge-assistant\"):\n",
+        "            return (\"ka\", a.get(\"name\"), (a.get(\"serving_endpoint\") or {}).get(\"name\"))\n",
+        "        return (t, a.get(\"name\"))\n",
+        "\n",
+        "    wired_keys  = {_key(a) for a in wired}\n",
+        "    target_keys = {_key(a) for a in SUPERVISOR_BODY[\"agents\"]}\n",
+        "\n",
+        "    # Also detect instructions drift — load_prompt above can load a newer\n",
+        "    # production version of the prompt that doesn't match what's currently\n",
+        "    # wired into the live supervisor. Without this check, a registry edit\n",
+        "    # would silently fail to take effect on already-existing supervisors.\n",
+        "    wired_instructions = ((existing.get(\"multi_agent_supervisor\") or existing) or {}).get(\"instructions\", \"\")\n",
+        "    target_instructions = SUPERVISOR_BODY[\"instructions\"]\n",
+        "    instructions_drift = (wired_instructions or \"\") != (target_instructions or \"\")\n",
+        "\n",
+        "    if wired_keys == target_keys and not instructions_drift:\n",
+        "        print(\"✅ Supervisor wiring + instructions match uc_state — no PATCH needed\")\n",
+        "    else:\n",
+        "        if wired_keys != target_keys:\n",
+        "            drifted = target_keys ^ wired_keys\n",
+        "            print(f\"⚠️  Supervisor wiring drift detected ({len(drifted)} mismatched sub-agents) — PATCHing…\")\n",
+        "        if instructions_drift:\n",
+        "            print(f\"⚠️  Supervisor instructions drift detected (load_prompt resolved a different version than the one wired in) — PATCHing…\")\n",
+        "        # NOTE on body shape: the MAS PATCH API rejects partial bodies with\n",
+        "        # `Missing required field: name` even when update_mask is set, so we\n",
+        "        # send the whole SUPERVISOR_BODY. `examples` are a separate resource\n",
+        "        # at `/api/2.0/tiles/{id}/examples` — they are NOT touched by this\n",
+        "        # PATCH. Cell 15 below re-POSTs EXAMPLES on every run as a defensive\n",
+        "        # measure in case a prior deploy lost them.\n",
+        "        _last_err = None\n",
+        "        for _attempt in range(1, 4):\n",
+        "            try:\n",
+        "                w.api_client.do(\"PATCH\", f\"{API_BASE}/{agent_id}\", body=SUPERVISOR_BODY)\n",
+        "                print(f\"✅ Supervisor PATCHed with current Genie/KA wiring (attempt {_attempt}/3)\")\n",
+        "                _last_err = None\n",
+        "                break\n",
+        "            except Exception as e:\n",
+        "                _last_err = e\n",
+        "                _wait = 2 ** (_attempt - 1)  # 1s, 2s, 4s\n",
+        "                print(f\"⚠️  Drift-recovery PATCH attempt {_attempt}/3 failed: {e!r}\")\n",
+        "                if _attempt < 3:\n",
+        "                    print(f\"   retrying in {_wait}s…\")\n",
+        "                    _time.sleep(_wait)\n",
+        "        if _last_err is not None:\n",
+        "            # Re-raise so the stage fails loudly.  A stale supervisor breaks\n",
+        "            # the demo chat (\"permissions issue accessing the revenue\n",
+        "            # analytics system\") in a way that's expensive to diagnose at\n",
+        "            # demo time — we'd much rather fail the deploy here.\n",
+        "            raise RuntimeError(\n",
+        "                f\"Supervisor drift-recovery PATCH failed after 3 attempts: {_last_err!r}. \"\n",
+        "                f\"The supervisor at tile_id={agent_id} is still wired to stale Genie/KA \"\n",
+        "                f\"resources.  Re-run this stage once the Databricks API is reachable, or \"\n",
+        "                f\"delete the supervisor from uc_state to force re-creation.\"\n",
+        "            ) from _last_err"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Attach evaluation examples (idempotent)\n",
+        "\n",
+        "Re-attaches `EXAMPLES` to the supervisor on every run — defensive against any\n",
+        "prior whole-body PATCH that may have wiped them. POSTing the same examples is\n",
+        "safe (server replaces the list)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Examples attachment is IDEMPOTENT — re-attach on every run so a prior\n",
+        "# wipe/transient failure self-heals.  Correct API:\n",
+        "#   POST /api/2.0/multi-agent-supervisors/{tile_id}/examples\n",
+        "#   body: {\"tile_id\": <id>, \"question\": str, \"guidelines\": [str]}\n",
+        "# (one example per request — no batched payload).  The legacy\n",
+        "# /api/2.0/tiles/{id}/examples endpoint that was here before was wrong\n",
+        "# and silently failed inside the old try/except, which is why examples\n",
+        "# were not surviving deploys.\n",
+        "#\n",
+        "# Idempotency: best-effort list+delete before re-creating.  The list/delete\n",
+        "# endpoints may not exist on this surface — if either step 404s we just\n",
+        "# POST anyway, and accept that duplicates may accumulate across deploys.\n",
+        "#\n",
+        "# Robustness: small inter-request sleep + one retry on POST/DELETE failure.\n",
+        "# The MAS examples API rate-limits bursts of >~5 req/s and a fraction of POSTs\n",
+        "# come back with empty error bodies (the SDK stringifies those as `None`),\n",
+        "# so we slow the loop down and retry once with a backoff before giving up.\n",
+        "\n",
+        "def _format_api_error(e: Exception) -> str:\n",
+        "    \"\"\"str(e) on databricks-sdk errors is sometimes empty/None when the\n",
+        "    server returns a non-standard error body. Surface enough detail to debug.\"\"\"\n",
+        "    msg = str(e) or \"\"\n",
+        "    if not msg or msg == \"None\":\n",
+        "        msg = repr(e)\n",
+        "    code = getattr(e, \"error_code\", None)\n",
+        "    return f\"{type(e).__name__}: {msg}\" + (f\" [error_code={code}]\" if code else \"\")\n",
+        "\n",
+        "\n",
+        "def _do_with_retry(method: str, path: str, body: dict | None = None, retries: int = 1, backoff_s: float = 2.0):\n",
+        "    \"\"\"Call api_client.do with one retry on Exception. Returns the response or\n",
+        "    re-raises the last exception after the retries are exhausted.\"\"\"\n",
+        "    last_exc = None\n",
+        "    for attempt in range(retries + 1):\n",
+        "        try:\n",
+        "            if body is None:\n",
+        "                return w.api_client.do(method, path)\n",
+        "            return w.api_client.do(method, path, body=body)\n",
+        "        except Exception as e:\n",
+        "            last_exc = e\n",
+        "            if attempt < retries:\n",
+        "                time.sleep(backoff_s)\n",
+        "    raise last_exc\n",
+        "\n",
+        "\n",
+        "_EXAMPLES_BASE = f\"{API_BASE}/{agent_id}/examples\"\n",
+        "if agent_id and agent_id != AGENT_NAME and actual_endpoint_name:\n",
+        "    if is_new:\n",
+        "        print(f\"\\nPolling MAS endpoint readiness ({actual_endpoint_name})...\")\n",
+        "        ep_ready = False\n",
+        "        for attempt in range(1, 61):\n",
+        "            try:\n",
+        "                resp = w.api_client.do(\"GET\", f\"/api/2.0/serving-endpoints/{actual_endpoint_name}\")\n",
+        "                state = resp.get(\"state\", {})\n",
+        "                ready = str(state.get(\"ready\", \"\")).upper()\n",
+        "                if ready == \"READY\":\n",
+        "                    print(f\"  \\u2705 Endpoint READY\")\n",
+        "                    ep_ready = True\n",
+        "                    break\n",
+        "                print(f\"  [{attempt}/60] state={ready} — waiting 20s…\")\n",
+        "            except Exception as e:\n",
+        "                print(f\"  [{attempt}/60] poll error: {e} — waiting 20s…\")\n",
+        "            time.sleep(20)\n",
+        "    else:\n",
+        "        # Re-runs: assume endpoint is already READY (Readiness_Check stage\n",
+        "        # would have failed earlier otherwise).  Skip the 20-min poll loop.\n",
+        "        ep_ready = True\n",
+        "\n",
+        "    if ep_ready:\n",
+        "        # Best-effort: clear existing examples before re-creating, so we\n",
+        "        # don't accumulate duplicates on every redeploy.  Skipped silently\n",
+        "        # if the list/delete endpoints aren't available on this surface.\n",
+        "        existing = []\n",
+        "        try:\n",
+        "            resp = w.api_client.do(\"GET\", _EXAMPLES_BASE)\n",
+        "            existing = resp.get(\"examples\", []) or []\n",
+        "        except Exception as _le:\n",
+        "            print(f\"  (skipping pre-clear: {_format_api_error(_le)})\")\n",
+        "        deleted, delete_failures = 0, 0\n",
+        "        for ex in existing:\n",
+        "            ex_id = ex.get(\"example_id\") or ex.get(\"id\")\n",
+        "            if not ex_id:\n",
+        "                continue\n",
+        "            try:\n",
+        "                _do_with_retry(\"DELETE\", f\"{_EXAMPLES_BASE}/{ex_id}\", retries=1, backoff_s=2.0)\n",
+        "                deleted += 1\n",
+        "            except Exception as _de:\n",
+        "                delete_failures += 1\n",
+        "                print(f\"  \\u26a0\\ufe0f  Could not delete existing example {ex_id}: {_format_api_error(_de)}\")\n",
+        "            time.sleep(0.4)  # gentle pacing — MAS examples API rate-limits bursts\n",
+        "        if existing:\n",
+        "            print(f\"  Cleared {deleted}/{len(existing)} existing example(s) before re-attach\"\n",
+        "                  f\"{f' (delete failures: {delete_failures})' if delete_failures else ''}\")\n",
+        "\n",
+        "        posted = 0\n",
+        "        failures = 0\n",
+        "        for ex in EXAMPLES:\n",
+        "            guideline = ex.get(\"guideline\")\n",
+        "            guidelines = ex.get(\"guidelines\")\n",
+        "            if guidelines is None and guideline is not None:\n",
+        "                guidelines = [guideline]\n",
+        "            body = {\"tile_id\": agent_id, \"question\": ex[\"question\"]}\n",
+        "            if guidelines:\n",
+        "                body[\"guidelines\"] = guidelines\n",
+        "            try:\n",
+        "                _do_with_retry(\"POST\", _EXAMPLES_BASE, body=body, retries=1, backoff_s=2.0)\n",
+        "                posted += 1\n",
+        "            except Exception as _pe:\n",
+        "                failures += 1\n",
+        "                print(f\"  \\u26a0\\ufe0f  Failed to attach example {ex['question']!r}: {_format_api_error(_pe)}\")\n",
+        "            time.sleep(0.4)  # gentle pacing — MAS examples API rate-limits bursts\n",
+        "        if failures:\n",
+        "            print(f\"\\u26a0\\ufe0f  Examples attached partially: {posted}/{len(EXAMPLES)} (failures={failures})\")\n",
+        "        else:\n",
+        "            print(f\"\\u2705 Examples attached ({posted}/{len(EXAMPLES)} questions, is_new={is_new})\")\n",
+        "    else:\n",
+        "        print(\"\\u26a0\\ufe0f  Endpoint not READY after 20 min — skipping examples (re-run to retry)\")\n",
+        "else:\n",
+        "    print(\"\\u26a0\\ufe0f  Skipping examples — agent_id or endpoint not resolved\")\n",
+        "\n",
+        "print(f\"\\n\\u2705 Operational Supervisor stage complete\")\n",
+        "print(f\"   Endpoint: {actual_endpoint_name}\")\n",
+        "print(\"   Sub-agents: revenue-analytics, operations-intelligence, menu-analytics, \"\n",
+        "      \"inspection-reports, menu-document-search, legal-complaints, regulatory-compliance, \"\n",
+        "      \"audit-findings, consultancy-strategy\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Production monitoring scorers\n",
+        "\n",
+        "Register the LLM-as-judge scorers that grade every live supervisor request.\n",
+        "Same idempotent register-or-restart pattern as `stages/refunder_agent.ipynb`\n",
+        "and `stages/complaint_agent.ipynb`, scoped to the supervisor's managed MLflow\n",
+        "experiment (`/Users/{me}/{mas_id}-dev-experiment`).\n",
+        "\n",
+        "Doing this inside the stage — rather than relying solely on\n",
+        "`stages/operational_evaluation.ipynb` cell 27 — means the\n",
+        "supervisor always has judges immediately after deploy, even when the\n",
+        "downstream `Evaluation` task is skipped or fails partway through its\n",
+        "`mlflow.genai.evaluate()` calls.\n",
+        "\n",
+        "5 scorers at 100% sampling:\n",
+        "\n",
+        "- `safety` — built-in `Safety()` LLM judge for harmful or inappropriate content\n",
+        "- `relevance_to_query` — built-in `RelevanceToQuery()` — does the answer address the question\n",
+        "- `operational_quality` — generic `Guidelines` — concrete data, not a hedge\n",
+        "- `routing_accuracy` — custom `@scorer` — vocabulary signals consistent with expected sub-agent (skipped in prod when no `expected_agent` is provided — useful for eval-time, harmless in prod)\n",
+        "- `cites_specific_data` — custom `@scorer` — does the response cite numbers, IDs, dates rather than hedge"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "\n",
+        "import mlflow\n",
+        "from mlflow.entities import Feedback\n",
+        "from mlflow.genai.scorers import (\n",
+        "    Guidelines,\n",
+        "    RelevanceToQuery,\n",
+        "    Safety,\n",
+        "    ScorerSamplingConfig,\n",
+        "    list_scorers,\n",
+        "    scorer,\n",
+        ")\n",
+        "\n",
+        "# Resolve the supervisor's managed experiment.  Agent Bricks names the dev\n",
+        "# experiment \"/Users/{me}/{mas_id}-dev-experiment\" where mas_id is the\n",
+        "# serving-endpoint name with \"-endpoint\" stripped.  set_experiment creates\n",
+        "# the experiment if Agent Bricks hasn't materialised it yet — AB normally\n",
+        "# creates it lazily on the first prediction call, which hasn't happened\n",
+        "# yet at this point in the stage.\n",
+        "_me = spark.sql(\"SELECT current_user()\").collect()[0][0]\n",
+        "_mas_id = actual_endpoint_name.replace(\"-endpoint\", \"\")\n",
+        "sup_experiment_name = f\"/Users/{_me}/{_mas_id}-dev-experiment\"\n",
+        "sup_experiment = mlflow.set_experiment(sup_experiment_name)\n",
+        "sup_experiment_id = sup_experiment.experiment_id\n",
+        "print(f\"Supervisor experiment: {sup_experiment_name} (id={sup_experiment_id})\")\n",
+        "\n",
+        "\n",
+        "# Custom scorers — duplicated from stages/operational_evaluation.ipynb\n",
+        "# to keep this stage self-contained (no shared utils import from /utils — the\n",
+        "# stage already imports prompt_registry from there and adding more shared eval\n",
+        "# code muddles the separation).  Edit BOTH places if signatures change.\n",
+        "_AGENT_SIGNALS = {\n",
+        "    \"revenue\":     [\"revenue\", \"cancellation rate\", \"order count\", \"orders placed\", \"sales\", \"avg order\", \"weekly\", \"total orders\"],\n",
+        "    \"operations\":  [\"complaint rate\", \"kitchen\", \"operational\", \"throughput\", \"busiest\", \"food safety grade\", \"cancel rate\"],\n",
+        "    \"inspection\":  [\"inspection report\", \"violation\", \"inspector\", \"corrective action\", \"grade\", \"score\", \"health permit\"],\n",
+        "    \"legal\":       [\"case no\", \"ck-\", \"risk level\", \"amount at stake\", \"counsel\", \"litigation\", \"plaintiff\", \"high risk\"],\n",
+        "    \"regulatory\":  [\"permit\", \"certificate\", \"expiry\", \"regulatory\", \"fda\", \"zoning\", \"issuing authority\"],\n",
+        "    \"audits\":      [\"audit\", \"auditor\", \"finding\", \"pwc\", \"deloitte\", \"kpmg\", \"significant\", \"critical finding\"],\n",
+        "    \"consultancy\": [\"consultant\", \"roi\", \"recommend\", \"strategy\", \"mckinsey\", \"phase 1\", \"investment\"],\n",
+        "    \"multi\":       [\"revenue\", \"legal\", \"audit\", \"operational\"],\n",
+        "}\n",
+        "\n",
+        "\n",
+        "@scorer\n",
+        "def routing_accuracy(inputs: dict, outputs, expectations: dict = None) -> Feedback:\n",
+        "    \"\"\"Heuristic: does the response use vocabulary consistent with the expected sub-agent?\n",
+        "\n",
+        "    Returns None (skipped) when no `expected_agent` is provided — that's the\n",
+        "    norm in production traffic, where users don't tag their messages with the\n",
+        "    expected routing target.  Useful at eval time, harmless in prod.\n",
+        "    \"\"\"\n",
+        "    def _as_text(o):\n",
+        "        # Inlined so the registered/serialized scorer can resolve it at runtime.\n",
+        "        if o is None: return \"\"\n",
+        "        if isinstance(o, str): return o\n",
+        "        if isinstance(o, dict):\n",
+        "            v = o.get(\"final_response\")\n",
+        "            if isinstance(v, str): return v\n",
+        "            msgs = o.get(\"messages\")\n",
+        "            if isinstance(msgs, list):\n",
+        "                for m in reversed(msgs):\n",
+        "                    if isinstance(m, dict) and m.get(\"role\") == \"assistant\":\n",
+        "                        c = m.get(\"content\")\n",
+        "                        if isinstance(c, str): return c\n",
+        "            choices = o.get(\"choices\")\n",
+        "            if isinstance(choices, list) and choices:\n",
+        "                try:\n",
+        "                    c = choices[0][\"message\"][\"content\"]\n",
+        "                    if isinstance(c, str): return c\n",
+        "                except (KeyError, TypeError):\n",
+        "                    pass\n",
+        "            output = o.get(\"output\")\n",
+        "            if isinstance(output, str): return output\n",
+        "            if isinstance(output, list):\n",
+        "                parts = []\n",
+        "                for it in output:\n",
+        "                    if isinstance(it, dict):\n",
+        "                        c = it.get(\"content\")\n",
+        "                        if isinstance(c, str): parts.append(c)\n",
+        "                        elif isinstance(c, list):\n",
+        "                            for piece in c:\n",
+        "                                if isinstance(piece, dict):\n",
+        "                                    parts.append(piece.get(\"text\", piece.get(\"value\", \"\")) or \"\")\n",
+        "                if parts: return \" \".join(parts)\n",
+        "        return str(o)\n",
+        "    expected_agent = (inputs or {}).get(\"expected_agent\") or (expectations or {}).get(\"expected_agent\", \"\")\n",
+        "    response_lower = _as_text(outputs).lower()\n",
+        "    if not expected_agent or expected_agent not in _AGENT_SIGNALS:\n",
+        "        return Feedback(value=None, rationale=\"No expected_agent specified — skipped\")\n",
+        "    signals = _AGENT_SIGNALS[expected_agent]\n",
+        "    if expected_agent == \"multi\":\n",
+        "        domains_present = sum(\n",
+        "            1 for ds in _AGENT_SIGNALS.values()\n",
+        "            if any(s in response_lower for s in ds)\n",
+        "        )\n",
+        "        score = min(1.0, domains_present / 4.0)\n",
+        "        rationale = f\"{domains_present} agent domains detected in board summary response\"\n",
+        "    else:\n",
+        "        matched = [s for s in signals if s in response_lower]\n",
+        "        score = min(1.0, len(matched) / max(2, len(signals) // 2))\n",
+        "        rationale = f\"Matched signals: {matched}\" if matched else \"No expected-agent signals detected in response\"\n",
+        "    return Feedback(value=score, rationale=rationale)\n",
+        "\n",
+        "\n",
+        "@scorer\n",
+        "def cites_specific_data(inputs: dict, outputs, expectations: dict = None) -> Feedback:\n",
+        "    \"\"\"Heuristic: did the response cite concrete data (numbers, IDs, dates) rather than hedge?\"\"\"\n",
+        "    import re  # imported inside the function so the registered/serialized scorer can resolve it at runtime\n",
+        "    def _as_text(o):\n",
+        "        # Inlined so the registered/serialized scorer can resolve it at runtime.\n",
+        "        # Eval time hands us the string from predict_fn; prod monitoring hands us\n",
+        "        # the raw trace outputs (dict-shaped for the MAS endpoint).\n",
+        "        if o is None: return \"\"\n",
+        "        if isinstance(o, str): return o\n",
+        "        if isinstance(o, dict):\n",
+        "            v = o.get(\"final_response\")\n",
+        "            if isinstance(v, str): return v\n",
+        "            msgs = o.get(\"messages\")\n",
+        "            if isinstance(msgs, list):\n",
+        "                for m in reversed(msgs):\n",
+        "                    if isinstance(m, dict) and m.get(\"role\") == \"assistant\":\n",
+        "                        c = m.get(\"content\")\n",
+        "                        if isinstance(c, str): return c\n",
+        "            choices = o.get(\"choices\")\n",
+        "            if isinstance(choices, list) and choices:\n",
+        "                try:\n",
+        "                    c = choices[0][\"message\"][\"content\"]\n",
+        "                    if isinstance(c, str): return c\n",
+        "                except (KeyError, TypeError):\n",
+        "                    pass\n",
+        "            output = o.get(\"output\")\n",
+        "            if isinstance(output, str): return output\n",
+        "            if isinstance(output, list):\n",
+        "                parts = []\n",
+        "                for it in output:\n",
+        "                    if isinstance(it, dict):\n",
+        "                        c = it.get(\"content\")\n",
+        "                        if isinstance(c, str): parts.append(c)\n",
+        "                        elif isinstance(c, list):\n",
+        "                            for piece in c:\n",
+        "                                if isinstance(piece, dict):\n",
+        "                                    parts.append(piece.get(\"text\", piece.get(\"value\", \"\")) or \"\")\n",
+        "                if parts: return \" \".join(parts)\n",
+        "        return str(o)\n",
+        "    response = _as_text(outputs)\n",
+        "    patterns = [\n",
+        "        r\"\\d+\\.?\\d*\\s*%\",                                # percentages\n",
+        "        r\"\\$\\s*[\\d,]+\",                                   # dollar amounts\n",
+        "        r\"CK-\\d+-\\d+\",                                    # legal case numbers\n",
+        "        r\"\\d{4}-\\d{2}-\\d{2}\",                             # ISO dates\n",
+        "        r\"\\b(?:score|grade)\\s*(?:of\\s*)?\\d+\",             # inspection scores\n",
+        "        r\"\\b\\d+x\\b\",                                      # ROI multiples\n",
+        "        r\"\\b\\d+\\s+(?:cases?|orders?|locations?|findings?)\",\n",
+        "    ]\n",
+        "    found = [p for p in patterns if re.search(p, response, re.IGNORECASE)]\n",
+        "    hedges = [\"i don't have access\", \"i cannot provide\", \"i'm unable\", \"consult your\", \"please check with\"]\n",
+        "    is_hedged = any(h in response.lower() for h in hedges)\n",
+        "    if is_hedged and len(found) < 2:\n",
+        "        return Feedback(value=0.0, rationale=\"Response is hedged with no concrete data — agent likely failed to retrieve\")\n",
+        "    score = min(1.0, len(found) / 3.0)\n",
+        "    return Feedback(value=score, rationale=f\"Data patterns found: {len(found)} types — {found}\")\n",
+        "\n",
+        "\n",
+        "def _register_scorer(scorer_obj, name: str, sample_rate: float = 1.0):\n",
+        "    \"\"\"Idempotent register-or-restart, scoped to the supervisor's prod experiment.\n",
+        "\n",
+        "    Re-running the stage hits the same code path; calling .register() on an\n",
+        "    already-registered scorer raises ValueError, so we look it up first and\n",
+        "    just .start() it instead.  Same shape as stages/refunder_agent.ipynb and\n",
+        "    stages/complaint_agent.ipynb.\n",
+        "    \"\"\"\n",
+        "    existing = {s.name: s for s in list_scorers(experiment_id=sup_experiment_id)}\n",
+        "    sampling = ScorerSamplingConfig(sample_rate=sample_rate)\n",
+        "    if name in existing:\n",
+        "        existing[name].start(sampling_config=sampling)\n",
+        "        print(f\"  ↺ {name} — restarted at {sample_rate:.0%} sample rate\")\n",
+        "        return existing[name]\n",
+        "    registered = scorer_obj.register(name=name, experiment_id=sup_experiment_id)\n",
+        "    registered.start(sampling_config=sampling)\n",
+        "    print(f\"  ✅ {name} — registered + started at {sample_rate:.0%} sample rate\")\n",
+        "    return registered\n",
+        "\n",
+        "\n",
+        "# Baseline — every agent in the bundle gets these three.\n",
+        "_register_scorer(Safety(),           name=\"safety\",             sample_rate=1.0)\n",
+        "_register_scorer(RelevanceToQuery(), name=\"relevance_to_query\", sample_rate=1.0)\n",
+        "_register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"operational_quality\",\n",
+        "        guidelines=(\n",
+        "            \"The response must include specific data points such as numbers, percentages, \"\n",
+        "            \"dates, case numbers, or named locations. \"\n",
+        "            \"The response must not be a generic hedge or refusal (e.g. 'I don't have access'). \"\n",
+        "            \"The response must directly answer the question asked.\"\n",
+        "        ),\n",
+        "    ),\n",
+        "    name=\"operational_quality\",\n",
+        "    sample_rate=1.0,\n",
+        ")\n",
+        "\n",
+        "# Domain — supervisor-specific routing and data-citation heuristics.\n",
+        "_register_scorer(routing_accuracy,    name=\"routing_accuracy\",    sample_rate=1.0)\n",
+        "_register_scorer(cites_specific_data, name=\"cites_specific_data\", sample_rate=1.0)\n",
+        "\n",
+        "print(\"\\n✅ Production monitoring enabled — 5 scorers active at 100% sampling\")\n",
+        "print(f\"   View judges:    {sup_experiment_name} → Monitoring tab\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/stages/raw_data.ipynb b/stages/raw_data.ipynb
deleted file mode 100644
index 870a49a..0000000
--- a/stages/raw_data.ipynb
+++ /dev/null
@@ -1,472 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "b4b235ce-c6b8-4573-bca3-2719632d4efc",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "### Raw Data\n",
-    "\n",
-    "This notebook will bootstrap Caspers raw data into the provided catalog and schema"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "e7ea4bbf-d953-4c42-8c04-046392612a75",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "f9100bbc-b3e0-4fff-8aac-af90d83f426e",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "dbutils.library.restartPython()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "8ed7fe02-e440-448a-a4e7-a3bb957e70b0",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "EVENTS_VOLUME = dbutils.widgets.get(\"EVENTS_VOLUME\")\n",
-    "SIMULATOR_SCHEMA = dbutils.widgets.get(\"SIMULATOR_SCHEMA\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "82e95cb7-3475-45f3-ba9f-1c508cda06eb",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Create main catalog, simulator related schemas and volumes"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "326b836a-0c13-4239-b013-18cc6f7c889e",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE CATALOG IF NOT EXISTS ${CATALOG};\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.${SIMULATOR_SCHEMA};\n",
-    "CREATE VOLUME IF NOT EXISTS ${CATALOG}.${SIMULATOR_SCHEMA}.${EVENTS_VOLUME};"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "3c2c4b0e-8a4c-459c-bb7b-67b19e5e6b1d",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Create tables from parquet data"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "21a83f2b-d1d3-4e33-bd43-ef7c5fd5baf1",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "import pandas as pd\n",
-    "\n",
-    "spark.createDataFrame(pd.read_parquet(\"../data/dimensional/brands.parquet\")) \\\n",
-    "    .write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.{SIMULATOR_SCHEMA}.brands\")\n",
-    "spark.createDataFrame(pd.read_parquet(\"../data/dimensional/menus.parquet\")) \\\n",
-    "    .write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.{SIMULATOR_SCHEMA}.menus\")\n",
-    "spark.createDataFrame(pd.read_parquet(\"../data/dimensional/categories.parquet\")) \\\n",
-    "    .write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.{SIMULATOR_SCHEMA}.categories\")\n",
-    "spark.createDataFrame(pd.read_parquet(\"../data/dimensional/items.parquet\")) \\\n",
-    "    .write.mode(\"overwrite\").saveAsTable(f\"{CATALOG}.{SIMULATOR_SCHEMA}.items\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "859d56d9-d728-44b2-be13-39b1a67e59e0",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Start data generation"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "2d57d601-108d-4ea2-a47d-8c52b0a8adba",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Read all .jsons in ./data/generator/configs. Each json file represents a location."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "ded63223-6426-43ec-aa6f-953e16879833",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "import glob\n",
-    "import os\n",
-    "\n",
-    "# Get all JSON file paths under the directory\n",
-    "json_paths = glob.glob(\"../data/generator/configs/*.json\")\n",
-    "\n",
-    "# Read each file's content as a string and collect into a dict mapping filename to content\n",
-    "config_json_map = {}\n",
-    "for path in json_paths:\n",
-    "    filename = os.path.basename(path)\n",
-    "    with open(path, \"r\", encoding=\"utf-8\") as f:\n",
-    "        config_json_map[filename] = f.read()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "2f9074aa-5853-492d-a54b-c31a3470dc25",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Start a job for each of the config jsons found in ./data/generator/configs"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "source": "# Filter locations based on LOCATIONS parameter\nlocations_param = dbutils.widgets.get(\"LOCATIONS\")\nif locations_param.lower() != \"all\":\n    selected = [loc.strip() for loc in locations_param.split(\",\")]\n    config_json_map = {k: v for k, v in config_json_map.items() if k in selected}\n    print(f\"Running selected locations: {list(config_json_map.keys())}\")\nelse:\n    print(f\"Running all locations: {list(config_json_map.keys())}\")",
-   "metadata": {},
-   "execution_count": null,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "fb5b2f59-c6a9-4158-bbdf-9397fe473e18",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "import databricks.sdk.service.jobs as j\n",
-    "import os, json\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "# Resolve the workspace notebook path (keeps your approach)\n",
-    "notebook_abs_path = os.path.abspath(\"../data/generator/generator\")\n",
-    "notebook_dbx_path = notebook_abs_path.replace(\n",
-    "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
-    "    \"/Workspace\"\n",
-    ")\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "for filename, json_content in config_json_map.items():\n",
-    "    job_name = f\"Order Flow Generator: {filename}\"\n",
-    "\n",
-    "    # Ensure SIM_CFG_JSON is a JSON string (Jobs widget params are strings)\n",
-    "    sim_cfg_str = json_content if isinstance(json_content, str) else json.dumps(json_content)\n",
-    "\n",
-    "    job = w.jobs.create(\n",
-    "        name=job_name,\n",
-    "        tasks=[\n",
-    "            j.Task(\n",
-    "                task_key=\"order_flow_generator\",\n",
-    "                notebook_task=j.NotebookTask(\n",
-    "                    notebook_path=notebook_dbx_path,\n",
-    "                    base_parameters={\n",
-    "                        \"CATALOG\": CATALOG,\n",
-    "                        \"VOLUME\": EVENTS_VOLUME,\n",
-    "                        \"SCHEMA\": SIMULATOR_SCHEMA,\n",
-    "                        \"SIM_CFG_JSON\": sim_cfg_str,\n",
-    "                    },\n",
-    "                )\n",
-    "            )\n",
-    "        ],\n",
-    "    )\n",
-    "    print(f\"Created job_id={job.job_id} for {filename}\")\n",
-    "    add(CATALOG, \"jobs\", job)\n",
-    "    w.jobs.run_now(job_id=job.job_id)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "8f0b77b8-650e-4ad9-a538-fbf39163af37",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "source": [
-    "\n",
-    "##### Blocking cell to wait for some data to arrive at the volume.\n",
-    "\n",
-    "The lakeflow declarative pipeline that comes next infers the schema from existing data.\n",
-    "\n",
-    "Lakeflow Jobs doesn't have a file arrival trigger at the task level (yet?)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 0,
-   "metadata": {
-    "application/vnd.databricks.v1+cell": {
-     "cellMetadata": {},
-     "inputWidgets": {},
-     "nuid": "f5b6e3df-ece6-477f-a057-ff2c97c6f888",
-     "showTitle": false,
-     "tableResultSettingsMap": {},
-     "title": ""
-    }
-   },
-   "outputs": [],
-   "source": [
-    "import time\n",
-    "\n",
-    "# Construct the path to the volume where JSONs will arrive\n",
-    "volume_path = f\"/Volumes/{CATALOG}/{SIMULATOR_SCHEMA}/{EVENTS_VOLUME}\"\n",
-    "\n",
-    "def wait_for_data(path, timeout=300, poll_interval=5):\n",
-    "    \"\"\"\n",
-    "    Wait until at least one file appears in the given path.\n",
-    "    Args:\n",
-    "        path (str): The directory to watch.\n",
-    "        timeout (int): Maximum seconds to wait.\n",
-    "        poll_interval (int): Seconds between checks.\n",
-    "    Raises:\n",
-    "        TimeoutError: If no file appears within the timeout.\n",
-    "    \"\"\"\n",
-    "    start = time.time()\n",
-    "    while time.time() - start < timeout:\n",
-    "        files = dbutils.fs.ls(path)\n",
-    "        if any(f.size > 0 for f in files if not f.path.endswith('/')):\n",
-    "            print(\"Data arrived. Safe to proceed.\")\n",
-    "            return\n",
-    "        time.sleep(poll_interval)\n",
-    "    raise TimeoutError(f\"No data found in {path} after {timeout} seconds.\")\n",
-    "\n",
-    "wait_for_data(volume_path)"
-   ]
-  }
- ],
- "metadata": {
-  "application/vnd.databricks.v1+notebook": {
-   "computePreferences": null,
-   "dashboards": [],
-   "environmentMetadata": {
-    "base_environment": "",
-    "environment_version": "3"
-   },
-   "inputWidgetPreferences": null,
-   "language": "python",
-   "notebookMetadata": {
-    "pythonIndentUnit": 4
-   },
-   "notebookName": "raw_data",
-   "widgets": {
-    "CATALOG": {
-     "currentValue": "",
-     "nuid": "39bc9f65-25ff-4696-83c3-89b3d5ecc686",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "CATALOG",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
-      },
-      "widgetType": "text"
-     }
-    },
-    "EVENTS_VOLUME": {
-     "currentValue": "",
-     "nuid": "06d6cc56-f73c-4948-b84f-f0f12cd47a94",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "EVENTS_VOLUME",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "EVENTS_VOLUME",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
-      },
-      "widgetType": "text"
-     }
-    },
-    "SIMULATOR_SCHEMA": {
-     "currentValue": "",
-     "nuid": "70241427-8b78-43ec-8435-9688f17f69d9",
-     "typedWidgetInfo": {
-      "autoCreated": false,
-      "defaultValue": "",
-      "label": "",
-      "name": "SIMULATOR_SCHEMA",
-      "options": {
-       "validationRegex": null,
-       "widgetDisplayType": "Text"
-      },
-      "parameterDataType": "String"
-     },
-     "widgetInfo": {
-      "defaultValue": "",
-      "label": "",
-      "name": "SIMULATOR_SCHEMA",
-      "options": {
-       "autoCreated": false,
-       "validationRegex": null,
-       "widgetType": "text"
-      },
-      "widgetType": "text"
-     }
-    }
-   }
-  },
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 0
-}
\ No newline at end of file
diff --git a/stages/refund_evaluation.ipynb b/stages/refund_evaluation.ipynb
new file mode 100644
index 0000000..3ca8df9
--- /dev/null
+++ b/stages/refund_evaluation.ipynb
@@ -0,0 +1,486 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Refund Agent — Evaluation\n",
+        "\n",
+        "Standalone evaluation task for the deployed Refund Agent. Runs after\n",
+        "`Refund_Recommender_Agent` in the pipeline so the endpoint is up before\n",
+        "we hit it.\n",
+        "\n",
+        "- **Gated by `SKIP_EVAL`** (default `\"true\"`) — flip to `\"false\"` to actually\n",
+        "  run the evaluation. The default skip is a deliberate rate-limit safeguard:\n",
+        "  evaluation is the burst-iest LLM consumer in the bundle and can hit the\n",
+        "  shared FMAPI endpoint's QPS cap when refund + complaint eval run\n",
+        "  back-to-back.\n",
+        "- Calls the deployed endpoint via `mlflow.deployments.get_deploy_client`\n",
+        "  rather than importing the agent module — so this notebook is fully\n",
+        "  self-contained and tests the actual production endpoint shape.\n",
+        "- Eval results land in `/Shared/{CATALOG}_refund_agent_dev`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install -U -qqqq mlflow-skinny[databricks] databricks-sdk\n",
+        "dbutils.library.restartPython()"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "ENDPOINT_NAME = dbutils.widgets.get(\"REFUND_AGENT_ENDPOINT_NAME\")\n",
+        "\n",
+        "try:\n",
+        "    SKIP_EVAL = dbutils.widgets.get(\"SKIP_EVAL\").strip().lower() == \"true\"\n",
+        "except Exception:\n",
+        "    SKIP_EVAL = True\n",
+        "\n",
+        "import mlflow\n",
+        "\n",
+        "DEV_EXPERIMENT = f\"/Shared/{CATALOG}_refund_agent_dev\"\n",
+        "mlflow.set_experiment(DEV_EXPERIMENT)\n",
+        "\n",
+        "print(f\"Catalog:          {CATALOG}\")\n",
+        "print(f\"Endpoint:         {ENDPOINT_NAME}\")\n",
+        "print(f\"SKIP_EVAL:        {SKIP_EVAL}\")\n",
+        "print(f\"Dev experiment:   {DEV_EXPERIMENT}\")\n",
+        "print(f\"MLflow version:   {mlflow.__version__}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "if SKIP_EVAL:\n",
+        "    print(\n",
+        "        f\"⏭  SKIP_EVAL=true — skipping mlflow.genai.evaluate to avoid the ~20 \"\n",
+        "        f\"LM-call eval burst.  Pass --params \\\"SKIP_EVAL=false\\\" to actually run \"\n",
+        "        f\"the evaluation (e.g. before a demo or after a prompt change).\"\n",
+        "    )\n",
+        "    dbutils.notebook.exit(\"skipped\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "POLL_INTERVAL_S = 15\n",
+        "MAX_POLLS = 40\n",
+        "\n",
+        "print(f\"Polling endpoint readiness ({MAX_POLLS * POLL_INTERVAL_S // 60} min max)…\")\n",
+        "\n",
+        "for attempt in range(1, MAX_POLLS + 1):\n",
+        "    try:\n",
+        "        ep = w.serving_endpoints.get(ENDPOINT_NAME)\n",
+        "        ready = str(getattr(ep.state, \"ready\", \"\")).upper() if ep.state else \"\"\n",
+        "        cfg_update = str(getattr(ep.state, \"config_update\", \"\")).upper() if ep.state else \"\"\n",
+        "        if \"READY\" in ready:\n",
+        "            print(f\"  ✅ Endpoint READY (config_update={cfg_update or 'n/a'})\")\n",
+        "            break\n",
+        "        print(f\"  ⏳ [{attempt}/{MAX_POLLS}] ready={ready}, config_update={cfg_update}\")\n",
+        "    except Exception as e:\n",
+        "        print(f\"  ⚠️  poll error: {type(e).__name__}: {e}\")\n",
+        "    time.sleep(POLL_INTERVAL_S)\n",
+        "else:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Endpoint {ENDPOINT_NAME} did not become READY within \"\n",
+        "        f\"{MAX_POLLS * POLL_INTERVAL_S // 60} minutes.\"\n",
+        "    )"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import os\n",
+        "import random\n",
+        "from mlflow.deployments import get_deploy_client\n",
+        "\n",
+        "os.environ[\"MLFLOW_GENAI_EVAL_MAX_WORKERS\"] = \"1\"\n",
+        "os.environ[\"MLFLOW_GENAI_EVAL_MAX_SCORER_WORKERS\"] = \"1\"\n",
+        "# Bump client-side HTTP timeouts. Defaults (120s) trip up agent endpoints and\n",
+        "# the LLM judge calls inside scorers (Safety / RelevanceToQuery / Guidelines).\n",
+        "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TIMEOUT\", \"600\")\n",
+        "os.environ.setdefault(\"MLFLOW_DEPLOYMENT_PREDICT_TOTAL_TIMEOUT\", \"900\")\n",
+        "os.environ.setdefault(\"MLFLOW_HTTP_REQUEST_TIMEOUT\", \"600\")\n",
+        "\n",
+        "_deploy_client = get_deploy_client(\"databricks\")\n",
+        "\n",
+        "\n",
+        "def _is_rate_limit(exc: BaseException) -> bool:\n",
+        "    msg = str(exc)\n",
+        "    return (\n",
+        "        \"REQUEST_LIMIT_EXCEEDED\" in msg\n",
+        "        or \"RateLimitError\" in type(exc).__name__\n",
+        "        or \"rate limit\" in msg.lower()\n",
+        "    )\n",
+        "\n",
+        "\n",
+        "def predict_fn(messages):\n",
+        "    \"\"\"Call the deployed Refund Agent endpoint with retry-on-rate-limit.\"\"\"\n",
+        "    max_attempts = 6\n",
+        "    for attempt in range(max_attempts):\n",
+        "        try:\n",
+        "            return _deploy_client.predict(\n",
+        "                endpoint=ENDPOINT_NAME,\n",
+        "                inputs={\"messages\": messages},\n",
+        "            )\n",
+        "        except Exception as exc:\n",
+        "            if not _is_rate_limit(exc) or attempt == max_attempts - 1:\n",
+        "                raise\n",
+        "            backoff = min(60, 2 ** attempt) + random.uniform(0, 1)\n",
+        "            print(f\"  ⚠️  rate-limited (attempt {attempt + 1}/{max_attempts}), sleeping {backoff:.1f}s\")\n",
+        "            time.sleep(backoff)\n",
+        "\n",
+        "\n",
+        "print(f\"✅ predict_fn defined — will call endpoint {ENDPOINT_NAME}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json as _json\n",
+        "import mlflow.genai.datasets\n",
+        "\n",
+        "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.refund_agent_eval_dataset\"\n",
+        "\n",
+        "# Read the dataset registered by stages/refund_setup.ipynb. The setup task\n",
+        "# JSON-stringifies any list-typed field on write (Arrow + mlflow.genai.datasets\n",
+        "# can't reliably serialize ARRAY<STRING>), so we deserialize symmetrically.\n",
+        "_rows = spark.table(UC_DATASET_TABLE).toPandas().to_dict(orient=\"records\")\n",
+        "\n",
+        "\n",
+        "def _deserialize_record(rec):\n",
+        "    \"\"\"Recursively undo the JSON-stringification done by setup.\"\"\"\n",
+        "    out = {}\n",
+        "    for k, v in rec.items():\n",
+        "        if isinstance(v, dict):\n",
+        "            out[k] = _deserialize_record(v)\n",
+        "        elif isinstance(v, str):\n",
+        "            try:\n",
+        "                parsed = _json.loads(v)\n",
+        "                out[k] = parsed if isinstance(parsed, (list, dict)) else v\n",
+        "            except (ValueError, TypeError):\n",
+        "                out[k] = v\n",
+        "        else:\n",
+        "            out[k] = v\n",
+        "    return out\n",
+        "\n",
+        "\n",
+        "EVAL_DATASET = [_deserialize_record(r) for r in _rows]\n",
+        "\n",
+        "if not EVAL_DATASET:\n",
+        "    raise RuntimeError(\n",
+        "        f\"{UC_DATASET_TABLE} is empty. Re-run the Refund_Setup task first \"\n",
+        "        \"(it builds the dataset from {CATALOG}.lakeflow.all_events).\"\n",
+        "    )\n",
+        "\n",
+        "print(f\"Loaded {len(EVAL_DATASET)} eval rows from {UC_DATASET_TABLE}\")\n",
+        "\n",
+        "import mlflow\n",
+        "import mlflow.genai\n",
+        "\n",
+        "# Required: without databricks-uc the registry client hits workspace MLflow,\n",
+        "# where 3-part names are opaque strings and load_prompt raises NotFound.\n",
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "\n",
+        "# Resolve the production prompt version so eval runs can be tagged with it.\n",
+        "# Lets a failing scorer point at exactly which prompt revision regressed.\n",
+        "PROMPT_NAME = \"refund_system\"\n",
+        "PROMPT_URI = f\"prompts:/{CATALOG}.prompts.{PROMPT_NAME}@production\"\n",
+        "try:\n",
+        "    PROMPT_VERSION = str(mlflow.genai.load_prompt(PROMPT_URI).version)\n",
+        "    print(f\"  Resolved {PROMPT_URI} -> v{PROMPT_VERSION}\")\n",
+        "except Exception as _exc:\n",
+        "    PROMPT_VERSION = \"unknown\"\n",
+        "    print(f\"  Could not resolve {PROMPT_URI}: {type(_exc).__name__}: {_exc}\")\n"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from mlflow.genai.scorers import Guidelines, Safety\n",
+        "try:\n",
+        "    from mlflow.genai.scorers import RelevanceToQuery\n",
+        "    _has_relevance = True\n",
+        "except ImportError:\n",
+        "    RelevanceToQuery = None\n",
+        "    _has_relevance = False\n",
+        "    print(\"⚠\\ufe0f  RelevanceToQuery not available in this MLflow version — skipping it from the eval mix\")\n",
+        "\n",
+        "refund_reason = Guidelines(\n",
+        "    name=\"refund_reason\",\n",
+        "    guidelines=[\n",
+        "        \"If a refund is offered, its reason must relate to order timing, \"\n",
+        "        \"not to other issues such as missing components.\"\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "policy_alignment = Guidelines(\n",
+        "    name=\"policy_alignment\",\n",
+        "    guidelines=[\n",
+        "        \"If the response is a refund decision, it must explicitly state APPROVED or DENIED \"\n",
+        "        \"(or partial), and the decision must be consistent with the cited order/customer evidence. \"\n",
+        "        \"An approval without supporting evidence (or a denial that ignores documented order issues) fails.\"\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "cites_evidence = Guidelines(\n",
+        "    name=\"cites_evidence\",\n",
+        "    guidelines=[\n",
+        "        \"The response must cite specific evidence from the order or customer history \\u2014 \"\n",
+        "        \"for example order ID, item names, prices, complaint history, refund amount, or timestamps. \"\n",
+        "        \"A response that just states a decision without grounding in the order data fails.\"\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "decision_clarity = Guidelines(\n",
+        "    name=\"decision_clarity\",\n",
+        "    guidelines=[\n",
+        "        \"The response must clearly explain WHY the refund decision was made, in 1\\u20133 sentences, \"\n",
+        "        \"in language a customer support agent could read aloud. \"\n",
+        "        \"It must not be a JSON dump or unstructured reasoning trace.\"\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "_DATASET_SCORERS = [\n",
+        "    refund_reason,\n",
+        "    policy_alignment,\n",
+        "    cites_evidence,\n",
+        "    decision_clarity,\n",
+        "    Safety(),\n",
+        "]\n",
+        "if _has_relevance:\n",
+        "    _DATASET_SCORERS.append(RelevanceToQuery())\n",
+        "\n",
+        "print(f\"✅ Scorers defined ({len(_DATASET_SCORERS)}): \" + \", \".join(s.name if hasattr(s, 'name') else type(s).__name__ for s in _DATASET_SCORERS))"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import mlflow.genai\n",
+        "\n",
+        "_mlflow_dataset = mlflow.data.from_spark(\n",
+        "    spark.table(UC_DATASET_TABLE),\n",
+        "    table_name=UC_DATASET_TABLE,\n",
+        ")\n",
+        "\n",
+        "with mlflow.start_run(run_name=f\"{CATALOG}-refund-agent-eval\"):\n",
+        "    mlflow.log_input(_mlflow_dataset, context=\"eval\")\n",
+        "    mlflow.log_param(\"prompt_uri\", PROMPT_URI)\n",
+        "    mlflow.log_param(\"prompt_version\", PROMPT_VERSION)\n",
+        "    results = mlflow.genai.evaluate(\n",
+        "        data=EVAL_DATASET,\n",
+        "        scorers=_DATASET_SCORERS,\n",
+        "        predict_fn=predict_fn,\n",
+        "    )\n",
+        "\n",
+        "print(\"\\n✅ Evaluation complete\")\n",
+        "print(f\"  metrics: {getattr(results, 'metrics', 'N/A')}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Trace-derived eval — recent production calls\n",
+        "\n",
+        "The block above runs a curated dataset against the deployed endpoint. That's\n",
+        "useful for catching regressions on **known-good scenarios**, but it doesn't\n",
+        "tell us how the agent is doing on **real production traffic**.\n",
+        "\n",
+        "This section harvests the most recent successful traces from the prod\n",
+        "experiment (`/Shared/{CATALOG}_refund_agent_prod` — populated whenever the\n",
+        "streaming pipeline triggers a refund decision), turns them back into eval\n",
+        "inputs, and re-runs the agent against them with a global quality\n",
+        "guideline.\n",
+        "\n",
+        "This mirrors the pattern in `stages/operational_evaluation.ipynb`\n",
+        "for the Operational Supervisor, so all three agents share the same flywheel:\n",
+        "\n",
+        "```\n",
+        "Production traffic → MLflow traces → resampled eval dataset → quality scoring\n",
+        "```\n",
+        "\n",
+        "Skipped gracefully if the prod experiment doesn't exist yet or has no\n",
+        "traces (fresh deploy with no traffic)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import pandas as pd\n",
+        "\n",
+        "prod_experiment_name = f\"/Shared/{CATALOG}_refund_agent_prod\"\n",
+        "trace_eval_data = []\n",
+        "traces_df = pd.DataFrame()\n",
+        "\n",
+        "try:\n",
+        "    _exp = mlflow.get_experiment_by_name(prod_experiment_name)\n",
+        "except Exception as exc:\n",
+        "    print(f\"  Could not look up prod experiment: {type(exc).__name__}: {exc}\")\n",
+        "    _exp = None\n",
+        "\n",
+        "if _exp is None:\n",
+        "    print(\n",
+        "        f\"Skipping trace eval — experiment {prod_experiment_name} not found.\\n\"\n",
+        "        \"  Send some refund decisions through the deployed endpoint first.\"\n",
+        "    )\n",
+        "else:\n",
+        "    print(f\"Found prod traces experiment: {prod_experiment_name} ({_exp.experiment_id})\")\n",
+        "\n",
+        "    # `return_type=\"list\"` is required — `mlflow.search_traces()` returns a\n",
+        "    # pandas DataFrame by default in MLflow 3, and iterating it yields column\n",
+        "    # names (strings).  The iteration below expects `Trace` objects with\n",
+        "    # `.data.spans` / `.info.request_id`, so we explicitly request the list form.\n",
+        "    traces = mlflow.search_traces(\n",
+        "        experiment_ids=[_exp.experiment_id],\n",
+        "        filter_string=\"status = 'OK'\",\n",
+        "        max_results=50,\n",
+        "        order_by=[\"timestamp DESC\"],\n",
+        "        return_type=\"list\",\n",
+        "    )\n",
+        "    print(f\"Pulled {len(traces)} OK-status traces (most recent 50).\")\n",
+        "\n",
+        "    records = []\n",
+        "    for trace in traces:\n",
+        "        try:\n",
+        "            root = trace.data.spans[0]\n",
+        "            inputs_raw = root.inputs or {}\n",
+        "            messages = inputs_raw.get(\"messages\", [])\n",
+        "            question = next(\n",
+        "                (m[\"content\"] for m in messages if m.get(\"role\") == \"user\"),\n",
+        "                None,\n",
+        "            )\n",
+        "            if question:\n",
+        "                records.append({\n",
+        "                    \"trace_id\": trace.info.request_id,\n",
+        "                    \"timestamp_ms\": trace.info.timestamp_ms,\n",
+        "                    \"latency_ms\": trace.info.execution_time_ms,\n",
+        "                    \"question\": question,\n",
+        "                })\n",
+        "        except Exception as _te:\n",
+        "            print(f\"  ⚠️  skipped trace {getattr(trace.info, 'request_id', '?')}: {_te}\")\n",
+        "            continue\n",
+        "\n",
+        "    traces_df = pd.DataFrame(records)\n",
+        "    print(f\"Extracted {len(traces_df)} usable user-question records.\")\n",
+        "\n",
+        "    if not traces_df.empty:\n",
+        "        TRACE_EVAL_LIMIT = 20\n",
+        "        trace_eval_data = [\n",
+        "            {\"inputs\": {\"messages\": [{\"role\": \"user\", \"content\": row[\"question\"]}]}}\n",
+        "            for _, row in traces_df.head(TRACE_EVAL_LIMIT).iterrows()\n",
+        "        ]\n",
+        "        print(f\"Trace-derived eval dataset: {len(trace_eval_data)} records (cap={TRACE_EVAL_LIMIT}).\")\n",
+        "        display(traces_df[[\"question\", \"latency_ms\"]].head(10))"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from mlflow.genai.scorers import Guidelines, Safety\n",
+        "\n",
+        "_TRACE_GUIDELINE = (\n",
+        "    \"Response must include specific data points (numbers, locations, dates, \"\n",
+        "    \"or order identifiers). \"\n",
+        "    \"Response must not be a generic hedge or refusal. \"\n",
+        "    \"Response must directly address the refund question asked.\"\n",
+        ")\n",
+        "\n",
+        "if trace_eval_data:\n",
+        "    _trace_df = pd.DataFrame(\n",
+        "        [{\"query\": row[\"inputs\"][\"messages\"][0][\"content\"]} for row in trace_eval_data]\n",
+        "    )\n",
+        "    _trace_dataset = mlflow.data.from_pandas(\n",
+        "        _trace_df,\n",
+        "        source=f\"{prod_experiment_name} (last {len(trace_eval_data)} OK traces)\",\n",
+        "        name=\"refund_agent_trace_eval_dataset\",\n",
+        "    )\n",
+        "\n",
+        "    with mlflow.start_run(run_name=f\"{CATALOG}-refund-agent-trace-eval\"):\n",
+        "        mlflow.log_input(_trace_dataset, context=\"trace_eval\")\n",
+        "        mlflow.log_param(\"prompt_uri\", PROMPT_URI)\n",
+        "        mlflow.log_param(\"prompt_version\", PROMPT_VERSION)\n",
+        "        trace_results = mlflow.genai.evaluate(\n",
+        "            data=trace_eval_data,\n",
+        "            scorers=[\n",
+        "                refund_reason,\n",
+        "                policy_alignment,\n",
+        "                cites_evidence,\n",
+        "                Guidelines(name=\"trace_quality\", guidelines=_TRACE_GUIDELINE),\n",
+        "                Safety(),\n",
+        "                *([RelevanceToQuery()] if _has_relevance else []),\n",
+        "            ],\n",
+        "            predict_fn=predict_fn,\n",
+        "        )\n",
+        "    print(\"\\n✅ Trace-derived evaluation complete\")\n",
+        "    print(f\"  metrics: {getattr(trace_results, 'metrics', 'N/A')}\")\n",
+        "else:\n",
+        "    print(\"Skipping trace evaluation — no trace data available yet.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "refund_evaluation",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python",
+      "language": "python",
+      "name": "python"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}
\ No newline at end of file
diff --git a/stages/refund_setup.ipynb b/stages/refund_setup.ipynb
new file mode 100644
index 0000000..75538ba
--- /dev/null
+++ b/stages/refund_setup.ipynb
@@ -0,0 +1,164 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Refund Agent \u2014 Eval Dataset Setup\n",
+    "\n",
+    "Builds a curated evaluation dataset for the Refund Agent and registers it\n",
+    "as a UC-managed MLflow dataset at\n",
+    "`{CATALOG}.evaluations.refund_agent_eval_dataset`.\n",
+    "\n",
+    "**Why a separate task:** matches the pattern in\n",
+    "`stages/operational_evaluation.ipynb` for the Operational\n",
+    "Supervisor \u2014 dataset creation is a one-time, governed, unconditional step;\n",
+    "evaluation is the ongoing, opt-in step. Splitting them means:\n",
+    "\n",
+    "- The dataset is visible in Catalog Explorer after every deploy, even when\n",
+    "  `SKIP_EVAL=true` (the default for `Refund_Evaluation`).\n",
+    "- Re-running the eval task doesn't rebuild the dataset \u2014 same records\n",
+    "  every time \u2192 reproducible eval runs.\n",
+    "- A future MemAlign / `optimize_prompts()` job can consume the same UC\n",
+    "  dataset without re-deriving it.\n",
+    "\n",
+    "This task runs after `Refund_Recommender_Agent` (so the streaming pipeline\n",
+    "has had time to land delivered orders into `{CATALOG}.lakeflow.all_events`)\n",
+    "and before `Refund_Evaluation` (which reads from this dataset)."
+   ],
+   "id": "4d387ec8"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "%pip install -U -qqqq mlflow-skinny[databricks]\n",
+    "dbutils.library.restartPython()"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "dd2a9992"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+    "print(f\"CATALOG = {CATALOG}\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "0cbdc9f5"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "refund_queries = [\n",
+    "    row[\"order_id\"]\n",
+    "    for row in spark.sql(\n",
+    "        f\"\"\"\n",
+    "        SELECT order_id\n",
+    "        FROM {CATALOG}.lakeflow.all_events\n",
+    "        WHERE event_type='delivered'\n",
+    "        LIMIT 10\n",
+    "        \"\"\"\n",
+    "    ).collect()\n",
+    "]\n",
+    "\n",
+    "EVAL_DATASET = [\n",
+    "    {\n",
+    "        \"inputs\": {\n",
+    "            \"messages\": [{\"role\": \"user\", \"content\": query}],\n",
+    "        }\n",
+    "    }\n",
+    "    for query in refund_queries\n",
+    "]\n",
+    "\n",
+    "print(f\"Built {len(EVAL_DATASET)} eval rows from {CATALOG}.lakeflow.all_events\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "875b7b57"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import json as _json\n",
+    "import mlflow\n",
+    "import mlflow.genai.datasets\n",
+    "\n",
+    "UC_DATASET_TABLE = f\"{CATALOG}.evaluations.refund_agent_eval_dataset\"\n",
+    "\n",
+    "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}.evaluations\")\n",
+    "\n",
+    "# Drop + recreate to avoid Arrow schema mismatches if a prior run wrote a\n",
+    "# different shape (mirrors evaluation.ipynb for the supervisor).\n",
+    "spark.sql(f\"DROP TABLE IF EXISTS {UC_DATASET_TABLE}\")\n",
+    "\n",
+    "eval_dataset = mlflow.genai.datasets.create_dataset(uc_table_name=UC_DATASET_TABLE)\n",
+    "\n",
+    "\n",
+    "def _serialize_record(rec):\n",
+    "    \"\"\"JSON-stringify list-of-primitives fields only (Arrow + mlflow.genai.datasets\n",
+    "    can't reliably serialize ARRAY<STRING>). Lists of dicts (chat-format\n",
+    "    `inputs.messages`) MUST stay native \u2014 mlflow.genai.datasets validates them\n",
+    "    against the chat schema and fails with `AttributeError: 'str' object has no\n",
+    "    attribute 'get'` if they arrive as a stringified JSON. Eval-side reader\n",
+    "    deserializes the primitive lists back symmetrically.\"\"\"\n",
+    "    out = {}\n",
+    "    for k, v in rec.items():\n",
+    "        if isinstance(v, dict):\n",
+    "            out[k] = _serialize_record(v)\n",
+    "        elif isinstance(v, list) and all(isinstance(x, (str, int, float, bool)) for x in v):\n",
+    "            out[k] = _json.dumps(v)\n",
+    "        else:\n",
+    "            out[k] = v\n",
+    "    return out\n",
+    "\n",
+    "\n",
+    "eval_dataset.merge_records([_serialize_record(r) for r in EVAL_DATASET])\n",
+    "print(f\"\u2705 Registered {UC_DATASET_TABLE} ({len(EVAL_DATASET)} records)\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "b07ec289"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "dev_experiment_name = f\"/Shared/{CATALOG}_refund_agent_dev\"\n",
+    "mlflow.set_experiment(dev_experiment_name)\n",
+    "\n",
+    "with mlflow.start_run(run_name=\"register_eval_dataset\"):\n",
+    "    mlflow.log_input(\n",
+    "        mlflow.data.from_spark(\n",
+    "            spark.table(UC_DATASET_TABLE),\n",
+    "            table_name=UC_DATASET_TABLE,\n",
+    "        ),\n",
+    "        context=\"eval\",\n",
+    "    )\n",
+    "\n",
+    "print(f\"\u2705 Linked {UC_DATASET_TABLE} to experiment {dev_experiment_name}\")\n",
+    "print(f\"   Use in evaluate(): mlflow.genai.datasets.get_dataset(uc_table_name=UC_DATASET_TABLE)\")"
+   ],
+   "execution_count": null,
+   "outputs": [],
+   "id": "0d25ed69"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/stages/refunder_agent.ipynb b/stages/refunder_agent.ipynb
index c725879..f74a088 100644
--- a/stages/refunder_agent.ipynb
+++ b/stages/refunder_agent.ipynb
@@ -37,6 +37,7 @@
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -51,15 +52,15 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "%sql\n",
         "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.ai;"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -74,12 +75,28 @@
           "title": ""
         }
       },
-      "source": "%sql\nCREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_details(oid STRING COMMENT 'order id of the order')\nRETURNS TABLE (\n  body STRING COMMENT 'Body of the event',\n  event_type STRING COMMENT 'The type of event',\n  order_id STRING COMMENT 'The order id',\n  ts STRING COMMENT 'The timestamp of the event',\n  location STRING COMMENT 'the location of the order'\n)\nCOMMENT 'Returns all events associated with the order id (oid)'\nRETURN\n  SELECT ae.body, ae.event_type, ae.order_id, ae.ts, loc.name as location\n  FROM ${CATALOG}.lakeflow.all_events ae\n  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n  WHERE ae.order_id = oid;",
-      "execution_count": null,
-      "outputs": []
+      "outputs": [],
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_details(oid STRING COMMENT 'order id of the order')\n",
+        "RETURNS TABLE (\n",
+        "  body STRING COMMENT 'Body of the event',\n",
+        "  event_type STRING COMMENT 'The type of event',\n",
+        "  order_id STRING COMMENT 'The order id',\n",
+        "  ts STRING COMMENT 'The timestamp of the event',\n",
+        "  location STRING COMMENT 'the location of the order'\n",
+        ")\n",
+        "COMMENT 'Returns all events associated with the order id (oid)'\n",
+        "RETURN\n",
+        "  SELECT ae.body, ae.event_type, ae.order_id, ae.ts, loc.name as location\n",
+        "  FROM ${CATALOG}.lakeflow.all_events ae\n",
+        "  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n",
+        "  WHERE ae.order_id = oid;"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -94,6 +111,7 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "%sql\n",
         "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_delivery_time(oid STRING COMMENT 'order id of the order')\n",
@@ -126,12 +144,11 @@
         "    ) AS duration_minutes\n",
         "  FROM\n",
         "    MinMaxTimestamps;"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -146,12 +163,50 @@
           "title": ""
         }
       },
-      "source": "%sql\nCREATE OR REPLACE VIEW ${CATALOG}.ai.order_delivery_times_per_location_view AS\nWITH order_times AS (\n  SELECT\n    ae.order_id,\n    loc.name as location,\n    MAX(CASE WHEN ae.event_type = 'order_created' THEN try_to_timestamp(ae.ts) END) AS order_created_time,\n    MAX(CASE WHEN ae.event_type = 'delivered' THEN try_to_timestamp(ae.ts) END) AS delivered_time\n  FROM\n    ${CATALOG}.lakeflow.all_events ae\n  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n  WHERE\n    try_to_timestamp(ae.ts) >= CURRENT_TIMESTAMP() - INTERVAL 1 DAY\n  GROUP BY\n    ae.order_id,\n    loc.name\n),\ntotal_order_times AS (\n  SELECT\n    order_id,\n    location,\n    (UNIX_TIMESTAMP(delivered_time) - UNIX_TIMESTAMP(order_created_time)) / 60 AS total_order_time_minutes\n  FROM\n    order_times\n  WHERE\n    order_created_time IS NOT NULL\n    AND delivered_time IS NOT NULL\n)\nSELECT\n  location,\n  PERCENTILE(total_order_time_minutes, 0.50) AS P50,\n  PERCENTILE(total_order_time_minutes, 0.75) AS P75,\n  PERCENTILE(total_order_time_minutes, 0.99) AS P99\nFROM\n  total_order_times\nGROUP BY\n  location",
-      "execution_count": null,
-      "outputs": []
+      "outputs": [],
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE VIEW ${CATALOG}.ai.order_delivery_times_per_location_view AS\n",
+        "WITH order_times AS (\n",
+        "  SELECT\n",
+        "    ae.order_id,\n",
+        "    loc.name as location,\n",
+        "    MAX(CASE WHEN ae.event_type = 'order_created' THEN try_to_timestamp(ae.ts) END) AS order_created_time,\n",
+        "    MAX(CASE WHEN ae.event_type = 'delivered' THEN try_to_timestamp(ae.ts) END) AS delivered_time\n",
+        "  FROM\n",
+        "    ${CATALOG}.lakeflow.all_events ae\n",
+        "  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n",
+        "  WHERE\n",
+        "    try_to_timestamp(ae.ts) >= CURRENT_TIMESTAMP() - INTERVAL 1 DAY\n",
+        "  GROUP BY\n",
+        "    ae.order_id,\n",
+        "    loc.name\n",
+        "),\n",
+        "total_order_times AS (\n",
+        "  SELECT\n",
+        "    order_id,\n",
+        "    location,\n",
+        "    (UNIX_TIMESTAMP(delivered_time) - UNIX_TIMESTAMP(order_created_time)) / 60 AS total_order_time_minutes\n",
+        "  FROM\n",
+        "    order_times\n",
+        "  WHERE\n",
+        "    order_created_time IS NOT NULL\n",
+        "    AND delivered_time IS NOT NULL\n",
+        ")\n",
+        "SELECT\n",
+        "  location,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.50) AS P50,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.75) AS P75,\n",
+        "  PERCENTILE(total_order_time_minutes, 0.99) AS P99\n",
+        "FROM\n",
+        "  total_order_times\n",
+        "GROUP BY\n",
+        "  location"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -166,6 +221,7 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "%sql\n",
         "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_location_timings(loc STRING COMMENT 'Location name as a string')\n",
@@ -180,9 +236,36 @@
         "  SELECT location, P50, P75, P99\n",
         "  FROM ${CATALOG}.ai.order_delivery_times_per_location_view AS odlt\n",
         "  WHERE odlt.location = loc;"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%sql\n",
+        "-- USE CATALOG is needed in addition to USE SCHEMA + EXECUTE so the serving\n",
+        "-- endpoint's auto-generated SP can traverse the catalog to reach the UC\n",
+        "-- functions at model-load time.  Normally granted by the root data stage\n",
+        "-- (canonical_data/raw_data), but repeated here so this stage is self-\n",
+        "-- sufficient if run standalone or against a pre-existing catalog.\n",
+        "GRANT USE CATALOG ON CATALOG ${CATALOG} TO `account users`;\n",
+        "GRANT USE SCHEMA ON SCHEMA ${CATALOG}.ai TO `account users`;"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "%sql\n",
+        "-- Grant EXECUTE so the serving endpoint SP can call these tools at inference time.\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_order_details        TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_order_delivery_time  TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_location_timings     TO `account users`;"
+      ]
     },
     {
       "cell_type": "markdown",
@@ -202,6 +285,7 @@
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -215,15 +299,15 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
-        "%pip install -U -qqqq mlflow-skinny[databricks] langgraph==0.3.4 databricks-langchain databricks-agents uv\n",
+        "%pip install -U -qqqq mlflow-skinny[databricks] \"langgraph>=0.3.5,<0.4.0\" databricks-langchain langchain-openai databricks-agents uv\n",
         "dbutils.library.restartPython()"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -237,15 +321,65 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")"
-      ],
-      "execution_count": 0,
-      "outputs": []
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
+        "\n",
+        "# Unity AI Gateway (v2 Beta) endpoint name.  Defined as a job parameter on\n",
+        "# the `all` target only — empty string everywhere else.  When set, the\n",
+        "# agent routes its internal LLM calls through the gateway URL\n",
+        "# (<host>/ai-gateway/mlflow/v1) instead of calling a foundation-model\n",
+        "# serving endpoint directly.  See databricks.yml comment on the param for\n",
+        "# the full rationale + UI setup steps.\n",
+        "try:\n",
+        "    AI_GATEWAY_ENDPOINT_NAME = dbutils.widgets.get(\"AI_GATEWAY_ENDPOINT_NAME\")\n",
+        "except Exception:\n",
+        "    # Widget not declared on this target — equivalent to \"no gateway\".\n",
+        "    AI_GATEWAY_ENDPOINT_NAME = \"\"\n",
+        "\n",
+        "if AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    print(f\"⛩  Routing refund agent LLM calls through AI Gateway: {AI_GATEWAY_ENDPOINT_NAME}\")\n",
+        "else:\n",
+        "    print(f\"→ Refund agent LLM calls go directly to foundation-model endpoint: {LLM_MODEL}\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import mlflow\n",
+        "\n",
+        "# Create/set dev experiment for development and evaluation traces.\n",
+        "# Use a shared path so the job-runner SP and the deployer both write to the\n",
+        "# same experiment and the runbook can link to a stable URL.  Mirrors the\n",
+        "# pattern in stages/complaint_agent.ipynb so all three pipeline agents\n",
+        "# (refund / complaint / supervisor) share the same dev/prod split.\n",
+        "dev_experiment_name = f\"/Shared/{CATALOG}_refund_agent_dev\"\n",
+        "\n",
+        "# set_experiment creates the experiment if it doesn't exist, or activates it if it does.\n",
+        "dev_experiment = mlflow.set_experiment(dev_experiment_name)\n",
+        "dev_experiment_id = dev_experiment.experiment_id\n",
+        "print(f\"✅ Using dev experiment: {dev_experiment_name} (ID: {dev_experiment_id})\")\n",
+        "\n",
+        "# Track the experiment in uc_state so `databricks bundle run cleanup` deletes it.\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "experiment_data = {\n",
+        "    \"experiment_id\": dev_experiment_id,\n",
+        "    \"name\": dev_experiment_name,\n",
+        "}\n",
+        "add(CATALOG, \"experiments\", experiment_data)\n",
+        "print(f\"✅ Added dev experiment to UC state\")"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -259,15 +393,38 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "import re\n",
+        "import os\n",
         "from IPython.core.magic import register_cell_magic\n",
         "\n",
+        "# Records absolute paths of files written by `%%writefilev`, keyed by the\n",
+        "# filename argument.  Cell 17 below imports `from agent import LLM_ENDPOINT_NAME`.\n",
+        "#\n",
+        "# Earlier versions wrote to `os.path.abspath(filename)` (i.e. CWD), but CWD\n",
+        "# on serverless notebooks is usually a `/Workspace/Users/...` path, and the\n",
+        "# workspace-files-as-Python-modules feature is not reliably wired through\n",
+        "# on serverless — the file ends up on disk, `os.path.exists()` returns True,\n",
+        "# but `import agent` still raises `ModuleNotFoundError`.  Pinning the write\n",
+        "# dir to a regular local-disk path (`/local_disk0/tmp/...`, falling back to\n",
+        "# `/tmp/...`) sidesteps the workspace-files importer entirely.\n",
+        "_WRITEFILEV_ABS_PATHS = {}\n",
+        "\n",
+        "_WRITEFILEV_DIR = \"/local_disk0/tmp/caspers_writefilev\"\n",
+        "if not os.path.isdir(\"/local_disk0\"):\n",
+        "    _WRITEFILEV_DIR = \"/tmp/caspers_writefilev\"\n",
+        "os.makedirs(_WRITEFILEV_DIR, exist_ok=True)\n",
+        "\n",
         "@register_cell_magic\n",
         "def writefilev(line, cell):\n",
         "    \"\"\"\n",
         "    %%writefilev file.py\n",
         "    Allows {{var}} substitutions while leaving normal {} intact.\n",
+        "\n",
+        "    Writes to a stable local-disk path (NOT CWD) so subsequent\n",
+        "    `from <module> import ...` always succeeds, even on serverless\n",
+        "    where CWD is a /Workspace path.\n",
         "    \"\"\"\n",
         "    filename = line.strip()\n",
         "\n",
@@ -275,18 +432,18 @@
         "        expr = match.group(1)\n",
         "        return str(eval(expr, globals(), locals()))\n",
         "\n",
-        "    # Replace only double braces {{var}}\n",
         "    content = re.sub(r\"\\{\\{(.*?)\\}\\}\", replacer, cell)\n",
         "\n",
-        "    with open(filename, \"w\") as f:\n",
+        "    abs_path = os.path.join(_WRITEFILEV_DIR, filename)\n",
+        "    with open(abs_path, \"w\") as f:\n",
         "        f.write(content)\n",
-        "    print(f\"Wrote file with substitutions: {filename}\")"
-      ],
-      "execution_count": 0,
-      "outputs": []
+        "    _WRITEFILEV_ABS_PATHS[filename] = abs_path\n",
+        "    print(f\"Wrote file with substitutions: {abs_path}\")"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -300,24 +457,29 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "%%writefilev agent.py\n",
-        "from typing import Any, Generator, Optional, Sequence, Union\n",
+        "from typing import Any, Generator, Literal, Optional, Sequence, Union\n",
         "\n",
         "import mlflow\n",
         "from databricks_langchain import (\n",
         "    ChatDatabricks,\n",
         "    VectorSearchRetrieverTool,\n",
-        "    DatabricksFunctionClient,\n",
-        "    UCFunctionToolkit,\n",
-        "    set_uc_function_client,\n",
         ")\n",
+        "from langchain_core.tools import tool\n",
+        "from unitycatalog.ai.core.base import get_uc_function_client\n",
         "from langchain_core.language_models import LanguageModelLike\n",
         "from langchain_core.runnables import RunnableConfig, RunnableLambda\n",
         "from langchain_core.tools import BaseTool\n",
         "from langgraph.graph import END, StateGraph\n",
-        "from langgraph.graph.graph import CompiledGraph\n",
-        "from langgraph.graph.state import CompiledStateGraph\n",
+        "try:\n",
+        "    from langgraph.graph.graph import CompiledGraph\n",
+        "    from langgraph.graph.state import CompiledStateGraph\n",
+        "except ImportError:  # langgraph >=0.4 restructured these internal modules\n",
+        "    from typing import Any\n",
+        "    CompiledGraph = Any\n",
+        "    CompiledStateGraph = Any\n",
         "from langgraph.prebuilt.tool_node import ToolNode\n",
         "from mlflow.langchain.chat_agent_langgraph import ChatAgentState, ChatAgentToolNode\n",
         "from mlflow.pyfunc import ChatAgent\n",
@@ -328,18 +490,146 @@
         "    ChatContext,\n",
         ")\n",
         "\n",
+        "import json as _json\n",
+        "import uuid as _uuid\n",
+        "from pydantic import BaseModel, ValidationError\n",
+        "\n",
         "mlflow.langchain.autolog()\n",
         "\n",
-        "client = DatabricksFunctionClient()\n",
-        "set_uc_function_client(client)\n",
+        "# Catalog and AI-Gateway endpoint name are substituted at notebook write\n",
+        "# time (via `%%writefilev {{...}}`) so the agent module is self-contained\n",
+        "# and does not depend on widgets at request time.\n",
+        "CATALOG = \"{{CATALOG}}\"\n",
+        "\n",
+        "# When non-empty, the agent routes every LLM call through the Unity AI\n",
+        "# Gateway (v2 Beta) URL `<host>/ai-gateway/mlflow/v1` so the gateway's\n",
+        "# guardrails / inference table / usage tracking / rate limits apply\n",
+        "# centrally.  When empty, the agent calls the foundation-model serving\n",
+        "# endpoint named by LLM_ENDPOINT_NAME directly via ChatDatabricks\n",
+        "# (legacy behaviour, used by the `default` and `complaints` targets).\n",
+        "AI_GATEWAY_ENDPOINT_NAME = \"{{AI_GATEWAY_ENDPOINT_NAME}}\"\n",
+        "\n",
+        "# Lazy UC function client — constructed on first tool call, NOT at\n",
+        "# module import / model load time.  This is the same pattern used by\n",
+        "# complaint_agent.py.  It matters because the serving endpoint's\n",
+        "# auto-created service principal is added to `account users` (which\n",
+        "# holds USE CATALOG / USE SCHEMA / EXECUTE) with a multi-minute\n",
+        "# propagation delay; if we introspect or execute UC functions at model\n",
+        "# LOAD time (the way the old UCFunctionToolkit code did), the first\n",
+        "# deploy fails before propagation completes.  Deferring all UC access to\n",
+        "# request time lets model load complete unconditionally, and by the time\n",
+        "# real traffic arrives the SP has propagated.\n",
+        "_uc_client = None\n",
+        "\n",
+        "\n",
+        "def _client():\n",
+        "    global _uc_client\n",
+        "    if _uc_client is None:\n",
+        "        _uc_client = get_uc_function_client()\n",
+        "    return _uc_client\n",
+        "\n",
+        "\n",
+        "class RefundDecision(BaseModel):\n",
+        "    refund_usd: float = 0.0\n",
+        "    refund_class: Literal[\"none\", \"partial\", \"full\"] = \"none\"\n",
+        "    reason: str = \"\"\n",
+        "\n",
         "\n",
         "############################################\n",
         "# Define your LLM endpoint and system prompt\n",
         "############################################\n",
-        "LLM_ENDPOINT_NAME = f\"{{LLM_MODEL}}\"\n",
-        "llm = ChatDatabricks(endpoint=LLM_ENDPOINT_NAME)\n",
+        "# `LLM_ENDPOINT_NAME` is the name we expose for `resources=[...]` and for\n",
+        "# logging.  When the AI Gateway is wired up, it points at the gateway\n",
+        "# endpoint (so the deploy-time SP gets CAN_QUERY auto-granted on the\n",
+        "# gateway endpoint).  When not, it points at the foundation-model\n",
+        "# endpoint as before.\n",
+        "LLM_ENDPOINT_NAME = AI_GATEWAY_ENDPOINT_NAME or \"{{LLM_MODEL}}\"\n",
+        "\n",
+        "if AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    # Route through Unity AI Gateway (v2 Beta).  The gateway URL is\n",
+        "    # OpenAI-compatible at `<host>/ai-gateway/mlflow/v1` and expects the\n",
+        "    # gateway-endpoint-name as the `model` field in the request body.\n",
+        "    #\n",
+        "    # Auth: in Model Serving the runtime authenticates as the deployed\n",
+        "    # endpoint's service principal via OAuth M2M.  In M2M mode there is\n",
+        "    # NO static token — `WorkspaceClient().config.token` returns None,\n",
+        "    # which then crashes the OpenAI SDK with\n",
+        "    #     OpenAIError: Missing credentials. Please pass an api_key ...\n",
+        "    # at agent construction time.\n",
+        "    #\n",
+        "    # The portable fix is `config.authenticate()`, which returns the\n",
+        "    # auth headers that the SDK would attach to a request right now —\n",
+        "    # `{\"Authorization\": \"Bearer <token>\"}` — regardless of whether the\n",
+        "    # underlying auth provider is PAT, OAuth U2M, or OAuth M2M.  We\n",
+        "    # strip the bearer prefix and hand the raw token to ChatOpenAI as\n",
+        "    # `api_key`.\n",
+        "    #\n",
+        "    # Token rotation — this used to be a caveat (the bearer was extracted\n",
+        "    # once at module load and baked into ChatOpenAI, so warm endpoints\n",
+        "    # surfaced HTTP 400 BAD_REQUEST / \"Invalid Token\" from the gateway\n",
+        "    # after the original OAuth M2M token's ~1h window closed; the agent\n",
+        "    # had to cold-reload to recover).  Fixed by mitigation (b) from the\n",
+        "    # original caveat: build a fresh ChatOpenAI per invocation from a\n",
+        "    # fresh `_w.config.authenticate()` call.  The SDK caches the token\n",
+        "    # internally and only hits the IdP when refresh is due, so the\n",
+        "    # per-call overhead is one in-process dict lookup in the steady state\n",
+        "    # and one OAuth refresh roughly hourly.  `call_model` (below) calls\n",
+        "    # `_build_gateway_llm()` on every request when in gateway mode.\n",
+        "    from langchain_openai import ChatOpenAI\n",
+        "    from databricks.sdk import WorkspaceClient as _WorkspaceClient\n",
+        "\n",
+        "    _w = _WorkspaceClient()\n",
+        "    _gateway_base_url = f\"{_w.config.host.rstrip('/')}/ai-gateway/mlflow/v1\"\n",
+        "\n",
+        "    def _build_gateway_llm():\n",
+        "        \"\"\"Construct a ChatOpenAI client pointing at the AI Gateway with the\n",
+        "        SDK's *current* bearer token.  Called fresh on every invocation by\n",
+        "        `call_model` so a rotated OAuth M2M token in the credentials\n",
+        "        provider is picked up immediately.  langchain-openai's ChatOpenAI\n",
+        "        bakes the api_key into its internal openai.OpenAI client at\n",
+        "        construction time and offers no callable-api_key hook, hence the\n",
+        "        full rebuild rather than a token-only update.\"\"\"\n",
+        "        _auth_headers = _w.config.authenticate()\n",
+        "        _bearer = _auth_headers.get(\"Authorization\", \"\")\n",
+        "        if not _bearer.lower().startswith(\"bearer \"):\n",
+        "            raise RuntimeError(\n",
+        "                f\"Databricks SDK auth headers do not contain a Bearer token \"\n",
+        "                f\"(got header keys: {list(_auth_headers.keys())}). \"\n",
+        "                f\"Cannot route refund agent through AI Gateway in this auth \"\n",
+        "                f\"mode — fall back to direct foundation-model endpoint by \"\n",
+        "                f\"unsetting AI_GATEWAY_ENDPOINT_NAME.\"\n",
+        "            )\n",
+        "        return ChatOpenAI(\n",
+        "            model=AI_GATEWAY_ENDPOINT_NAME,\n",
+        "            base_url=_gateway_base_url,\n",
+        "            api_key=_bearer[len(\"Bearer \"):],\n",
+        "            max_tokens=2000,\n",
+        "        )\n",
+        "\n",
+        "    # Initial instance: needed for `bind_tools(...)` further down so the\n",
+        "    # tool-bound runnable can be wired up at module load.  The instance is\n",
+        "    # NOT what serves requests in steady state — `call_model` rebuilds via\n",
+        "    # `_build_gateway_llm()` per invocation to pick up rotated tokens.\n",
+        "    llm = _build_gateway_llm()\n",
+        "else:\n",
+        "    # Direct foundation-model endpoint (default behaviour for `default` and\n",
+        "    # `complaints` targets — no gateway routing).  ChatDatabricks handles\n",
+        "    # auth refresh internally via the SDK on every call, so no per-call\n",
+        "    # rebuild is needed.\n",
+        "    _build_gateway_llm = None\n",
+        "    llm = ChatDatabricks(endpoint=LLM_ENDPOINT_NAME)\n",
+        "\n",
+        "# At endpoint startup, try to load the prompt from the MLflow Prompt\n",
+        "# Registry so that editing the prompt and bumping the `production` alias\n",
+        "# takes effect on the next endpoint replica restart — without rebuilding\n",
+        "# the UC model.  Falls back to the literal _FALLBACK_PROMPT below if the\n",
+        "# registry is empty (first-ever deploy) or unreachable (auth, etc.).\n",
+        "# The literal is the source of truth: the Prompt Registry cell at the\n",
+        "# bottom of stages/refunder_agent.ipynb extracts it via regex and\n",
+        "# registers it as a new version on every deploy.\n",
+        "PROMPT_URI = f\"prompts:/{CATALOG}.prompts.refund_system@production\"\n",
         "\n",
-        "system_prompt = \"\"\"You are RefundGPT, a CX agent responsible for refunding late food delivery orders.\n",
+        "_FALLBACK_PROMPT = \"\"\"You are RefundGPT, a CX agent responsible for refund decisions on food delivery orders.\n",
         "\n",
         "    You can call tools to gather the information you need. Start with an `order_id`.\n",
         "\n",
@@ -348,32 +638,94 @@
         "    2. Figure out the delivery duration by calling `get_order_delivery_time(order_id)`.\n",
         "    3. Extract the location (either directly or from the first event's body).\n",
         "    4. Call `get_location_timings(location)` to get the P50/P75/P99 values.\n",
-        "    5. Compare actual delivery time to those percentiles to decide on a fair refund.\n",
+        "    5. Compare actual delivery time to those percentiles.\n",
         "\n",
-        "    Only provide refunds for late orders, and use only the tool call results to determine whether a refund is appropriate.\n",
+        "    Refund policy:\n",
         "\n",
-        "    Do not provide any refund for orders arriving before the P75 delivery time value.\n",
+        "    A) SLA-based refund (primary path):\n",
+        "       - If the order arrived AFTER the P75 delivery time: recommend a `partial` or `full` refund based on how late.\n",
+        "       - If the order arrived BEFORE the P75: no SLA-based refund.\n",
+        "\n",
+        "    B) Goodwill credit (only when complaint context is provided in the user message):\n",
+        "       The user may include lines such as:\n",
+        "           Customer complaint: \"<text>\"\n",
+        "           Complaint category: <category>\n",
+        "           Complaint agent suggested credit: $<amount>\n",
+        "       When all three are present AND the SLA path returns \"none\", you MAY ratify the\n",
+        "       complaint agent's goodwill credit:\n",
+        "       - Set `refund_class` = \"partial\"\n",
+        "       - Set `refund_usd` to the suggested credit amount (capped at $10)\n",
+        "       - In `reason`, note that the order was on time per SLA but a goodwill credit\n",
+        "         is being issued in response to the customer's complaint (cite the category).\n",
+        "       Only ratify when the suggested credit is plausible (>$0 and ≤$10) and the\n",
+        "       complaint category is non-empty. Otherwise return \"none\" with an SLA-based reason.\n",
+        "\n",
+        "    When NO complaint context is provided, behave exactly as the SLA-based path (A) —\n",
+        "    do not invent goodwill credits.\n",
         "\n",
         "    Output a single-line JSON with these fields:\n",
         "    - `refund_usd` (float),\n",
         "    - `refund_class` (\"none\" | \"partial\" | \"full\"),\n",
-        "    - `reason` (short human explanation of whether the order was late and, if late, how late the order was)\n",
+        "    - `reason` (short human explanation. If goodwill, say so explicitly.)\n",
         "\n",
         "    You must return only the JSON. No extra text or markdown.\"\"\"\n",
         "\n",
+        "# Required at endpoint startup: prompt registry URI defaults vary across\n",
+        "# Model Serving runtimes; without this the 3-part UC name is treated as\n",
+        "# an opaque string in workspace MLflow and load_prompt raises NotFound.\n",
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "\n",
+        "try:\n",
+        "    system_prompt = mlflow.genai.load_prompt(PROMPT_URI).template\n",
+        "    print(f\"[refund-agent] Loaded system prompt from {PROMPT_URI}\")\n",
+        "except Exception as _exc:\n",
+        "    print(\n",
+        "        f\"[refund-agent] Failed to load {PROMPT_URI} \"\n",
+        "        f\"({type(_exc).__name__}: {_exc}); using _FALLBACK_PROMPT.\"\n",
+        "    )\n",
+        "    system_prompt = _FALLBACK_PROMPT\n",
+        "\n",
         "###############################################################################\n",
         "## Define tools for your agent, enabling it to retrieve data or take actions\n",
-        "## beyond text generation\n",
-        "## To create and see usage examples of more tools, see\n",
-        "## https://docs.databricks.com/generative-ai/agent-framework/agent-tool.html\n",
+        "## beyond text generation.\n",
+        "##\n",
+        "## We use plain @tool-decorated wrappers (instead of UCFunctionToolkit) so\n",
+        "## the UC functions are only introspected/executed at REQUEST time, not at\n",
+        "## model LOAD time.  This is the same lazy pattern used by complaint_agent\n",
+        "## and support_request_agent, and is required for first-attempt success of\n",
+        "## agents.deploy() — see _client() above for the full rationale.\n",
         "###############################################################################\n",
-        "tools = []\n",
         "\n",
-        "uc_tool_names = [f\"{{CATALOG}}.ai.get_order_details\", \n",
-        "                 f\"{{CATALOG}}.ai.get_location_timings\",\n",
-        "                 f\"{{CATALOG}}.ai.get_order_delivery_time\"]\n",
-        "uc_toolkit = UCFunctionToolkit(function_names=uc_tool_names)\n",
-        "tools.extend(uc_toolkit.tools)\n",
+        "\n",
+        "@tool\n",
+        "def get_order_details(order_id: str) -> str:\n",
+        "    \"\"\"Get the full event history for an order (creation, accepted, dispatched,\n",
+        "    delivered, etc).  Use this first to verify the order id is valid and to\n",
+        "    confirm the order was delivered.\"\"\"\n",
+        "    return str(_client().execute_function(\n",
+        "        f\"{CATALOG}.ai.get_order_details\", {\"oid\": order_id}\n",
+        "    ).value)\n",
+        "\n",
+        "\n",
+        "@tool\n",
+        "def get_order_delivery_time(order_id: str) -> str:\n",
+        "    \"\"\"Return the creation timestamp, delivered timestamp, and elapsed delivery\n",
+        "    duration for an order.  Use this to compute the actual delivery time.\"\"\"\n",
+        "    return str(_client().execute_function(\n",
+        "        f\"{CATALOG}.ai.get_order_delivery_time\", {\"oid\": order_id}\n",
+        "    ).value)\n",
+        "\n",
+        "\n",
+        "@tool\n",
+        "def get_location_timings(location: str) -> str:\n",
+        "    \"\"\"Return the P50/P75/P99 delivery time percentiles for a kitchen location\n",
+        "    so the actual delivery time can be compared to the SLA bands.\"\"\"\n",
+        "    return str(_client().execute_function(\n",
+        "        f\"{CATALOG}.ai.get_location_timings\", {\"loc\": location}\n",
+        "    ).value)\n",
+        "\n",
+        "\n",
+        "tools = [get_order_details, get_order_delivery_time, get_location_timings]\n",
         "\n",
         "#####################\n",
         "## Define agent logic\n",
@@ -410,8 +762,17 @@
         "        state: ChatAgentState,\n",
         "        config: RunnableConfig,\n",
         "    ):\n",
-        "        response = model_runnable.invoke(state, config)\n",
-        "\n",
+        "        # Gateway-mode token refresh: when routing through the AI Gateway\n",
+        "        # we rebuild ChatOpenAI on every call with a fresh OAuth M2M token\n",
+        "        # from the SDK.  Without this, warm endpoints fail with HTTP 400\n",
+        "        # / \"Invalid Token\" from the gateway once the cached token's ~1h\n",
+        "        # window closes.  Direct ChatDatabricks mode handles auth refresh\n",
+        "        # internally and reuses `model_runnable` as-is.\n",
+        "        if _build_gateway_llm is not None:\n",
+        "            fresh_model = _build_gateway_llm().bind_tools(tools)\n",
+        "            response = (preprocessor | fresh_model).invoke(state, config)\n",
+        "        else:\n",
+        "            response = model_runnable.invoke(state, config)\n",
         "        return {\"messages\": [response]}\n",
         "\n",
         "    workflow = StateGraph(ChatAgentState)\n",
@@ -445,13 +806,25 @@
         "    ) -> ChatAgentResponse:\n",
         "        request = {\"messages\": self._convert_messages_to_dict(messages)}\n",
         "\n",
-        "        messages = []\n",
+        "        result_messages = []\n",
         "        for event in self.agent.stream(request, stream_mode=\"updates\"):\n",
         "            for node_data in event.values():\n",
-        "                messages.extend(\n",
+        "                result_messages.extend(\n",
         "                    ChatAgentMessage(**msg) for msg in node_data.get(\"messages\", [])\n",
         "                )\n",
-        "        return ChatAgentResponse(messages=messages)\n",
+        "        for i in range(len(result_messages) - 1, -1, -1):\n",
+        "            msg = result_messages[i]\n",
+        "            role = msg.role if hasattr(msg, \"role\") else (msg.get(\"role\") if isinstance(msg, dict) else None)\n",
+        "            content = msg.content if hasattr(msg, \"content\") else (msg.get(\"content\", \"\") if isinstance(msg, dict) else \"\")\n",
+        "            if role == \"assistant\" and content:\n",
+        "                try:\n",
+        "                    parsed = RefundDecision.model_validate_json(content)\n",
+        "                    orig_id = getattr(msg, 'id', None) or str(_uuid.uuid4())\n",
+        "                    result_messages[i] = ChatAgentMessage(id=orig_id, role=\"assistant\", content=parsed.model_dump_json())\n",
+        "                except (ValidationError, Exception):\n",
+        "                    pass\n",
+        "                break\n",
+        "        return ChatAgentResponse(messages=result_messages)\n",
         "\n",
         "    def predict_stream(\n",
         "        self,\n",
@@ -472,12 +845,11 @@
         "agent = create_tool_calling_agent(llm, tools, system_prompt)\n",
         "AGENT = LangGraphChatAgent(agent)\n",
         "mlflow.models.set_model(AGENT)"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -491,6 +863,7 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "import time\n",
         "\n",
@@ -513,12 +886,11 @@
         "        f\"No delivered events found in {CATALOG}.lakeflow.all_events after 6 minutes. \"\n",
         "        \"Ensure the Canonical_Data and Lakeflow pipeline stages completed and processed data.\"\n",
         "    )"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -532,15 +904,15 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "assert sample_order_id is not None\n",
         "print(sample_order_id)"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -554,17 +926,94 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "import mlflow\n",
-        "from agent import LLM_ENDPOINT_NAME, tools\n",
-        "from databricks_langchain import VectorSearchRetrieverTool\n",
+        "import sys\n",
+        "import os\n",
+        "\n",
+        "# Use the absolute path captured by `%%writefilev` (see cell 13). This is\n",
+        "# stable across CWD drift / kernel restarts; the older `sys.path.append(os.getcwd())`\n",
+        "# pattern was failing with `ModuleNotFoundError: No module named 'agent'` when\n",
+        "# CWD changed between the writefile cell and this one.\n",
+        "_agent_py_path = _WRITEFILEV_ABS_PATHS.get(\"agent.py\")\n",
+        "if _agent_py_path and os.path.exists(_agent_py_path):\n",
+        "    _agent_dir = os.path.dirname(_agent_py_path)\n",
+        "    print(f\"Importing agent from: {_agent_py_path}\")\n",
+        "else:\n",
+        "    # Defensive fallback: try the same locations the old code did, plus\n",
+        "    # /databricks/driver which is the typical CWD on classic clusters,\n",
+        "    # and the new pinned local-disk dir used by `%%writefilev`.\n",
+        "    _candidate_dirs = [\n",
+        "        os.getcwd(),\n",
+        "        \"/databricks/driver\",\n",
+        "        \"/local_disk0/tmp/caspers_writefilev\",\n",
+        "        \"/local_disk0/tmp\",\n",
+        "        \"/tmp/caspers_writefilev\",\n",
+        "        \"/tmp\",\n",
+        "    ]\n",
+        "    try:\n",
+        "        _nb_path = dbutils.notebook.entry_point.getDbutils().notebook().getContext().notebookPath().get()\n",
+        "        _candidate_dirs.append(os.path.dirname(_nb_path))\n",
+        "    except Exception:\n",
+        "        pass\n",
+        "    _agent_dir = next((d for d in _candidate_dirs if os.path.exists(os.path.join(d, \"agent.py\"))), None)\n",
+        "    if _agent_dir is None:\n",
+        "        raise FileNotFoundError(\n",
+        "            f\"agent.py not found. _WRITEFILEV_ABS_PATHS={_WRITEFILEV_ABS_PATHS}, \"\n",
+        "            f\"CWD={os.getcwd()}, candidates tried: {_candidate_dirs}\"\n",
+        "        )\n",
+        "    _agent_py_path = os.path.join(_agent_dir, \"agent.py\")\n",
+        "    print(f\"Importing agent from fallback dir: {_agent_py_path}\")\n",
+        "\n",
+        "if _agent_dir not in sys.path:\n",
+        "    sys.path.insert(0, _agent_dir)\n",
+        "\n",
+        "# Invalidate any cached `agent` module that may be left over from a prior\n",
+        "# attempt on the same warehouse (e.g. after a transient failure) — without\n",
+        "# this, a partially-imported / stale entry in `sys.modules` can cause\n",
+        "# subsequent `from agent import ...` to fail or return stale symbols.\n",
+        "sys.modules.pop(\"agent\", None)\n",
+        "\n",
+        "from agent import LLM_ENDPOINT_NAME\n",
         "from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint\n",
         "from pkg_resources import get_distribution\n",
-        "from unitycatalog.ai.langchain.toolkit import UnityCatalogTool\n",
         "\n",
-        "resources = [DatabricksServingEndpoint(endpoint_name=LLM_ENDPOINT_NAME)]\n",
-        "for tool in tools:\n",
-        "    resources.append(DatabricksFunction(function_name=tool.uc_function_name))\n",
+        "# Resource list for `agents.deploy()` — auto-grants permissions on each\n",
+        "# resource to the deployment SP at deploy time.\n",
+        "#\n",
+        "# IMPORTANT — gateway routing is special:\n",
+        "# When AI_GATEWAY_ENDPOINT_NAME is set, we deliberately do NOT add a\n",
+        "# DatabricksServingEndpoint(...) entry for it.  v2 Beta Unity AI Gateway\n",
+        "# endpoints live under a separate API surface (`/api/2.0/ai-gateway/*`)\n",
+        "# and are NOT discoverable via the regular `/api/2.0/serving-endpoints/*`\n",
+        "# API that `mlflow.models.resources.DatabricksServingEndpoint` validates\n",
+        "# against.  Listing the gateway here causes `agents.deploy()` to fail\n",
+        "# with \"NOT_FOUND: Dependent serving endpoint <gateway> does not exist\".\n",
+        "#\n",
+        "# Consequence: the deployment SP must have CAN_QUERY on the gateway via\n",
+        "# some other path — grant manually in the UI (AI Gateway → endpoint →\n",
+        "# Permissions) or via an `account users` ACL on the gateway.  At\n",
+        "# request time the agent authenticates with the SP's OAuth token via\n",
+        "# `WorkspaceClient().config.authenticate()` (see agent.py), so a CAN_QUERY\n",
+        "# grant is sufficient.\n",
+        "#\n",
+        "# Listing the UC functions lets agents.deploy() auto-grant EXECUTE on\n",
+        "# them to the endpoint SP.  Combined with the lazy @tool wrappers in\n",
+        "# agent.py (which defer UC introspection until request time), this lets\n",
+        "# model LOAD complete without needing any UC permission, so the first\n",
+        "# deploy succeeds even while the SP's `account users` membership is\n",
+        "# still propagating.\n",
+        "resources = [\n",
+        "    DatabricksFunction(function_name=f\"{CATALOG}.ai.get_order_details\"),\n",
+        "    DatabricksFunction(function_name=f\"{CATALOG}.ai.get_order_delivery_time\"),\n",
+        "    DatabricksFunction(function_name=f\"{CATALOG}.ai.get_location_timings\"),\n",
+        "]\n",
+        "if not AI_GATEWAY_ENDPOINT_NAME:\n",
+        "    # No gateway in play → the agent calls the foundation-model serving\n",
+        "    # endpoint directly, which IS a regular serving endpoint and CAN\n",
+        "    # safely be auto-granted via the resources list.\n",
+        "    resources.insert(0, DatabricksServingEndpoint(endpoint_name=LLM_ENDPOINT_NAME))\n",
         "\n",
         "input_example = {\n",
         "    \"messages\": [\n",
@@ -578,21 +1027,28 @@
         "with mlflow.start_run():\n",
         "    logged_agent_info = mlflow.pyfunc.log_model(\n",
         "        name=\"agent_v2\",\n",
-        "        python_model=\"agent.py\",\n",
+        "        python_model=_agent_py_path,\n",
         "        input_example=input_example,\n",
         "        resources=resources,\n",
         "        pip_requirements=[\n",
         "            f\"databricks-connect=={get_distribution('databricks-connect').version}\",\n",
         "            f\"mlflow=={get_distribution('mlflow').version}\",\n",
         "            f\"databricks-langchain=={get_distribution('databricks-langchain').version}\",\n",
+        "            # langchain-openai is only USED when AI_GATEWAY_ENDPOINT_NAME is set\n",
+        "            # (gateway routing on the `all` target), but we always pin it so\n",
+        "            # `import` succeeds at model-load time on every target — the agent\n",
+        "            # module imports `from langchain_openai import ChatOpenAI` lazily\n",
+        "            # inside the gateway branch, but a stale wheel cache or a missing\n",
+        "            # transitive dep can still surface at import time, and shipping\n",
+        "            # the same wheel set in every target keeps the failure modes\n",
+        "            # consistent.\n",
+        "            f\"langchain-openai=={get_distribution('langchain-openai').version}\",\n",
         "            f\"langgraph=={get_distribution('langgraph').version}\",\n",
         "        ],\n",
         "    )\n",
         "\n",
         "mlflow.set_active_model(model_id = logged_agent_info.model_id)"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -600,65 +1056,19 @@
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {},
           "inputWidgets": {},
-          "nuid": "93c5ffb0-ed1b-4e86-809e-9b7af90656e1",
+          "nuid": "b2f870d6-05d0-478e-8784-98793ba8480c",
           "showTitle": false,
           "tableResultSettingsMap": {},
           "title": ""
         }
       },
       "source": [
-        "#### eval"
+        "#### log refunder to `UC`"
       ]
     },
     {
       "cell_type": "code",
-      "metadata": {
-        "application/vnd.databricks.v1+cell": {
-          "cellMetadata": {
-            "byteLimit": 2048000,
-            "rowLimit": 10000
-          },
-          "inputWidgets": {},
-          "nuid": "72348da2-fd71-4413-8e0a-5cb16ed03d17",
-          "showTitle": false,
-          "tableResultSettingsMap": {},
-          "title": ""
-        }
-      },
-      "source": [
-        "# sample 10 order_ids\n",
-        "refund_queries = [\n",
-        "    row['order_id'] for row in spark.sql(f\"\"\"\n",
-        "        SELECT order_id \n",
-        "        FROM {CATALOG}.lakeflow.all_events \n",
-        "        WHERE event_type='delivered'\n",
-        "        LIMIT 10\n",
-        "    \"\"\").collect()\n",
-        "]\n",
-        "\n",
-        "# wrap in correct input schema\n",
-        "data = []\n",
-        "for query in refund_queries:\n",
-        "    data.append(\n",
-        "        {\n",
-        "            \"inputs\": {\n",
-        "                \"messages\": [\n",
-        "                    {\n",
-        "                        \"role\": \"user\",\n",
-        "                        \"content\": query,\n",
-        "                    }\n",
-        "                ]\n",
-        "            },\n",
-        "        }\n",
-        "    )\n",
-        "\n",
-        "print(data)"
-      ],
       "execution_count": 0,
-      "outputs": []
-    },
-    {
-      "cell_type": "code",
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -666,43 +1076,67 @@
             "rowLimit": 10000
           },
           "inputWidgets": {},
-          "nuid": "bfcf41db-e682-4ef3-964d-e5c40a07983c",
+          "nuid": "273249df-a966-45fc-9ddf-d7138af804b7",
           "showTitle": false,
           "tableResultSettingsMap": {},
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
-        "# create guideline, run evals\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.serving import EndpointStateReady\n",
         "\n",
-        "from mlflow.genai.scorers import Guidelines\n",
-        "import mlflow\n",
-        "import sys\n",
-        "import os\n",
-        "sys.path.append(os.getcwd())\n",
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
         "\n",
-        "notebook_path = dbutils.notebook.entry_point.getDbutils().notebook().getContext().notebookPath().get()\n",
-        "project_directory = os.path.dirname(notebook_path)\n",
+        "UC_MODEL_NAME = f\"{CATALOG}.ai.refunder\"\n",
+        "endpoint_name = dbutils.widgets.get(\"REFUND_AGENT_ENDPOINT_NAME\")\n",
         "\n",
-        "# Add the project directory to the system path\n",
-        "sys.path.append(project_directory)\n",
         "\n",
-        "from agent import AGENT\n",
+        "def _endpoint_already_serving(name: str, uc_model_name: str) -> bool:\n",
+        "    \"\"\"Return True iff a serving endpoint is READY and already serving uc_model_name.\n",
         "\n",
-        "refund_reason = Guidelines(\n",
-        "    name=\"refund_reason\",\n",
-        "    guidelines=[\"If a refund is offered, its reason must relate to order timing, not to other issues such as missing components.\"]\n",
-        ")\n",
+        "    Used to short-circuit register_model + agents.deploy on re-runs of this\n",
+        "    stage when the endpoint from a previous run is still healthy — saves ~15\n",
+        "    minutes of cold container build + serving provisioning.  To force a fresh\n",
+        "    deploy after editing agent code, delete the endpoint and rerun the stage.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        ep = WorkspaceClient().serving_endpoints.get(name)\n",
+        "    except Exception:\n",
+        "        return False\n",
+        "    if not ep.state or ep.state.ready != EndpointStateReady.READY:\n",
+        "        return False\n",
+        "    cfg = getattr(ep, \"config\", None) or getattr(ep, \"pending_config\", None)\n",
+        "    if not cfg:\n",
+        "        return False\n",
+        "    served = []\n",
+        "    for se in (getattr(cfg, \"served_entities\", None) or []):\n",
+        "        n = getattr(se, \"entity_name\", None)\n",
+        "        if n:\n",
+        "            served.append(n)\n",
+        "    for sm in (getattr(cfg, \"served_models\", None) or []):\n",
+        "        n = getattr(sm, \"model_name\", None)\n",
+        "        if n:\n",
+        "            served.append(n)\n",
+        "    return uc_model_name in served\n",
         "\n",
         "\n",
-        "results = mlflow.genai.evaluate(\n",
-        "    data=data,\n",
-        "    scorers=[refund_reason],\n",
-        "    predict_fn = lambda messages: AGENT.predict({\"messages\": messages})\n",
-        ")"
-      ],
-      "execution_count": 0,
-      "outputs": []
+        "_reuse_endpoint = _endpoint_already_serving(endpoint_name, UC_MODEL_NAME)\n",
+        "\n",
+        "if _reuse_endpoint:\n",
+        "    print(\n",
+        "        f\"\\u267b\\ufe0f Endpoint {endpoint_name} is already READY and serving {UC_MODEL_NAME}; \"\n",
+        "        f\"skipping register_model + agents.deploy (saves ~15 min). \"\n",
+        "        f\"Delete the endpoint to force a fresh deploy.\"\n",
+        "    )\n",
+        "    uc_registered_model_info = None\n",
+        "else:\n",
+        "    # register the model to UC\n",
+        "    uc_registered_model_info = mlflow.register_model(\n",
+        "        model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
+        "    )"
+      ]
     },
     {
       "cell_type": "markdown",
@@ -710,62 +1144,54 @@
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {},
           "inputWidgets": {},
-          "nuid": "b2f870d6-05d0-478e-8784-98793ba8480c",
+          "nuid": "bf715fb3-953c-4516-8d07-79c0d362a99e",
           "showTitle": false,
           "tableResultSettingsMap": {},
           "title": ""
         }
       },
       "source": [
-        "#### log refunder to `UC`"
+        "#### deploy the agent to model serving"
       ]
     },
     {
       "cell_type": "code",
-      "metadata": {
-        "application/vnd.databricks.v1+cell": {
-          "cellMetadata": {
-            "byteLimit": 2048000,
-            "rowLimit": 10000
-          },
-          "inputWidgets": {},
-          "nuid": "273249df-a966-45fc-9ddf-d7138af804b7",
-          "showTitle": false,
-          "tableResultSettingsMap": {},
-          "title": ""
-        }
-      },
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
       "source": [
-        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "import mlflow\n",
         "\n",
-        "UC_MODEL_NAME = f\"{CATALOG}.ai.refunder\"\n",
+        "# Create prod experiment for production inference traces.\n",
+        "# The serving endpoint logs every request as a trace; pointing\n",
+        "# MLFLOW_EXPERIMENT_ID at this experiment (in the agents.deploy() call\n",
+        "# below) ensures those traces land somewhere stable and findable, instead\n",
+        "# of the auto-created /Serving/{endpoint} experiment.  Mirrors the pattern\n",
+        "# in stages/complaint_agent.ipynb so the runbook can link to a single\n",
+        "# `/Shared/{CATALOG}_refund_agent_prod` URL across deploys.\n",
+        "prod_experiment_name = f\"/Shared/{CATALOG}_refund_agent_prod\"\n",
         "\n",
-        "# register the model to UC\n",
-        "uc_registered_model_info = mlflow.register_model(\n",
-        "    model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
-        ")"
-      ],
-      "execution_count": 0,
-      "outputs": []
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {
-        "application/vnd.databricks.v1+cell": {
-          "cellMetadata": {},
-          "inputWidgets": {},
-          "nuid": "bf715fb3-953c-4516-8d07-79c0d362a99e",
-          "showTitle": false,
-          "tableResultSettingsMap": {},
-          "title": ""
-        }
-      },
-      "source": [
-        "#### deploy the agent to model serving"
+        "# set_experiment creates the experiment if it doesn't exist, or activates it if it does.\n",
+        "prod_experiment = mlflow.set_experiment(prod_experiment_name)\n",
+        "prod_experiment_id = prod_experiment.experiment_id\n",
+        "print(f\"✅ Using prod experiment: {prod_experiment_name} (ID: {prod_experiment_id})\")\n",
+        "\n",
+        "# Track the experiment in uc_state so `databricks bundle run cleanup` deletes it.\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "experiment_data = {\n",
+        "    \"experiment_id\": prod_experiment_id,\n",
+        "    \"name\": prod_experiment_name,\n",
+        "}\n",
+        "add(CATALOG, \"experiments\", experiment_data)\n",
+        "print(f\"✅ Added prod experiment to UC state\")"
       ]
     },
     {
       "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -779,19 +1205,85 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
+        "from datetime import timedelta\n",
+        "\n",
         "from databricks import agents\n",
-        "deployment_info = agents.deploy(\n",
-        "    model_name=UC_MODEL_NAME, \n",
-        "    model_version=uc_registered_model_info.version, \n",
-        "    scale_to_zero=False,\n",
-        "    endpoint_name=f\"{dbutils.widgets.get(\"REFUND_AGENT_ENDPOINT_NAME\")}\")"
-      ],
-      "execution_count": 0,
-      "outputs": []
+        "\n",
+        "if _reuse_endpoint:\n",
+        "    deployment_info = None\n",
+        "    print(f\"\\u2705 Endpoint {endpoint_name} is READY (reused from previous deploy)\")\n",
+        "else:\n",
+        "    deployment_info = agents.deploy(\n",
+        "        model_name=UC_MODEL_NAME,\n",
+        "        model_version=uc_registered_model_info.version,\n",
+        "        scale_to_zero=False,\n",
+        "        endpoint_name=endpoint_name,\n",
+        "        environment_vars={\"MLFLOW_EXPERIMENT_ID\": str(prod_experiment_id)},\n",
+        "    )\n",
+        "\n",
+        "    # Block the stage until the endpoint finishes deploying so the task\n",
+        "    # fails fast (and visibly) when the deploy fails, instead of returning\n",
+        "    # SUCCESS while the container is still building / failing in the\n",
+        "    # background.  Matches the wait pattern used by complaint_agent.\n",
+        "    workspace = WorkspaceClient()\n",
+        "    ready_endpoint = workspace.serving_endpoints.wait_get_serving_endpoint_not_updating(\n",
+        "        name=endpoint_name,\n",
+        "        timeout=timedelta(minutes=30),\n",
+        "    )\n",
+        "\n",
+        "    if ready_endpoint.state.ready != EndpointStateReady.READY:\n",
+        "        raise RuntimeError(\n",
+        "            f\"Endpoint {endpoint_name} is {ready_endpoint.state.ready} after deployment; retry or investigate.\"\n",
+        "        )\n",
+        "\n",
+        "    print(f\"\\u2705 Endpoint {endpoint_name} is READY\")"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# === Grant UC perms to the endpoint's runtime System Service Principal ===\n",
+        "#\n",
+        "# Model serving endpoints (including ones created by agents.deploy()) run\n",
+        "# their inference container as a workspace-level SCIM SP whose displayName\n",
+        "# is \"System Service Principal\".  These SPs are NOT members of\n",
+        "# `account users`, so the catalog/schema/function grants made to\n",
+        "# `account users` elsewhere in the bundle do NOT apply to them.\n",
+        "#\n",
+        "# Result without this cell: every fresh agent endpoint fails on its first\n",
+        "# tool call with PERMISSION_DENIED (\"USE CATALOG\" / \"USE SCHEMA\" / \"EXECUTE\")\n",
+        "# until somebody manually grants permissions.  The cell below discovers\n",
+        "# the System SPs via SCIM and grants them the perms they need.  Idempotent\n",
+        "# (re-granting an existing privilege in UC is a no-op).\n",
+        "#\n",
+        "# Skipped when we reused an existing endpoint (no fresh SP to grant to).\n",
+        "if deployment_info is not None:\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from agent_runtime_grants import grant_agent_runtime_perms\n",
+        "\n",
+        "    # Pass endpoint_name so the helper also grants to the endpoint\n",
+        "    # creator — that's the actual runtime identity in EMBEDDED_CREDENTIALS\n",
+        "    # mode workspaces (where 'System Service Principal' isn't created and\n",
+        "    # `account users` may be empty at the workspace level).\n",
+        "    grant_agent_runtime_perms(\n",
+        "        spark,\n",
+        "        CATALOG,\n",
+        "        workspace_client=WorkspaceClient(),\n",
+        "        endpoint_name=endpoint_name,\n",
+        "    )\n",
+        "else:\n",
+        "    print(\"♻ Endpoint reused — skipping runtime SP grants (already applied on first deploy).\")\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 0,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -805,11 +1297,10 @@
           "title": ""
         }
       },
+      "outputs": [],
       "source": [
         "print(deployment_info)"
-      ],
-      "execution_count": 0,
-      "outputs": []
+      ]
     },
     {
       "cell_type": "markdown",
@@ -829,6 +1320,7 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
       "metadata": {
         "application/vnd.databricks.v1+cell": {
           "cellMetadata": {
@@ -842,16 +1334,225 @@
           "title": ""
         }
       },
+      "outputs": [],
+      "source": [
+        "# Also add to UC-state — but only when we actually deployed a new endpoint.\n",
+        "# On the reuse path the endpoint was already registered by a previous run,\n",
+        "# so re-adding here would just create a duplicate uc_state row.\n",
+        "if deployment_info is not None:\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from uc_state import add\n",
+        "\n",
+        "    add(dbutils.widgets.get(\"CATALOG\"), \"endpoints\", deployment_info)\n",
+        "else:\n",
+        "    print(\"\\u267b\\ufe0f Endpoint already tracked in uc_state from a previous deploy; skipping add.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Production Monitoring\n",
+        "\n",
+        "Register MLflow scorers on the prod experiment so every live request that\n",
+        "hits the refund agent is automatically scored.  Mirrors the in-stage\n",
+        "pattern in `stages/complaint_agent.ipynb` and the helper in\n",
+        "`stages/operational_evaluation.ipynb`.\n",
+        "\n",
+        "Scorer set (4, all at 100% sampling):\n",
+        "\n",
+        "- `safety` — built-in `Safety()` LLM judge for harmful or inappropriate content\n",
+        "- `relevance_to_query` — built-in `RelevanceToQuery()` LLM judge — does the answer address the question\n",
+        "- `operational_quality` — generic `Guidelines` — concrete data, not a hedge\n",
+        "- `refund_policy_compliance` — refund-specific `Guidelines` — recommendation matches the policy"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from mlflow.genai.scorers import (\n",
+        "    Safety,\n",
+        "    RelevanceToQuery,\n",
+        "    Guidelines,\n",
+        "    ScorerSamplingConfig,\n",
+        "    list_scorers,\n",
+        ")\n",
+        "\n",
+        "\n",
+        "def _register_scorer(scorer_obj, name: str, sample_rate: float = 1.0):\n",
+        "    \"\"\"Idempotent register-or-restart, scoped to the prod experiment.\n",
+        "\n",
+        "    Re-running the stage hits the same code path; calling .register() on\n",
+        "    an already-registered scorer raises ValueError, so we look it up first\n",
+        "    and just .start() it instead.  Same shape as\n",
+        "    stages/complaint_agent.ipynb and stages/operational_evaluation.ipynb.\n",
+        "    \"\"\"\n",
+        "    existing = {s.name: s for s in list_scorers(experiment_id=prod_experiment_id)}\n",
+        "    sampling = ScorerSamplingConfig(sample_rate=sample_rate)\n",
+        "    if name in existing:\n",
+        "        existing[name].start(sampling_config=sampling)\n",
+        "        print(f\"  ↺ {name} — restarted at {sample_rate:.0%} sample rate\")\n",
+        "        return existing[name]\n",
+        "    registered = scorer_obj.register(name=name, experiment_id=prod_experiment_id)\n",
+        "    registered.start(sampling_config=sampling)\n",
+        "    print(f\"  ✅ {name} — registered + started at {sample_rate:.0%} sample rate\")\n",
+        "    return registered\n",
+        "\n",
+        "\n",
+        "# Baseline (every agent in the bundle gets these three).\n",
+        "_register_scorer(Safety(),           name=\"safety\",             sample_rate=1.0)\n",
+        "_register_scorer(RelevanceToQuery(), name=\"relevance_to_query\", sample_rate=1.0)\n",
+        "_register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"operational_quality\",\n",
+        "        guidelines=(\n",
+        "            \"The response must include specific data points such as numbers, \"\n",
+        "            \"percentages, dates, order IDs, or named locations. \"\n",
+        "            \"The response must not be a generic hedge or refusal \"\n",
+        "            \"(e.g. 'I don't have access'). \"\n",
+        "            \"The response must directly answer the question asked.\"\n",
+        "        ),\n",
+        "    ),\n",
+        "    name=\"operational_quality\",\n",
+        "    sample_rate=1.0,\n",
+        ")\n",
+        "\n",
+        "# Domain — refund-specific policy compliance.\n",
+        "_register_scorer(\n",
+        "    Guidelines(\n",
+        "        name=\"refund_policy_compliance\",\n",
+        "        guidelines=[\n",
+        "            \"Recommendations must be one of: no refund, partial refund, or full refund — never anything outside this set.\",\n",
+        "            \"If a refund is recommended, the response must cite the order_id it applies to.\",\n",
+        "            \"If the order is older than the refund window, the response must explicitly mention that the refund window has expired.\",\n",
+        "            \"The response must reference the specific reason from the order data (e.g. late delivery, missing item, food quality).\",\n",
+        "        ],\n",
+        "    ),\n",
+        "    name=\"refund_policy_compliance\",\n",
+        "    sample_rate=1.0,\n",
+        ")\n",
+        "\n",
+        "print(\"✅ Production monitoring enabled — 4 scorers active at 100% sampling\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Prompt Registry\n",
+        "\n",
+        "Register the system prompt that was just baked into `agent.py` under\n",
+        "`{CATALOG}.prompts.refund_system` so it lives alongside the deployed model\n",
+        "in Unity Catalog. We extract the template directly from `agent.py` rather\n",
+        "than re-declaring it here, so the registry tracks **exactly** what was\n",
+        "deployed (no drift possible).\n",
+        "\n",
+        "Re-running the stage creates a new prompt version and bumps the\n",
+        "`production` alias. The schema and all prompts are dropped automatically\n",
+        "by `DROP CATALOG ... CASCADE` in `destroy.ipynb`, so no extra cleanup\n",
+        "wiring is needed."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
       "source": [
-        "# Also add to UC-state\n",
+        "import re\n",
         "import sys\n",
+        "\n",
         "sys.path.append('../utils')\n",
-        "from uc_state import add\n",
+        "from prompt_registry import seed_prompt_history\n",
         "\n",
-        "add(dbutils.widgets.get(\"CATALOG\"), \"endpoints\", deployment_info)"
-      ],
-      "execution_count": null,
-      "outputs": []
+        "# Use the absolute path captured by %%writefilev (see cell 13) so this works\n",
+        "# even when CWD has drifted between cells.\n",
+        "_agent_py_path = _WRITEFILEV_ABS_PATHS.get(\"agent.py\", \"agent.py\")\n",
+        "with open(_agent_py_path) as f:\n",
+        "    _agent_py = f.read()\n",
+        "\n",
+        "# Extract from _FALLBACK_PROMPT — the source-of-truth literal in agent.py.\n",
+        "# The deployed agent prefers mlflow.genai.load_prompt() at startup but\n",
+        "# falls back to this literal if the registry is empty or unreachable.\n",
+        "_match = re.search(r'_FALLBACK_PROMPT\\s*=\\s*\"\"\"(.*?)\"\"\"', _agent_py, re.DOTALL)\n",
+        "if not _match:\n",
+        "    raise RuntimeError(\n",
+        "        \"Could not extract _FALLBACK_PROMPT from agent.py. \"\n",
+        "        \"If the prompt block was renamed, update this regex.\"\n",
+        "    )\n",
+        "\n",
+        "_uc_version = (\n",
+        "    uc_registered_model_info.version\n",
+        "    if uc_registered_model_info is not None\n",
+        "    else \"reused-endpoint\"\n",
+        ")\n",
+        "\n",
+        "# Two earlier versions of the refund prompt, seeded on first deploy so the\n",
+        "# Prompt Registry UI shows v1 → v2 → v3 history. These are demo seeds, NOT a\n",
+        "# real engineering changelog — seed_prompt_history tags each with\n",
+        "# is_demo_seed=\"true\" so anyone auditing the registry can tell.\n",
+        "_REFUND_V1 = (\n",
+        "    \"You are a refund agent for a food delivery service. \"\n",
+        "    \"Given an order_id, decide whether to issue a refund and how much. \"\n",
+        "    \"Return a single-line JSON with `refund_usd` (float), `refund_class` \"\n",
+        "    \"(\\\"none\\\" | \\\"partial\\\" | \\\"full\\\"), and `reason` (short explanation).\"\n",
+        ")\n",
+        "_REFUND_V2 = \"\"\"You are RefundGPT, a CX agent responsible for refund decisions on food delivery orders.\n",
+        "\n",
+        "    You can call tools to gather the information you need. Start with an `order_id`.\n",
+        "\n",
+        "    Instructions:\n",
+        "    1. Call `order_details(order_id)` first to get event history and confirm the id is valid and the order was delivered.\n",
+        "    2. Figure out the delivery duration by calling `get_order_delivery_time(order_id)`.\n",
+        "    3. Extract the location (either directly or from the first event's body).\n",
+        "    4. Call `get_location_timings(location)` to get the P50/P75/P99 values.\n",
+        "    5. Compare actual delivery time to those percentiles.\n",
+        "\n",
+        "    Refund policy (SLA-based):\n",
+        "       - If the order arrived AFTER the P75 delivery time: recommend a `partial` or `full` refund based on how late.\n",
+        "       - If the order arrived BEFORE the P75: no refund.\n",
+        "\n",
+        "    Output a single-line JSON with these fields:\n",
+        "    - `refund_usd` (float),\n",
+        "    - `refund_class` (\\\"none\\\" | \\\"partial\\\" | \\\"full\\\"),\n",
+        "    - `reason` (short human explanation).\n",
+        "\n",
+        "    You must return only the JSON. No extra text or markdown.\"\"\"\n",
+        "\n",
+        "_common_tags = {\n",
+        "    \"agent\": \"refund\",\n",
+        "    \"stage\": \"refunder_agent\",\n",
+        "    \"uc_model\": UC_MODEL_NAME,\n",
+        "    \"consumed_via\": \"mlflow.genai.load_prompt at endpoint startup\",\n",
+        "}\n",
+        "\n",
+        "seed_prompt_history(\n",
+        "    spark=spark,\n",
+        "    catalog=CATALOG,\n",
+        "    name=\"refund_system\",\n",
+        "    historical=[\n",
+        "        {\n",
+        "            \"template\": _REFUND_V1,\n",
+        "            \"commit_message\": \"v1: bare-bones refund decisioner, no SLA logic or tool use (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "        {\n",
+        "            \"template\": _REFUND_V2,\n",
+        "            \"commit_message\": \"v2: added tool-calling + SLA-based refund policy (P75 cutoff) (demo history seed)\",\n",
+        "            \"tags\": _common_tags,\n",
+        "        },\n",
+        "    ],\n",
+        "    current={\n",
+        "        \"template\": _match.group(1).strip(),\n",
+        "        \"commit_message\": f\"v3 (production): SLA + goodwill credit path — UC model version {_uc_version}\",\n",
+        "        \"tags\": {**_common_tags, \"uc_model_version\": str(_uc_version)},\n",
+        "    },\n",
+        ")"
+      ]
     }
   ],
   "metadata": {
@@ -961,4 +1662,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 0
-}
\ No newline at end of file
+}
diff --git a/stages/refunder_stream.ipynb b/stages/refunder_stream.ipynb
index 488f41f..0835d3f 100644
--- a/stages/refunder_stream.ipynb
+++ b/stages/refunder_stream.ipynb
@@ -85,9 +85,14 @@
         "\n",
         "job_name = f\"Refund Recommender Stream ({CATALOG})\"\n",
         "\n",
+        "# timeout_seconds=600 (10 min, matches cron) so a single hung UDF call against\n",
+        "# a stalled refund-agent endpoint cannot block the whole queue forever.\n",
+        "# Without this, an orphaned run from an earlier test session can hold the queue\n",
+        "# slot indefinitely while every subsequent cron tick piles up as QUEUED.\n",
         "task_def = [\n",
         "    j.Task(\n",
         "        task_key=\"refund_recommender_stream\",\n",
+        "        timeout_seconds=600,\n",
         "        notebook_task=j.NotebookTask(\n",
         "            notebook_path=notebook_dbx_path,\n",
         "            base_parameters={\n",
@@ -103,15 +108,21 @@
         "    pause_status=j.PauseStatus.UNPAUSED,\n",
         ")\n",
         "\n",
+        "# queue.enabled=False: drop cron triggers if a previous run is still active\n",
+        "# instead of stacking them up.  For an availableNow catch-up stream, dropping\n",
+        "# is correct: the NEXT tick will pick up whatever rows the previous run didn't\n",
+        "# get to.  Default (enabled=True) creates an unbounded backlog on any hang.\n",
+        "queue_def = j.QueueSettings(enabled=False)\n",
+        "\n",
         "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
         "if existing:\n",
         "    job_id = existing[0].job_id\n",
         "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
-        "        name=job_name, tasks=task_def, schedule=schedule_def,\n",
+        "        name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def,\n",
         "    ))\n",
         "    print(f\"♻️ Updated existing job_id={job_id}\")\n",
         "else:\n",
-        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def)\n",
+        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def)\n",
         "    job_id = job.job_id\n",
         "    import sys\n",
         "    sys.path.append('../utils')\n",
diff --git a/stages/support_lakebase.ipynb b/stages/support_lakebase.ipynb
index 9a266c5..7593bea 100644
--- a/stages/support_lakebase.ipynb
+++ b/stages/support_lakebase.ipynb
@@ -1,254 +1,500 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Support Lakebase & App\n",
-    "\n",
-    "Provision Lakebase instance, create synced table for support_agent_reports,\n",
-    "create OLTP tables, set up warehouse, deploy the support console app."
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Support Lakebase & App\n",
+        "\n",
+        "Provision Lakebase instance, create synced table for support_agent_reports,\n",
+        "create OLTP tables, set up warehouse, deploy the support console app."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install databricks-sdk psycopg2-binary --upgrade"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "import re\nimport time\nimport sys\n\nsys.path.append('../utils')\nfrom uc_state import add\n\nCATALOG = dbutils.widgets.get(\"CATALOG\")\nSUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")\n\nSUPPORT_LAKEBASE_INSTANCE_NAME = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}supportmanager\".lower())\nSUPPORT_DB_NAME = \"databricks_postgres\"",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Lakebase Instance & Database"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.database import DatabaseInstance\n",
+        "from databricks.sdk.errors import NotFound, ResourceDoesNotExist\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "instance_name = SUPPORT_LAKEBASE_INSTANCE_NAME\n",
+        "\n",
+        "try:\n",
+        "    existing = w.database.get_database_instance(instance_name)\n",
+        "    print(f\"Found existing database instance: {existing.name} (state: {existing.state})\")\n",
+        "    instance = existing\n",
+        "except (NotFound, ResourceDoesNotExist):\n",
+        "    print(f\"Creating new database instance: {instance_name}\")\n",
+        "    instance = w.database.create_database_instance(\n",
+        "        DatabaseInstance(\n",
+        "            name=instance_name,\n",
+        "            capacity=\"CU_1\"\n",
+        "        )\n",
+        "    )\n",
+        "    print(f\"Created database instance: {instance.name}\")\n",
+        "    add(CATALOG, \"databaseinstances\", {\"name\": instance.name})\n",
+        "\n",
+        "print(\"Waiting for database instance to be available...\")\n",
+        "for _ in range(60):\n",
+        "    state = str(w.database.get_database_instance(instance_name).state)\n",
+        "    if state == \"DatabaseInstanceState.AVAILABLE\":\n",
+        "        print(f\"Instance ready: {state}\")\n",
+        "        break\n",
+        "    time.sleep(10)\n",
+        "else:\n",
+        "    raise TimeoutError(f\"Database instance {instance_name} did not become available within 10 minutes\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "from databricks.sdk.service.database import DatabaseCatalog\n\ncatalog_name = SUPPORT_LAKEBASE_INSTANCE_NAME\n\ntry:\n    existing_cat = w.catalogs.get(catalog_name)\n    print(f\"Found existing catalog: {existing_cat.name}\")\nexcept Exception:\n    catalog = w.database.create_database_catalog(\n        DatabaseCatalog(\n            name=catalog_name,\n            database_instance_name=SUPPORT_LAKEBASE_INSTANCE_NAME,\n            database_name=SUPPORT_DB_NAME,\n            create_database_if_not_exists=True\n        )\n    )\n    print(f\"Created new database and catalog: {catalog.name}\")\n    add(CATALOG, \"databasecatalogs\", catalog)",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Synced Table"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk.service.database import SyncedDatabaseTable, SyncedTableSpec, NewPipelineSpec, SyncedTableSchedulingPolicy\n",
+        "\n",
+        "# Synced-table UC entry lives under the source schema; backing Delta lives\n",
+        "# under `_lakebase_storage` (different schema, so the two cannot collide).\n",
+        "# Both paths can hold stale Delta from a previous half-succeeded run and\n",
+        "# must be cleared before create.\n",
+        "synced_table_name = f\"{CATALOG}.support.support_agent_reports_sync\"\n",
+        "SYNCED_BASENAME = synced_table_name.split(\".\")[-1]\n",
+        "BACKING_TABLE_NAME = f\"{CATALOG}._lakebase_storage.{SYNCED_BASENAME}\"\n",
+        "\n",
+        "# Postgres-side destination that the synced pipeline materialises inside the\n",
+        "# kept Lakebase instance.  Schema/table mirror the synced-table source schema\n",
+        "# and basename by API convention; logical DB matches the `logical_database_name`\n",
+        "# in the create call below.\n",
+        "POSTGRES_DB_NAME = SUPPORT_DB_NAME\n",
+        "POSTGRES_SCHEMA = \"support\"\n",
+        "\n",
+        "spark.sql(f\"CREATE SCHEMA IF NOT EXISTS {CATALOG}._lakebase_storage\")\n",
+        "\n",
+        "\n",
+        "def _drop_postgres_destination():\n",
+        "    \"\"\"Drop the Postgres-side destination table that a previous synced-table\n",
+        "    pipeline materialised on the kept Lakebase instance.\n",
+        "\n",
+        "    This is the third place a `create_synced_database_table` AlreadyExists can\n",
+        "    come from — UC entry, backing Delta, OR the Postgres destination itself —\n",
+        "    and is the only one invisible to `w.tables.*` or the synced-table GET\n",
+        "    endpoints, so it manifests as the confusing 'reported AlreadyExists but\n",
+        "    get_synced_database_table cannot retrieve it' error.\n",
+        "\n",
+        "    Why this lives here:\n",
+        "      `bundle run cleanup` only drops the UC catalog.  We intentionally keep\n",
+        "      the Lakebase database instance across cleanups (recreate is slow), but\n",
+        "      that means the Postgres table the synced pipeline materialised survives\n",
+        "      — and the next deploy's create refuses because its destination exists.\n",
+        "\n",
+        "    Best-effort: any failure (psycopg2 missing, network, permission denied)\n",
+        "    is logged and swallowed; the subsequent create_synced_database_table will\n",
+        "    surface a real error if the leftover is still in the way.\n",
+        "    \"\"\"\n",
+        "    try:\n",
+        "        import psycopg2  # noqa: F401 — provided by the %pip install in cell 1\n",
+        "    except ImportError:\n",
+        "        print(\"  ⚠️ Postgres sweep: psycopg2 not installed; skipping\")\n",
+        "        return False\n",
+        "    try:\n",
+        "        host = w.database.get_database_instance(name=instance_name).read_write_dns\n",
+        "        token = w.config.oauth_token().access_token\n",
+        "        user = w.current_user.me().user_name\n",
+        "    except Exception as e:\n",
+        "        print(f\"  ⚠️ Postgres sweep: setup failed: {type(e).__name__}: {e}\")\n",
+        "        return False\n",
+        "    try:\n",
+        "        conn = psycopg2.connect(\n",
+        "            host=host, port=5432, dbname=POSTGRES_DB_NAME,\n",
+        "            user=user, password=token, sslmode=\"require\",\n",
+        "        )\n",
+        "        conn.autocommit = True\n",
+        "        with conn:\n",
+        "            with conn.cursor() as cur:\n",
+        "                cur.execute(\n",
+        "                    f'DROP TABLE IF EXISTS \"{POSTGRES_SCHEMA}\".\"{SYNCED_BASENAME}\" CASCADE;'\n",
+        "                )\n",
+        "        conn.close()\n",
+        "        print(\n",
+        "            f\"  🗑️  Cleared Postgres destination \"\n",
+        "            f\"{POSTGRES_DB_NAME}.{POSTGRES_SCHEMA}.{SYNCED_BASENAME} (no-op if absent)\"\n",
+        "        )\n",
+        "        return True\n",
+        "    except Exception as e:\n",
+        "        print(f\"  ⚠️ Postgres sweep failed: {type(e).__name__}: {e}\")\n",
+        "        return False\n",
+        "\n",
+        "\n",
+        "def _try_get_synced(name):\n",
+        "    \"\"\"Synced-table-specific GET.  Distinct from `w.tables.get()` because the\n",
+        "    latter returns ANY UC table at the same path — including a stale Delta\n",
+        "    left behind from a failed previous run, which we then erroneously treat\n",
+        "    as a 'reusable synced table' and skip the recreate.\"\"\"\n",
+        "    try:\n",
+        "        return w.database.get_synced_database_table(name=name)\n",
+        "    except Exception:\n",
+        "        return None\n",
+        "\n",
+        "\n",
+        "existing_synced = _try_get_synced(synced_table_name)\n",
+        "if existing_synced is not None:\n",
+        "    print(f\"♻️ Found existing synced table: {getattr(existing_synced, 'name', synced_table_name)}\")\n",
+        "else:\n",
+        "    # Sweep stale Delta at both UC paths.  Failure modes that put a stale\n",
+        "    # table at synced_table_name: a previous `create_synced_database_table`\n",
+        "    # half-succeeded (the UC SyncedTable entity was created but the synced-\n",
+        "    # pipeline failed, leaving the UC name occupied).  Failure modes at\n",
+        "    # BACKING_TABLE_NAME: a previous delete that bypassed our cleanup\n",
+        "    # notebook, or a `delete_synced_database_table(purge_data=False)`.\n",
+        "    for stale in (synced_table_name, BACKING_TABLE_NAME):\n",
+        "        try:\n",
+        "            spark.sql(f\"DROP TABLE IF EXISTS {stale}\")\n",
+        "            print(f\"  🗑️  Cleared stale Delta at {stale} (no-op if absent)\")\n",
+        "        except Exception as e:\n",
+        "            print(f\"  ⚠️ Could not drop {stale}: {e}\")\n",
+        "\n",
+        "    # Third sweep target: Postgres-side destination inside the kept Lakebase\n",
+        "    # instance (see _drop_postgres_destination docstring above).  Required\n",
+        "    # because `bundle run cleanup` only drops the UC catalog, so the Postgres\n",
+        "    # table the synced pipeline materialised survives across deploy cycles.\n",
+        "    _drop_postgres_destination()\n",
+        "\n",
+        "    try:\n",
+        "        synced_table = w.database.create_synced_database_table(\n",
+        "            SyncedDatabaseTable(\n",
+        "                name=synced_table_name,\n",
+        "                database_instance_name=instance_name,\n",
+        "                logical_database_name=SUPPORT_DB_NAME,\n",
+        "                spec=SyncedTableSpec(\n",
+        "                    source_table_full_name=f\"{CATALOG}.support.support_agent_reports\",\n",
+        "                    primary_key_columns=[\"support_request_id\"],\n",
+        "                    scheduling_policy=SyncedTableSchedulingPolicy.CONTINUOUS,\n",
+        "                    create_database_objects_if_missing=True,\n",
+        "                    # Backing Delta storage for the synced table.  MUST live in a\n",
+        "                    # schema *different from the synced table's own schema*, because\n",
+        "                    # the synced-table pipeline materializes its backing Delta at\n",
+        "                    # `{storage_catalog}.{storage_schema}.<synced_table_basename>`\n",
+        "                    # — which would collide with the synced-table UC entry itself if\n",
+        "                    # storage_schema equalled the source schema.\n",
+        "                    new_pipeline_spec=NewPipelineSpec(\n",
+        "                        storage_catalog=CATALOG,\n",
+        "                        storage_schema=\"_lakebase_storage\",\n",
+        "                    ),\n",
+        "                ),\n",
+        "            )\n",
+        "        )\n",
+        "        print(f\"Created synced table: {synced_table.name}\")\n",
+        "        add(CATALOG, \"pipelines\", synced_table.data_synchronization_status)\n",
+        "    except Exception as e:\n",
+        "        # Last-line defense: the API sometimes returns AlreadyExists even\n",
+        "        # after our drop pass — e.g. a concurrent deploy raced us, or the\n",
+        "        # API caches existence checks against the storage Delta we just\n",
+        "        # dropped.  Re-query via the synced-table-specific endpoint; if it\n",
+        "        # comes back, treat as success.  If not, surface the original error.\n",
+        "        is_already_exists = (\n",
+        "            type(e).__name__ == \"AlreadyExists\"\n",
+        "            or \"already exists\" in str(e).lower()\n",
+        "        )\n",
+        "        if not is_already_exists:\n",
+        "            raise\n",
+        "        print(f\"⚠️ create_synced_database_table raised AlreadyExists: {e}\")\n",
+        "        existing_synced = _try_get_synced(synced_table_name)\n",
+        "        if existing_synced is None:\n",
+        "            raise RuntimeError(\n",
+        "                f\"create_synced_database_table reported AlreadyExists for {synced_table_name}, \"\n",
+        "                f\"but get_synced_database_table cannot retrieve it.  All three pre-create \"\n",
+        "                f\"sweeps (UC entry {synced_table_name}, backing Delta {BACKING_TABLE_NAME}, \"\n",
+        "                f\"Postgres destination {POSTGRES_DB_NAME}.{POSTGRES_SCHEMA}.{SYNCED_BASENAME} \"\n",
+        "                f\"on {instance_name}) already ran and did not unblock the create.  Manual \"\n",
+        "                f\"inspection required.\"\n",
+        "            ) from e\n",
+        "        print(f\"♻️ Reusing synced table found on refetch: {getattr(existing_synced, 'name', synced_table_name)}\")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### OLTP Tables (Postgres)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "import psycopg2\n\n# Resolve the Postgres endpoint via the new Postgres API\nPROJECT = f\"projects/{SUPPORT_LAKEBASE_INSTANCE_NAME}\"\nbranches = list(w.postgres.list_branches(PROJECT))\ndefault_branch = next((b for b in branches if getattr(getattr(b, \"status\", None), \"default\", False)), branches[0])\nbranch_name = default_branch.name\n\nendpoints = list(w.postgres.list_endpoints(parent=branch_name))\nif not endpoints:\n    for _ in range(12):\n        time.sleep(5)\n        endpoints = list(w.postgres.list_endpoints(parent=branch_name))\n        if endpoints:\n            break\n    if not endpoints:\n        raise RuntimeError(\"No Lakebase endpoint found\")\n\nendpoint = next((e for e in endpoints if str(getattr(getattr(e, \"status\", None), \"endpoint_type\", \"\")).endswith(\"READ_WRITE\")), endpoints[0])\nendpoint_name = endpoint.name\nendpoint_host = endpoint.status.hosts.host\n\nprint(f\"Branch: {branch_name}\")\nprint(f\"Endpoint: {endpoint_name}\")\nprint(f\"Host: {endpoint_host}\")\n\n# Connect and create OLTP tables\ncreds = w.postgres.generate_database_credential(endpoint=endpoint_name)\ncurrent_user = w.current_user.me().user_name\n\nconn = psycopg2.connect(\n    host=endpoint_host,\n    port=5432,\n    dbname=SUPPORT_DB_NAME,\n    user=current_user,\n    password=creds.token,\n    sslmode=\"require\",\n)\nconn.autocommit = False\n\nwith conn.cursor() as cur:\n    cur.execute(\"CREATE SCHEMA IF NOT EXISTS support\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.operator_actions (\n          action_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          action_type TEXT NOT NULL CHECK (action_type IN ('apply_refund','apply_credit','send_reply')),\n          amount_usd NUMERIC(10,2),\n          payload JSONB,\n          status TEXT NOT NULL DEFAULT 'recorded',\n          actor TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.support_replies (\n          reply_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          message_text TEXT NOT NULL,\n          sent_by TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.request_status (\n          support_request_id TEXT PRIMARY KEY,\n          status TEXT NOT NULL DEFAULT 'pending',\n          assigned_to TEXT,\n          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n          last_action TEXT,\n          notes TEXT\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.response_ratings (\n          rating_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          rating TEXT NOT NULL CHECK (rating IN ('thumbs_up','thumbs_down')),\n          reason_code TEXT,\n          feedback_notes TEXT,\n          actor TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n          UNIQUE (support_request_id)\n        )\n    \"\"\")\n\n    conn.commit()\n\nconn.close()\nprint(\"OLTP tables created\")",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Warehouse"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "WAREHOUSE_NAME = f\"{CATALOG}-warehouse\"\n",
+        "existing_wh = [wh for wh in w.warehouses.list() if wh.name == WAREHOUSE_NAME]\n",
+        "if existing_wh:\n",
+        "    warehouse = existing_wh[0]\n",
+        "    print(f\"Using existing warehouse: {warehouse.id}\")\n",
+        "else:\n",
+        "    warehouse = w.warehouses.create(\n",
+        "        name=WAREHOUSE_NAME,\n",
+        "        cluster_size=\"2X-Small\",\n",
+        "        max_num_clusters=1,\n",
+        "        min_num_clusters=1,\n",
+        "        enable_serverless_compute=True,\n",
+        "    ).result()\n",
+        "    add(CATALOG, \"warehouses\", warehouse)\n",
+        "    print(f\"Created warehouse: {warehouse.id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### App Deployment"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "import os\n\n# Write app.yaml with computed values\napp_yaml_contents = f\"\"\"command: ['npm', 'run', 'start']\nenv:\n  - name: PGPORT\n    value: '5432'\n  - name: PGDATABASE\n    value: '{SUPPORT_DB_NAME}'\n  - name: PGSSLMODE\n    value: 'require'\n  - name: LAKEBASE_ENDPOINT\n    value: '{endpoint_name}'\n  - name: DATABRICKS_WAREHOUSE_ID\n    value: '{warehouse.id}'\n  - name: SUPPORT_AGENT_ENDPOINT_NAME\n    value: '{SUPPORT_AGENT_ENDPOINT_NAME}'\n\"\"\"\n\napp_yaml_path = os.path.abspath(\"../apps/supportconsolek/supportconsolek/app.yaml\")\nif os.path.exists(app_yaml_path):\n    os.remove(app_yaml_path)\n\ntime.sleep(3)\n\nwith open(app_yaml_path, \"w\") as f:\n    f.write(app_yaml_contents)\n\nprint(f\"Wrote app.yaml with warehouse={warehouse.id}, endpoint={endpoint_name}\")",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk.service.apps import App, AppResource, AppResourceSqlWarehouse\n",
+        "from databricks.sdk.service.apps import AppResourceSqlWarehouseSqlWarehousePermission\n",
+        "\n",
+        "source_code_path = os.path.abspath(\"../apps/supportconsolek/supportconsolek\")\n",
+        "\n",
+        "# P1-18: catalog-scope the app name so two users on the same workspace don't\n",
+        "# fight over the global `supportconsole` slug.\n",
+        "import re as _re_app\n",
+        "APP_NAME = _re_app.sub(r\"-+\", \"-\", _re_app.sub(r\"[^a-z0-9-]\", \"-\", f\"supportconsole-{CATALOG}\".lower())).strip(\"-\")[:30]\n",
+        "print(f\"App name: {APP_NAME}\")\n",
+        "\n",
+        "app_def = App(\n",
+        "    name=APP_NAME,\n",
+        "    default_source_code_path=source_code_path,\n",
+        "    resources=[\n",
+        "        AppResource(\n",
+        "            name=\"sql-warehouse\",\n",
+        "            sql_warehouse=AppResourceSqlWarehouse(\n",
+        "                id=warehouse.id,\n",
+        "                permission=AppResourceSqlWarehouseSqlWarehousePermission.CAN_USE),\n",
+        "        ),\n",
+        "    ],\n",
+        ")\n",
+        "\n",
+        "try:\n",
+        "    existing_app = w.apps.get(APP_NAME)\n",
+        "    print(f\"App {APP_NAME} already exists, updating...\")\n",
+        "    w.apps.update(APP_NAME, app_def)\n",
+        "except Exception:\n",
+        "    w.apps.create(app_def)\n",
+        "\n",
+        "# w.apps.create / w.apps.update return an App dataclass (Google LRO-style),\n",
+        "# not an SDK Wait wrapper — there is no .result().  Poll w.apps.get() until\n",
+        "# the app reaches a healthy state.\n",
+        "import time\n",
+        "\n",
+        "\n",
+        "def _app_state(a):\n",
+        "    cs = getattr(a, \"compute_status\", None)\n",
+        "    s = getattr(cs, \"state\", None) if cs is not None else None\n",
+        "    if s is None:\n",
+        "        s = getattr(a, \"state\", None)\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current = w.apps.get(APP_NAME)\n",
+        "    state = _app_state(current)\n",
+        "    print(f\"App {APP_NAME} state: {state}\")\n",
+        "    if state in (\"ACTIVE\", \"RUNNING\", \"READY\"):\n",
+        "        app_status = current\n",
+        "        break\n",
+        "    if state in (\"ERROR\", \"FAILED\"):\n",
+        "        raise RuntimeError(f\"App {APP_NAME} entered failure state: {state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"App {APP_NAME} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(15)\n",
+        "\n",
+        "add(CATALOG, \"apps\", app_status)\n",
+        "print(f\"App {APP_NAME} ready\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Grants & Postgres Role"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk.service import catalog as cat\n",
+        "\n",
+        "# Grant app permissions to UC catalog/schema/table\n",
+        "w.grants.update(\n",
+        "    full_name=CATALOG,\n",
+        "    securable_type=\"CATALOG\",\n",
+        "    changes=[\n",
+        "        cat.PermissionsChange(\n",
+        "            add=[cat.Privilege.USE_CATALOG],\n",
+        "            principal=app_status.id\n",
+        "        )\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "w.grants.update(\n",
+        "    full_name=f\"{CATALOG}.support\",\n",
+        "    securable_type=\"SCHEMA\",\n",
+        "    changes=[\n",
+        "        cat.PermissionsChange(\n",
+        "            add=[cat.Privilege.USE_SCHEMA],\n",
+        "            principal=app_status.id\n",
+        "        )\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "w.grants.update(\n",
+        "    full_name=f\"{CATALOG}.support.support_agent_reports\",\n",
+        "    securable_type=\"TABLE\",\n",
+        "    changes=[\n",
+        "        cat.PermissionsChange(\n",
+        "            add=[cat.Privilege.SELECT],\n",
+        "            principal=app_status.id\n",
+        "        )\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "print(\"UC grants applied\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "import psycopg2\n\n# Resolve app service principal identities for Postgres grants\napp_principal_ids = []\ntry:\n    app_info = w.apps.get(name=APP_NAME)\n    if app_info.service_principal_client_id:\n        app_principal_ids.append(app_info.service_principal_client_id)\n    if app_info.oauth2_app_client_id:\n        app_principal_ids.append(app_info.oauth2_app_client_id)\n    if app_info.service_principal_name:\n        app_principal_ids.append(app_info.service_principal_name)\n    app_principal_ids = sorted(set(app_principal_ids))\n    print(f\"App principal identities: {app_principal_ids}\")\nexcept Exception as e:\n    print(f\"Warning: could not resolve app principals: {e}\")\n\nif app_principal_ids:\n    creds = w.postgres.generate_database_credential(endpoint=endpoint_name)\n    current_user = w.current_user.me().user_name\n\n    conn = psycopg2.connect(\n        host=endpoint_host,\n        port=5432,\n        dbname=SUPPORT_DB_NAME,\n        user=current_user,\n        password=creds.token,\n        sslmode=\"require\",\n    )\n    conn.autocommit = False\n\n    def quote_ident(identifier):\n        return '\"' + identifier.replace('\"', '\"\"') + '\"'\n\n    with conn.cursor() as cur:\n        cur.execute(\"CREATE EXTENSION IF NOT EXISTS databricks_auth\")\n\n        for principal_id in app_principal_ids:\n            principal = quote_ident(principal_id)\n\n            # Create the Postgres role for this service principal\n            cur.execute(\"SAVEPOINT create_sp_role\")\n            try:\n                cur.execute(\n                    \"SELECT databricks_create_role(%s, 'SERVICE_PRINCIPAL')\",\n                    (principal_id,),\n                )\n            except psycopg2.errors.DuplicateObject:\n                cur.execute(\"ROLLBACK TO SAVEPOINT create_sp_role\")\n            except Exception as role_error:\n                cur.execute(\"ROLLBACK TO SAVEPOINT create_sp_role\")\n                if \"Identity not found\" in str(role_error):\n                    cur.execute(\n                        f\"DO $$ BEGIN CREATE ROLE {principal}; EXCEPTION WHEN duplicate_object THEN NULL; END $$;\"\n                    )\n                else:\n                    raise\n            finally:\n                cur.execute(\"RELEASE SAVEPOINT create_sp_role\")\n\n            # Grant on support schema (OLTP tables + synced tables)\n            cur.execute(f\"GRANT USAGE, CREATE ON SCHEMA support TO {principal}\")\n            cur.execute(f\"GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA support TO {principal}\")\n            cur.execute(f\"GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA support TO {principal}\")\n\n            # Grant on public schema (AppKit persistent cache)\n            cur.execute(f\"GRANT USAGE, CREATE ON SCHEMA public TO {principal}\")\n            cur.execute(f\"GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO {principal}\")\n            cur.execute(f\"GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO {principal}\")\n\n            # Default privileges for future tables/sequences\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA support \"\n                f\"GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA support \"\n                f\"GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA public \"\n                f\"GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA public \"\n                f\"GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO {principal}\"\n            )\n\n            print(f\"Granted permissions to {principal_id}\")\n\n        conn.commit()\n    conn.close()\n    print(\"Postgres grants applied\")\nelse:\n    print(\"Warning: no app principal IDs found, skipping Postgres grants\")",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Deploy"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time\n",
+        "from databricks.sdk.service.apps import AppDeployment\n",
+        "\n",
+        "deployment = w.apps.deploy(\n",
+        "    app_name=app_status.name,\n",
+        "    app_deployment=AppDeployment(\n",
+        "        source_code_path=source_code_path\n",
+        "    )\n",
+        ")\n",
+        "\n",
+        "\n",
+        "def _deploy_state(d):\n",
+        "    st = getattr(d, \"status\", None)\n",
+        "    s = getattr(st, \"state\", None) if st is not None else None\n",
+        "    return getattr(s, \"value\", str(s)) if s is not None else \"\"\n",
+        "\n",
+        "\n",
+        "# w.apps.deploy returns an AppDeployment dataclass (Google LRO-style), not\n",
+        "# an SDK Wait — poll w.apps.get_deployment() until it reaches SUCCEEDED.\n",
+        "deadline = time.time() + 30 * 60\n",
+        "while True:\n",
+        "    current_dep = w.apps.get_deployment(app_name=app_status.name, deployment_id=deployment.deployment_id)\n",
+        "    state = _deploy_state(current_dep)\n",
+        "    print(f\"Deployment state: {state}\")\n",
+        "    if state == \"SUCCEEDED\":\n",
+        "        deployment_status = current_dep\n",
+        "        break\n",
+        "    if state in (\"FAILED\", \"STOPPED\"):\n",
+        "        raise RuntimeError(f\"Deployment failed for {app_status.name}: state={state}\")\n",
+        "    if time.time() > deadline:\n",
+        "        raise TimeoutError(f\"Deployment for {app_status.name} not ready after 30 minutes (last state: {state})\")\n",
+        "    time.sleep(10)\n",
+        "\n",
+        "print(f\"App deployed: {deployment_status}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install databricks-sdk psycopg2-binary --upgrade"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import re\nimport time\nimport sys\n\nsys.path.append('../utils')\nfrom uc_state import add\n\nCATALOG = dbutils.widgets.get(\"CATALOG\")\nSUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")\n\nSUPPORT_LAKEBASE_INSTANCE_NAME = re.sub(r'[^a-z0-9-]', '-', f\"{CATALOG}supportmanager\".lower())\nSUPPORT_DB_NAME = \"databricks_postgres\""
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Lakebase Instance & Database"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.database import DatabaseInstance\n",
-    "from databricks.sdk.errors import NotFound, ResourceDoesNotExist\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "instance_name = SUPPORT_LAKEBASE_INSTANCE_NAME\n",
-    "\n",
-    "try:\n",
-    "    existing = w.database.get_database_instance(instance_name)\n",
-    "    print(f\"Found existing database instance: {existing.name} (state: {existing.state})\")\n",
-    "    instance = existing\n",
-    "except (NotFound, ResourceDoesNotExist):\n",
-    "    print(f\"Creating new database instance: {instance_name}\")\n",
-    "    instance = w.database.create_database_instance(\n",
-    "        DatabaseInstance(\n",
-    "            name=instance_name,\n",
-    "            capacity=\"CU_1\"\n",
-    "        )\n",
-    "    )\n",
-    "    print(f\"Created database instance: {instance.name}\")\n",
-    "    add(CATALOG, \"databaseinstances\", {\"name\": instance.name})\n",
-    "\n",
-    "print(\"Waiting for database instance to be available...\")\n",
-    "for _ in range(60):\n",
-    "    state = str(w.database.get_database_instance(instance_name).state)\n",
-    "    if state == \"DatabaseInstanceState.AVAILABLE\":\n",
-    "        print(f\"Instance ready: {state}\")\n",
-    "        break\n",
-    "    time.sleep(10)\n",
-    "else:\n",
-    "    raise TimeoutError(f\"Database instance {instance_name} did not become available within 10 minutes\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk.service.database import DatabaseCatalog\n\ncatalog_name = SUPPORT_LAKEBASE_INSTANCE_NAME\n\ntry:\n    existing_cat = w.catalogs.get(catalog_name)\n    print(f\"Found existing catalog: {existing_cat.name}\")\nexcept Exception:\n    catalog = w.database.create_database_catalog(\n        DatabaseCatalog(\n            name=catalog_name,\n            database_instance_name=SUPPORT_LAKEBASE_INSTANCE_NAME,\n            database_name=SUPPORT_DB_NAME,\n            create_database_if_not_exists=True\n        )\n    )\n    print(f\"Created new database and catalog: {catalog.name}\")\n    add(CATALOG, \"databasecatalogs\", catalog)"
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Synced Table"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk.service.database import SyncedDatabaseTable, SyncedTableSpec, NewPipelineSpec, SyncedTableSchedulingPolicy\n\nsynced_table_name = f\"{CATALOG}.support.support_agent_reports_sync\"\n\ntry:\n    existing_table = w.tables.get(synced_table_name)\n    print(f\"Found existing synced table: {existing_table.full_name}\")\nexcept Exception:\n    synced_table = w.database.create_synced_database_table(\n        SyncedDatabaseTable(\n            name=synced_table_name,\n            database_instance_name=instance_name,\n            logical_database_name=SUPPORT_DB_NAME,\n            spec=SyncedTableSpec(\n                source_table_full_name=f\"{CATALOG}.support.support_agent_reports\",\n                primary_key_columns=[\"support_request_id\"],\n                scheduling_policy=SyncedTableSchedulingPolicy.CONTINUOUS,\n                create_database_objects_if_missing=True,\n                new_pipeline_spec=NewPipelineSpec(\n                    storage_catalog=\"storage_catalog\",\n                    storage_schema=\"storage_schema\"\n                )\n            ),\n        )\n    )\n    print(f\"Created synced table: {synced_table.name}\")\n    add(CATALOG, \"pipelines\", synced_table.data_synchronization_status)"
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### OLTP Tables (Postgres)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import psycopg2\n\n# Resolve the Postgres endpoint via the new Postgres API\nPROJECT = f\"projects/{SUPPORT_LAKEBASE_INSTANCE_NAME}\"\nbranches = list(w.postgres.list_branches(PROJECT))\ndefault_branch = next((b for b in branches if getattr(getattr(b, \"status\", None), \"default\", False)), branches[0])\nbranch_name = default_branch.name\n\nendpoints = list(w.postgres.list_endpoints(parent=branch_name))\nif not endpoints:\n    for _ in range(12):\n        time.sleep(5)\n        endpoints = list(w.postgres.list_endpoints(parent=branch_name))\n        if endpoints:\n            break\n    if not endpoints:\n        raise RuntimeError(\"No Lakebase endpoint found\")\n\nendpoint = next((e for e in endpoints if str(getattr(getattr(e, \"status\", None), \"endpoint_type\", \"\")).endswith(\"READ_WRITE\")), endpoints[0])\nendpoint_name = endpoint.name\nendpoint_host = endpoint.status.hosts.host\n\nprint(f\"Branch: {branch_name}\")\nprint(f\"Endpoint: {endpoint_name}\")\nprint(f\"Host: {endpoint_host}\")\n\n# Connect and create OLTP tables\ncreds = w.postgres.generate_database_credential(endpoint=endpoint_name)\ncurrent_user = w.current_user.me().user_name\n\nconn = psycopg2.connect(\n    host=endpoint_host,\n    port=5432,\n    dbname=SUPPORT_DB_NAME,\n    user=current_user,\n    password=creds.token,\n    sslmode=\"require\",\n)\nconn.autocommit = False\n\nwith conn.cursor() as cur:\n    cur.execute(\"CREATE SCHEMA IF NOT EXISTS support\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.operator_actions (\n          action_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          action_type TEXT NOT NULL CHECK (action_type IN ('apply_refund','apply_credit','send_reply')),\n          amount_usd NUMERIC(10,2),\n          payload JSONB,\n          status TEXT NOT NULL DEFAULT 'recorded',\n          actor TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.support_replies (\n          reply_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          message_text TEXT NOT NULL,\n          sent_by TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.request_status (\n          support_request_id TEXT PRIMARY KEY,\n          status TEXT NOT NULL DEFAULT 'pending',\n          assigned_to TEXT,\n          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n          last_action TEXT,\n          notes TEXT\n        )\n    \"\"\")\n\n    cur.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS support.response_ratings (\n          rating_id BIGSERIAL PRIMARY KEY,\n          support_request_id TEXT NOT NULL,\n          order_id TEXT NOT NULL,\n          user_id TEXT,\n          rating TEXT NOT NULL CHECK (rating IN ('thumbs_up','thumbs_down')),\n          reason_code TEXT,\n          feedback_notes TEXT,\n          actor TEXT,\n          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n          UNIQUE (support_request_id)\n        )\n    \"\"\")\n\n    conn.commit()\n\nconn.close()\nprint(\"OLTP tables created\")"
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Warehouse"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "WAREHOUSE_NAME = f\"{CATALOG}-warehouse\"\n",
-    "existing_wh = [wh for wh in w.warehouses.list() if wh.name == WAREHOUSE_NAME]\n",
-    "if existing_wh:\n",
-    "    warehouse = existing_wh[0]\n",
-    "    print(f\"Using existing warehouse: {warehouse.id}\")\n",
-    "else:\n",
-    "    warehouse = w.warehouses.create(\n",
-    "        name=WAREHOUSE_NAME,\n",
-    "        cluster_size=\"2X-Small\",\n",
-    "        max_num_clusters=1,\n",
-    "        min_num_clusters=1,\n",
-    "        enable_serverless_compute=True,\n",
-    "    ).result()\n",
-    "    add(CATALOG, \"warehouses\", warehouse)\n",
-    "    print(f\"Created warehouse: {warehouse.id}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### App Deployment"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import os\n\n# Write app.yaml with computed values\napp_yaml_contents = f\"\"\"command: ['npm', 'run', 'start']\nenv:\n  - name: PGPORT\n    value: '5432'\n  - name: PGDATABASE\n    value: '{SUPPORT_DB_NAME}'\n  - name: PGSSLMODE\n    value: 'require'\n  - name: LAKEBASE_ENDPOINT\n    value: '{endpoint_name}'\n  - name: DATABRICKS_WAREHOUSE_ID\n    value: '{warehouse.id}'\n  - name: SUPPORT_AGENT_ENDPOINT_NAME\n    value: '{SUPPORT_AGENT_ENDPOINT_NAME}'\n\"\"\"\n\napp_yaml_path = os.path.abspath(\"../apps/supportconsolek/supportconsolek/app.yaml\")\nif os.path.exists(app_yaml_path):\n    os.remove(app_yaml_path)\n\ntime.sleep(3)\n\nwith open(app_yaml_path, \"w\") as f:\n    f.write(app_yaml_contents)\n\nprint(f\"Wrote app.yaml with warehouse={warehouse.id}, endpoint={endpoint_name}\")"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "from databricks.sdk.service.apps import App, AppResource, AppResourceSqlWarehouse\nfrom databricks.sdk.service.apps import AppResourceSqlWarehouseSqlWarehousePermission\n\nsource_code_path = os.path.abspath(\"../apps/supportconsolek/supportconsolek\")\nAPP_NAME = \"supportconsole\"\n\napp_def = App(\n    name=APP_NAME,\n    default_source_code_path=source_code_path,\n    resources=[\n        AppResource(\n            name=\"sql-warehouse\",\n            sql_warehouse=AppResourceSqlWarehouse(\n                id=warehouse.id,\n                permission=AppResourceSqlWarehouseSqlWarehousePermission.CAN_USE),\n        ),\n    ],\n)\n\ntry:\n    existing_app = w.apps.get(APP_NAME)\n    print(f\"App {APP_NAME} already exists, updating...\")\n    app = w.apps.update(APP_NAME, app_def)\nexcept Exception:\n    app = w.apps.create(app_def)\n\napp_status = app.result()\nadd(CATALOG, \"apps\", app_status)\nprint(f\"App {APP_NAME} ready\")"
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Grants & Postgres Role"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk.service import catalog as cat\n",
-    "\n",
-    "# Grant app permissions to UC catalog/schema/table\n",
-    "w.grants.update(\n",
-    "    full_name=CATALOG,\n",
-    "    securable_type=\"CATALOG\",\n",
-    "    changes=[\n",
-    "        cat.PermissionsChange(\n",
-    "            add=[cat.Privilege.USE_CATALOG],\n",
-    "            principal=app_status.id\n",
-    "        )\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "w.grants.update(\n",
-    "    full_name=f\"{CATALOG}.support\",\n",
-    "    securable_type=\"SCHEMA\",\n",
-    "    changes=[\n",
-    "        cat.PermissionsChange(\n",
-    "            add=[cat.Privilege.USE_SCHEMA],\n",
-    "            principal=app_status.id\n",
-    "        )\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "w.grants.update(\n",
-    "    full_name=f\"{CATALOG}.support.support_agent_reports\",\n",
-    "    securable_type=\"TABLE\",\n",
-    "    changes=[\n",
-    "        cat.PermissionsChange(\n",
-    "            add=[cat.Privilege.SELECT],\n",
-    "            principal=app_status.id\n",
-    "        )\n",
-    "    ]\n",
-    ")\n",
-    "\n",
-    "print(\"UC grants applied\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "import psycopg2\n\n# Resolve app service principal identities for Postgres grants\napp_principal_ids = []\ntry:\n    app_info = w.apps.get(name=APP_NAME)\n    if app_info.service_principal_client_id:\n        app_principal_ids.append(app_info.service_principal_client_id)\n    if app_info.oauth2_app_client_id:\n        app_principal_ids.append(app_info.oauth2_app_client_id)\n    if app_info.service_principal_name:\n        app_principal_ids.append(app_info.service_principal_name)\n    app_principal_ids = sorted(set(app_principal_ids))\n    print(f\"App principal identities: {app_principal_ids}\")\nexcept Exception as e:\n    print(f\"Warning: could not resolve app principals: {e}\")\n\nif app_principal_ids:\n    creds = w.postgres.generate_database_credential(endpoint=endpoint_name)\n    current_user = w.current_user.me().user_name\n\n    conn = psycopg2.connect(\n        host=endpoint_host,\n        port=5432,\n        dbname=SUPPORT_DB_NAME,\n        user=current_user,\n        password=creds.token,\n        sslmode=\"require\",\n    )\n    conn.autocommit = False\n\n    def quote_ident(identifier):\n        return '\"' + identifier.replace('\"', '\"\"') + '\"'\n\n    with conn.cursor() as cur:\n        cur.execute(\"CREATE EXTENSION IF NOT EXISTS databricks_auth\")\n\n        for principal_id in app_principal_ids:\n            principal = quote_ident(principal_id)\n\n            # Create the Postgres role for this service principal\n            cur.execute(\"SAVEPOINT create_sp_role\")\n            try:\n                cur.execute(\n                    \"SELECT databricks_create_role(%s, 'SERVICE_PRINCIPAL')\",\n                    (principal_id,),\n                )\n            except psycopg2.errors.DuplicateObject:\n                cur.execute(\"ROLLBACK TO SAVEPOINT create_sp_role\")\n            except Exception as role_error:\n                cur.execute(\"ROLLBACK TO SAVEPOINT create_sp_role\")\n                if \"Identity not found\" in str(role_error):\n                    cur.execute(\n                        f\"DO $$ BEGIN CREATE ROLE {principal}; EXCEPTION WHEN duplicate_object THEN NULL; END $$;\"\n                    )\n                else:\n                    raise\n            finally:\n                cur.execute(\"RELEASE SAVEPOINT create_sp_role\")\n\n            # Grant on support schema (OLTP tables + synced tables)\n            cur.execute(f\"GRANT USAGE, CREATE ON SCHEMA support TO {principal}\")\n            cur.execute(f\"GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA support TO {principal}\")\n            cur.execute(f\"GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA support TO {principal}\")\n\n            # Grant on public schema (AppKit persistent cache)\n            cur.execute(f\"GRANT USAGE, CREATE ON SCHEMA public TO {principal}\")\n            cur.execute(f\"GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO {principal}\")\n            cur.execute(f\"GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO {principal}\")\n\n            # Default privileges for future tables/sequences\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA support \"\n                f\"GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA support \"\n                f\"GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA public \"\n                f\"GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO {principal}\"\n            )\n            cur.execute(\n                f\"ALTER DEFAULT PRIVILEGES IN SCHEMA public \"\n                f\"GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO {principal}\"\n            )\n\n            print(f\"Granted permissions to {principal_id}\")\n\n        conn.commit()\n    conn.close()\n    print(\"Postgres grants applied\")\nelse:\n    print(\"Warning: no app principal IDs found, skipping Postgres grants\")"
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Deploy"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk.service.apps import AppDeployment\n",
-    "\n",
-    "deployment = w.apps.deploy(\n",
-    "    app_name=app_status.name,\n",
-    "    app_deployment=AppDeployment(\n",
-    "        source_code_path=source_code_path\n",
-    "    )\n",
-    ")\n",
-    "deployment_status = deployment.result()\n",
-    "print(f\"App deployed: {deployment_status}\")"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/stages/support_request_agent.ipynb b/stages/support_request_agent.ipynb
index e7d9931..747aefa 100644
--- a/stages/support_request_agent.ipynb
+++ b/stages/support_request_agent.ipynb
@@ -1,675 +1,731 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Support Request Agent\n",
-    "\n",
-    "Build and deploy a support-request triage agent with order context and user interaction history.\n",
-    "\n",
-    "Outputs include:\n",
-    "- credit recommendation\n",
-    "- refund recommendation\n",
-    "- draft customer response\n",
-    "- past interactions summary\n",
-    "- order details summary"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Support Request Agent\n",
+        "\n",
+        "Build and deploy a support-request triage agent with order context and user interaction history.\n",
+        "\n",
+        "Outputs include:\n",
+        "- credit recommendation\n",
+        "- refund recommendation\n",
+        "- draft customer response\n",
+        "- past interactions summary\n",
+        "- order details summary"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Tool & View Registration"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
+        "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.ai;\n",
+        "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.support;"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "%sql\n-- Stub tables so UC functions that reference them can be created.\n-- Downstream jobs use CREATE TABLE IF NOT EXISTS with the same schema — no-op if already exists.\n\nCREATE TABLE IF NOT EXISTS ${CATALOG}.support.raw_support_requests (\n  support_request_id STRING,\n  user_id STRING,\n  order_id STRING,\n  ts TIMESTAMP,\n  request_type STRING,\n  request_text STRING,\n  edge_case_type STRING,\n  request_attempt INT,\n  generated_by STRING\n);\n\nCREATE TABLE IF NOT EXISTS ${CATALOG}.support.support_agent_reports (\n  support_request_id STRING,\n  user_id STRING,\n  order_id STRING,\n  request_text STRING,\n  ts TIMESTAMP,\n  agent_response STRING\n);",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": "%sql\n-- Namespaced as `support_get_order_overview` so it does not clobber\n-- `${CATALOG}.ai.get_order_overview` from the complaint agent, which has a different\n-- column list (6 vs 5) and would silently win/lose the CREATE OR REPLACE race when\n-- the support target shares a catalog with the complaints target.\nCREATE OR REPLACE FUNCTION ${CATALOG}.ai.support_get_order_overview(oid STRING)\nRETURNS TABLE (\n  order_id STRING,\n  location STRING,\n  items_json STRING,\n  customer_address STRING,\n  order_created_ts TIMESTAMP\n)\nRETURN\n  SELECT\n    ae.order_id,\n    loc.name AS location,\n    get_json_object(ae.body, '$.items') AS items_json,\n    get_json_object(ae.body, '$.customer_addr') AS customer_address,\n    try_to_timestamp(ae.ts) AS order_created_ts\n  FROM ${CATALOG}.lakeflow.all_events ae\n  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n  WHERE ae.order_id = oid AND ae.event_type = 'order_created'\n  LIMIT 1",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "-- Namespaced as `support_get_order_timing` so it does not clobber\n",
+        "-- `${CATALOG}.ai.get_order_timing` from the complaint agent (5 cols incl.\n",
+        "-- delivery_status vs the 4 cols below).  See note on support_get_order_overview.\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.support_get_order_timing(oid STRING)\n",
+        "RETURNS TABLE (\n",
+        "  order_id STRING,\n",
+        "  order_created_ts TIMESTAMP,\n",
+        "  delivered_ts TIMESTAMP,\n",
+        "  delivery_duration_minutes FLOAT\n",
+        ")\n",
+        "RETURN\n",
+        "  WITH order_events AS (\n",
+        "    SELECT order_id, event_type, try_to_timestamp(ts) AS event_ts\n",
+        "    FROM ${CATALOG}.lakeflow.all_events\n",
+        "    WHERE order_id = oid\n",
+        "  )\n",
+        "  SELECT\n",
+        "    order_id,\n",
+        "    MIN(CASE WHEN event_type='order_created' THEN event_ts END) AS order_created_ts,\n",
+        "    MAX(CASE WHEN event_type='delivered' THEN event_ts END) AS delivered_ts,\n",
+        "    CAST((UNIX_TIMESTAMP(MAX(CASE WHEN event_type='delivered' THEN event_ts END)) - UNIX_TIMESTAMP(MIN(CASE WHEN event_type='order_created' THEN event_ts END))) / 60 AS FLOAT) AS delivery_duration_minutes\n",
+        "  FROM order_events\n",
+        "  GROUP BY order_id"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_user_support_history(uid STRING)\n",
+        "RETURNS TABLE (\n",
+        "  support_request_id STRING,\n",
+        "  order_id STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  request_text STRING,\n",
+        "  agent_response STRING\n",
+        ")\n",
+        "RETURN\n",
+        "  SELECT support_request_id, order_id, ts, request_text, agent_response\n",
+        "  FROM ${CATALOG}.support.support_agent_reports\n",
+        "  WHERE user_id = uid\n",
+        "  ORDER BY ts DESC\n",
+        "  LIMIT 10"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_user_request_history(uid STRING)\n",
+        "RETURNS TABLE (\n",
+        "  support_request_id STRING,\n",
+        "  order_id STRING,\n",
+        "  ts TIMESTAMP,\n",
+        "  request_type STRING,\n",
+        "  edge_case_type STRING,\n",
+        "  request_text STRING\n",
+        ")\n",
+        "RETURN\n",
+        "  SELECT support_request_id, order_id, ts, request_type, edge_case_type, request_text\n",
+        "  FROM ${CATALOG}.support.raw_support_requests\n",
+        "  WHERE user_id = uid\n",
+        "  ORDER BY ts DESC\n",
+        "  LIMIT 10"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%sql\n",
+        "-- Grant catalog/schema/function privileges so the serving endpoint's\n",
+        "-- auto-generated SP can resolve UC functions at model-load time.  USE CATALOG\n",
+        "-- is normally granted by the root data stage (canonical_data/raw_data) but is\n",
+        "-- repeated here so this stage is self-sufficient.  Without these grants the\n",
+        "-- first deploy of a brand-new agent endpoint fails with\n",
+        "-- `Permission denied: User does not have EXECUTE on Routine`.\n",
+        "GRANT USE CATALOG ON CATALOG ${CATALOG} TO `account users`;\n",
+        "GRANT USE SCHEMA ON SCHEMA ${CATALOG}.ai TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.support_get_order_overview  TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.support_get_order_timing    TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_user_support_history    TO `account users`;\n",
+        "GRANT EXECUTE ON FUNCTION ${CATALOG}.ai.get_user_request_history    TO `account users`;"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Model"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install -U -qqqq typing_extensions dspy-ai mlflow unitycatalog-openai[databricks] openai databricks-sdk databricks-agents pydantic\n",
+        "%restart_python"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
+        "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "import sys\n",
+        "\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "dev_experiment = mlflow.set_experiment(f\"/Shared/{CATALOG}_support_agent_dev\")\n",
+        "add(CATALOG, \"experiments\", {\"experiment_id\": dev_experiment.experiment_id, \"name\": dev_experiment.name})\n",
+        "print(f\"Using dev experiment: {dev_experiment.name} (ID: {dev_experiment.experiment_id})\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import re\n",
+        "from IPython.core.magic import register_cell_magic\n",
+        "\n",
+        "@register_cell_magic\n",
+        "def writefilev(line, cell):\n",
+        "    \"\"\"\n",
+        "    %%writefilev file.py\n",
+        "    Allows {{var}} substitutions while leaving normal {} intact.\n",
+        "    \"\"\"\n",
+        "    filename = line.strip()\n",
+        "\n",
+        "    def replacer(match):\n",
+        "        expr = match.group(1)\n",
+        "        return str(eval(expr, globals(), locals()))\n",
+        "\n",
+        "    content = re.sub(r\"\\{\\{(.*?)\\}\\}\", replacer, cell)\n",
+        "\n",
+        "    with open(filename, \"w\") as f:\n",
+        "        f.write(content)\n",
+        "    print(f\"Wrote file with substitutions: {filename}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%%writefilev agent.py\n",
+        "import json\n",
+        "import re\n",
+        "import warnings\n",
+        "from typing import Any, Dict, Literal, Optional\n",
+        "from uuid import uuid4\n",
+        "\n",
+        "import dspy\n",
+        "import mlflow\n",
+        "from mlflow.pyfunc import ResponsesAgent\n",
+        "from mlflow.types.responses import ResponsesAgentRequest, ResponsesAgentResponse\n",
+        "from pydantic import BaseModel, Field\n",
+        "from unitycatalog.ai.core.base import get_uc_function_client\n",
+        "\n",
+        "warnings.filterwarnings(\"ignore\", message=\".*Ignoring the default notebook Spark session.*\")\n",
+        "\n",
+        "mlflow.dspy.autolog(log_traces=True)\n",
+        "\n",
+        "LLM_MODEL = \"{{LLM_MODEL}}\"\n",
+        "CATALOG = \"{{CATALOG}}\"\n",
+        "\n",
+        "lm = dspy.LM(f\"databricks/{LLM_MODEL}\", max_tokens=2000, num_retries=20)\n",
+        "dspy.configure(lm=lm)\n",
+        "uc_client = get_uc_function_client()\n",
+        "\n",
+        "\n",
+        "class SupportReport(BaseModel):\n",
+        "    support_request_id: str\n",
+        "    user_id: str\n",
+        "    order_id: str\n",
+        "    credit_recommendation: Optional[dict] = None\n",
+        "    refund_recommendation: Optional[dict] = None\n",
+        "    draft_response: str\n",
+        "    past_interactions_summary: str\n",
+        "    order_details_summary: str\n",
+        "    decision_confidence: Literal[\"high\", \"medium\", \"low\"] = Field(default=\"medium\")\n",
+        "    escalation_flag: bool = Field(default=False)\n",
+        "\n",
+        "\n",
+        "class SupportTriage(dspy.Signature):\n",
+        "    \"\"\"Produce a final support resolution report using full context.\n",
+        "\n",
+        "    Required inputs to reason over:\n",
+        "    - support request text and edge-case metadata\n",
+        "    - order details and delivery timing\n",
+        "    - prior support history for this user\n",
+        "\n",
+        "    Decision policy:\n",
+        "    - Severe repeat/high-risk issue: provide concrete refund + credit and apology.\n",
+        "    - Moderate issue: provide bounded partial refund and/or credit with rationale.\n",
+        "    - Minor/non-compensable issue: typically no refund, small goodwill credit or clear denial.\n",
+        "    - Spam/abusive patterns: avoid excessive compensation, set escalation_flag=true.\n",
+        "\n",
+        "    Never return placeholder text like \"we will look into this\".\n",
+        "    Always return a final customer-ready message with concrete next steps.\n",
+        "    \"\"\"\n",
+        "\n",
+        "    support_request: str = dspy.InputField(desc=\"Structured case payload JSON string\")\n",
+        "    support_request_id: str = dspy.OutputField()\n",
+        "    user_id: str = dspy.OutputField()\n",
+        "    order_id: str = dspy.OutputField()\n",
+        "    credit_recommendation_json: str = dspy.OutputField(desc=\"JSON object with amount_usd/reason\")\n",
+        "    refund_recommendation_json: str = dspy.OutputField(desc=\"JSON object with amount_usd/reason\")\n",
+        "    draft_response: str = dspy.OutputField()\n",
+        "    past_interactions_summary: str = dspy.OutputField()\n",
+        "    order_details_summary: str = dspy.OutputField()\n",
+        "    decision_confidence: str = dspy.OutputField(desc=\"high, medium, low\")\n",
+        "    escalation_flag: str = dspy.OutputField(desc=\"true or false\")\n",
+        "\n",
+        "\n",
+        "def get_order_overview(order_id: str) -> str:\n",
+        "    return str(uc_client.execute_function(f\"{CATALOG}.ai.support_get_order_overview\", {\"oid\": order_id}).value)\n",
+        "\n",
+        "\n",
+        "def get_order_timing(order_id: str) -> str:\n",
+        "    return str(uc_client.execute_function(f\"{CATALOG}.ai.support_get_order_timing\", {\"oid\": order_id}).value)\n",
+        "\n",
+        "\n",
+        "def get_user_support_history(user_id: str) -> str:\n",
+        "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_user_support_history\", {\"uid\": user_id}).value)\n",
+        "\n",
+        "\n",
+        "def get_user_request_history(user_id: str) -> str:\n",
+        "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_user_request_history\", {\"uid\": user_id}).value)\n",
+        "\n",
+        "\n",
+        "def _parse_case_payload(raw: str) -> Dict[str, Any]:\n",
+        "    try:\n",
+        "        payload = json.loads(raw)\n",
+        "        return payload if isinstance(payload, dict) else {}\n",
+        "    except Exception:\n",
+        "        parsed: Dict[str, Any] = {}\n",
+        "        for key in [\"support_request_id\", \"user_id\", \"order_id\", \"text\"]:\n",
+        "            match = re.search(rf\"{key}=([^\\s]+)\", raw)\n",
+        "            if match:\n",
+        "                parsed[key] = match.group(1)\n",
+        "        if \"text\" in parsed:\n",
+        "            parsed[\"request_text\"] = parsed[\"text\"]\n",
+        "        return parsed\n",
+        "\n",
+        "\n",
+        "def _safe_float(value: Any, default: float = 0.0) -> float:\n",
+        "    try:\n",
+        "        return float(value)\n",
+        "    except Exception:\n",
+        "        return default\n",
+        "\n",
+        "\n",
+        "def _safe_int(value: Any, default: int = 0) -> int:\n",
+        "    try:\n",
+        "        return int(value)\n",
+        "    except Exception:\n",
+        "        return default\n",
+        "\n",
+        "\n",
+        "def _compute_policy_resolution(payload: Dict[str, Any]) -> Dict[str, Any]:\n",
+        "    request_text = str(payload.get(\"request_text\", \"\"))\n",
+        "    edge_case_type = str(payload.get(\"edge_case_type\", \"standard\"))\n",
+        "\n",
+        "    repeat_count = _safe_int(payload.get(\"repeat_complaints_30d\"), 0)\n",
+        "    risk_score = _safe_float(payload.get(\"risk_score\"), 0.25)\n",
+        "    policy_limit = max(0.0, _safe_float(payload.get(\"policy_limit_usd\"), 20.0))\n",
+        "\n",
+        "    text_lower = request_text.lower()\n",
+        "    mentions_missing = \"missing\" in text_lower\n",
+        "    mentions_delay = \"late\" in text_lower or \"delay\" in text_lower\n",
+        "    abusive = edge_case_type == \"abusive_language\"\n",
+        "    spammy = edge_case_type == \"spammy_escalation\"\n",
+        "\n",
+        "    if abusive or (spammy and repeat_count >= 4 and risk_score < 0.4):\n",
+        "        refund_amount = 0.0\n",
+        "        credit_amount = min(3.0, policy_limit)\n",
+        "        escalation = True\n",
+        "        confidence = \"medium\"\n",
+        "        reason = \"Abusive/spammy pattern detected; restricted compensation with escalation.\"\n",
+        "    elif repeat_count >= 2 or risk_score >= 0.75 or (mentions_missing and mentions_delay):\n",
+        "        refund_amount = round(min(policy_limit, max(policy_limit * 0.9, 15.0)), 2)\n",
+        "        credit_amount = round(min(10.0, max(5.0, policy_limit * 0.25)), 2)\n",
+        "        escalation = False\n",
+        "        confidence = \"high\"\n",
+        "        reason = \"Repeated or high-risk service failure.\"\n",
+        "    elif repeat_count == 1 or risk_score >= 0.45 or mentions_missing or mentions_delay:\n",
+        "        refund_amount = round(min(policy_limit, max(policy_limit * 0.5, 6.0)), 2)\n",
+        "        credit_amount = round(min(7.0, max(3.0, policy_limit * 0.15)), 2)\n",
+        "        escalation = False\n",
+        "        confidence = \"high\"\n",
+        "        reason = \"Moderate service issue with customer impact.\"\n",
+        "    else:\n",
+        "        refund_amount = 0.0\n",
+        "        credit_amount = round(min(5.0, max(2.0, policy_limit * 0.1)), 2)\n",
+        "        escalation = False\n",
+        "        confidence = \"medium\"\n",
+        "        reason = \"Minor issue or low-confidence compensable case.\"\n",
+        "\n",
+        "    return {\n",
+        "        \"refund_amount\": refund_amount,\n",
+        "        \"credit_amount\": credit_amount,\n",
+        "        \"escalation\": escalation,\n",
+        "        \"confidence\": confidence,\n",
+        "        \"reason\": reason,\n",
+        "        \"repeat_count\": repeat_count,\n",
+        "    }\n",
+        "\n",
+        "\n",
+        "def _ordinal(value: int) -> str:\n",
+        "    if 10 <= value % 100 <= 20:\n",
+        "        suffix = \"th\"\n",
+        "    else:\n",
+        "        suffix = {1: \"st\", 2: \"nd\", 3: \"rd\"}.get(value % 10, \"th\")\n",
+        "    return f\"{value}{suffix}\"\n",
+        "\n",
+        "\n",
+        "def _compose_customer_message(payload: Dict[str, Any], policy: Dict[str, Any]) -> str:\n",
+        "    request_text = str(payload.get(\"request_text\", \"\")).strip()\n",
+        "    repeat_count = policy[\"repeat_count\"]\n",
+        "    refund_amount = policy[\"refund_amount\"]\n",
+        "    credit_amount = policy[\"credit_amount\"]\n",
+        "\n",
+        "    lead = \"Thanks for contacting us, and I am really sorry about this experience.\"\n",
+        "    if repeat_count >= 2:\n",
+        "        lead = (\n",
+        "            f\"I see this is at least the {_ordinal(repeat_count)} time you've had to contact us for similar issues, \"\n",
+        "            \"and that is not acceptable.\"\n",
+        "        )\n",
+        "\n",
+        "    resolution_parts = []\n",
+        "    if refund_amount > 0:\n",
+        "        resolution_parts.append(f\"a ${refund_amount:.2f} refund\")\n",
+        "    if credit_amount > 0:\n",
+        "        resolution_parts.append(f\"a ${credit_amount:.2f} credit\")\n",
+        "\n",
+        "    if resolution_parts:\n",
+        "        resolution = \"We are offering \" + \" and \".join(resolution_parts) + \" on this case.\"\n",
+        "    else:\n",
+        "        resolution = \"We are escalating this case for manual review and will follow up quickly.\"\n",
+        "\n",
+        "    context_line = f\"Issue noted: {request_text}\" if request_text else \"Issue noted from your support ticket.\"\n",
+        "\n",
+        "    return f\"{lead} {resolution} {context_line}\"\n",
+        "\n",
+        "\n",
+        "class SupportModule(dspy.Module):\n",
+        "    def __init__(self):\n",
+        "        super().__init__()\n",
+        "        self.react = dspy.ReAct(\n",
+        "            signature=SupportTriage,\n",
+        "            tools=[\n",
+        "                get_order_overview,\n",
+        "                get_order_timing,\n",
+        "                get_user_support_history,\n",
+        "                get_user_request_history,\n",
+        "            ],\n",
+        "            max_iters=10,\n",
+        "        )\n",
+        "\n",
+        "    def forward(self, support_request: str) -> SupportReport:\n",
+        "        payload = _parse_case_payload(support_request)\n",
+        "        result = self.react(support_request=support_request)\n",
+        "\n",
+        "        policy = _compute_policy_resolution(payload)\n",
+        "        final_message = _compose_customer_message(payload, policy)\n",
+        "\n",
+        "        credit_recommendation = {\n",
+        "            \"amount_usd\": policy[\"credit_amount\"],\n",
+        "            \"reason\": policy[\"reason\"],\n",
+        "        }\n",
+        "        refund_recommendation = {\n",
+        "            \"amount_usd\": policy[\"refund_amount\"],\n",
+        "            \"reason\": policy[\"reason\"],\n",
+        "        }\n",
+        "\n",
+        "        return SupportReport(\n",
+        "            support_request_id=str(payload.get(\"support_request_id\") or result.support_request_id),\n",
+        "            user_id=str(payload.get(\"user_id\") or result.user_id),\n",
+        "            order_id=str(payload.get(\"order_id\") or result.order_id),\n",
+        "            credit_recommendation=credit_recommendation,\n",
+        "            refund_recommendation=refund_recommendation,\n",
+        "            draft_response=final_message,\n",
+        "            past_interactions_summary=str(result.past_interactions_summary),\n",
+        "            order_details_summary=str(result.order_details_summary),\n",
+        "            decision_confidence=policy[\"confidence\"],\n",
+        "            escalation_flag=bool(policy[\"escalation\"]),\n",
+        "        )\n",
+        "\n",
+        "\n",
+        "class DSPySupportAgent(ResponsesAgent):\n",
+        "    def __init__(self):\n",
+        "        self.module = SupportModule()\n",
+        "\n",
+        "    def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:\n",
+        "        user_message = None\n",
+        "        for msg in request.input:\n",
+        "            msg_dict = msg.model_dump() if hasattr(msg, \"model_dump\") else msg\n",
+        "            if msg_dict.get(\"role\") == \"user\":\n",
+        "                user_message = msg_dict.get(\"content\", \"\")\n",
+        "                break\n",
+        "        if not user_message:\n",
+        "            raise ValueError(\"No user message found\")\n",
+        "\n",
+        "        result = self.module(support_request=user_message)\n",
+        "        return ResponsesAgentResponse(\n",
+        "            output=[self.create_text_output_item(text=result.model_dump_json(), id=str(uuid4()))],\n",
+        "            custom_outputs=request.custom_inputs,\n",
+        "        )\n",
+        "\n",
+        "\n",
+        "AGENT = DSPySupportAgent()\n",
+        "mlflow.models.set_model(AGENT)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import time\n",
+        "\n",
+        "sample_order_id = None\n",
+        "for attempt in range(12):\n",
+        "    rows = spark.sql(f\"\"\"\n",
+        "        SELECT order_id \n",
+        "        FROM {CATALOG}.lakeflow.all_events \n",
+        "        WHERE event_type='delivered'\n",
+        "        LIMIT 1\n",
+        "    \"\"\").collect()\n",
+        "    if rows:\n",
+        "        sample_order_id = rows[0]['order_id']\n",
+        "        break\n",
+        "    print(f\"No delivered events yet (attempt {attempt+1}/12). Waiting 30s for pipeline data...\")\n",
+        "    time.sleep(30)\n",
+        "\n",
+        "if not sample_order_id:\n",
+        "    raise RuntimeError(\n",
+        "        f\"No delivered events found in {CATALOG}.lakeflow.all_events after 6 minutes. \"\n",
+        "        \"Ensure the Canonical_Data and Lakeflow pipeline stages completed and processed data.\"\n",
+        "    )\n",
+        "\n",
+        "print(f\"Sample order_id: {sample_order_id}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "import mlflow\n",
+        "from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint\n",
+        "from pkg_resources import get_distribution\n",
+        "\n",
+        "payload = {\n",
+        "    \"support_request_id\": \"sample-1\",\n",
+        "    \"user_id\": \"user-001\",\n",
+        "    \"order_id\": sample_order_id,\n",
+        "    \"request_type\": \"missing_items\",\n",
+        "    \"edge_case_type\": \"standard\",\n",
+        "    \"request_text\": \"My order was missing one or more items. Please review and advise next steps.\",\n",
+        "}\n",
+        "\n",
+        "resources = [DatabricksServingEndpoint(endpoint_name=LLM_MODEL)]\n",
+        "for fn in [\n",
+        "    f\"{CATALOG}.ai.support_get_order_overview\",\n",
+        "    f\"{CATALOG}.ai.support_get_order_timing\",\n",
+        "    f\"{CATALOG}.ai.get_user_support_history\",\n",
+        "    f\"{CATALOG}.ai.get_user_request_history\",\n",
+        "]:\n",
+        "    resources.append(DatabricksFunction(function_name=fn))\n",
+        "\n",
+        "input_example = {\"input\": [{\"role\": \"user\", \"content\": json.dumps(payload)}]}\n",
+        "\n",
+        "conda_env = {\n",
+        "    \"channels\": [\"conda-forge\"],\n",
+        "    \"dependencies\": [\n",
+        "        \"python=3.11\",\n",
+        "        \"pip\",\n",
+        "        {\n",
+        "            \"pip\": [\n",
+        "                \"mlflow==3.6\",\n",
+        "                f\"typing_extensions=={get_distribution('typing_extensions').version}\",\n",
+        "                f\"dspy-ai=={get_distribution('dspy-ai').version}\",\n",
+        "                f\"unitycatalog-openai[databricks]=={get_distribution('unitycatalog-openai').version}\",\n",
+        "                f\"pydantic=={get_distribution('pydantic').version}\",\n",
+        "            ]\n",
+        "        }\n",
+        "    ],\n",
+        "    \"name\": \"mlflow-env\"\n",
+        "}\n",
+        "\n",
+        "with mlflow.start_run():\n",
+        "    logged_agent_info = mlflow.pyfunc.log_model(\n",
+        "        name=\"support_agent\",\n",
+        "        python_model=\"agent.py\",\n",
+        "        input_example=input_example,\n",
+        "        resources=resources,\n",
+        "        conda_env=conda_env,\n",
+        "    )\n",
+        "\n",
+        "mlflow.set_active_model(model_id=logged_agent_info.model_id)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Log to Unity Catalog"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "mlflow.set_registry_uri(\"databricks-uc\")\n",
+        "\n",
+        "UC_MODEL_NAME = f\"{CATALOG}.ai.support_agent\"\n",
+        "\n",
+        "uc_registered_model_info = mlflow.register_model(\n",
+        "    model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
+        ")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Deploy to Model Serving"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import mlflow\n",
+        "from datetime import timedelta\n",
+        "\n",
+        "from databricks import agents\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.service.serving import EndpointStateReady\n",
+        "\n",
+        "import sys\n",
+        "sys.path.append('../utils')\n",
+        "from uc_state import add\n",
+        "\n",
+        "prod_experiment = mlflow.set_experiment(f\"/Shared/{CATALOG}_support_agent_prod\")\n",
+        "add(CATALOG, \"experiments\", {\"experiment_id\": prod_experiment.experiment_id, \"name\": prod_experiment.name})\n",
+        "\n",
+        "deployment_info = agents.deploy(\n",
+        "    model_name=UC_MODEL_NAME,\n",
+        "    model_version=uc_registered_model_info.version,\n",
+        "    scale_to_zero=False,\n",
+        "    endpoint_name=SUPPORT_AGENT_ENDPOINT_NAME,\n",
+        "    environment_vars={\"MLFLOW_EXPERIMENT_ID\": str(prod_experiment.experiment_id)},\n",
+        ")\n",
+        "\n",
+        "workspace = WorkspaceClient()\n",
+        "ready_endpoint = workspace.serving_endpoints.wait_get_serving_endpoint_not_updating(\n",
+        "    name=SUPPORT_AGENT_ENDPOINT_NAME,\n",
+        "    timeout=timedelta(minutes=30),\n",
+        ")\n",
+        "\n",
+        "if ready_endpoint.state.ready != EndpointStateReady.READY:\n",
+        "    raise RuntimeError(\n",
+        "        f\"Endpoint {SUPPORT_AGENT_ENDPOINT_NAME} is {ready_endpoint.state.ready} after deployment; retry or investigate.\"\n",
+        "    )\n",
+        "\n",
+        "print(f\"Endpoint {SUPPORT_AGENT_ENDPOINT_NAME} is READY\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# === Grant UC perms to the endpoint's runtime System Service Principal ===\n",
+        "#\n",
+        "# Model serving endpoints run inference as a workspace-level SCIM SP whose\n",
+        "# displayName is \"System Service Principal\".  These SPs are NOT members of\n",
+        "# `account users`, so the grants made earlier to `account users` do NOT apply\n",
+        "# to them — every fresh endpoint would fail on its first tool call with\n",
+        "# PERMISSION_DENIED until permissions were granted manually.\n",
+        "#\n",
+        "# See utils/agent_runtime_grants.py for the full rationale.  Grants are\n",
+        "# idempotent.\n",
+        "sys.path.append('../utils')\n",
+        "from agent_runtime_grants import grant_agent_runtime_perms\n",
+        "\n",
+        "# Pass endpoint_name so the helper also grants to the endpoint creator —\n",
+        "# that's the actual runtime identity in EMBEDDED_CREDENTIALS mode workspaces\n",
+        "# (where 'System Service Principal' isn't created and `account users` may be\n",
+        "# empty at the workspace level).\n",
+        "grant_agent_runtime_perms(\n",
+        "    spark,\n",
+        "    CATALOG,\n",
+        "    workspace_client=workspace,\n",
+        "    endpoint_name=SUPPORT_AGENT_ENDPOINT_NAME,\n",
+        ")\n",
+        ""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Record in State"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "add(CATALOG, \"endpoints\", deployment_info)\n",
+        "print(f\"Registered {SUPPORT_AGENT_ENDPOINT_NAME} in UC state\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Tool & View Registration"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
-    "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.ai;\n",
-    "CREATE SCHEMA IF NOT EXISTS ${CATALOG}.support;"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "source": "%sql\n-- Stub tables so UC functions that reference them can be created.\n-- Downstream jobs use CREATE TABLE IF NOT EXISTS with the same schema — no-op if already exists.\n\nCREATE TABLE IF NOT EXISTS ${CATALOG}.support.raw_support_requests (\n  support_request_id STRING,\n  user_id STRING,\n  order_id STRING,\n  ts TIMESTAMP,\n  request_type STRING,\n  request_text STRING,\n  edge_case_type STRING,\n  request_attempt INT,\n  generated_by STRING\n);\n\nCREATE TABLE IF NOT EXISTS ${CATALOG}.support.support_agent_reports (\n  support_request_id STRING,\n  user_id STRING,\n  order_id STRING,\n  request_text STRING,\n  ts TIMESTAMP,\n  agent_response STRING\n);",
-   "metadata": {},
-   "execution_count": null,
-   "outputs": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": "%sql\nCREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_overview(oid STRING)\nRETURNS TABLE (\n  order_id STRING,\n  location STRING,\n  items_json STRING,\n  customer_address STRING,\n  order_created_ts TIMESTAMP\n)\nRETURN\n  SELECT\n    ae.order_id,\n    loc.name AS location,\n    get_json_object(ae.body, '$.items') AS items_json,\n    get_json_object(ae.body, '$.customer_addr') AS customer_address,\n    try_to_timestamp(ae.ts) AS order_created_ts\n  FROM ${CATALOG}.lakeflow.all_events ae\n  LEFT JOIN ${CATALOG}.simulator.locations loc ON ae.location_id = loc.location_id\n  WHERE ae.order_id = oid AND ae.event_type = 'order_created'\n  LIMIT 1"
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_order_timing(oid STRING)\n",
-    "RETURNS TABLE (\n",
-    "  order_id STRING,\n",
-    "  order_created_ts TIMESTAMP,\n",
-    "  delivered_ts TIMESTAMP,\n",
-    "  delivery_duration_minutes FLOAT\n",
-    ")\n",
-    "RETURN\n",
-    "  WITH order_events AS (\n",
-    "    SELECT order_id, event_type, try_to_timestamp(ts) AS event_ts\n",
-    "    FROM ${CATALOG}.lakeflow.all_events\n",
-    "    WHERE order_id = oid\n",
-    "  )\n",
-    "  SELECT\n",
-    "    order_id,\n",
-    "    MIN(CASE WHEN event_type='order_created' THEN event_ts END) AS order_created_ts,\n",
-    "    MAX(CASE WHEN event_type='delivered' THEN event_ts END) AS delivered_ts,\n",
-    "    CAST((UNIX_TIMESTAMP(MAX(CASE WHEN event_type='delivered' THEN event_ts END)) - UNIX_TIMESTAMP(MIN(CASE WHEN event_type='order_created' THEN event_ts END))) / 60 AS FLOAT) AS delivery_duration_minutes\n",
-    "  FROM order_events\n",
-    "  GROUP BY order_id"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_user_support_history(uid STRING)\n",
-    "RETURNS TABLE (\n",
-    "  support_request_id STRING,\n",
-    "  order_id STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  request_text STRING,\n",
-    "  agent_response STRING\n",
-    ")\n",
-    "RETURN\n",
-    "  SELECT support_request_id, order_id, ts, request_text, agent_response\n",
-    "  FROM ${CATALOG}.support.support_agent_reports\n",
-    "  WHERE user_id = uid\n",
-    "  ORDER BY ts DESC\n",
-    "  LIMIT 10"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%sql\n",
-    "CREATE OR REPLACE FUNCTION ${CATALOG}.ai.get_user_request_history(uid STRING)\n",
-    "RETURNS TABLE (\n",
-    "  support_request_id STRING,\n",
-    "  order_id STRING,\n",
-    "  ts TIMESTAMP,\n",
-    "  request_type STRING,\n",
-    "  edge_case_type STRING,\n",
-    "  request_text STRING\n",
-    ")\n",
-    "RETURN\n",
-    "  SELECT support_request_id, order_id, ts, request_type, edge_case_type, request_text\n",
-    "  FROM ${CATALOG}.support.raw_support_requests\n",
-    "  WHERE user_id = uid\n",
-    "  ORDER BY ts DESC\n",
-    "  LIMIT 10"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Model"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install -U -qqqq typing_extensions dspy-ai mlflow unitycatalog-openai[databricks] openai databricks-sdk databricks-agents pydantic\n",
-    "%restart_python"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "LLM_MODEL = dbutils.widgets.get(\"LLM_MODEL\")\n",
-    "SUPPORT_AGENT_ENDPOINT_NAME = dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import mlflow\n",
-    "import sys\n",
-    "\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "dev_experiment = mlflow.set_experiment(f\"/Shared/{CATALOG}_support_agent_dev\")\n",
-    "add(CATALOG, \"experiments\", {\"experiment_id\": dev_experiment.experiment_id, \"name\": dev_experiment.name})\n",
-    "print(f\"Using dev experiment: {dev_experiment.name} (ID: {dev_experiment.experiment_id})\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import re\n",
-    "from IPython.core.magic import register_cell_magic\n",
-    "\n",
-    "@register_cell_magic\n",
-    "def writefilev(line, cell):\n",
-    "    \"\"\"\n",
-    "    %%writefilev file.py\n",
-    "    Allows {{var}} substitutions while leaving normal {} intact.\n",
-    "    \"\"\"\n",
-    "    filename = line.strip()\n",
-    "\n",
-    "    def replacer(match):\n",
-    "        expr = match.group(1)\n",
-    "        return str(eval(expr, globals(), locals()))\n",
-    "\n",
-    "    content = re.sub(r\"\\{\\{(.*?)\\}\\}\", replacer, cell)\n",
-    "\n",
-    "    with open(filename, \"w\") as f:\n",
-    "        f.write(content)\n",
-    "    print(f\"Wrote file with substitutions: {filename}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%%writefilev agent.py\n",
-    "import json\n",
-    "import re\n",
-    "import warnings\n",
-    "from typing import Any, Dict, Literal, Optional\n",
-    "from uuid import uuid4\n",
-    "\n",
-    "import dspy\n",
-    "import mlflow\n",
-    "from mlflow.pyfunc import ResponsesAgent\n",
-    "from mlflow.types.responses import ResponsesAgentRequest, ResponsesAgentResponse\n",
-    "from pydantic import BaseModel, Field\n",
-    "from unitycatalog.ai.core.base import get_uc_function_client\n",
-    "\n",
-    "warnings.filterwarnings(\"ignore\", message=\".*Ignoring the default notebook Spark session.*\")\n",
-    "\n",
-    "mlflow.dspy.autolog(log_traces=True)\n",
-    "\n",
-    "LLM_MODEL = \"{{LLM_MODEL}}\"\n",
-    "CATALOG = \"{{CATALOG}}\"\n",
-    "\n",
-    "lm = dspy.LM(f\"databricks/{LLM_MODEL}\", max_tokens=2000)\n",
-    "dspy.configure(lm=lm)\n",
-    "uc_client = get_uc_function_client()\n",
-    "\n",
-    "\n",
-    "class SupportReport(BaseModel):\n",
-    "    support_request_id: str\n",
-    "    user_id: str\n",
-    "    order_id: str\n",
-    "    credit_recommendation: Optional[dict] = None\n",
-    "    refund_recommendation: Optional[dict] = None\n",
-    "    draft_response: str\n",
-    "    past_interactions_summary: str\n",
-    "    order_details_summary: str\n",
-    "    decision_confidence: Literal[\"high\", \"medium\", \"low\"] = Field(default=\"medium\")\n",
-    "    escalation_flag: bool = Field(default=False)\n",
-    "\n",
-    "\n",
-    "class SupportTriage(dspy.Signature):\n",
-    "    \"\"\"Produce a final support resolution report using full context.\n",
-    "\n",
-    "    Required inputs to reason over:\n",
-    "    - support request text and edge-case metadata\n",
-    "    - order details and delivery timing\n",
-    "    - prior support history for this user\n",
-    "\n",
-    "    Decision policy:\n",
-    "    - Severe repeat/high-risk issue: provide concrete refund + credit and apology.\n",
-    "    - Moderate issue: provide bounded partial refund and/or credit with rationale.\n",
-    "    - Minor/non-compensable issue: typically no refund, small goodwill credit or clear denial.\n",
-    "    - Spam/abusive patterns: avoid excessive compensation, set escalation_flag=true.\n",
-    "\n",
-    "    Never return placeholder text like \"we will look into this\".\n",
-    "    Always return a final customer-ready message with concrete next steps.\n",
-    "    \"\"\"\n",
-    "\n",
-    "    support_request: str = dspy.InputField(desc=\"Structured case payload JSON string\")\n",
-    "    support_request_id: str = dspy.OutputField()\n",
-    "    user_id: str = dspy.OutputField()\n",
-    "    order_id: str = dspy.OutputField()\n",
-    "    credit_recommendation_json: str = dspy.OutputField(desc=\"JSON object with amount_usd/reason\")\n",
-    "    refund_recommendation_json: str = dspy.OutputField(desc=\"JSON object with amount_usd/reason\")\n",
-    "    draft_response: str = dspy.OutputField()\n",
-    "    past_interactions_summary: str = dspy.OutputField()\n",
-    "    order_details_summary: str = dspy.OutputField()\n",
-    "    decision_confidence: str = dspy.OutputField(desc=\"high, medium, low\")\n",
-    "    escalation_flag: str = dspy.OutputField(desc=\"true or false\")\n",
-    "\n",
-    "\n",
-    "def get_order_overview(order_id: str) -> str:\n",
-    "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_order_overview\", {\"oid\": order_id}).value)\n",
-    "\n",
-    "\n",
-    "def get_order_timing(order_id: str) -> str:\n",
-    "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_order_timing\", {\"oid\": order_id}).value)\n",
-    "\n",
-    "\n",
-    "def get_user_support_history(user_id: str) -> str:\n",
-    "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_user_support_history\", {\"uid\": user_id}).value)\n",
-    "\n",
-    "\n",
-    "def get_user_request_history(user_id: str) -> str:\n",
-    "    return str(uc_client.execute_function(f\"{CATALOG}.ai.get_user_request_history\", {\"uid\": user_id}).value)\n",
-    "\n",
-    "\n",
-    "def _parse_case_payload(raw: str) -> Dict[str, Any]:\n",
-    "    try:\n",
-    "        payload = json.loads(raw)\n",
-    "        return payload if isinstance(payload, dict) else {}\n",
-    "    except Exception:\n",
-    "        parsed: Dict[str, Any] = {}\n",
-    "        for key in [\"support_request_id\", \"user_id\", \"order_id\", \"text\"]:\n",
-    "            match = re.search(rf\"{key}=([^\\s]+)\", raw)\n",
-    "            if match:\n",
-    "                parsed[key] = match.group(1)\n",
-    "        if \"text\" in parsed:\n",
-    "            parsed[\"request_text\"] = parsed[\"text\"]\n",
-    "        return parsed\n",
-    "\n",
-    "\n",
-    "def _safe_float(value: Any, default: float = 0.0) -> float:\n",
-    "    try:\n",
-    "        return float(value)\n",
-    "    except Exception:\n",
-    "        return default\n",
-    "\n",
-    "\n",
-    "def _safe_int(value: Any, default: int = 0) -> int:\n",
-    "    try:\n",
-    "        return int(value)\n",
-    "    except Exception:\n",
-    "        return default\n",
-    "\n",
-    "\n",
-    "def _compute_policy_resolution(payload: Dict[str, Any]) -> Dict[str, Any]:\n",
-    "    request_text = str(payload.get(\"request_text\", \"\"))\n",
-    "    edge_case_type = str(payload.get(\"edge_case_type\", \"standard\"))\n",
-    "\n",
-    "    repeat_count = _safe_int(payload.get(\"repeat_complaints_30d\"), 0)\n",
-    "    risk_score = _safe_float(payload.get(\"risk_score\"), 0.25)\n",
-    "    policy_limit = max(0.0, _safe_float(payload.get(\"policy_limit_usd\"), 20.0))\n",
-    "\n",
-    "    text_lower = request_text.lower()\n",
-    "    mentions_missing = \"missing\" in text_lower\n",
-    "    mentions_delay = \"late\" in text_lower or \"delay\" in text_lower\n",
-    "    abusive = edge_case_type == \"abusive_language\"\n",
-    "    spammy = edge_case_type == \"spammy_escalation\"\n",
-    "\n",
-    "    if abusive or (spammy and repeat_count >= 4 and risk_score < 0.4):\n",
-    "        refund_amount = 0.0\n",
-    "        credit_amount = min(3.0, policy_limit)\n",
-    "        escalation = True\n",
-    "        confidence = \"medium\"\n",
-    "        reason = \"Abusive/spammy pattern detected; restricted compensation with escalation.\"\n",
-    "    elif repeat_count >= 2 or risk_score >= 0.75 or (mentions_missing and mentions_delay):\n",
-    "        refund_amount = round(min(policy_limit, max(policy_limit * 0.9, 15.0)), 2)\n",
-    "        credit_amount = round(min(10.0, max(5.0, policy_limit * 0.25)), 2)\n",
-    "        escalation = False\n",
-    "        confidence = \"high\"\n",
-    "        reason = \"Repeated or high-risk service failure.\"\n",
-    "    elif repeat_count == 1 or risk_score >= 0.45 or mentions_missing or mentions_delay:\n",
-    "        refund_amount = round(min(policy_limit, max(policy_limit * 0.5, 6.0)), 2)\n",
-    "        credit_amount = round(min(7.0, max(3.0, policy_limit * 0.15)), 2)\n",
-    "        escalation = False\n",
-    "        confidence = \"high\"\n",
-    "        reason = \"Moderate service issue with customer impact.\"\n",
-    "    else:\n",
-    "        refund_amount = 0.0\n",
-    "        credit_amount = round(min(5.0, max(2.0, policy_limit * 0.1)), 2)\n",
-    "        escalation = False\n",
-    "        confidence = \"medium\"\n",
-    "        reason = \"Minor issue or low-confidence compensable case.\"\n",
-    "\n",
-    "    return {\n",
-    "        \"refund_amount\": refund_amount,\n",
-    "        \"credit_amount\": credit_amount,\n",
-    "        \"escalation\": escalation,\n",
-    "        \"confidence\": confidence,\n",
-    "        \"reason\": reason,\n",
-    "        \"repeat_count\": repeat_count,\n",
-    "    }\n",
-    "\n",
-    "\n",
-    "def _ordinal(value: int) -> str:\n",
-    "    if 10 <= value % 100 <= 20:\n",
-    "        suffix = \"th\"\n",
-    "    else:\n",
-    "        suffix = {1: \"st\", 2: \"nd\", 3: \"rd\"}.get(value % 10, \"th\")\n",
-    "    return f\"{value}{suffix}\"\n",
-    "\n",
-    "\n",
-    "def _compose_customer_message(payload: Dict[str, Any], policy: Dict[str, Any]) -> str:\n",
-    "    request_text = str(payload.get(\"request_text\", \"\")).strip()\n",
-    "    repeat_count = policy[\"repeat_count\"]\n",
-    "    refund_amount = policy[\"refund_amount\"]\n",
-    "    credit_amount = policy[\"credit_amount\"]\n",
-    "\n",
-    "    lead = \"Thanks for contacting us, and I am really sorry about this experience.\"\n",
-    "    if repeat_count >= 2:\n",
-    "        lead = (\n",
-    "            f\"I see this is at least the {_ordinal(repeat_count)} time you've had to contact us for similar issues, \"\n",
-    "            \"and that is not acceptable.\"\n",
-    "        )\n",
-    "\n",
-    "    resolution_parts = []\n",
-    "    if refund_amount > 0:\n",
-    "        resolution_parts.append(f\"a ${refund_amount:.2f} refund\")\n",
-    "    if credit_amount > 0:\n",
-    "        resolution_parts.append(f\"a ${credit_amount:.2f} credit\")\n",
-    "\n",
-    "    if resolution_parts:\n",
-    "        resolution = \"We are offering \" + \" and \".join(resolution_parts) + \" on this case.\"\n",
-    "    else:\n",
-    "        resolution = \"We are escalating this case for manual review and will follow up quickly.\"\n",
-    "\n",
-    "    context_line = f\"Issue noted: {request_text}\" if request_text else \"Issue noted from your support ticket.\"\n",
-    "\n",
-    "    return f\"{lead} {resolution} {context_line}\"\n",
-    "\n",
-    "\n",
-    "class SupportModule(dspy.Module):\n",
-    "    def __init__(self):\n",
-    "        super().__init__()\n",
-    "        self.react = dspy.ReAct(\n",
-    "            signature=SupportTriage,\n",
-    "            tools=[\n",
-    "                get_order_overview,\n",
-    "                get_order_timing,\n",
-    "                get_user_support_history,\n",
-    "                get_user_request_history,\n",
-    "            ],\n",
-    "            max_iters=10,\n",
-    "        )\n",
-    "\n",
-    "    def forward(self, support_request: str) -> SupportReport:\n",
-    "        payload = _parse_case_payload(support_request)\n",
-    "        result = self.react(support_request=support_request)\n",
-    "\n",
-    "        policy = _compute_policy_resolution(payload)\n",
-    "        final_message = _compose_customer_message(payload, policy)\n",
-    "\n",
-    "        credit_recommendation = {\n",
-    "            \"amount_usd\": policy[\"credit_amount\"],\n",
-    "            \"reason\": policy[\"reason\"],\n",
-    "        }\n",
-    "        refund_recommendation = {\n",
-    "            \"amount_usd\": policy[\"refund_amount\"],\n",
-    "            \"reason\": policy[\"reason\"],\n",
-    "        }\n",
-    "\n",
-    "        return SupportReport(\n",
-    "            support_request_id=str(payload.get(\"support_request_id\") or result.support_request_id),\n",
-    "            user_id=str(payload.get(\"user_id\") or result.user_id),\n",
-    "            order_id=str(payload.get(\"order_id\") or result.order_id),\n",
-    "            credit_recommendation=credit_recommendation,\n",
-    "            refund_recommendation=refund_recommendation,\n",
-    "            draft_response=final_message,\n",
-    "            past_interactions_summary=str(result.past_interactions_summary),\n",
-    "            order_details_summary=str(result.order_details_summary),\n",
-    "            decision_confidence=policy[\"confidence\"],\n",
-    "            escalation_flag=bool(policy[\"escalation\"]),\n",
-    "        )\n",
-    "\n",
-    "\n",
-    "class DSPySupportAgent(ResponsesAgent):\n",
-    "    def __init__(self):\n",
-    "        self.module = SupportModule()\n",
-    "\n",
-    "    def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:\n",
-    "        user_message = None\n",
-    "        for msg in request.input:\n",
-    "            msg_dict = msg.model_dump() if hasattr(msg, \"model_dump\") else msg\n",
-    "            if msg_dict.get(\"role\") == \"user\":\n",
-    "                user_message = msg_dict.get(\"content\", \"\")\n",
-    "                break\n",
-    "        if not user_message:\n",
-    "            raise ValueError(\"No user message found\")\n",
-    "\n",
-    "        result = self.module(support_request=user_message)\n",
-    "        return ResponsesAgentResponse(\n",
-    "            output=[self.create_text_output_item(text=result.model_dump_json(), id=str(uuid4()))],\n",
-    "            custom_outputs=request.custom_inputs,\n",
-    "        )\n",
-    "\n",
-    "\n",
-    "AGENT = DSPySupportAgent()\n",
-    "mlflow.models.set_model(AGENT)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import time\n",
-    "\n",
-    "sample_order_id = None\n",
-    "for attempt in range(12):\n",
-    "    rows = spark.sql(f\"\"\"\n",
-    "        SELECT order_id \n",
-    "        FROM {CATALOG}.lakeflow.all_events \n",
-    "        WHERE event_type='delivered'\n",
-    "        LIMIT 1\n",
-    "    \"\"\").collect()\n",
-    "    if rows:\n",
-    "        sample_order_id = rows[0]['order_id']\n",
-    "        break\n",
-    "    print(f\"No delivered events yet (attempt {attempt+1}/12). Waiting 30s for pipeline data...\")\n",
-    "    time.sleep(30)\n",
-    "\n",
-    "if not sample_order_id:\n",
-    "    raise RuntimeError(\n",
-    "        f\"No delivered events found in {CATALOG}.lakeflow.all_events after 6 minutes. \"\n",
-    "        \"Ensure the Canonical_Data and Lakeflow pipeline stages completed and processed data.\"\n",
-    "    )\n",
-    "\n",
-    "print(f\"Sample order_id: {sample_order_id}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "import mlflow\n",
-    "from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint\n",
-    "from pkg_resources import get_distribution\n",
-    "\n",
-    "payload = {\n",
-    "    \"support_request_id\": \"sample-1\",\n",
-    "    \"user_id\": \"user-001\",\n",
-    "    \"order_id\": sample_order_id,\n",
-    "    \"request_type\": \"missing_items\",\n",
-    "    \"edge_case_type\": \"standard\",\n",
-    "    \"request_text\": \"My order was missing one or more items. Please review and advise next steps.\",\n",
-    "}\n",
-    "\n",
-    "resources = [DatabricksServingEndpoint(endpoint_name=LLM_MODEL)]\n",
-    "for fn in [\n",
-    "    f\"{CATALOG}.ai.get_order_overview\",\n",
-    "    f\"{CATALOG}.ai.get_order_timing\",\n",
-    "    f\"{CATALOG}.ai.get_user_support_history\",\n",
-    "    f\"{CATALOG}.ai.get_user_request_history\",\n",
-    "]:\n",
-    "    resources.append(DatabricksFunction(function_name=fn))\n",
-    "\n",
-    "input_example = {\"input\": [{\"role\": \"user\", \"content\": json.dumps(payload)}]}\n",
-    "\n",
-    "conda_env = {\n",
-    "    \"channels\": [\"conda-forge\"],\n",
-    "    \"dependencies\": [\n",
-    "        \"python=3.11\",\n",
-    "        \"pip\",\n",
-    "        {\n",
-    "            \"pip\": [\n",
-    "                \"mlflow==3.6\",\n",
-    "                f\"typing_extensions=={get_distribution('typing_extensions').version}\",\n",
-    "                f\"dspy-ai=={get_distribution('dspy-ai').version}\",\n",
-    "                f\"unitycatalog-openai[databricks]=={get_distribution('unitycatalog-openai').version}\",\n",
-    "                f\"pydantic=={get_distribution('pydantic').version}\",\n",
-    "            ]\n",
-    "        }\n",
-    "    ],\n",
-    "    \"name\": \"mlflow-env\"\n",
-    "}\n",
-    "\n",
-    "with mlflow.start_run():\n",
-    "    logged_agent_info = mlflow.pyfunc.log_model(\n",
-    "        name=\"support_agent\",\n",
-    "        python_model=\"agent.py\",\n",
-    "        input_example=input_example,\n",
-    "        resources=resources,\n",
-    "        conda_env=conda_env,\n",
-    "    )\n",
-    "\n",
-    "mlflow.set_active_model(model_id=logged_agent_info.model_id)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Log to Unity Catalog"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "mlflow.set_registry_uri(\"databricks-uc\")\n",
-    "\n",
-    "UC_MODEL_NAME = f\"{CATALOG}.ai.support_agent\"\n",
-    "\n",
-    "uc_registered_model_info = mlflow.register_model(\n",
-    "    model_uri=logged_agent_info.model_uri, name=UC_MODEL_NAME\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Deploy to Model Serving"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import mlflow\n",
-    "from datetime import timedelta\n",
-    "\n",
-    "from databricks import agents\n",
-    "from databricks.sdk import WorkspaceClient\n",
-    "from databricks.sdk.service.serving import EndpointStateReady\n",
-    "\n",
-    "import sys\n",
-    "sys.path.append('../utils')\n",
-    "from uc_state import add\n",
-    "\n",
-    "prod_experiment = mlflow.set_experiment(f\"/Shared/{CATALOG}_support_agent_prod\")\n",
-    "add(CATALOG, \"experiments\", {\"experiment_id\": prod_experiment.experiment_id, \"name\": prod_experiment.name})\n",
-    "\n",
-    "deployment_info = agents.deploy(\n",
-    "    model_name=UC_MODEL_NAME,\n",
-    "    model_version=uc_registered_model_info.version,\n",
-    "    scale_to_zero=False,\n",
-    "    endpoint_name=SUPPORT_AGENT_ENDPOINT_NAME,\n",
-    "    environment_vars={\"MLFLOW_EXPERIMENT_ID\": str(prod_experiment.experiment_id)},\n",
-    ")\n",
-    "\n",
-    "workspace = WorkspaceClient()\n",
-    "ready_endpoint = workspace.serving_endpoints.wait_get_serving_endpoint_not_updating(\n",
-    "    name=SUPPORT_AGENT_ENDPOINT_NAME,\n",
-    "    timeout=timedelta(minutes=30),\n",
-    ")\n",
-    "\n",
-    "if ready_endpoint.state.ready != EndpointStateReady.READY:\n",
-    "    raise RuntimeError(\n",
-    "        f\"Endpoint {SUPPORT_AGENT_ENDPOINT_NAME} is {ready_endpoint.state.ready} after deployment; retry or investigate.\"\n",
-    "    )\n",
-    "\n",
-    "print(f\"Endpoint {SUPPORT_AGENT_ENDPOINT_NAME} is READY\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Record in State"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "add(CATALOG, \"endpoints\", deployment_info)\n",
-    "print(f\"Registered {SUPPORT_AGENT_ENDPOINT_NAME} in UC state\")"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/stages/support_request_agent_stream.ipynb b/stages/support_request_agent_stream.ipynb
index 2109659..ec0a72c 100644
--- a/stages/support_request_agent_stream.ipynb
+++ b/stages/support_request_agent_stream.ipynb
@@ -1,89 +1,96 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Support Request Agent Stream\n",
-    "\n",
-    "This notebook creates a scheduled job to process support requests through the support agent"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Support Request Agent Stream\n",
+        "\n",
+        "This notebook creates a scheduled job to process support requests through the support agent"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import databricks.sdk.service.jobs as j\n",
+        "import os\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "notebook_abs_path = os.path.abspath(\"../jobs/support_request_agent_stream\")\n",
+        "notebook_dbx_path = notebook_abs_path.replace(\n",
+        "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
+        "    \"/Workspace\"\n",
+        ")\n",
+        "\n",
+        "job_name = f\"Support Request Agent Stream ({CATALOG})\"\n",
+        "\n",
+        "# timeout_seconds=600 (10 min, matches cron) so a single hung UDF call against\n",
+        "# a stalled support-agent endpoint cannot block the whole queue forever.\n",
+        "task_def = [\n",
+        "    j.Task(\n",
+        "        task_key=\"support_request_agent_stream\",\n",
+        "        timeout_seconds=600,\n",
+        "        notebook_task=j.NotebookTask(\n",
+        "            notebook_path=notebook_dbx_path,\n",
+        "            base_parameters={\n",
+        "                \"CATALOG\": CATALOG,\n",
+        "                \"SUPPORT_AGENT_ENDPOINT_NAME\": dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\"),\n",
+        "            },\n",
+        "        )\n",
+        "    )\n",
+        "]\n",
+        "schedule_def = j.CronSchedule(\n",
+        "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
+        "    timezone_id=\"UTC\",\n",
+        "    pause_status=j.PauseStatus.UNPAUSED,\n",
+        ")\n",
+        "\n",
+        "# queue.enabled=False: drop cron triggers if a previous run is still active\n",
+        "# instead of stacking them up (default enabled=True creates an unbounded backlog).\n",
+        "queue_def = j.QueueSettings(enabled=False)\n",
+        "\n",
+        "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
+        "if existing:\n",
+        "    job_id = existing[0].job_id\n",
+        "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
+        "        name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def,\n",
+        "    ))\n",
+        "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
+        "else:\n",
+        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def)\n",
+        "    job_id = job.job_id\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from uc_state import add\n",
+        "    add(CATALOG, \"jobs\", job)\n",
+        "    print(f\"\\u2705 Created job_id={job_id}\")\n",
+        "\n",
+        "w.jobs.run_now(job_id=job_id)\n",
+        "print(f\"\\U0001f680 Started run of {job_name}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "import databricks.sdk.service.jobs as j\n",
-    "import os\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "\n",
-    "notebook_abs_path = os.path.abspath(\"../jobs/support_request_agent_stream\")\n",
-    "notebook_dbx_path = notebook_abs_path.replace(\n",
-    "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
-    "    \"/Workspace\"\n",
-    ")\n",
-    "\n",
-    "job_name = f\"Support Request Agent Stream ({CATALOG})\"\n",
-    "\n",
-    "task_def = [\n",
-    "    j.Task(\n",
-    "        task_key=\"support_request_agent_stream\",\n",
-    "        notebook_task=j.NotebookTask(\n",
-    "            notebook_path=notebook_dbx_path,\n",
-    "            base_parameters={\n",
-    "                \"CATALOG\": CATALOG,\n",
-    "                \"SUPPORT_AGENT_ENDPOINT_NAME\": dbutils.widgets.get(\"SUPPORT_AGENT_ENDPOINT_NAME\"),\n",
-    "            },\n",
-    "        )\n",
-    "    )\n",
-    "]\n",
-    "schedule_def = j.CronSchedule(\n",
-    "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
-    "    timezone_id=\"UTC\",\n",
-    "    pause_status=j.PauseStatus.UNPAUSED,\n",
-    ")\n",
-    "\n",
-    "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
-    "if existing:\n",
-    "    job_id = existing[0].job_id\n",
-    "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
-    "        name=job_name, tasks=task_def, schedule=schedule_def,\n",
-    "    ))\n",
-    "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
-    "else:\n",
-    "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def)\n",
-    "    job_id = job.job_id\n",
-    "    import sys\n",
-    "    sys.path.append('../utils')\n",
-    "    from uc_state import add\n",
-    "    add(CATALOG, \"jobs\", job)\n",
-    "    print(f\"\\u2705 Created job_id={job_id}\")\n",
-    "\n",
-    "w.jobs.run_now(job_id=job_id)\n",
-    "print(f\"\\U0001f680 Started run of {job_name}\")"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/stages/support_request_generator_stream.ipynb b/stages/support_request_generator_stream.ipynb
index 2c48eb1..bfc66f7 100644
--- a/stages/support_request_generator_stream.ipynb
+++ b/stages/support_request_generator_stream.ipynb
@@ -1,90 +1,97 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "##### Support Request Generator Stream\n",
-    "\n",
-    "This notebook creates a scheduled job to generate synthetic support requests from delivered orders"
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "##### Support Request Generator Stream\n",
+        "\n",
+        "This notebook creates a scheduled job to generate synthetic support requests from delivered orders"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install --upgrade databricks-sdk"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from databricks.sdk import WorkspaceClient\n",
+        "import databricks.sdk.service.jobs as j\n",
+        "import os\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
+        "\n",
+        "notebook_abs_path = os.path.abspath(\"../jobs/support_request_generator\")\n",
+        "notebook_dbx_path = notebook_abs_path.replace(\n",
+        "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
+        "    \"/Workspace\"\n",
+        ")\n",
+        "\n",
+        "job_name = f\"Support Request Generator ({CATALOG})\"\n",
+        "\n",
+        "# timeout_seconds=600 (10 min, matches cron) so a hung generation batch cannot\n",
+        "# block the queue forever and pile up cron triggers.\n",
+        "task_def = [\n",
+        "    j.Task(\n",
+        "        task_key=\"support_request_generator\",\n",
+        "        timeout_seconds=600,\n",
+        "        notebook_task=j.NotebookTask(\n",
+        "            notebook_path=notebook_dbx_path,\n",
+        "            base_parameters={\n",
+        "                \"CATALOG\": CATALOG,\n",
+        "                \"SUPPORT_RATE\": dbutils.widgets.get(\"SUPPORT_RATE\"),\n",
+        "                \"LLM_MODEL\": dbutils.widgets.get(\"LLM_MODEL\"),\n",
+        "            },\n",
+        "        )\n",
+        "    )\n",
+        "]\n",
+        "schedule_def = j.CronSchedule(\n",
+        "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
+        "    timezone_id=\"UTC\",\n",
+        "    pause_status=j.PauseStatus.UNPAUSED,\n",
+        ")\n",
+        "\n",
+        "# queue.enabled=False: drop cron triggers if a previous run is still active\n",
+        "# instead of stacking them up (default enabled=True creates an unbounded backlog).\n",
+        "queue_def = j.QueueSettings(enabled=False)\n",
+        "\n",
+        "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
+        "if existing:\n",
+        "    job_id = existing[0].job_id\n",
+        "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
+        "        name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def,\n",
+        "    ))\n",
+        "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
+        "else:\n",
+        "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def, queue=queue_def)\n",
+        "    job_id = job.job_id\n",
+        "    import sys\n",
+        "    sys.path.append('../utils')\n",
+        "    from uc_state import add\n",
+        "    add(CATALOG, \"jobs\", job)\n",
+        "    print(f\"\\u2705 Created job_id={job_id}\")\n",
+        "\n",
+        "w.jobs.run_now(job_id=job_id)\n",
+        "print(f\"\\U0001f680 Started run of {job_name}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install --upgrade databricks-sdk"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from databricks.sdk import WorkspaceClient\n",
-    "import databricks.sdk.service.jobs as j\n",
-    "import os\n",
-    "\n",
-    "w = WorkspaceClient()\n",
-    "\n",
-    "CATALOG = dbutils.widgets.get(\"CATALOG\")\n",
-    "\n",
-    "notebook_abs_path = os.path.abspath(\"../jobs/support_request_generator\")\n",
-    "notebook_dbx_path = notebook_abs_path.replace(\n",
-    "    os.environ.get(\"DATABRICKS_WORKSPACE_ROOT\", \"/Workspace\"),\n",
-    "    \"/Workspace\"\n",
-    ")\n",
-    "\n",
-    "job_name = f\"Support Request Generator ({CATALOG})\"\n",
-    "\n",
-    "task_def = [\n",
-    "    j.Task(\n",
-    "        task_key=\"support_request_generator\",\n",
-    "        notebook_task=j.NotebookTask(\n",
-    "            notebook_path=notebook_dbx_path,\n",
-    "            base_parameters={\n",
-    "                \"CATALOG\": CATALOG,\n",
-    "                \"SUPPORT_RATE\": dbutils.widgets.get(\"SUPPORT_RATE\"),\n",
-    "                \"LLM_MODEL\": dbutils.widgets.get(\"LLM_MODEL\"),\n",
-    "            },\n",
-    "        )\n",
-    "    )\n",
-    "]\n",
-    "schedule_def = j.CronSchedule(\n",
-    "    quartz_cron_expression=\"0 0/10 * * * ?\",\n",
-    "    timezone_id=\"UTC\",\n",
-    "    pause_status=j.PauseStatus.UNPAUSED,\n",
-    ")\n",
-    "\n",
-    "existing = [jb for jb in w.jobs.list(name=job_name) if jb.settings.name == job_name]\n",
-    "if existing:\n",
-    "    job_id = existing[0].job_id\n",
-    "    w.jobs.reset(job_id=job_id, new_settings=j.JobSettings(\n",
-    "        name=job_name, tasks=task_def, schedule=schedule_def,\n",
-    "    ))\n",
-    "    print(f\"\\u267b\\ufe0f Updated existing job_id={job_id}\")\n",
-    "else:\n",
-    "    job = w.jobs.create(name=job_name, tasks=task_def, schedule=schedule_def)\n",
-    "    job_id = job.job_id\n",
-    "    import sys\n",
-    "    sys.path.append('../utils')\n",
-    "    from uc_state import add\n",
-    "    add(CATALOG, \"jobs\", job)\n",
-    "    print(f\"\\u2705 Created job_id={job_id}\")\n",
-    "\n",
-    "w.jobs.run_now(job_id=job_id)\n",
-    "print(f\"\\U0001f680 Started run of {job_name}\")"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }
\ No newline at end of file
diff --git a/utils/__init__.py b/utils/__init__.py
index 05f5e25..48fab2a 100644
--- a/utils/__init__.py
+++ b/utils/__init__.py
@@ -3,5 +3,6 @@
 """
 
 from .uc_state import UCState, create_state_manager, add
+from . import status
 
-__all__ = ['UCState', 'create_state_manager', 'add']
\ No newline at end of file
+__all__ = ['UCState', 'create_state_manager', 'add', 'status']
\ No newline at end of file
diff --git a/utils/agent_runtime_grants.py b/utils/agent_runtime_grants.py
new file mode 100644
index 0000000..60abd67
--- /dev/null
+++ b/utils/agent_runtime_grants.py
@@ -0,0 +1,245 @@
+"""Grant Unity Catalog runtime permissions to model serving runtime identities.
+
+Why this exists
+---------------
+`agents.deploy()` creates a model serving endpoint whose runtime identity
+depends on the workspace's auth-policy configuration.  Three patterns we
+have to support:
+
+1. **System Service Principal mode** — some workspaces.  The endpoint
+   runs as an auto-generated workspace SP whose displayName is literally
+   "System Service Principal".  These SPs are NOT members of
+   `account users`, so the catalog/schema/function grants made to
+   `account users` (the standard pattern used elsewhere in the bundle)
+   do NOT apply to them.  Discoverable via SCIM.
+
+2. **EMBEDDED_CREDENTIALS mode (creator identity)** — older / single-user
+   workspaces where the endpoint runs as the creator's user identity
+   (their PAT is baked into the deployment).  Discoverable via
+   `serving_endpoints.get(name).creator`.
+
+3. **EMBEDDED_CREDENTIALS mode (hidden auto-managed SP)** — observed in
+   real production deploys (2026-06-08).  The framework auto-creates an
+   internal SP (UUID like `5b403323-4cf0-473a-adac-585479d24824`) that
+   is **invisible in workspace SCIM** and is supposed to receive
+   automatic EXECUTE grants via the `resources=[DatabricksFunction(...)]`
+   list passed to `mlflow.pyfunc.log_model()`.  When that auto-grant
+   silently fails, the endpoint returns
+       PermissionError("...does not have EXECUTE on Routine 'X'")
+   on every tool call, and the SP is only discoverable by querying the
+   audit log for 403 getFunction events on the agent's UC functions —
+   see `discover_runtime_sp_from_audit_log()` below.
+
+Net effect: every freshly-deployed agent endpoint can hit
+    PERMISSION_DENIED: User does not have USE CATALOG on Catalog '<catalog>'
+or
+    PERMISSION_DENIED: User does not have EXECUTE on Routine '<catalog>.ai.<fn>'
+on its first tool call, until somebody manually grants permissions to the
+endpoint's runtime identity.
+
+This module discovers the runtime identity through all three paths and
+grants USE CATALOG / USE SCHEMA / EXECUTE / SELECT on the catalog,
+schemas, and functions the agents need.  It is idempotent — re-granting
+an existing permission is a no-op in Unity Catalog.
+
+Call from an agent stage immediately after `agents.deploy()` +
+`wait_get_serving_endpoint_not_updating` so the perms are in place before
+any external traffic hits the endpoint.
+
+If you suspect the hidden-SP failure mode but the endpoint hasn't logged
+a failure yet, you can probe it once (any chat request) and re-run the
+helper — by then the audit log will have a row identifying the SP.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+import requests
+
+
+def discover_system_service_principals(workspace_client) -> List[str]:
+    """Return the applicationId of every workspace "System Service Principal".
+
+    These are the runtime identities used by model serving endpoints
+    in workspaces that auto-create a managed runtime SP.  Returns []
+    in workspaces that use EMBEDDED_CREDENTIALS mode instead.
+    """
+    cfg = workspace_client.config
+    url = f"{cfg.host}/api/2.0/preview/scim/v2/ServicePrincipals"
+    r = requests.get(url, headers=cfg.authenticate(), params={"count": 200})
+    r.raise_for_status()
+    resources = r.json().get("Resources", []) or []
+    return [
+        sp["applicationId"]
+        for sp in resources
+        if sp.get("displayName") == "System Service Principal"
+        and sp.get("applicationId")
+    ]
+
+
+def discover_endpoint_creator(workspace_client, endpoint_name: str) -> Optional[str]:
+    """Return the creator (user email) of a model serving endpoint.
+
+    In EMBEDDED_CREDENTIALS mode this is sometimes the actual runtime
+    identity: the creator's PAT is baked into the deployment and used
+    for every downstream UC call.
+    """
+    try:
+        ep = workspace_client.serving_endpoints.get(endpoint_name)
+    except Exception as exc:  # noqa: BLE001
+        print(f"  ⚠ couldn't look up endpoint {endpoint_name}: {exc}")
+        return None
+    return getattr(ep, "creator", None)
+
+
+def discover_runtime_sp_from_audit_log(
+    spark,
+    catalog: str,
+    schema: str = "ai",
+    lookback_minutes: int = 60,
+) -> List[str]:
+    """Find hidden auto-managed runtime SPs by searching the UC audit log.
+
+    The framework's auto-managed runtime SP for `agents.deploy()`
+    EMBEDDED_CREDENTIALS endpoints is invisible in workspace SCIM, but
+    every UC operation it performs is logged in system.access.audit.
+    Failed `getFunction` calls against `<catalog>.<schema>.*` give us a
+    `user_identity.email` of the SP UUID.
+
+    Returns the unique SP UUIDs that have made any UC call against the
+    agent's function schema in the last `lookback_minutes`.  Caller
+    should grant these the same UC perms as any other runtime identity.
+
+    Requires `system.access.audit` to be queryable from `spark` and a
+    few minutes of audit log ingestion lag (typical: 1-10 min).
+    """
+    try:
+        rows = spark.sql(f"""
+            SELECT DISTINCT user_identity.email AS principal
+            FROM system.access.audit
+            WHERE event_time >= current_timestamp() - INTERVAL {int(lookback_minutes)} MINUTES
+              AND service_name = 'unityCatalog'
+              AND request_params.full_name_arg LIKE '{catalog}.{schema}.%'
+              AND user_identity.email IS NOT NULL
+        """).collect()
+    except Exception as exc:  # noqa: BLE001
+        print(f"  ⚠ audit-log SP discovery failed: {exc}")
+        return []
+    # Filter to UUID-shaped principals (skips real users / workspace SPs
+    # which are already discovered through the other paths).
+    import re
+    uuid_re = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+    return [r["principal"] for r in rows if r["principal"] and uuid_re.match(r["principal"])]
+
+
+def grant_agent_runtime_perms(
+    spark,
+    catalog: str,
+    schemas: Sequence[str] = ("ai", "lakeflow", "simulator"),
+    select_schemas: Sequence[str] = ("lakeflow", "simulator"),
+    workspace_client=None,
+    endpoint_name: Optional[str] = None,
+    extra_principals: Sequence[str] = (),
+    audit_log_lookback_minutes: int = 60,
+) -> List[str]:
+    """Grant catalog/schema/function perms to every runtime identity.
+
+    Parameters
+    ----------
+    spark
+        Active SparkSession (used to run GRANT statements).
+    catalog
+        Unity Catalog catalog name (e.g. "oleksandra").
+    schemas
+        Schemas where USE_SCHEMA + EXECUTE should be granted (so the
+        runtime identities can traverse to functions and execute them).
+    select_schemas
+        Schemas where SELECT on all tables should be granted (so UC
+        functions that read tables can do so).
+    workspace_client
+        Optional pre-built WorkspaceClient.  A fresh one is created if None.
+    endpoint_name
+        Optional model serving endpoint name.  When supplied, the
+        endpoint's creator (user email) is also added to the principal
+        list — this is the runtime identity in EMBEDDED_CREDENTIALS mode
+        and ensures agent endpoints work in workspaces where
+        `account users` is empty at the workspace level.
+    extra_principals
+        Optional explicit list of additional principals (user emails or
+        SP applicationIds) to grant the same perms to.
+    audit_log_lookback_minutes
+        How far back to search system.access.audit for hidden auto-managed
+        runtime SPs that have already attempted UC calls.  Set to 0 to
+        skip audit-log discovery entirely (e.g. on first deploy when the
+        SP hasn't made any calls yet).
+
+    Returns
+    -------
+    The list of principals (SP applicationIds and user emails) that
+    received grants.
+    """
+    if workspace_client is None:
+        from databricks.sdk import WorkspaceClient
+        workspace_client = WorkspaceClient()
+
+    principals: List[str] = []
+
+    sps = discover_system_service_principals(workspace_client)
+    principals.extend(sps)
+
+    if endpoint_name:
+        creator = discover_endpoint_creator(workspace_client, endpoint_name)
+        if creator and creator not in principals:
+            principals.append(creator)
+
+    if audit_log_lookback_minutes > 0 and "ai" in schemas:
+        audit_sps = discover_runtime_sp_from_audit_log(
+            spark, catalog, schema="ai",
+            lookback_minutes=audit_log_lookback_minutes,
+        )
+        for sp in audit_sps:
+            if sp not in principals:
+                principals.append(sp)
+
+    for p in extra_principals:
+        if p and p not in principals:
+            principals.append(p)
+
+    if not principals:
+        print(
+            "ℹ️  No runtime identities discovered.  Model serving may not be "
+            "provisioned yet, or this workspace uses a different runtime SP "
+            "naming convention and no endpoint_name was provided.  Skipping grants."
+        )
+        return []
+
+    print(f"Granting agent runtime UC perms to {len(principals)} principal(s):")
+    for p in principals:
+        kind = "user" if "@" in p else "service principal"
+        print(f"  • {p}  ({kind})")
+
+    stmts: List[str] = []
+    for p in principals:
+        stmts.append(f"GRANT USE CATALOG ON CATALOG {catalog} TO `{p}`")
+        for schema in schemas:
+            stmts.append(f"GRANT USE SCHEMA ON SCHEMA {catalog}.{schema} TO `{p}`")
+        # EXECUTE at schema level cascades to all current AND future functions
+        # in that schema (Unity Catalog privilege inheritance).  Functions
+        # created by *later* stages also become callable by the principal.
+        for schema in schemas:
+            stmts.append(f"GRANT EXECUTE ON SCHEMA {catalog}.{schema} TO `{p}`")
+        for schema in select_schemas:
+            stmts.append(f"GRANT SELECT ON SCHEMA {catalog}.{schema} TO `{p}`")
+
+    n_ok, n_err = 0, 0
+    for stmt in stmts:
+        try:
+            spark.sql(stmt)
+            n_ok += 1
+        except Exception as exc:  # noqa: BLE001 — log + continue (idempotency)
+            n_err += 1
+            print(f"  ⚠ grant failed: {stmt}\n     → {exc}")
+
+    print(f"✅ Applied {n_ok} grants ({n_err} errors)")
+    return principals
diff --git a/utils/casperslogo_green.png b/utils/casperslogo_green.png
new file mode 100644
index 0000000..2524dcb
Binary files /dev/null and b/utils/casperslogo_green.png differ
diff --git a/utils/domain_tags.py b/utils/domain_tags.py
new file mode 100644
index 0000000..8b1d21b
--- /dev/null
+++ b/utils/domain_tags.py
@@ -0,0 +1,156 @@
+"""
+Discover Domain tagging helpers (DAIS 2026 beat).
+
+Three boolean governed tags drive the three Catalog \u2192 Discover \u2192 Domains
+that the demo binds in the UI (Operations / Revenue & Customers /
+Compliance & Safety).  This module gives stages one place to:
+
+  1. Create the three governed tag policies (best-effort \u2014 falls back to
+     plain UC tags via SQL DDL if the caller lacks tag-policy admin).
+  2. Apply the tags to UC securables (schemas, tables) via SQL DDL.
+  3. Apply the tags to workspace-scoped assets (Genie spaces, dashboards,
+     apps, notebooks) via the workspace-entity tag-assignment API.
+
+Tag key naming
+--------------
+Keys use underscores (``caspers_domain_operations``) instead of dots
+(``caspers.domain.operations``) because the workspace-entity tag-assignment
+API rejects the characters ``, . : / - =`` in tag keys (UC SQL DDL accepts
+dots fine, but we need ONE key shape that works for both APIs so a single
+Domain in Discover can surface UC tables AND Genie spaces/apps/dashboards
+side by side).
+
+All operations in this module are best-effort and idempotent:
+
+* Governed tag creation: 409 (already exists) and permission errors are
+  swallowed.  If the caller isn't tag-policy admin, we fall back to plain
+  ``CREATE TAG IF NOT EXISTS`` via SQL DDL so the *application* of the tag
+  still works \u2014 the tag just lands in the UI's "Other" section instead
+  of "Governed".
+* Tag application: every per-securable / per-entity call is wrapped so a
+  missing target (target that doesn't materialise the asset) prints a
+  warning and the loop continues.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+
+DOMAINS = ("operations", "revenue", "compliance")
+TAG_KEYS = tuple(f"caspers_domain_{d}" for d in DOMAINS)
+
+
+def ensure_domain_tag_policies(w, *, spark=None, verbose: bool = True) -> None:
+    """Create the three governed tag policies if they don't exist.
+
+    Falls back to plain UC tags via ``CREATE TAG IF NOT EXISTS`` when
+    ``spark`` is provided and the Tag Policy API call fails (insufficient
+    privileges, older account, etc.).  Either path leaves the tag key
+    usable for downstream ``SET TAGS`` / ``create_tag_assignment`` calls.
+    """
+    try:
+        from databricks.sdk.service.tags import TagPolicy, Value
+    except Exception as e:
+        if verbose:
+            print(f"  \u26a0\ufe0f  databricks-sdk too old for tag policies ({e}); falling back to plain SQL tags")
+        TagPolicy = Value = None  # type: ignore[assignment]
+
+    for key in TAG_KEYS:
+        created = False
+        if TagPolicy is not None:
+            try:
+                w.tag_policies.create_tag_policy(
+                    TagPolicy(
+                        tag_key=key,
+                        description=f"Casper's Discover Domain tag ({key.split('_')[-1]}).",
+                        values=[Value(name="true")],
+                    )
+                )
+                if verbose:
+                    print(f"  \u2705 governed tag policy: {key}")
+                created = True
+            except Exception as e:
+                msg = str(e).splitlines()[0]
+                if "ALREADY_EXISTS" in msg or "already exists" in msg.lower() or "409" in msg:
+                    if verbose:
+                        print(f"  \u267b\ufe0f  governed tag policy already exists: {key}")
+                    created = True
+                elif verbose:
+                    print(f"  \u26a0\ufe0f  could not create governed tag policy {key} "
+                          f"({type(e).__name__}); falling back to plain SQL tag. Detail: {msg}")
+
+        if not created and spark is not None:
+            try:
+                spark.sql(f"CREATE TAG IF NOT EXISTS `{key}`")
+                if verbose:
+                    print(f"  \u2705 plain SQL tag: {key}")
+            except Exception as e:
+                if verbose:
+                    print(f"  \u26a0\ufe0f  CREATE TAG fallback also failed for {key}: {str(e).splitlines()[0]}")
+
+
+def tag_uc_securable(spark, kind: str, full_name: str, domains: Iterable[str],
+                     *, verbose: bool = True) -> None:
+    """Apply one or more domain tags to a UC securable via SQL DDL.
+
+    ``kind`` is one of {"schema", "table", "catalog", "volume"}.
+    ``domains`` is an iterable of short domain names from ``DOMAINS``.
+    """
+    kw = {"schema": "SCHEMA", "table": "TABLE", "catalog": "CATALOG", "volume": "VOLUME"}[kind]
+    pairs = [(f"caspers_domain_{d}", "true") for d in domains]
+    clause = ", ".join(f"'{k}' = '{v}'" for k, v in pairs)
+    try:
+        spark.sql(f"ALTER {kw} {full_name} SET TAGS ({clause})")
+        if verbose:
+            print(f"  \u2705 tagged {kind}: {full_name} \u2192 {', '.join(domains)}")
+    except Exception as e:
+        if verbose:
+            print(f"  \u26a0\ufe0f  skipped {kind} {full_name}: {str(e).splitlines()[0]}")
+
+
+def tag_workspace_entity(w, entity_type: str, entity_id: str, domains: Iterable[str],
+                         *, verbose: bool = True, label: Optional[str] = None) -> None:
+    """Apply one or more domain tags to a workspace-scoped asset.
+
+    ``entity_type`` is one of {"apps", "dashboards", "geniespaces", "notebooks"}.
+    For ``apps``, ``entity_id`` is the app NAME (not a numeric id).  For
+    ``dashboards`` and ``geniespaces``, ``entity_id`` is the object id.
+
+    Best-effort: if the workspace tagging API isn't available on this SDK
+    (older version), or the user lacks permission, the call prints a
+    warning and returns.
+    """
+    try:
+        from databricks.sdk.service.tags import TagAssignment
+    except Exception as e:
+        if verbose:
+            print(f"  \u26a0\ufe0f  databricks-sdk too old for workspace-entity tags ({e})")
+        return
+
+    api = getattr(w, "workspace_entity_tag_assignments", None)
+    if api is None:
+        if verbose:
+            print("  \u26a0\ufe0f  w.workspace_entity_tag_assignments not available on this SDK")
+        return
+
+    display = label or f"{entity_type}:{entity_id}"
+    for d in domains:
+        key = f"caspers_domain_{d}"
+        try:
+            api.create_tag_assignment(TagAssignment(
+                entity_type=entity_type,
+                entity_id=entity_id,
+                tag_key=key,
+                tag_value="true",
+            ))
+            if verbose:
+                print(f"  \u2705 tagged {display} \u2192 {d}")
+        except Exception as e:
+            msg = str(e).splitlines()[0]
+            if "ALREADY_EXISTS" in msg or "already exists" in msg.lower() or "409" in msg:
+                if verbose:
+                    print(f"  \u267b\ufe0f  {display} already tagged {d}")
+            else:
+                if verbose:
+                    print(f"  \u26a0\ufe0f  skipped {display} \u2192 {d}: {msg}")
diff --git a/utils/fix_agent_perms.ipynb b/utils/fix_agent_perms.ipynb
new file mode 100644
index 0000000..b320673
--- /dev/null
+++ b/utils/fix_agent_perms.ipynb
@@ -0,0 +1,310 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Fix agent endpoint UC perms\n",
+        "\n",
+        "Run this notebook in the workspace **after** an agent stage has deployed an endpoint that returns `PermissionError(\"User does not have EXECUTE on Routine '<catalog>.ai.<fn>'\")` on tool calls.\n",
+        "\n",
+        "## What it does\n",
+        "\n",
+        "1. For each agent endpoint you list, sends one probe chat request to force the runtime to attempt a UC function call.  This generates a 403 `getFunction` audit event whose `user_identity.email` is the endpoint's hidden auto-managed runtime SP UUID — the SP that `agents.deploy()` was supposed to grant `EXECUTE` to but silently didn't.\n",
+        "2. Polls `system.access.audit` until that SP UUID surfaces (typically 1–3 minutes).\n",
+        "3. Grants the SP `USE_CATALOG` + `USE_SCHEMA` + `EXECUTE` on the agent's function schema (and `SELECT` on tables the functions read).  Idempotent.\n",
+        "4. Re-invokes each endpoint to confirm the tool calls now succeed.\n",
+        "\n",
+        "## Why this exists\n",
+        "\n",
+        "The Mosaic AI Agent Framework's `agents.deploy()` creates an internal runtime SP for `EMBEDDED_CREDENTIALS` endpoints.  That SP is meant to receive automatic `EXECUTE` grants via the `resources=[DatabricksFunction(...)]` list passed to `mlflow.pyfunc.log_model()`, but the auto-grant silently fails in some workspaces (observed 2026-06-08).  The SP is **not visible in workspace SCIM** — the audit log is the only path that surfaces its UUID.  See `utils/agent_runtime_grants.py` for the full backstory."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "dbutils.widgets.text(\"CATALOG\", \"\", \"UC catalog (REQUIRED)\")\n",
+        "dbutils.widgets.text(\n",
+        "    \"ENDPOINT_NAMES\",\n",
+        "    \"\",\n",
+        "    \"Endpoints to fix, comma-separated (default: <catalog>_{refund,complaint,support}_agent)\",\n",
+        ")\n",
+        "dbutils.widgets.text(\"MAX_WAIT_SECONDS\", \"300\", \"Max seconds to wait for audit log\")\n",
+        "\n",
+        "CATALOG = dbutils.widgets.get(\"CATALOG\").strip()\n",
+        "if not CATALOG:\n",
+        "    raise ValueError(\n",
+        "        \"CATALOG widget is empty. Set it to the UC catalog name that matches \"\n",
+        "        \"the `--var catalog=<name>` from your last `bundle deploy` \"\n",
+        "        \"(bundle default: 'caspersdev').\"\n",
+        "    )\n",
+        "\n",
+        "_eps = dbutils.widgets.get(\"ENDPOINT_NAMES\").strip()\n",
+        "if _eps:\n",
+        "    ENDPOINTS = [e.strip() for e in _eps.split(\",\") if e.strip()]\n",
+        "else:\n",
+        "    # Mirrors the endpoint name pattern from databricks.yml job params:\n",
+        "    #   ${var.catalog}_{refund,complaint,support}_agent\n",
+        "    ENDPOINTS = [\n",
+        "        f\"{CATALOG}_refund_agent\",\n",
+        "        f\"{CATALOG}_complaint_agent\",\n",
+        "        f\"{CATALOG}_support_agent\",\n",
+        "    ]\n",
+        "\n",
+        "MAX_WAIT = int(dbutils.widgets.get(\"MAX_WAIT_SECONDS\"))\n",
+        "\n",
+        "print(f\"Catalog:   {CATALOG}\")\n",
+        "print(f\"Endpoints: {ENDPOINTS}\")\n",
+        "print(f\"Audit-log wait budget: {MAX_WAIT}s\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "import re\n",
+        "import sys\n",
+        "import time\n",
+        "from typing import List, Optional, Set\n",
+        "\n",
+        "from databricks.sdk import WorkspaceClient\n",
+        "from databricks.sdk.errors import ResourceDoesNotExist\n",
+        "\n",
+        "w = WorkspaceClient()\n",
+        "\n",
+        "UUID_RE = re.compile(r\"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$\")\n",
+        "\n",
+        "# A trivial probe that any of the 3 agents will accept and that always\n",
+        "# forces at least one UC function call (the agents all start with a UC\n",
+        "# lookup before reasoning).  We don't care about the response — we only\n",
+        "# care that the runtime tried a UC call so the audit log captures the SP.\n",
+        "PROBE_PAYLOAD = {\n",
+        "    \"messages\": [\n",
+        "        {\"role\": \"user\", \"content\": \"Look up order ABCDEF and return whatever you find.\"}\n",
+        "    ]\n",
+        "}"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "def probe(endpoint_name: str) -> bool:\n",
+        "    \"\"\"Send one chat request to the endpoint.  Returns True iff the\n",
+        "    response indicates a UC permission denial (the case we're fixing).\n",
+        "    Returns False if the call already succeeded — nothing to do.\"\"\"\n",
+        "    try:\n",
+        "        resp = w.serving_endpoints.query(\n",
+        "            name=endpoint_name,\n",
+        "            messages=[{\"role\": \"user\", \"content\": PROBE_PAYLOAD[\"messages\"][0][\"content\"]}],\n",
+        "        )\n",
+        "        # The SDK returns a typed object; cast through json for uniform inspection.\n",
+        "        body = json.dumps(resp.as_dict())\n",
+        "    except Exception as exc:  # noqa: BLE001\n",
+        "        # Some agent endpoints return 200 with the error in the message body;\n",
+        "        # others raise.  Treat both as \"likely the perm bug\".\n",
+        "        body = repr(exc)\n",
+        "    if \"Permission denied\" in body and \"EXECUTE on Routine\" in body:\n",
+        "        return True\n",
+        "    if \"Permission denied\" in body or \"PermissionError\" in body:\n",
+        "        # Different perm error — surface it so user can see, but still try\n",
+        "        # to grant; the audit log will tell us what the runtime tried.\n",
+        "        print(f\"  ⚠\\ufe0f  endpoint returned a permission-related error; raw fragment:\")\n",
+        "        print(f\"     {body[:300]}\")\n",
+        "        return True\n",
+        "    return False\n",
+        "\n",
+        "\n",
+        "def discover_runtime_sps(catalog: str, schema: str, since_seconds: int) -> Set[str]:\n",
+        "    \"\"\"Read system.access.audit for UUID-shaped principals that have\n",
+        "    touched <catalog>.<schema>.* in the last `since_seconds`.  Returns\n",
+        "    the set of distinct SP UUIDs.\"\"\"\n",
+        "    rows = spark.sql(f\"\"\"\n",
+        "        SELECT DISTINCT user_identity.email AS principal\n",
+        "        FROM system.access.audit\n",
+        "        WHERE event_time >= current_timestamp() - INTERVAL {int(since_seconds)} SECONDS\n",
+        "          AND service_name = 'unityCatalog'\n",
+        "          AND request_params.full_name_arg LIKE '{catalog}.{schema}.%'\n",
+        "          AND user_identity.email IS NOT NULL\n",
+        "    \"\"\").collect()\n",
+        "    return {r[\"principal\"] for r in rows if r[\"principal\"] and UUID_RE.match(r[\"principal\"])}\n",
+        "\n",
+        "\n",
+        "def grant_perms(catalog: str, principal: str) -> None:\n",
+        "    \"\"\"Apply the standard agent runtime grant bundle to one principal.\n",
+        "    Idempotent.  Mirrors what utils/agent_runtime_grants.py does so this\n",
+        "    notebook stays self-contained.\"\"\"\n",
+        "    stmts = [\n",
+        "        f\"GRANT USE CATALOG ON CATALOG {catalog} TO `{principal}`\",\n",
+        "        f\"GRANT USE SCHEMA ON SCHEMA {catalog}.ai TO `{principal}`\",\n",
+        "        f\"GRANT EXECUTE  ON SCHEMA {catalog}.ai TO `{principal}`\",\n",
+        "        f\"GRANT USE SCHEMA ON SCHEMA {catalog}.lakeflow TO `{principal}`\",\n",
+        "        f\"GRANT SELECT  ON SCHEMA {catalog}.lakeflow TO `{principal}`\",\n",
+        "        f\"GRANT USE SCHEMA ON SCHEMA {catalog}.simulator TO `{principal}`\",\n",
+        "        f\"GRANT SELECT  ON SCHEMA {catalog}.simulator TO `{principal}`\",\n",
+        "    ]\n",
+        "    ok = err = 0\n",
+        "    for stmt in stmts:\n",
+        "        try:\n",
+        "            spark.sql(stmt)\n",
+        "            ok += 1\n",
+        "        except Exception as exc:  # noqa: BLE001 (schema may not exist in this catalog)\n",
+        "            err += 1\n",
+        "            print(f\"     ⚠ {stmt} → {exc}\")\n",
+        "    print(f\"     {ok} grants ok, {err} skipped\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Step 1 — probe each endpoint to generate audit events"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "needs_fix: List[str] = []\n",
+        "for ep in ENDPOINTS:\n",
+        "    try:\n",
+        "        w.serving_endpoints.get(ep)\n",
+        "    except ResourceDoesNotExist:\n",
+        "        print(f\"➖ {ep}: endpoint does not exist in this workspace — skipping\")\n",
+        "        continue\n",
+        "    print(f\"→ probing {ep} ...\")\n",
+        "    if probe(ep):\n",
+        "        print(f\"  ❌ perm error confirmed — will fix\")\n",
+        "        needs_fix.append(ep)\n",
+        "    else:\n",
+        "        print(f\"  ✅ endpoint already works — no action needed\")\n",
+        "\n",
+        "print()\n",
+        "print(f\"Endpoints needing fix: {needs_fix or 'none — you can stop here'}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Step 2 — wait for audit log, discover runtime SPs"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "discovered: Set[str] = set()\n",
+        "if needs_fix:\n",
+        "    deadline = time.time() + MAX_WAIT\n",
+        "    poll_every = 30  # seconds\n",
+        "    attempt = 0\n",
+        "    while time.time() < deadline:\n",
+        "        attempt += 1\n",
+        "        # Look back ~10 minutes to be generous on audit-log lag drift.\n",
+        "        sps = discover_runtime_sps(CATALOG, \"ai\", since_seconds=600)\n",
+        "        new = sps - discovered\n",
+        "        discovered |= sps\n",
+        "        if new:\n",
+        "            print(f\"  [attempt {attempt}] +{len(new)} new SP(s): {sorted(new)}\")\n",
+        "        if len(discovered) >= len(needs_fix):\n",
+        "            # Heuristic: one SP per endpoint; if we have at least that many,\n",
+        "            # we've probably caught them all.  We still poll a bit more in\n",
+        "            # case audit-log ingestion is racing us.\n",
+        "            print(f\"  found {len(discovered)} SP(s) — likely complete\")\n",
+        "            break\n",
+        "        time.sleep(poll_every)\n",
+        "    else:\n",
+        "        print(f\"  ⚠\\ufe0f  wait budget ({MAX_WAIT}s) exhausted; proceeding with what we have\")\n",
+        "\n",
+        "print()\n",
+        "print(f\"Discovered runtime SPs: {sorted(discovered) or 'NONE — nothing to grant'}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Step 3 — grant the SPs the required UC perms"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "for sp in sorted(discovered):\n",
+        "    print(f\"→ granting perms to {sp}\")\n",
+        "    grant_perms(CATALOG, sp)"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Step 4 — verify by re-invoking each endpoint"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "still_broken: List[str] = []\n",
+        "for ep in needs_fix:\n",
+        "    print(f\"→ verifying {ep} ...\")\n",
+        "    if probe(ep):\n",
+        "        print(f\"  ❌ still failing\")\n",
+        "        still_broken.append(ep)\n",
+        "    else:\n",
+        "        print(f\"  ✅ now works\")\n",
+        "\n",
+        "print()\n",
+        "if still_broken:\n",
+        "    print(f\"⚠\\ufe0f  still broken: {still_broken}\")\n",
+        "    print(\"   This usually means either (a) the new audit events have not yet\")\n",
+        "    print(\"   propagated; re-run this notebook in ~5 minutes, or (b) the runtime\")\n",
+        "    print(\"   SP needs different perms than the standard bundle this script grants.\")\n",
+        "else:\n",
+        "    print(\"✅ all probed endpoints now succeed.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    }
+  ],
+  "metadata": {
+    "application/vnd.databricks.v1+notebook": {
+      "computePreferences": null,
+      "dashboards": [],
+      "environmentMetadata": null,
+      "language": "python",
+      "notebookMetadata": {
+        "pythonIndentUnit": 2
+      },
+      "notebookName": "fix_agent_perms",
+      "widgets": {}
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/utils/lakebase_autoscale.py b/utils/lakebase_autoscale.py
new file mode 100644
index 0000000..ba964e8
--- /dev/null
+++ b/utils/lakebase_autoscale.py
@@ -0,0 +1,383 @@
+"""Helpers for Lakebase Autoscaling synced tables.
+
+The Python SDK (``databricks-sdk==0.102.0`` at time of writing) wraps the
+*Provisioned* synced-table API (``POST /api/2.0/database/synced_tables``) via
+``w.database.create_synced_database_table``, but does NOT yet wrap the
+*Autoscaling*-specific endpoint:
+
+    POST /api/2.0/postgres/synced_tables?synced_table_id={uc_name}
+    {
+      "spec": {
+        "source_table_full_name":  "...",
+        "branch":                  "projects/{project_id}/branches/{branch_id}",
+        "primary_key_columns":     [...],
+        "postgres_database":       "...",
+        "scheduling_policy":       "SNAPSHOT|TRIGGERED|CONTINUOUS",
+        "create_database_objects_if_missing": true
+      }
+    }
+
+This module wraps that endpoint through the SDK's raw-REST escape hatch
+(``w.api_client.do``) so stages can target Autoscaling projects with the
+same ergonomics as the Provisioned SDK.
+
+When Databricks ships the Autoscaling synced-table API in the Python SDK
+(tracked in databricks/terraform-provider-databricks#5456), swap these to the
+official wrappers and delete this module.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from databricks.sdk import WorkspaceClient
+
+POSTGRES_SYNCED_TABLES_PATH = "/api/2.0/postgres/synced_tables"
+POSTGRES_DATABASES_PATH = "/api/2.0/postgres/databases"
+
+
+def _resource_path(synced_table_name: str) -> str:
+    return f"{POSTGRES_SYNCED_TABLES_PATH}/{synced_table_name}"
+
+
+def _is_not_found(exc: BaseException) -> bool:
+    msg = str(exc)
+    return (
+        "NOT_FOUND" in msg
+        or "RESOURCE_DOES_NOT_EXIST" in msg
+        or "does not exist" in msg.lower()
+        or " 404" in msg
+        or msg.endswith("404")
+    )
+
+
+def _is_already_exists(exc: BaseException) -> bool:
+    msg = str(exc).lower()
+    return (
+        "alreadyexists" in msg.replace(" ", "")
+        or "already exists" in msg
+        or "duplicate" in msg
+    )
+
+
+def _is_not_found_v2(exc: BaseException) -> bool:
+    """Slightly broader than ``_is_not_found`` \u2014 also matches the SDK's
+    ``NotFound`` exception, which formats as ``"NotFound: ..."`` (mixed case)
+    and ``"Database not found"`` style messages."""
+    msg = str(exc).lower()
+    return (
+        "not_found" in msg
+        or "resource_does_not_exist" in msg
+        or "does not exist" in msg
+        or "not found" in msg
+        or " 404" in msg
+        or msg.endswith("404")
+    )
+
+
+def get_autoscale_synced_table(
+    w: WorkspaceClient, synced_table_name: str
+) -> dict[str, Any] | None:
+    """GET a synced table by its fully-qualified UC name.
+
+    Returns the API response dict, or ``None`` if no synced table exists at
+    that UC name.  Re-raises any other error.
+    """
+    try:
+        return w.api_client.do("GET", _resource_path(synced_table_name))
+    except Exception as e:
+        if _is_not_found(e):
+            return None
+        raise
+
+
+def create_autoscale_synced_table(
+    w: WorkspaceClient,
+    *,
+    synced_table_name: str,
+    source_table_full_name: str,
+    primary_key_columns: list[str],
+    branch: str,
+    postgres_database: str,
+    scheduling_policy: str = "CONTINUOUS",
+    create_database_objects_if_missing: bool = True,
+) -> dict[str, Any]:
+    """Create a new synced table targeting a Lakebase Autoscaling branch.
+
+    Args:
+        synced_table_name: Fully-qualified UC name for the synced table,
+            e.g. ``"{CATALOG}.recommender.pg_recommendations"``.  The synced
+            table is created in the same Unity Catalog the caller has
+            CREATE_TABLE on (typically the user catalog, NOT the Lakebase-
+            managed catalog).
+        source_table_full_name: Fully-qualified UC name of the source Delta
+            table.
+        primary_key_columns: Column names that uniquely identify a row.
+        branch: Resource path of the destination Lakebase branch, in the form
+            ``"projects/{project_id}/branches/{branch_id}"``.  For projects
+            created with default settings use ``branch_id="production"``.
+        postgres_database: Logical Postgres database name within the branch.
+            Use ``"databricks_postgres"`` for the default DB created with a
+            new project, or any other DB created via
+            ``w.postgres.create_database()``.
+        scheduling_policy: One of ``"SNAPSHOT"``, ``"TRIGGERED"`` or
+            ``"CONTINUOUS"``.  Triggered/Continuous require Change Data Feed
+            enabled on the source Delta table.
+        create_database_objects_if_missing: When True, the sync pipeline
+            creates the destination Postgres schema if it doesn't exist.
+    """
+    return w.api_client.do(
+        method="POST",
+        path=POSTGRES_SYNCED_TABLES_PATH,
+        query={"synced_table_id": synced_table_name},
+        body={
+            "spec": {
+                "source_table_full_name": source_table_full_name,
+                "branch": branch,
+                "primary_key_columns": primary_key_columns,
+                "postgres_database": postgres_database,
+                "scheduling_policy": scheduling_policy,
+                "create_database_objects_if_missing": create_database_objects_if_missing,
+            }
+        },
+    )
+
+
+def get_or_create_autoscale_synced_table(
+    w: WorkspaceClient,
+    *,
+    synced_table_name: str,
+    source_table_full_name: str,
+    primary_key_columns: list[str],
+    branch: str,
+    postgres_database: str,
+    scheduling_policy: str = "CONTINUOUS",
+    create_database_objects_if_missing: bool = True,
+) -> dict[str, Any]:
+    """Idempotent create-or-reuse.
+
+    Returns the existing synced table if one already lives at
+    ``synced_table_name``, otherwise creates and returns a new one.
+
+    Note: this helper does NOT pre-drop a stale plain Delta table that may be
+    occupying the destination UC name (see the defensive ``DROP TABLE IF
+    EXISTS`` pattern in the Provisioned stages for that case).  If the
+    destination name holds a stale Delta but no synced table, the GET will
+    return ``None`` and the POST will fail with ``AlreadyExists``.  Callers
+    that need that defence should wrap this helper with the same drop-then-
+    create pattern used in ``stages/lakebase.ipynb``.
+    """
+    existing = get_autoscale_synced_table(w, synced_table_name)
+    if existing is not None:
+        return existing
+    return create_autoscale_synced_table(
+        w,
+        synced_table_name=synced_table_name,
+        source_table_full_name=source_table_full_name,
+        primary_key_columns=primary_key_columns,
+        branch=branch,
+        postgres_database=postgres_database,
+        scheduling_policy=scheduling_policy,
+        create_database_objects_if_missing=create_database_objects_if_missing,
+    )
+
+
+def delete_autoscale_synced_table(
+    w: WorkspaceClient, synced_table_name: str
+) -> bool:
+    """Best-effort delete.  Returns True if a synced table was deleted,
+    False if it wasn't there to begin with.  Re-raises non-404 errors."""
+    try:
+        w.api_client.do("DELETE", _resource_path(synced_table_name))
+        return True
+    except Exception as e:
+        if _is_not_found(e):
+            return False
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Postgres logical databases inside an Autoscaling project
+# ---------------------------------------------------------------------------
+#
+# An Autoscaling project ships with a default ``databricks_postgres`` database
+# in its default ``production`` branch.  For the consolidated-Lakebase pattern
+# (one project, per-component DBs) we need additional logical databases
+# (``caspers_refund``, ``caspers_complaint``, …) inside the same project.
+#
+# Important: databases hang off **branches**, not projects directly.
+# Resource shape:
+#
+#   Project:  projects/{project_id}
+#   Branch:   projects/{project_id}/branches/{branch_id}
+#   Database: projects/{project_id}/branches/{branch_id}/databases/{database_id}
+#
+# (early prototypes here used `projects/{project_id}/databases/{database_id}`
+# which the server rejects with `NotFound: No API found for ...`)
+#
+# We use ``w.postgres.{create,get,delete}_database`` directly \u2014 the SDK has
+# wrapped these as of databricks-sdk 0.102+.
+
+
+def _database_resource_name(
+    project_id: str, database_id: str, *, branch_id: str = "production"
+) -> str:
+    return f"projects/{project_id}/branches/{branch_id}/databases/{database_id}"
+
+
+def get_current_user_role_path(
+    w: WorkspaceClient, *, project_id: str, branch_id: str = "production"
+) -> str:
+    """Return the full resource path of the current user's auto-created role
+    in ``projects/{project_id}/branches/{branch_id}``.
+
+    The Lakebase Autoscale ``create_database`` endpoint requires
+    ``spec.role`` to be set to the full resource path of an existing role,
+    not the bare role name.  When the deploying user provisions a project,
+    a role is auto-created for them with id = ``{localpart-of-email}``
+    where dots are replaced with hyphens (e.g. ``alice.smith@example.com``
+    -> ``alice-smith``).  We try that direct construction first and fall
+    back to listing roles if the slug guess doesn't match.
+
+    Raises ``RuntimeError`` if no role can be resolved.
+    """
+    branch_path = f"projects/{project_id}/branches/{branch_id}"
+    me = w.current_user.me().user_name or ""
+    local = me.split("@", 1)[0]
+    slug = local.replace(".", "-").replace("_", "-").lower()
+    candidate = f"{branch_path}/roles/{slug}"
+    try:
+        w.postgres.get_role(name=candidate)
+        return candidate
+    except Exception:
+        pass
+    # Fallback: scan all roles in the branch for one whose tail matches the slug,
+    # or whose spec.postgres_role / membership identifies the current user.
+    for r in w.postgres.list_roles(parent=branch_path):
+        if r.name and r.name.rsplit("/", 1)[-1] == slug:
+            return r.name
+    # Last resort: a fresh single-user project usually has exactly one role; use it.
+    roles = list(w.postgres.list_roles(parent=branch_path))
+    if len(roles) == 1 and roles[0].name:
+        return roles[0].name
+    raise RuntimeError(
+        f"Could not resolve current-user role for {me!r} in {branch_path}: "
+        f"tried {candidate!r} (got 404) and scanning {len(roles)} role(s) by slug."
+    )
+
+
+def get_postgres_database(
+    w: WorkspaceClient,
+    *,
+    project_id: str,
+    database_id: str,
+    branch_id: str = "production",
+) -> dict[str, Any] | None:
+    """GET a Postgres database within a project branch.  Returns ``None``
+    if absent.  Re-raises any non-404 error."""
+    name = _database_resource_name(project_id, database_id, branch_id=branch_id)
+    try:
+        db = w.postgres.get_database(name=name)
+        return db.as_dict() if hasattr(db, "as_dict") else dict(db)  # type: ignore[arg-type]
+    except Exception as e:
+        if _is_not_found_v2(e):
+            return None
+        raise
+
+
+def create_postgres_database(
+    w: WorkspaceClient,
+    *,
+    project_id: str,
+    database_id: str,
+    branch_id: str = "production",
+    owner_role: str | None = None,
+) -> dict[str, Any]:
+    """Create a Postgres database in ``projects/{project_id}/branches/{branch_id}``.
+
+    ``database_id`` becomes the resource id AND the Postgres-side database
+    name; per the SDK doc it must be 4-63 chars and RFC-1123 DNS-safe
+    (alphanumerics + hyphens, NO underscores).
+
+    ``owner_role`` is the full resource path of an existing Postgres role
+    (``projects/{p}/branches/{b}/roles/{r}``).  If ``None``, defaults to the
+    current user's auto-created role via :func:`get_current_user_role_path`.
+
+    Raises on any non-``AlreadyExists`` error.  Use
+    :func:`get_or_create_postgres_database` for idempotent create-or-reuse.
+    """
+    from databricks.sdk.service.postgres import Database, DatabaseDatabaseSpec
+
+    parent = f"projects/{project_id}/branches/{branch_id}"
+    if owner_role is None:
+        owner_role = get_current_user_role_path(
+            w, project_id=project_id, branch_id=branch_id,
+        )
+    # The server requires BOTH spec.postgres_database (the Postgres-side
+    # name) AND spec.role (the full resource path of the owner role).  An
+    # empty spec is rejected with "Field 'database' is required and must
+    # contain at least one subfield with a non-default value".
+    w.postgres.create_database(
+        parent=parent,
+        database=Database(
+            spec=DatabaseDatabaseSpec(
+                postgres_database=database_id,
+                role=owner_role,
+            )
+        ),
+        database_id=database_id,
+    )
+    # create_database returns a CreateDatabaseOperation (Google LRO wrapper)
+    # without an .as_dict() method.  Rather than poll for completion (creates
+    # finalise in milliseconds for our use case), we return a synthetic dict
+    # with the resource name so the caller can register it with uc_state.
+    return {
+        "name": _database_resource_name(
+            project_id, database_id, branch_id=branch_id
+        ),
+        "spec": {"postgres_database": database_id, "role": owner_role},
+    }
+
+
+def get_or_create_postgres_database(
+    w: WorkspaceClient,
+    *,
+    project_id: str,
+    database_id: str,
+    branch_id: str = "production",
+    owner_role: str | None = None,
+) -> tuple[dict[str, Any], bool]:
+    """Idempotent create.
+
+    Returns ``(database_dict, created)`` where ``created`` is True when the
+    POST actually ran and False when an existing database was reused.
+
+    Note: ``database_id`` must be RFC-1123 DNS-safe (a-z, 0-9, hyphens;
+    no underscores) per the Lakebase Autoscale API.
+    """
+    existing = get_postgres_database(
+        w, project_id=project_id, database_id=database_id, branch_id=branch_id,
+    )
+    if existing is not None:
+        return existing, False
+    try:
+        return (
+            create_postgres_database(
+                w,
+                project_id=project_id,
+                database_id=database_id,
+                branch_id=branch_id,
+                owner_role=owner_role,
+            ),
+            True,
+        )
+    except Exception as e:
+        if not _is_already_exists(e):
+            raise
+        # Lost a race with a concurrent create \u2014 refetch and treat as reuse.
+        refetched = get_postgres_database(
+            w, project_id=project_id, database_id=database_id, branch_id=branch_id,
+        )
+        if refetched is None:
+            raise
+        return refetched, False
diff --git a/utils/prompt_registry.py b/utils/prompt_registry.py
new file mode 100644
index 0000000..e559378
--- /dev/null
+++ b/utils/prompt_registry.py
@@ -0,0 +1,268 @@
+"""
+prompt_registry.py
+==================
+
+Helper for registering Casper's Kitchens agent prompts in the MLflow Prompt
+Registry under Unity Catalog.
+
+All prompts live in ``{catalog}.prompts.<name>`` to mirror the
+``{catalog}.evaluations`` schema convention used for eval datasets.
+
+Cleanup
+-------
+Prompts are dropped automatically by ``DROP CATALOG ... CASCADE`` in
+``destroy.ipynb``, so they don't need to be tracked in ``uc_state``.
+
+API
+---
+``register_prompt_uc(spark, catalog, name, template, ...)`` registers a new
+prompt version, sets the ``production`` alias to it, and returns the
+``prompts:/<full_name>@production`` URI. **Content-aware** by default — if
+the template is byte-identical to the current ``@production`` version, no
+new version is created and the alias is left as-is. Pass ``force=True`` to
+always create a new version.
+
+``load_prompt_template(catalog, name, ...)`` loads a registered prompt and
+returns the template string for use in agent code or API calls.
+"""
+
+from typing import Optional
+
+
+_DEFAULT_SCHEMA = "prompts"
+_DEFAULT_ALIAS = "production"
+
+
+def _use_uc_registry() -> None:
+    """Point MLflow's registry client at Unity Catalog.
+
+    Without this, ``mlflow.genai.register_prompt`` / ``load_prompt`` /
+    ``search_prompts`` go to the workspace MLflow registry (the runtime
+    default on most Databricks workspaces), where 3-part names like
+    ``catalog.schema.name`` are treated as opaque strings and the prompts
+    never show up in Catalog Explorer or in UC-filtered searches.
+
+    Idempotent and cheap — safe to call at the top of every helper.
+    """
+    import mlflow
+
+    mlflow.set_registry_uri("databricks-uc")
+
+
+def _ensure_schema(spark, catalog: str, schema: str = _DEFAULT_SCHEMA) -> None:
+    """Idempotently create ``{catalog}.{schema}`` if missing.
+
+    Requires the caller to have ``CREATE FUNCTION``, ``EXECUTE``, and
+    ``MANAGE`` privileges on the schema for prompt-registry reads/writes.
+    """
+    spark.sql(
+        f"CREATE SCHEMA IF NOT EXISTS `{catalog}`.`{schema}` "
+        f"COMMENT 'Casper''s Kitchens MLflow Prompt Registry'"
+    )
+
+
+def register_prompt_uc(
+    spark,
+    catalog: str,
+    name: str,
+    template: str,
+    *,
+    schema: str = _DEFAULT_SCHEMA,
+    alias: str = _DEFAULT_ALIAS,
+    commit_message: str = "",
+    tags: Optional[dict] = None,
+    force: bool = False,
+) -> str:
+    """Register a prompt under ``{catalog}.{schema}.{name}`` and set the alias.
+
+    By default this is **content-aware**: if the template is byte-identical to
+    the current ``@{alias}`` version, no new version is created and the alias
+    is left as-is. Pass ``force=True`` to always create a new version (e.g. to
+    refresh tags). Without this, every deploy unconditionally bumped the
+    version even when nothing about the prompt had changed.
+
+    Parameters
+    ----------
+    spark : SparkSession
+        Used only to ``CREATE SCHEMA IF NOT EXISTS`` on first call.
+    catalog : str
+        UC catalog (typically the ``CATALOG`` widget value).
+    name : str
+        Short prompt name (e.g. ``refund_system``).
+    template : str
+        The prompt template string.  May contain ``{{var}}`` placeholders.
+    schema : str
+        UC schema for prompts.  Defaults to ``prompts``.
+    alias : str
+        Alias to point at the new version.  Defaults to ``production``.
+    commit_message : str
+        Optional human-readable commit message.
+    tags : dict, optional
+        Optional tags to attach to the new version.
+    force : bool
+        If True, always create a new version even when the template is
+        unchanged. Defaults to False.
+
+    Returns
+    -------
+    str
+        The prompt URI: ``prompts:/{catalog}.{schema}.{name}@{alias}``.
+    """
+    import mlflow
+
+    _use_uc_registry()
+    _ensure_schema(spark, catalog, schema)
+    full_name = f"{catalog}.{schema}.{name}"
+    uri = f"prompts:/{full_name}@{alias}"
+
+    # Skip-if-same: read the current @alias version's template and compare.
+    # Cheap (one registry GET) and avoids a versions-explosion across deploys.
+    if not force:
+        try:
+            current = mlflow.genai.load_prompt(name_or_uri=uri)
+            if current is not None and current.template == template:
+                print(f"  \u267b  {full_name}  v{current.version}  alias={alias} (no change)")
+                return uri
+        except Exception:
+            # No alias yet, no prompt yet, or any registry hiccup — fall
+            # through to register the first version.
+            pass
+
+    prompt = mlflow.genai.register_prompt(
+        name=full_name,
+        template=template,
+        commit_message=commit_message
+        or "Registered from Casper's Kitchens stage",
+        tags=tags or {},
+    )
+    mlflow.genai.set_prompt_alias(
+        name=full_name, alias=alias, version=prompt.version
+    )
+    print(f"  \u2705 {full_name}  v{prompt.version}  alias={alias}")
+    return uri
+
+
+def load_prompt_template(
+    catalog: str,
+    name: str,
+    *,
+    schema: str = _DEFAULT_SCHEMA,
+    alias: str = _DEFAULT_ALIAS,
+) -> str:
+    """Load a registered prompt and return its template string.
+
+    Use this in agent stages to read the deployed template back out of the
+    registry — e.g. to populate the ``instructions`` field of a Multi-Agent
+    Supervisor or Knowledge Assistant config.
+    """
+    import mlflow
+
+    _use_uc_registry()
+    full_name = f"{catalog}.{schema}.{name}"
+    prompt = mlflow.genai.load_prompt(
+        name_or_uri=f"prompts:/{full_name}@{alias}"
+    )
+    return prompt.template
+
+
+def seed_prompt_history(
+    spark,
+    catalog: str,
+    name: str,
+    historical: list,
+    current: dict,
+    *,
+    schema: str = _DEFAULT_SCHEMA,
+    alias: str = _DEFAULT_ALIAS,
+) -> str:
+    """Seed historical prompt versions on first deploy, register the current
+    production version on every deploy.
+
+    Intended for demo / runbook contexts where you want the MLflow Prompt
+    Registry UI to show *multiple* versions of the same prompt (so reviewers
+    can see diffs and rollback workflows) — not just the single version that
+    a fresh deploy would create.
+
+    Honesty note: the historical versions are **seeded demo history**, not a
+    real engineering log. Tag them as such (we set ``is_demo_seed="true"``
+    on every seeded version automatically) so anyone auditing the registry
+    later can tell synthetic baselines from real iterations.
+
+    Idempotency rules:
+
+    - **First-ever deploy** (no ``@{alias}`` exists): register each historical
+      version in order with ``force=True``, then register the current version
+      and set the ``@{alias}`` alias to it.
+    - **Re-deploy** (``@{alias}`` already exists): skip historical seeding
+      entirely; re-register the current version via the content-aware
+      ``register_prompt_uc`` (no-ops if the current template is unchanged).
+
+    Without the existence check the version count would explode every deploy.
+
+    Parameters
+    ----------
+    spark : SparkSession
+        Used only to ``CREATE SCHEMA IF NOT EXISTS`` on first call.
+    catalog : str
+        UC catalog.
+    name : str
+        Short prompt name (e.g. ``refund_system``).
+    historical : list of dict
+        Older versions to seed on first deploy. Each item is
+        ``{"template": str, "commit_message": str, "tags": dict}``. Order is
+        chronological — element 0 becomes v1, element 1 becomes v2, etc.
+    current : dict
+        The current production version, same shape as a ``historical`` item.
+        Always registered (content-aware), and gets the ``@{alias}`` alias.
+
+    Returns
+    -------
+    str
+        The prompt URI: ``prompts:/{catalog}.{schema}.{name}@{alias}``.
+    """
+    import mlflow
+
+    _use_uc_registry()
+    _ensure_schema(spark, catalog, schema)
+    full_name = f"{catalog}.{schema}.{name}"
+    alias_uri = f"prompts:/{full_name}@{alias}"
+
+    # Existence check: does this prompt already have an @alias?  If so, the
+    # historical versions have already been seeded on a prior deploy (or
+    # someone manually set the alias).  Skip seeding to avoid version
+    # explosion on re-deploys.
+    has_production = False
+    try:
+        existing = mlflow.genai.load_prompt(name_or_uri=alias_uri)
+        has_production = existing is not None
+    except Exception:
+        has_production = False
+
+    if not has_production and historical:
+        print(f"  Seeding {len(historical)} demo-history version(s) for {full_name}")
+        for i, v in enumerate(historical):
+            seed_tags = {**(v.get("tags") or {}), "is_demo_seed": "true"}
+            register_prompt_uc(
+                spark=spark,
+                catalog=catalog,
+                name=name,
+                template=v["template"],
+                commit_message=v.get("commit_message") or f"[demo history v{i + 1}]",
+                tags=seed_tags,
+                schema=schema,
+                alias=alias,  # alias bounces along, ends up on the last seed; final register below overwrites it
+                force=True,
+            )
+
+    # Always (re)register the current production version.  Content-aware skip
+    # means no-op when the template hasn't changed since last deploy.
+    return register_prompt_uc(
+        spark=spark,
+        catalog=catalog,
+        name=name,
+        template=current["template"],
+        commit_message=current.get("commit_message") or "Current production version",
+        tags=current.get("tags"),
+        schema=schema,
+        alias=alias,
+    )
diff --git a/utils/status.py b/utils/status.py
new file mode 100644
index 0000000..754d1c1
--- /dev/null
+++ b/utils/status.py
@@ -0,0 +1,105 @@
+"""Small print helpers for stage / job status output.
+
+Why this module exists:
+
+Stages and helpers across the repo print operator-visible status lines like
+``"✅ Created warehouse: ..."`` or ``"♻️ Reusing existing project"``.  Emojis
+render fine in the Databricks notebook UI and a modern terminal, but show up
+as garbled boxes in some CI log viewers and screen readers.
+
+Using ``status.ok(...)`` / ``status.reuse(...)`` instead of bare
+``print("✅ ...")`` localizes the rendering decision:
+
+- In the default state, output is identical to today's emoji prints.
+- Set ``CASPERS_NO_EMOJI=1`` (or ``true`` / ``yes`` / ``on``) in the job
+  environment to swap emojis for ASCII tags (``[OK]``, ``[REUSE]``, ``[WARN]``,
+  ``[FAIL]``, ``[RUN]``, ``[INFO]``, ``[SKIP]``, ``[SEARCH]``, ``[DROP]``).
+
+The helpers are intentionally tiny and free of any Databricks-specific
+dependency so they can be imported from notebooks, app code, and unit tests.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import IO, Optional
+
+_ASCII_ENV_VAR = "CASPERS_NO_EMOJI"
+
+# Single source of truth for the (emoji, ascii-tag) pair per status level.
+# Add a new level here and a one-line wrapper below if you need it.
+_LEVELS: dict[str, tuple[str, str]] = {
+    "ok":     ("✅",  "[OK]"),
+    "reuse":  ("♻️",  "[REUSE]"),
+    "warn":   ("⚠️",  "[WARN]"),
+    "fail":   ("❌",  "[FAIL]"),
+    "run":    ("🚀",  "[RUN]"),
+    "info":   ("ℹ️",  "[INFO]"),
+    "skip":   ("⏭️",  "[SKIP]"),
+    "search": ("🔎",  "[SEARCH]"),
+    "drop":   ("🗑️",  "[DROP]"),
+}
+
+
+def _ascii_mode() -> bool:
+    return os.environ.get(_ASCII_ENV_VAR, "").lower() in ("1", "true", "yes", "on")
+
+
+def _prefix(level: str) -> str:
+    emoji, ascii_tag = _LEVELS[level]
+    return ascii_tag if _ascii_mode() else emoji
+
+
+def _emit(level: str, msg: str, *, file: Optional[IO[str]] = None) -> None:
+    print(f"{_prefix(level)} {msg}", file=file or sys.stdout, flush=True)
+
+
+def ok(msg: str) -> None:
+    """Success / created.  Replaces ``print("✅ ...")``."""
+    _emit("ok", msg)
+
+
+def reuse(msg: str) -> None:
+    """Idempotent reuse of an existing resource.  Replaces ``print("♻️ ...")``."""
+    _emit("reuse", msg)
+
+
+def warn(msg: str) -> None:
+    """Non-fatal warning.  Replaces ``print("⚠️ ...")``.  Goes to stderr."""
+    _emit("warn", msg, file=sys.stderr)
+
+
+def fail(msg: str) -> None:
+    """Fatal-ish error message.  Replaces ``print("❌ ...")``.  Goes to stderr."""
+    _emit("fail", msg, file=sys.stderr)
+
+
+def run(msg: str) -> None:
+    """Triggered an async job / pipeline run.  Replaces ``print("🚀 ...")``."""
+    _emit("run", msg)
+
+
+def info(msg: str) -> None:
+    """Neutral progress / configuration line.  Replaces ``print("ℹ️ ...")``."""
+    _emit("info", msg)
+
+
+def skip(msg: str) -> None:
+    """Step intentionally skipped.  Replaces ``print("⏭️ ...")``."""
+    _emit("skip", msg)
+
+
+def search(msg: str) -> None:
+    """Scanning / sweep step.  Replaces ``print("🔎 ...")``."""
+    _emit("search", msg)
+
+
+def drop(msg: str) -> None:
+    """Dropped a stale resource.  Replaces ``print("🗑️ ...")``."""
+    _emit("drop", msg)
+
+
+__all__ = [
+    "ok", "reuse", "warn", "fail", "run", "info", "skip", "search", "drop",
+]
diff --git a/utils/uc_state/state_manager.py b/utils/uc_state/state_manager.py
index d864e1a..b74d3a3 100644
--- a/utils/uc_state/state_manager.py
+++ b/utils/uc_state/state_manager.py
@@ -7,8 +7,6 @@
 import uuid
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Union
-from databricks.sdk import WorkspaceClient
-from databricks.sdk.service.catalog import CatalogInfo, SchemaInfo
 import logging
 
 logger = logging.getLogger(__name__)
@@ -16,22 +14,27 @@
 
 class UCState:
     """Unity Catalog-based state management for Databricks resources."""
-    
+
     def __init__(self, catalog: str, schema: str = "_internal_state", table: str = "resources"):
         """
         Initialize UC-State manager.
-        
+
         Args:
             catalog: The catalog name to store state in
-            schema: Schema name (default: _internal_state)  
+            schema: Schema name (default: _internal_state)
             table: Table name (default: resources)
         """
         self.catalog = catalog
         self.schema = schema
         self.table = table
         self.full_table_name = f"{catalog}.{schema}.{table}"
+        # Lazy-import the SDK so `from uc_state import add` doesn't pay the
+        # WorkspaceClient discovery cost in notebooks that only import the
+        # module (e.g. for type hints or convenience functions) without ever
+        # constructing a UCState.
+        from databricks.sdk import WorkspaceClient
         self.w = WorkspaceClient()
-        
+
         self._ensure_catalog_schema_table()
     
     def _ensure_catalog_schema_table(self):
@@ -111,7 +114,14 @@ def add(self, resource_type: str, resource_obj: Any) -> str:
         else:
             # Handle primitive types or dictionaries
             resource_data = json.dumps(resource_obj, default=str)
-        
+
+        # SQL-escape single quotes in the JSON payload before string interpolation.
+        # JSON does not escape `'`, so descriptions like "Casper's Ops Dashboard"
+        # would break the f-string-built INSERT below with PARSE_SYNTAX_ERROR
+        # ("extra input 'Ops'" etc.).  Doubling the apostrophe is the SQL-standard
+        # escape and is safe to apply unconditionally.
+        resource_data = resource_data.replace("'", "''")
+
         insert_sql = f"""
         INSERT INTO {self.full_table_name} 
         (internal_id, resource_type, resource_data, created_at)
@@ -206,7 +216,7 @@ def remove(self, internal_id: str) -> bool:
     def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str, str]]]]:
         """
         Remove all resources from Databricks and clear state.
-        Deletion order: experiments → jobs → pipelines → multi_agent_supervisors → knowledge_assistants → genie_spaces → endpoints → vector_search_indexes → vector_search_endpoints → apps → warehouses → databasecatalogs → catalogs → databaseinstances
+        Deletion order: experiments → jobs → pipelines → multi_agent_supervisors → knowledge_assistants → genie_spaces → endpoints → vector_search_indexes → vector_search_endpoints → apps → warehouses → databasecatalogs → catalogs → postgres_projects → databaseinstances
         
         Args:
             dry_run: If True, only show what would be deleted without actually deleting
@@ -219,7 +229,14 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                 }
             }
         """
-        deletion_order = ['experiments', 'jobs', 'pipelines', 'multi_agent_supervisors', 'knowledge_assistants', 'genie_spaces', 'endpoints', 'vector_search_indexes', 'vector_search_endpoints', 'apps', 'warehouses', 'databasecatalogs', 'catalogs', 'databaseinstances']
+        # postgres_projects (Lakebase Autoscale) goes after apps so any app consuming
+        # a Lakebase endpoint is removed first, and adjacent to databaseinstances
+        # (legacy Lakebase Provisioned) for logical grouping.
+        # autoscale_synced_tables (Postgres synced tables created via
+        # `utils/lakebase_autoscale.py`) MUST be deleted before postgres_projects,
+        # otherwise the parent-project delete cascades and orphans the synced-table
+        # UC entries, which then fail their own UC drop on the catalog cascade.
+        deletion_order = ['experiments', 'jobs', 'pipelines', 'multi_agent_supervisors', 'knowledge_assistants', 'genie_spaces', 'endpoints', 'vector_search_indexes', 'vector_search_endpoints', 'apps', 'warehouses', 'databasecatalogs', 'catalogs', 'autoscale_synced_tables', 'postgres_projects', 'databaseinstances']
         results = {}
         
         for resource_type in deletion_order:
@@ -256,6 +273,10 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                     resource_name = resource_data.get('name') or resource_data.get('id', 'Unknown')
                 elif resource_type == 'databaseinstances':
                     resource_name = resource_data.get('name', 'Unknown')
+                elif resource_type == 'postgres_projects':
+                    resource_name = resource_data.get('name') or resource_data.get('project_id', 'Unknown')
+                elif resource_type == 'autoscale_synced_tables':
+                    resource_name = resource_data.get('synced_table_name') or resource_data.get('name', 'Unknown')
                 elif resource_type == 'databasecatalogs':
                     resource_name = resource_data if isinstance(resource_data, str) else resource_data.get('name', 'Unknown')
                 elif resource_type == 'catalogs':
@@ -316,7 +337,13 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                         agent_id = resource_data.get('agent_id')
                         endpoint_name = resource_data.get('endpoint_name')
                         if agent_id:
-                            for api_path in ["/api/2.0/knowledge-assistants", "/api/2.0/multi-agent-supervisors"]:
+                            # Try v2.1 KA first (current), then v2.0 KA (legacy, in case the
+                            # resource was created by an older deploy), then MAS.
+                            for api_path in [
+                                "/api/2.1/knowledge-assistants",
+                                "/api/2.0/knowledge-assistants",
+                                "/api/2.0/multi-agent-supervisors",
+                            ]:
                                 try:
                                     self.w.api_client.do("DELETE", f"{api_path}/{agent_id}")
                                     logger.info(f"Deleted agent {agent_id} via {api_path}")
@@ -346,6 +373,23 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                         tile_id = resource_data.get('tile_id')
                         agent_id = resource_data.get('agent_id')
                         agent_name = resource_data.get('name')
+                        # For KAs, prefer the typed v2.1 delete endpoint (DELETE /api/2.1/knowledge-assistants/{id});
+                        # for MAS, the typed endpoint is still v2.0. Fall back to the Tiles API in both cases
+                        # for legacy resources that may not be reachable through the typed paths.
+                        if resource_type == 'knowledge_assistants':
+                            typed_paths = ["/api/2.1/knowledge-assistants", "/api/2.0/knowledge-assistants"]
+                        else:
+                            typed_paths = ["/api/2.0/multi-agent-supervisors"]
+                        for ref in [tile_id, agent_id]:
+                            if ref and not deletion_successful:
+                                for typed_path in typed_paths:
+                                    try:
+                                        self.w.api_client.do("DELETE", f"{typed_path}/{ref}")
+                                        logger.info(f"Deleted {resource_type} {ref} via {typed_path}")
+                                        deletion_successful = True
+                                        break
+                                    except Exception:
+                                        pass
                         for ref in [tile_id, agent_id, agent_name]:
                             if ref and not deletion_successful:
                                 try:
@@ -355,7 +399,7 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                                 except Exception:
                                     pass
                         if not deletion_successful:
-                            error_message = f"Could not delete via /api/2.0/tiles/ with tile_id={tile_id}, agent_id={agent_id}, or name={agent_name}"
+                            error_message = f"Could not delete via typed or tiles APIs with tile_id={tile_id}, agent_id={agent_id}, or name={agent_name}"
                     
                     elif resource_type == 'apps':
                         app_name = resource_data.get('name')
@@ -383,6 +427,45 @@ def clear_all(self, dry_run: bool = False) -> Dict[str, Dict[str, List[Dict[str,
                             deletion_successful = True
                         else:
                             error_message = "No instance name found in resource data"
+
+                    elif resource_type == 'autoscale_synced_tables':
+                        # Lakebase Autoscale synced table created via
+                        # `utils/lakebase_autoscale.create_autoscale_synced_table`.
+                        # Resource data: {synced_table_name: "<catalog>.<schema>.<table>",
+                        #                 project_id: "...", postgres_database: "..."}
+                        # Delete via the helper's DELETE; the UC table entry itself
+                        # disappears with the cascading catalog drop below.
+                        from lakebase_autoscale import delete_autoscale_synced_table  # local import; utils on sys.path
+                        synced_table_name = resource_data.get('synced_table_name') or resource_data.get('name')
+                        if synced_table_name:
+                            try:
+                                deleted = delete_autoscale_synced_table(self.w, synced_table_name)
+                                logger.info(
+                                    f"Autoscale synced table {synced_table_name}: "
+                                    f"{'deleted' if deleted else 'already gone'}"
+                                )
+                                deletion_successful = True
+                            except Exception as e:
+                                error_message = f"delete_autoscale_synced_table({synced_table_name}) failed: {e}"
+                        else:
+                            error_message = "No synced_table_name found in resource data"
+
+                    elif resource_type == 'postgres_projects':
+                        # Lakebase Autoscale project. Resource data is either:
+                        #   {project_id, name="projects/{project_id}"}  (new format from operational_lakebase)
+                        #   {name="projects/{project_id}"}              (older entries)
+                        project_resource_name = resource_data.get('name')
+                        project_id = resource_data.get('project_id')
+                        if not project_resource_name and project_id:
+                            project_resource_name = f"projects/{project_id}"
+                        if project_resource_name:
+                            # delete_project returns a DeleteProjectOperation (no .result());
+                            # purge=True performs a hard delete so the project is fully removed.
+                            self.w.postgres.delete_project(name=project_resource_name, purge=True)
+                            logger.info(f"Deleted Lakebase Autoscale project {project_resource_name}")
+                            deletion_successful = True
+                        else:
+                            error_message = "No project_id or name found in resource data"
                     
                     elif resource_type == 'databasecatalogs':
                         catalog_name = resource_data if isinstance(resource_data, str) else resource_data.get('name')