@@ -25,7 +25,7 @@ The deploy payload is declared twice: the proto in the universe repo (`proto/log
 ## Adding a new metric
 
 1. Add the field to the relevant message in `libs/telemetry/protos/`, and populate it in `bundle/phases/telemetry.go`.
-2. Refresh the acceptance golden: `go test ./acceptance -run '^TestAccept/bundle/telemetry' -update`. Anything engine-dependent belongs in a per-engine `out.*.$DATABRICKS_BUNDLE_ENGINE.txt` file rather than the engine-agnostic `out.telemetry.txt`; see the comments in that test's `script`.
+2. Refresh the acceptance golden: `go test ./acceptance -run '^TestAccept/bundle/telemetry' -update`.
 3. Send the universe PR adding the same field to the proto, with a `compliance.data_label` annotation matching the neighbouring fields.
 
 **RULE: Never send a resource name, path, or any other user-authored string.** Names are PII. Resource identity goes through the numeric/UUID ID lists (`resource_job_ids` and friends), and only for types that have such an ID.
@@ -37,7 +37,7 @@ Other things worth knowing:
 - A one-off boolean needs no proto change: add a key constant to `bundle/metrics/metrics.go` (snake_case, matching the constant name) and call `b.Metrics.SetBoolValue(...)`. It lands in `experimental.bool_values`.
 - Metrics that may be removed later belong in `BundleDeployExperimental`, which carries no compatibility guarantees.
 - Positional encodings such as the `upload_file_sizes` histogram are frozen once the metric has adoption: changing a bucket bound silently changes the meaning of every previously reported entry.
-- Anything measured from the deployment state is engine-dependent. The direct engine keeps per-resource state in `resources.json` and reports sizes; the terraform path leaves `StateSizeBytes` zero and reports only counts.
+- Per-resource state sizes come from the direct engine's state in `resources.json`.
 
 ## Where the data lands
 
 
@@ -50,8 +50,8 @@ go test ./acceptance -run '^TestAccept$' -timeout=60m       # MUST pass on its o
 ```
 
 The verify pass is not optional.
-Bundle tests run under an `EnvMatrix` of both engines (`terraform`, `direct`).
-When a schema change makes one engine error while the other succeeds, the variants produce different output; `-update` runs both and each overwrites the other's `output.txt`, so it can silently settle on the passing variant and report `ok` while the golden is actually wrong.
+Many bundle tests run under an `EnvMatrix` (e.g. `DMS`, `READPLAN`).
+When a schema change makes one variant error while another succeeds, the variants produce different output; `-update` runs all of them and each overwrites the other's `output.txt`, so it can silently settle on the passing variant and report `ok` while the golden is actually wrong.
 Only the non-update run catches this.
 (Ignore `rejecting_proxy.go: blocking proxy` log lines, which are normal.
 A test that times out under full parallel load but passes when run alone is a flake, not a regression.)
 
@@ -13,7 +13,7 @@ Before submitting a PR, run these commands to match what CI checks. CI uses the
 # 2. Linting (CI runs full golangci-lint across all modules, not the diff-only wrapper)
 ./task lint
 
-# 3. Tests (CI runs with both deployment engines)
+# 3. Tests
 ./task test
 
 # 4. If you changed bundle config structs, schema, or direct-engine resource code:
 
@@ -68,7 +68,7 @@ GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true VISUAL=true GIT_PAGER=cat git rebase or
 **bundle/** - Core bundle functionality for Declarative Automation Bundles
 - `bundle/bundle.go` - Main Bundle struct and lifecycle management
 - `bundle/config/` - Configuration loading, validation, and schema
-- `bundle/deploy/` - Deployment logic (Terraform and direct modes)
+- `bundle/deploy/` - Deployment logic (file upload, locking, state)
 - `bundle/mutator/` - Configuration transformation pipeline
 - `bundle/phases/` - High-level deployment phases
 
@@ -84,9 +84,7 @@ GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true VISUAL=true GIT_PAGER=cat git rebase or
 
 **Mutators**: Transform bundle configuration through a pipeline. Located in `bundle/config/mutator/` and `bundle/mutator/`. Each mutator implements the `Mutator` interface.
 
-**Direct vs Terraform Deployment**: The CLI supports two deployment modes controlled by `DATABRICKS_BUNDLE_ENGINE` environment variable:
-- `direct` (default) - Direct API calls without Terraform
-- `terraform` - Uses Terraform for resource management
+**Direct deployment engine**: Bundles are deployed by the direct engine (`bundle/direct/`), which calls the APIs without Terraform. The Terraform engine was removed in v1.20.0: `bundle.engine: terraform` and `DATABRICKS_BUNDLE_ENGINE=terraform` are rejected, and existing Terraform state is migrated to the direct engine before the command runs.
 
 # Development Tips
 
 
@@ -19,7 +19,7 @@ Flags:
       --force                 Force-override Git branch validation.
       --force-lock            Force acquisition of deployment lock.
   -h, --help                  help for deploy
-      --plan string           Path to a JSON plan file to apply instead of planning (direct engine only).
+      --plan string           Path to a JSON plan file to apply instead of planning.
   -q, --quiet count           Reduce output: -q prints only the summary, -qq prints only warnings and errors.
       --select strings        Deploy only the specified resource (e.g. 'my_job' or 'jobs.my_job'). Can be repeated or comma-separated.
 
 
@@ -86,7 +86,7 @@ type Metrics struct {
 	// ResourceState is the direct engine's per-resource deployment state
 	// captured right after the deploy. It carries each resource's state-size in
 	// bytes so deploy telemetry can be derived without re-reading or re-parsing
-	// the state file. Nil for terraform deploys.
+	// the state file.
 	ResourceState resourcestate.ExportedResourcesMap
 }
 
@@ -188,12 +188,10 @@ type Bundle struct {
 	// When non-empty, only the specified resources are included in deployment.
 	Select []string
 
-	// MigratingToDirect is set when the direct engine is requested but the existing
-	// state still uses terraform, so the state is migrated to the direct engine after
-	// this deploy. Resources that only the direct engine supports are skipped by this
-	// run rather than rejected: terraform cannot deploy them, and since terraform
-	// could never have deployed them they are absent from its state. The next deploy,
-	// which runs on the migrated state, creates them.
+	// MigratingToDirect is set when the existing state still uses terraform, so it is
+	// migrated to the direct engine in memory before the command runs (statemgmt.Migrate).
+	// Deploy and destroy commit the migration (statemgmt.CommitMigration); other commands
+	// leave the terraform state untouched.
 	MigratingToDirect bool
 
 	// Quiet is the output verbosity reduction requested via -q/--quiet, which is
 
@@ -46,8 +46,8 @@ type Bundle struct {
 	// Overrides the cluster used for jobs and other supported assets.
 	ClusterId string `json:"cluster_id,omitempty"`
 
-	// Engine specifies the deployment engine to use ("terraform" or "direct").
-	// Defaults to "direct"; set "terraform" to opt out.
+	// Engine specifies the deployment engine to use. "direct" is the only supported
+	// engine and the default; "terraform" is rejected with the removal error.
 	// Can be overridden with the DATABRICKS_BUNDLE_ENGINE environment variable.
 	Engine engine.EngineType `json:"engine,omitempty"`
 
 
@@ -18,7 +18,7 @@ const (
 )
 
 // Default is used when the user has not set the value, both for new bundles and
-// for existing terraform deployments (which are migrated to it after a deploy).
+// for existing terraform deployments (whose state is migrated to it before the command runs).
 const Default = EngineDirect
 
 // TerraformRemovedMessage is the error text shown when a bundle pins the removed
 
@@ -7,7 +7,7 @@ type Experimental struct {
 	// single immutable snapshot rather than being synced individually. When true,
 	// the deployment calls /api/2.0/repos/snapshots with a zip of all files and sets
 	// workspace.file_path and workspace.artifact_path to the returned content-addressed
-	// path. Only supported with the direct deployment engine.
+	// path.
 	ImmutableFolder bool `json:"immutable_folder,omitempty"`
 
 	// By default Python wheel tasks deployed as is to Databricks platform.
 
@@ -17,10 +17,10 @@ type dropEmptyStrings struct{}
 // either literally (policy_id: "") or via a variable that resolved to "", so
 // this must run after variable resolution.
 //
-// Both engines convert the resolved config through convert.ToTyped, which
+// The direct engine converts the resolved config through convert.ToTyped, which
 // force-sends explicitly-set zero values, defeating the omitempty tag. Dropping
-// here fixes it uniformly for terraform and direct and makes the result visible
-// in `bundle validate -o json`, which serializes the dynamic value.
+// here fixes it and makes the result visible in `bundle validate -o json`, which
+// serializes the dynamic value.
 func DropEmptyStrings() bundle.Mutator {
 	return &dropEmptyStrings{}
 }
@@ -43,11 +43,9 @@ func (m *dropEmptyStrings) Apply(ctx context.Context, b *bundle.Bundle) diag.Dia
 			return root, err
 		}
 
-		// It seems safe to send an empty description "" to the backend, but for apps
-		// it causes drift in terraform: the Apps API always returns "" for an unset
-		// description, so bundle/deploy/terraform/tfdyn/convert_app.go injects it
-		// anyway. To avoid an unnecessary difference between the direct and terraform
-		// engines, keep the empty apps description here instead of dropping it.
+		// Keep an empty apps description instead of dropping it: an app update without
+		// the field leaves the remote description unchanged, so removing description
+		// from config would never converge. Force-sending "" clears it.
 		return dyn.MapByPattern(root, dyn.NewPattern(dyn.Key("resources"), dyn.Key("apps"), dyn.AnyKey()), func(_ dyn.Path, app dyn.Value) (dyn.Value, error) {
 			if _, err := dyn.Get(app, "description"); err != nil {
 				return dyn.Set(app, "description", dyn.V(""))
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ const (`
`18`	`18`	`)`
`19`	`19`
`20`	`20`	`// Default is used when the user has not set the value, both for new bundles and`
`21`		`-// for existing terraform deployments (which are migrated to it after a deploy).`
	`21`	`+// for existing terraform deployments (whose state is migrated to it before the command runs).`
`22`	`22`	`const Default = EngineDirect`
`23`	`23`
`24`	`24`	`// TerraformRemovedMessage is the error text shown when a bundle pins the removed`