docs(databricks): amend-and-build runs the dbt job and waits for it (forge-cli#861)

docs/advanced/environment-variables.md

@@ -65,6 +65,7 @@ Since `0.20.0`, a project's `.env`, `.env.<environment>` and `.env.local` may ho
 |---|---|
 | `FLUID_STATE_BACKEND` | Default of `--state-backend` for `fluid apply`, `fluid diff` and `fluid verify --state-drift`: `s3://<bucket>[/<key>]` or `gcs://<bucket>[/<prefix>]` (see [Remote state](../cli/apply.md#remote-state)). A spec that names only a bucket gives every contract its own key (see below); the flag does not. An empty `--state-backend ""` forces local state for one run. |
 | `FLUID_TOFU_TIMEOUT_SECONDS` | Wall-clock cap per `tofu` invocation. Default `1800`. A timed-out call reports exit code 124. *(since 0.27.0, [forge-cli #787](https://github.com/Agenticstiger/forge-cli/pull/787))* `tofu` is interrupted first, so it releases its state lock, and killed only if it is still running 30 seconds later. |
+| `FLUID_DATABRICKS_RUN_TIMEOUT_SECONDS` | *On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* How long `fluid apply --mode amend-and-build` or `replace-and-build` waits for a Databricks job run, in whole seconds, before it cancels the run and fails the build. Unset, an hour, or the job's own timeouts and retries plus 15 minutes when that is longer. A value that is not a whole number of seconds above 0, in at most nine digits, is not used, and the apply says so. `fluid doctor --env` lists it, and a project `.env` may set it. See [Running the job from `fluid apply`](../providers/databricks.md#running-the-job-from-fluid-apply). |
 | `FLUID_TOFU_S3_LOCKFILE` | *(since 0.27.0, [forge-cli #787](https://github.com/Agenticstiger/forge-cli/pull/787))* `0`, `false`, `no` or `off` stops `fluid apply` from asking `tofu init` to lock S3 state (`-backend-config=use_lockfile=true`, OpenTofu 1.10 or newer). Set it for a role that cannot write `<key>.tflock`, in the environment of the job: a project `.env` cannot set it (see [project `.env` trust](./project-dotenv-trust.md)). Unset, or any other value, keeps the lock on. See [Locking](../concepts/state.md#locking). |
 | `FLUID_OPENTOFU_VERSION` | Pins the OpenTofu version that [`fluid apply --ensure-opentofu`](../cli/apply.md) installs when `tofu` is missing. |
 | `FLUID_REDSHIFT_WORKGROUP`, `FLUID_REDSHIFT_DATABASE`, `FLUID_REDSHIFT_SQL` | Set by the generated AWS module for its Redshift Serverless statements. They are outputs of the generator, not settings. |

docs/advanced/error-codes.md

@@ -228,6 +228,8 @@ The state refusals (`state_shared_with_another_provider`, `state_migration_ambig
 
 *(since 0.20.0, [forge-cli #714](https://github.com/Agenticstiger/forge-cli/pull/714) and [forge-cli #715](https://github.com/Agenticstiger/forge-cli/pull/715))* `apply_contract_invalid`, `apply_plan_missing_contract` and `unsupported_binding` (kind `mwaa-environment-not-emitted`) are not catalogued, so they print no curated suggestions. [Production troubleshooting](./production-troubleshooting.md#environment-mode-and-plan-file-errors) explains the first two, and [Scheduling on AWS](../providers/aws.md#scheduling-on-aws) the third. `contract_version_unsupported`, catalogued [above](#contract-version-unsupported), is now raised by `fluid apply` on both engines and in every mode.
 
+*On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* `apply_databricks_sdk_missing` is not catalogued either: its own `hint` line gives the fix. [Running the job from `fluid apply`](../providers/databricks.md#running-the-job-from-fluid-apply) explains it.
+
 ### planner_failed
 
 `ERR_PLANNER_FAILED`. The documentation link lands on [Production troubleshooting](./production-troubleshooting.md).

docs/advanced/operating-in-ci.md

@@ -209,6 +209,7 @@ Cloud applies go through the OpenTofu engine, which runs the `tofu` binary:
 - **State.** CI wipes the workspace after every run, and a wiped local state re-plans every resource as new. Set `FLUID_STATE_BACKEND=s3://<bucket>` or `gcs://<bucket>` once for the pipeline: each contract and provider then gets its own key. See [Environment variables](./environment-variables.md#apply-state-and-opentofu).
 - **S3 state lock.** *(since 0.27.0, [forge-cli #787](https://github.com/Agenticstiger/forge-cli/pull/787))* With OpenTofu 1.10 or newer, S3 state is locked through a `<key>.tflock` object, and `tofu plan` takes the lock too. Every role in the pipeline that plans or applies, a plan-only job and a drift check (`fluid diff`, `fluid verify --state-drift`) included, needs `s3:GetObject`, `s3:PutObject` and `s3:DeleteObject` on that object, or `FLUID_TOFU_S3_LOCKFILE=0` in the job's environment (a project `.env` cannot set it). A job that is killed hard can leave the lock behind; `tofu force-unlock <ID>` in the contract's workdir clears it. See [Locking](../concepts/state.md#locking).
 - **Timeouts.** Each `tofu` call is capped at 1800 s by default; raise it for a large first apply with `FLUID_TOFU_TIMEOUT_SECONDS`. *(since 0.27.0, [forge-cli #787](https://github.com/Agenticstiger/forge-cli/pull/787))* A call that runs past the cap is interrupted first, so `tofu` releases its state lock, and killed only if it is still running 30 seconds later.
+- **Databricks job runs.** *On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* Under `--mode amend-and-build`, a dbt build that runs as a Databricks job holds the CI job until its run ends, up to `FLUID_DATABRICKS_RUN_TIMEOUT_SECONDS`. A cancelled CI job that stops the apply with SIGINT, SIGTERM or SIGHUP cancels the run too. See [Running the job from `fluid apply`](../providers/databricks.md#running-the-job-from-fluid-apply).
 - **Review before apply.** `fluid generate iac <contract>` emits a deterministic, credential-free `main.tf.json` you can archive or review in a pull request; see [`fluid generate iac`](../cli/generate-iac.md).
 
 ## Contract SQL in CI

docs/cli/apply.md

@@ -154,6 +154,8 @@ amend-and-build (or replace-and-build) to run that build, or drop --build-id.
 
 Before 0.16.3 the flag was accepted and dropped, so a DDL-only apply exited 0.
 
+*On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* On Databricks, a dbt build with `execution.runtime.platform: databricks` runs as the job the apply provisions. The build phase starts a run of the job and waits for it to end, and a failed run fails the apply. See [Running the job from `fluid apply`](../providers/databricks.md#running-the-job-from-fluid-apply).
+
 ## Contract validation
 
 *([forge-cli #714](https://github.com/Agenticstiger/forge-cli/pull/714), since 0.20.0)* `fluid apply` checks the contract against its schema before it plans anything, on both engines and in every mode, `--dry-run` and the build modes included. A GCP contract that still carries the deprecated `metadata.policies` mapping stops before `tofu` runs:
@@ -624,6 +626,7 @@ Each failure prints the typed event name and an `[ERR_<EVENT>]` slug, and exits
 | `apply_build_id_requires_build_mode` | `--build-id` with a mode that runs no build. |
 | `apply_build_identifier_invalid` | *(since 0.27.0, [forge-cli #803](https://github.com/Agenticstiger/forge-cli/pull/803))* A build mode, and an `id` or `builds[].id` the build phase cannot use. Nothing is applied. See [Build ids](#build-ids). |
 | `apply_build_id_not_found` | *(since 0.27.0, [forge-cli #808](https://github.com/Agenticstiger/forge-cli/pull/808))* A build mode, and a `--build-id` that matches no `builds[].id`. The error lists the ids the contract has. Nothing is applied. See [Build ids](#build-ids). |
+| `apply_databricks_sdk_missing` | *On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* A build mode without `--dry-run`, a selected dbt build that runs as a Databricks job and is not continuous, and no `databricks-sdk`. Nothing is applied. Install `data-product-forge[databricks]`, or apply with `--mode amend`. See [Running the job from `fluid apply`](../providers/databricks.md#running-the-job-from-fluid-apply). |
 | `apply_mode_data_loss_blocked` | `replace` or `replace-and-build` without `--allow-data-loss`. |
 | `opentofu_data_loss_gate` | An OpenTofu plan destroys a resource and `--allow-data-loss` is not set. *(since 0.27.0, [forge-cli #793](https://github.com/Agenticstiger/forge-cli/pull/793))* Also a plan that changes the column types of a Glue table in place. |
 | `opentofu_plan_failed` | `tofu plan` failed. *(since 0.27.0, [forge-cli #786](https://github.com/Agenticstiger/forge-cli/pull/786))* A plan that failed on a held state lock suggests `tofu force-unlock <id>`. |

docs/providers/README.md

@@ -21,7 +21,7 @@ Fluid Forge uses one contract format across local and provider-backed execution
 | [GCP](./gcp.md) | Yes (OpenTofu) | Prefer `fluid generate schedule` | Production |
 | [AWS](./aws.md) | Yes (OpenTofu) | Prefer `fluid generate schedule` | Production |
 | [Snowflake](./snowflake.md) | Yes (OpenTofu) | Prefer `fluid generate schedule` | Production |
-| [Databricks](./databricks.md) | Yes (OpenTofu) | dbt builds run as Databricks jobs on their own trigger | Added in 0.26.0 |
+| [Databricks](./databricks.md) | Yes (OpenTofu) | dbt builds run as Databricks jobs on their own trigger. *On forge-cli's feat/databricks-build-run-now branch ([forge-cli #861](https://github.com/Agenticstiger/forge-cli/pull/861)), not yet on `main` or in a release.* `--mode amend-and-build` also starts a run and waits for it | Added in 0.26.0 |
 | [Local](./local.md) | Yes (native DuckDB) | Local-first onboarding | Production |
 
 "Production" covers provisioning and builds. Governance differs by cloud: on GCP, `fluid apply` emits dataset grants, column policy tags and, on `0.7.6`, retention and Cloud KMS keys; on Snowflake, as of 0.18.1, `accessPolicy` grants, column restrictions and masking are not applied. Each provider page lists what its module emits.