docs: improve dev containers accuracy and clarity

mafredri · mafredri · commit eacb14679a53 · 2025-12-04T09:49:48.000Z
- Add third devcontainer.json location for monorepos, link to spec
- Clarify hostname suffix is a deployment setting
- Tighten project discovery section, clarify autostart behavior
diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md
@@ -25,7 +25,9 @@ This is the recommended approach for most use cases.
 
 ### Project Discovery
 
-Enable automatic discovery of Dev Containers in Git repositories. Project discovery automatically scans Git repositories for `.devcontainer/devcontainer.json` or `.devcontainer.json` files and surfaces them in the Coder UI. See the [Environment Variables](#environment-variables) section for detailed configuration options.
+Alternatively, enable automatic discovery of Dev Containers in Git repositories.
+The agent scans for `devcontainer.json` files and surfaces them in the Coder UI.
+See [Environment Variables](#environment-variables) for configuration options.
 
 ## Install the Dev Containers CLI
 
@@ -123,11 +125,10 @@ When enabled, the agent will:
 
 - Scan the agent directory for Git repositories
 - Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files
-- Surface discovered Dev Containers automatically in the Coder UI
+- Surface discovered Dev Containers in the Coder UI
 - Respect `.gitignore` patterns during discovery
 
-You can disable automatic discovery by setting this to `false` if you prefer to
-use only the `coder_devcontainer` resource for explicit configuration.
+Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
 
 ### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
 
@@ -194,9 +195,10 @@ resource "coder_devcontainer" "my-repository" {
 }
 ```
 
-### Alternative: Project Discovery Mode
+### Alternative: Project Discovery with Autostart
 
-You can enable automatic starting of discovered Dev Containers:
+By default, discovered containers appear in the dashboard but developers must
+manually start them. To have them start automatically, enable autostart:
 
 ```terraform
 resource "docker_container" "workspace" {
@@ -212,11 +214,11 @@ resource "docker_container" "workspace" {
 }
 ```
 
-With this configuration:
+With autostart enabled:
 
-- Project discovery is enabled (default behavior)
-- Discovered containers are automatically started (via the env var)
-- The `coder_devcontainer` resource is **not** required
+- Discovered containers automatically build and start during workspace
+  initialization
+- The `coder_devcontainer` resource is not required
 - Developers can work with multiple projects seamlessly
 
 > [!NOTE]
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -37,6 +37,12 @@ development environment. You can place it in:
 
 - `.devcontainer/devcontainer.json` (recommended)
 - `.devcontainer.json` (root of repository)
+- `.devcontainer/<folder>/devcontainer.json` (for multiple configurations)
+
+The third option allows monorepos to define multiple dev container
+configurations in separate sub-folders. See the
+[Dev Container specification](https://containers.dev/implementors/spec/#devcontainerjson)
+for details.
 
 Here's a minimal example:
 
diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md
@@ -57,8 +57,10 @@ For example:
 ssh my-project.my-workspace.alice.coder
 ```
 
-The hostname suffix defaults to `coder` but can be customized via
-`CODER_WORKSPACE_HOSTNAME_SUFFIX`.
+The hostname suffix defaults to `coder` but can be customized by your
+deployment administrator via the
+[`--workspace-hostname-suffix`](../../reference/cli/server.md#--workspace-hostname-suffix)
+server option.
 
 This method works with any SSH client, IDE remote extensions, `rsync`, `scp`,
 and other tools that use SSH.
