docs: improve dev containers accuracy and clarity

mafredri · mafredri · commit 0141028c27e9 · 2025-12-04T09:41:32.000Z
- Add third valid devcontainer.json location for monorepos
- Clarify hostname suffix is a deployment setting, link to server docs
- Clarify project discovery requires autostart for automatic startup
diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md
@@ -194,9 +194,11 @@ 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, project discovery finds dev containers in Git repositories and
+displays them in the Coder UI, but developers must manually start them. To
+have discovered containers start automatically, enable autostart:
 
 ```terraform
 resource "docker_container" "workspace" {
@@ -212,13 +214,15 @@ 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)
+- Discovered containers automatically build and start during workspace initialization
 - The `coder_devcontainer` resource is **not** required
 - Developers can work with multiple projects seamlessly
 
+Without autostart (the default), discovered containers appear in the dashboard
+but require manual startup, giving developers control over which containers run.
+
 > [!NOTE]
 >
 > When using project discovery, you still need to install the devcontainers CLI
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.
