docs: clarify discovery behavior and improve cross-references

mafredri · mafredri · commit 0b2da3fed54f · 2025-12-04T10:00:47.000Z
- Explain discovery scans working directory for Git repos, not 'agent directory'
- Cross-reference standard devcontainer.json locations instead of repeating
- Fix 'Currently available' phrasing to avoid staleness
- Improve link placement for customization docs
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/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
 {
