feat: improve the image management experience with template builder (#27018)

Makes it easier to pick the right workspace image, both in the template
builder and in the docs.

- Template builder: the Docker and Kubernetes bases now expose a
`container_image` variable in the wizard (freeform text, defaults to
`codercom/example-base:ubuntu`), and their prerequisites explain why
image choice matters, with tradeoffs between
`codercom/example-base:ubuntu` (minimal) and
`codercom/example-universal:ubuntu` (catch-all), plus pointers to
[coder/images](https://github.com/coder/images) and the image management
docs.
- Docs: reworked [image
management](https://coder.com/docs/@ben%2Fdevrel-201-image-guidance-prereqs/admin/templates/managing-templates/image-management)
into a clearer maturity ladder (minimal → golden → project-specific →
developer customization), with pullable image references in every
example, `codercom/oss-dogfood` as a project-specific example, and Dev
Containers + [mise](https://mise.jdx.dev/) as ways to customize without
new images.

Companion PR for the starter templates: coder/registry#943

Part of DEVREL-201.

🤖 Generated with Coder Agents using Claude, on behalf of @bpmct (wizard
variable by @jeremyruppel in #27024)

---------

Co-authored-by: Jeremy Ruppel <jeremyruppel@users.noreply.github.com>

coderd/templatebuilder/bases/docker/README.md

@@ -17,6 +17,19 @@ Provision Docker containers as [Coder workspaces](https://coder.com/docs/user-gu
 
 ## Prerequisites
 
+### Workspace image
+
+The container image determines what tools, languages, and runtimes are available in the workspace out of the box, so it has a major impact on the developer experience.
+
+Some options to consider:
+
+- [`codercom/example-base:ubuntu`](https://github.com/coder/images/tree/main/images/base) (default): minimal and lightweight, but may not include many tools developers expect by default
+- [`codercom/example-universal:ubuntu`](https://github.com/coder/images/tree/main/images/universal): catch-all image with many languages and tools available, but larger and slower to pull
+
+More language-specific images (Go, Java, Node.js, and more) are available in [coder/images](https://github.com/coder/images), and the [devcontainers/images](https://github.com/devcontainers/images) collection is another good source of ready-made development images.
+You can also build your own image to pre-bake the exact tools your team needs.
+Visit [Coder's image management docs](https://coder.com/docs/admin/templates/managing-templates/image-management) for additional guidance.
+
 ### Infrastructure
 
 The VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:

coderd/templatebuilder/bases/docker/base.json

@@ -3,6 +3,17 @@
 	"display_name": "Docker",
 	"os": "linux",
 	"default_context": {
-		"container_image": "codercom/enterprise-base:ubuntu"
-	}
+		"container_image": "codercom/example-base:ubuntu"
+	},
+	"variables": [
+		{
+			"name": "container_image",
+			"type": "string",
+			"description": "Container image for workspaces. The image determines which tools and languages are available in the workspace by default. See the template README for guidance on choosing an image.",
+			"default": "codercom/example-base:ubuntu",
+			"required": false,
+			"sensitive": false,
+			"computed": false
+		}
+	]
 }

coderd/templatebuilder/bases/docker/main.tf.tmpl

@@ -166,7 +166,7 @@ resource "docker_container" "workspace" {
   {{- if .ImageOptions }}
   image = data.coder_parameter.container_image.value
   {{- else }}
-  image = "{{ .ContainerImage }}"
+  image = {{ .Variables.container_image }}
   {{- end }}
   # Uses lower() to avoid Docker restriction on container names.
   name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"