docs: address second-pass review on cpflow vs. Terraform appendix

Apply the optional improvements from the second claude[bot] review of the
Terraform HCL appendix (#751):

- DATABASE_URL: add a production-guidance comment (sensitive var or
  cpln://secret ref) so the placeholder credentials aren't cargo-culted,
  matching the note already on SECRET_KEY_BASE.
- image_link: clarify that an image bump is a scoped `terraform apply`
  (plan + state lock), not a "full apply" -- Terraform only diffs the
  changed argument. Fixed the same overstatement in the closing paragraph.
- Expand the single-line `app_name`/`image_link` variable blocks to the
  idiomatic multi-line form, consistent with `location`.

The reviewer's env-must-be-blocks claim was not applied: the official cpln
provider docs type container `env` as a Map of String and use the
`env = { ... }` map literal in every example, so the doc is already correct.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: justin808

.controlplane/docs/cpflow-vs-terraform.md

@@ -54,15 +54,19 @@ models actually diverge.
 
 ```hcl
 # variables.tf
-variable "app_name"   { type = string }                 # cpflow injects {{APP_NAME}} per review app;
-                                                          # in TF this is a -var or a workspace name.
+variable "app_name" {                                    # cpflow injects {{APP_NAME}} per review app;
+  type = string                                          # in TF this is a -var or a workspace name.
+}
 variable "location" {
   type    = string
   default = "aws-us-east-2"
 }
-variable "image_link" { type = string }                 # cpflow's {{APP_IMAGE_LINK}} is set at *deploy*
-                                                          # time by `deploy-image`. In TF the image is a
-                                                          # plain argument, so every deploy is a full apply.
+# cpflow's {{APP_IMAGE_LINK}} is set at *deploy* time by `deploy-image`. In TF the image
+# is a plain argument, so each image bump is its own `terraform apply` (plan + state lock)
+# rather than a one-shot `deploy-image` call.
+variable "image_link" {
+  type = string
+}
 
 # gvc.tf  —  was templates/app.yml (kind: gvc + kind: identity)
 resource "cpln_gvc" "app" {
@@ -71,6 +75,8 @@ resource "cpln_gvc" "app" {
 
   # was spec.env: (a list of {name,value}); in TF it is a flat map.
   env = {
+    # Placeholder credentials mirror templates/app.yml; in production set DATABASE_URL via a
+    # sensitive var or a cpln://secret ref (like RENDERER_PASSWORD below) — never embed a real password.
     DATABASE_URL             = "postgres://the_user:the_password@postgres.${var.app_name}.cpln.local:5432/${var.app_name}"
     REDIS_URL                = "redis://redis.${var.app_name}.cpln.local:6379"
     RAILS_ENV                = "production"
@@ -145,6 +151,7 @@ What the comments are really showing: the three things cpflow gives you for free
 injection, and the implicit "provision ≠ deploy" separation) all become *your*
 problem in Terraform. The image being a plain argument is the big one: in
 cpflow, `deploy-image` bumps the running tag without touching infra; in
-Terraform, a new image is a `terraform apply` that diffs the whole workload. And
-none of `controlplane.yml` (release script, upstream promotion, review-app
-prefix matching) has any representation above at all.
+Terraform, a new image means a `terraform apply` — only that one argument changes,
+but the full plan / state-lock cycle still runs. And none of `controlplane.yml`
+(release script, upstream promotion, review-app prefix matching) has any
+representation above at all.