docs(app): drop runner Lakebase prerequisite after #1564 and fill Studio install gaps

The runner stages oversized configs in the Delta dq_run_configs table since
#1564, so it needs no Lakebase role or grants; remove the remaining guidance.
Also document prefix/audience bundle variables (CLI, make, PowerShell),
broad mode via --var, admin verification and role assignment for the DAB
route, prefix reuse on upgrade, and use <prefix> in Studio SQL examples.

Co-authored-by: Isaac <no-reply@databricks.com>

Author: laurencewells

app/DEPLOYMENT.md

@@ -367,7 +367,7 @@ The script requires `uv`, Node.js 18+, yarn classic v1, and Databricks CLI v1.4.
 2. `databricks bundle deploy` — provisions or updates the schemas, wheels volume, Lakebase project (+ endpoint + the app SP's Postgres role), the SQL warehouse, the task-runner job, and the Databricks App in dependency order, and applies **bundle-declared grants** via the `grants:` / `permissions:` blocks in `databricks.yml`. Stateful resources carry `lifecycle.prevent_destroy: true` so a future destroy can't drop them — see [Step 3](#step-3-stateful-storage-and-destroy-protection).
 3. `databricks bundle run` — starts the app.
 
-Remember the manual prerequisites: the [catalog grants](#the-use-catalog-prerequisite) for the app SP (`USE CATALOG`, `CREATE SCHEMA`), task-runner SP, and audience, plus [runner Lakebase role and grants](#task-runner-lakebase-access) for the current oversized-config path. Cold-start UC checks must pass before Studio is ready; they do not verify runner Lakebase access.
+Remember the manual prerequisites: the [catalog grants](#the-use-catalog-prerequisite) for the app SP (`USE CATALOG`, `CREATE SCHEMA`), task-runner SP, and audience. Cold-start UC checks must pass before Studio is ready. The task runner needs no Lakebase role or grants.
 
 > **First start**: The app runs Delta analytical and Lakebase application migrations on startup, and publishes the task-runner wheel to the UC volume. Wait for the setup checks to report that wheel publishing is ready before triggering runs. Also wait for `"Lakebase OLTP routing enabled"` before opening the UI. If Lakebase initialization fails, the app refuses to start and the Apps platform restarts the container. It never falls back to Delta-backed application state.
 
@@ -510,7 +510,7 @@ rm -rf .databricks                                          # clean local bundle
 databricks bundle deploy -p <your-profile> --force          # or force deploy
 ```
 
-**First deploy fails with `cannot create resources.postgres_roles.task_runner_sp: Project with name 'projects/<id>' not found (404)`:**
+**First deploy fails with `cannot create resources.postgres_roles.app_sp: Project with name 'projects/<id>' not found (404)`:**
 This happens on a fresh workspace right after the Lakebase project is created (eventual consistency). Re-run `make app-deploy`; the second run succeeds.
 
 **Profiler or dry-run not starting:**

app/README.md

@@ -81,9 +81,7 @@ The setup workflow applies the grants and ACL updates it has authority for, then
 
 The audience is a dedicated existing group, or `users` in DAB **broad mode** (workspace ACL `users` plus Unity Catalog `account users`, which is account-wide; the Marketplace form never accepts it). Members of `DQX_ADMIN_GROUP` or the workspace `admins` group may run setup; Unity Catalog cannot grant to `admins`, so UC grants for administrators go only to a custom admin account group, and with `admins` administrators must also be audience members to use OBO features. Per-user SQL entitlement, OAuth consent, and source-data privileges are checked for the active user, never for the group.
 
-On every cold startup, setup resolves the task-runner job's actual `run_as`, grants it `USE SCHEMA` on the main and temporary schemas, `READ VOLUME` on the wheels volume, and schema-level `SELECT` / `MODIFY` on the main schema (never `ALL PRIVILEGES`, catalog, Genie, or demo access), and verifies these plus its `USE CATALOG`. Schema grants cover current and future tables; table-specific grants alone do not satisfy setup. Runner Lakebase roles and privileges are not checked by setup.
-
-The current oversized-config staging implementation still needs a Lakebase administrator to create/map the runner's OAuth `SERVICE_PRINCIPAL` role and apply scoped grants manually. Changing that staging implementation is separate work; removing its setup checks does not remove the runtime requirement. Setup applies no automatic runner PostgreSQL grants. The Postgres username must match the resolved Jobs runner client ID; a legacy `DQX_TASK_RUNNER_POSTGRES_ROLE` override must also match. Never grant superuser membership to the runner. See [Deployment](DEPLOYMENT.md#task-runner-lakebase-access) for the UI and SQL steps.
+On every cold startup, setup resolves the task-runner job's actual `run_as`, grants it `USE SCHEMA` on the main and temporary schemas, schema-level `SELECT` on the temporary schema (how it reads OBO temp views), `READ VOLUME` on the wheels volume, and schema-level `SELECT` / `MODIFY` on the main schema (never `ALL PRIVILEGES`, catalog, Genie, or demo access), and verifies these plus its `USE CATALOG`. Schema grants cover current and future tables; table-specific grants alone do not satisfy setup. The runner needs no Lakebase access: run configs too large for job parameters are staged in the Delta `dq_run_configs` table in the main schema, which the main-schema `SELECT` / `MODIFY` grants already cover.
 
 Genie audience access requires space `CAN_RUN`, Consumer access or Databricks SQL access entitlement, parent usages, and only the five approved view plus two dimension-table grants, never whole-schema `SELECT` or access to the entitlement table. Genie uses embedded compute credentials; Studio's OBO SQL workflows additionally require SQL access entitlement and warehouse `CAN_USE`. Both DAB and Marketplace use the `genie` OAuth scope. Warehouse rebind re-runs the warehouse checks and reconciles Genie compute. See [the deployment grants reference](DEPLOYMENT.md#grants-reference).
 

docs/dqx/docs/installation.mdx

@@ -519,7 +519,7 @@ If you can't use the Marketplace, or want to customize the deployment, use the [
    - `catalog_name` — Unity Catalog catalog where the studio's schemas and volume live (must already exist).
    - `dqx_service_principal_application_id` — the task-runner SP you created in step 2.
 
-   The bundle manages its own SQL warehouse and Lakebase project. Pass the two values with `--var` in step 4; other settings can also be overridden with `--var name=value`. Two optional settings control storage and audience: `prefix` (default `dqx_studio`) derives the schema names, and `studio_user_group` (default `dqx-studio-users`, which must already exist) is the audience. With `make app-deploy` these are the `STUDIO_PREFIX=<prefix>` and `STUDIO_USER_GROUP=<group>` arguments. Set `STUDIO_USER_GROUP=users` for **broad mode**, which shares Studio with the workspace `users` group and grants Unity Catalog access to `account users` (account-wide).
+   The bundle manages its own SQL warehouse and Lakebase project. Pass the two values with `--var` in step 4; other settings can also be overridden with `--var name=value`. Two optional settings control storage and audience: `prefix` (default `dqx_studio`) derives the schema names, and `studio_user_group` (default `dqx-studio-users`, which must already exist) is the audience. With `make app-deploy` these are the `STUDIO_PREFIX=<prefix>` and `STUDIO_USER_GROUP=<group>` arguments; with the Databricks CLI pass `--var prefix=<prefix>` and `--var studio_user_group=<group>`. Set `STUDIO_USER_GROUP=users` for **broad mode**, which shares Studio with the workspace `users` group and grants Unity Catalog access to `account users` (account-wide). When you set broad mode with `--var studio_user_group=users` (or through `BUNDLE_VARS` / `-BundleVars`) instead of `STUDIO_USER_GROUP`, also pass `--var studio_uc_principal="account users"`. Catalog and prefix cannot be changed once Studio's storage exists, so choose them before the first deploy.
 
    See the [DQX Studio deployment guide](https://github.com/databrickslabs/dqx/blob/main/app/DEPLOYMENT.md#step-4-configure-databricksyml) for the full reference of each variable, including security implications of `admin_group` and when to override per target.
 
@@ -538,14 +538,16 @@ If you can't use the Marketplace, or want to customize the deployment, use the [
    GRANT USE CATALOG ON CATALOG <catalog> TO `<audience>`;
    ```
 
-   The setup wizard verifies these on every start and prints any that are still missing. With a custom `admin_group` account group, administrators receive the same catalog access as the audience; with the built-in `admins` group they must also belong to the audience group to use OBO features.
+   The setup wizard verifies these and prints the exact `GRANT` statement for any that are still missing. With a custom `admin_group` account group, also grant it `USE CATALOG`: administrators then receive the same access as the audience. With the built-in `admins` group (the default), Unity Catalog cannot grant to it, so administrators must also belong to the audience group to use OBO features.
 
 6. Start Studio:
    ```commandline
    databricks bundle run dqx-studio -p <your-profile> -t release --var catalog_name=<your-catalog> --var dqx_service_principal_application_id=<your-sp-application-id>
    ```
 
-7. Open the deployed app from the **Apps** page in your Databricks workspace.
+7. Open the deployed app from the **Apps** page as a workspace administrator (a member of `admins` or of `admin_group`). The bundle supplies the catalog, prefix, and audience, so the setup wizard shows them read-only. Run any `GRANT` statements it prints and choose **Verify again** until every step is green.
+
+8. **Assign roles**: in Studio, open **Admin Settings → Entitlements** and map your audience groups to the Author, Approver, and Viewer roles. See [Permissions & Entitlements](/docs/studio/governance/permissions-and-entitlements) for the full permission matrix.
 
 Once the catalog grants in step 5 are in place, one helper command **from the repository root** can deploy and start the prebuilt release without running `app-build`. On macOS or Linux:
 
@@ -559,6 +561,8 @@ On Windows, use the experimental PowerShell helper:
 .\make.ps1 app-deploy -Profile <your-profile> -Release -BundleVars @('catalog_name=<your-catalog>', 'dqx_service_principal_application_id=<your-sp-application-id>')
 ```
 
+To set a non-default prefix or audience, add `STUDIO_PREFIX=<prefix> STUDIO_USER_GROUP=<group|users>` to the `make` command. The PowerShell helper has no equivalent arguments: add `'prefix=<prefix>'` and `'studio_user_group=<group>'` to `-BundleVars` (broad mode also needs `'studio_uc_principal=account users'`).
+
 To build and deploy Studio from source instead, use `make app-deploy PROFILE=<profile> TARGET=<target>` on macOS or Linux. On Windows, run the experimental PowerShell helper from the repository root:
 
 ```powershell
@@ -574,7 +578,7 @@ The studio's schemas (`<prefix>`, `<prefix>_tmp`, `<prefix>_genie`, `<prefix>_de
 For the full walkthrough — including step-by-step commands, the `USE CATALOG` prerequisite, troubleshooting, and target-specific configuration — see the [DQX Studio deployment guide](https://github.com/databrickslabs/dqx/blob/main/app/DEPLOYMENT.md).
 
 <Admonition type="note" title="Hybrid storage backend">
-DQX Studio splits its data across two physical backends: high-volume append-mostly tables (`dq_validation_runs`, `dq_profiling_results`, `dq_quarantine_records`, `dq_metrics`) live in **Delta Lake** because they're written by Spark; transactional tables (rules catalog, app settings, RBAC, comments, schedule configs) live in **Lakebase Postgres** for fast row-level reads/writes from the FastAPI request handlers.
+DQX Studio splits its data across two physical backends: high-volume append-mostly tables (`dq_validation_runs`, `dq_profiling_results`, `dq_quarantine_records`, `dq_metrics`) live in **Delta Lake** because they're written by Spark; transactional tables (rules catalog, app settings, RBAC, comments, schedule configs) live in **Lakebase Postgres** for fast row-level reads/writes from the FastAPI request handlers. Run configs too large to pass as job parameters are staged in the Delta `dq_run_configs` table in the main schema, so the task runner reads and writes only Delta and needs no Lakebase role or grants.
 </Admonition>
 
 <Admonition type="note" title="First-run wheel upload">
@@ -593,7 +597,7 @@ When a new version is published to the listing, update the app from your workspa
 
 #### Using a Declarative Automation Bundle (DAB)
 
-From the repository root, fetch the new Studio release tag, check it out, and redeploy with the same catalog and task-runner service principal:
+From the repository root, fetch the new Studio release tag, check it out, and redeploy with the same catalog and task-runner service principal. If you set a non-default prefix or audience at install time, pass the same `STUDIO_PREFIX` / `STUDIO_USER_GROUP` again: the catalog and prefix are locked once storage exists.
 
 ```commandline
 git fetch --tags origin

docs/dqx/docs/reference/query_results_cookbook.mdx

@@ -912,21 +912,21 @@ Then drill into a single check to get the failing rows. Replace `<your_check_nam
 ## DQX Studio quarantine records {#dqx-studio-quarantine-records}
 
 DQX Studio stores its quarantined rows in its own `dq_quarantine_records` table in the
-Studio catalog (`<catalog>.dqx_studio.dq_quarantine_records`) — a different shape from
+Studio catalog (`<catalog>.<prefix>.dq_quarantine_records`) — a different shape from
 the tables above. `row_data` holds the full source row, and `errors` / `warnings` the
 checks each row failed, all as
 [`VARIANT`](https://docs.databricks.com/aws/en/semi-structured/variant). For an overview
 and the basic "recent rows" query, see
 [Analyse in Lakehouse](/docs/studio/running/#analyse-in-lakehouse); the recipes below go
-further. Replace `<catalog>` with your Studio catalog.
+further. Replace `<catalog>` with your Studio catalog and `<prefix>` with its storage prefix (default `dqx_studio`).
 
 **Read individual fields out of the source row:**
 
 ```sql
 SELECT quarantine_id,
        row_data:order_id::string   AS order_id,
        row_data:amount::double     AS amount
-FROM <catalog>.dqx_studio.dq_quarantine_records
+FROM <catalog>.<prefix>.dq_quarantine_records
 WHERE source_table_fqn = 'main.sales.orders';
 ```
 
@@ -939,7 +939,7 @@ SELECT q.quarantine_id,
        e.value:name::string     AS check_name,
        e.value:message::string  AS message,
        e.value:columns          AS columns
-FROM <catalog>.dqx_studio.dq_quarantine_records AS q,
+FROM <catalog>.<prefix>.dq_quarantine_records AS q,
      LATERAL variant_explode(q.errors) AS e
 WHERE q.run_id = '<run_id>';
 ```
@@ -948,7 +948,7 @@ WHERE q.run_id = '<run_id>';
 
 ```sql
 SELECT e.value:name::string AS check_name, count(*) AS failing_rows
-FROM <catalog>.dqx_studio.dq_quarantine_records AS q,
+FROM <catalog>.<prefix>.dq_quarantine_records AS q,
      LATERAL variant_explode(q.errors) AS e
 WHERE q.source_table_fqn = 'main.sales.orders'
 GROUP BY e.value:name::string
@@ -960,8 +960,8 @@ what triggered it, and whether it succeeded:
 
 ```sql
 SELECT q.quarantine_id, q.source_table_fqn, q.created_at, r.*
-FROM <catalog>.dqx_studio.dq_quarantine_records AS q
-JOIN <catalog>.dqx_studio.dq_validation_runs   AS r
+FROM <catalog>.<prefix>.dq_quarantine_records AS q
+JOIN <catalog>.<prefix>.dq_validation_runs   AS r
   ON q.run_id = r.run_id
 WHERE q.source_table_fqn = 'main.sales.orders'
 ORDER BY q.created_at DESC;

docs/dqx/docs/studio/governance/permissions-and-entitlements.mdx

@@ -84,6 +84,8 @@ Setup applies the access below, then **re-reads it to verify**. A missing grant,
 
 The Genie `SELECT` allowlist is exactly the five approved views plus `dim_dq_rules` and `dim_dq_monitored_tables`. Studio never grants whole-schema Genie `SELECT`, quarantine tables, or `dq_user_table_entitlements`. On a bundle deployment the schemas are owned by the deploying identity, so the app service principal receives an explicit privilege list that includes `MANAGE` (not `ALL_PRIVILEGES`, which makes the bundle engine drop `MANAGE`) instead. The bundle grants the administrator group only its workspace permissions; the app re-applies and verifies the administrator group's Unity Catalog grants after each deploy restart.
 
+The runner service principal needs no Lakebase role or grants. Run configs too large to pass as job parameters are staged in the Delta `dq_run_configs` table in the main schema, which its main-schema `SELECT` / `MODIFY` already covers.
+
 ### Audience, broad mode, and administrators
 
 The **audience** is a dedicated, existing workspace group. Studio never creates groups, and the setup form rejects `users`, `account users`, and `admins`.

docs/dqx/docs/studio/integrations.mdx

@@ -62,7 +62,7 @@ administrator to grant two things:
   GRANT SELECT ON dqx_studio.dq_rules_core TO "<principal>";
   ```
 
-`<principal>` is the Postgres role for the reader's identity — for a service
+`dqx_studio` here is Studio's Lakebase schema (`lakebase_schema_name`, default `dqx_studio`). It does not follow the Unity Catalog storage prefix. `<principal>` is the Postgres role for the reader's identity — for a service
 principal, its **application id**. `SELECT` on the view is enough; readers don't need
 access to the underlying `dq_resolved_rules` table.
 

docs/dqx/docs/studio/monitoring/load-checks-in-a-pipeline.mdx

@@ -62,7 +62,7 @@ administrator to grant two things:
   GRANT SELECT ON dqx_studio.dq_rules_core TO "<principal>";
   ```
 
-`<principal>` is the Postgres role for the reader's identity — for a service
+`dqx_studio` here is Studio's Lakebase schema (`lakebase_schema_name`, default `dqx_studio`). It does not follow the Unity Catalog storage prefix. `<principal>` is the Postgres role for the reader's identity — for a service
 principal, its **application id**. `SELECT` on the view is enough; readers don't need
 access to the underlying `dq_resolved_rules` table.