docs: clarify discovery behavior and improve cross-references

mafredri · mafredri · commit d0529766d1d8 · 2025-12-04T10:10:52.000Z
- Explain discovery scans working directory for Git repos
- Cross-reference standard devcontainer.json locations instead of repeating
- Clarify 'How it works' steps depend on auto-start configuration
- Add link to admin docs for autostart env var
- Fix 'Currently available' phrasing to avoid staleness
diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md
@@ -121,12 +121,15 @@ by setting this to `false`.
 
 Enables automatic discovery of Dev Containers in Git repositories.
 
-When enabled, the agent will:
+When enabled, the agent scans the configured working directory (set via the
+`directory` attribute in `coder_agent`, typically the user's home directory) for
+Git repositories. If the directory itself is a Git repository, it searches that
+project. Otherwise, it searches immediate subdirectories for Git repositories.
 
-- Scan the agent directory for Git repositories
-- Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files
-- Surface discovered Dev Containers in the Coder UI
-- Respect `.gitignore` patterns during discovery
+For each repository found, the agent looks for `devcontainer.json` files in the
+[standard locations](../../../user-guides/devcontainers/index.md#1-add-a-devcontainerjson)
+and surfaces discovered Dev Containers in the Coder UI. Discovery respects
+`.gitignore` patterns.
 
 Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
 
@@ -153,8 +156,8 @@ block in their `devcontainer.json` file. Available options include:
 - `displayApps` — Control which built-in apps appear
 - `apps` — Define custom applications
 
-See [Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
-for the full reference.
+For the full reference, see
+[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
 
 ## Complete Template Example
 
diff --git a/docs/user-guides/devcontainers/customizing-dev-containers.md b/docs/user-guides/devcontainers/customizing-dev-containers.md
@@ -54,8 +54,8 @@ and shown in the UI, but users must manually start it.
 > [!NOTE]
 >
 > The `autoStart` option only takes effect when your template administrator has
-> enabled `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`. If this
-> setting is disabled at the template level, containers won't auto-start
+> enabled [`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`](../../admin/templates/extending-templates/devcontainers.md#coder_agent_devcontainers_discovery_autostart_enable).
+> If this setting is disabled at the template level, containers won't auto-start
 > regardless of this option.
 
 ## Custom agent name
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -88,8 +88,13 @@ When a workspace with Dev Containers integration starts:
 
 1. The workspace initializes the Docker environment.
 1. The integration detects repositories with dev container configurations.
-1. The integration builds and starts the dev container.
-1. Coder creates a sub-agent for the container, enabling direct access.
+1. Detected dev containers appear in the Coder dashboard.
+1. If auto-start is configured (via `coder_devcontainer` or autostart settings),
+   the integration builds and starts the dev container automatically.
+1. Coder creates a sub-agent for the running container, enabling direct access.
+
+Without auto-start, users can manually start discovered dev containers from the
+dashboard.
 
 ### Agent naming
 
diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md
@@ -138,8 +138,9 @@ in your `devcontainer.json` file. Coder also maintains a
 [repository of features](https://github.com/coder/devcontainer-features) to
 enhance your development experience.
 
-Currently available Coder features include
-[code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server):
+For example, the
+[code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server)
+feature from the [Coder features repository](https://github.com/coder/devcontainer-features):
 
 ```json
 {
