@@ -1,8 +1,32 @@
-# Configure a template for dev containers
+# Configure a template for Dev Containers
 
-To enable dev containers in workspaces, configure your template with the dev containers
+To enable Dev Containers in workspaces, configure your template with the Dev Containers
 modules and configurations outlined in this doc.
 
+> [!NOTE]
+>
+> Dev Containers require a **Linux or macOS workspace**. Windows is not supported.
+
+## Configuration Modes
+
+There are two approaches to configuring Dev Containers in Coder:
+
+### Manual Configuration
+
+Use the [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev
+Containers should be started in your workspace. This approach provides:
+
+- Predictable behavior and explicit control
+- Clear template configuration
+- Easier troubleshooting
+- Better for production environments
+
+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.
+
 ## Install the Dev Containers CLI
 
 Use the
@@ -23,7 +47,7 @@ Alternatively, install the devcontainer CLI manually in your base image.
 
 The
 [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
-resource automatically starts a dev container in your workspace, ensuring it's
+resource automatically starts a Dev Container in your workspace, ensuring it's
 ready when you access the workspace:
 
 ```terraform
@@ -50,30 +74,140 @@ resource "coder_devcontainer" "my-repository" {
 
 ## Enable Dev Containers Integration
 
-To enable the dev containers integration in your workspace, you must set the
-`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your
-workspace container:
+Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
+You don't need to set any environment variables unless you want to change the
+default behavior.
+
+If you need to explicitly disable Dev Containers, set the
+`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:
 
 ```terraform
 resource "docker_container" "workspace" {
   count = data.coder_workspace.me.start_count
   image = "codercom/oss-dogfood:latest"
   env = [
-    "CODER_AGENT_DEVCONTAINERS_ENABLE=true",
+    "CODER_AGENT_DEVCONTAINERS_ENABLE=false",  # Explicitly disable
     # ... Other environment variables.
   ]
   # ... Other container configuration.
 }
 ```
 
-This environment variable is required for the Coder agent to detect and manage
-dev containers. Without it, the agent will not attempt to start or connect to
-dev containers even if the `coder_devcontainer` resource is defined.
+See the [Environment Variables](#environment-variables) section below for more
+details on available configuration options.
+
+## Environment Variables
+
+The following environment variables control Dev Container behavior in your
+workspace. Both `CODER_AGENT_DEVCONTAINERS_ENABLE` and
+`CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are **enabled by default**,
+so you typically don't need to set them unless you want to explicitly disable
+the feature.
+
+### CODER_AGENT_DEVCONTAINERS_ENABLE
+
+**Default: `true`** • **Added in: v2.24.0**
+
+Enables the Dev Containers integration in the Coder agent.
+
+The Dev Containers feature is enabled by default. You can explicitly disable it
+by setting this to `false`.
+
+### CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE
+
+**Default: `true`** • **Added in: v2.25.0**
+
+Enables automatic discovery of Dev Containers in Git repositories.
+
+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
+- 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.
+
+### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
+
+**Default: `false`** • **Added in: v2.25.0**
+
+Automatically starts Dev Containers discovered via project discovery.
+
+When enabled, discovered Dev Containers will be automatically built and started
+during workspace initialization. This only applies to Dev Containers found via
+project discovery. Dev Containers defined with the `coder_devcontainer` resource
+always auto-start regardless of this setting.
+
+## Per-Container Customizations
+
+Individual Dev Containers can be customized using the `customizations.coder` block
+in your `devcontainer.json` file. These customizations allow you to control
+container-specific behavior without modifying your template.
+
+### Ignore Specific Containers
+
+Use the `ignore` option to hide a Dev Container from Coder completely:
+
+```json
+{
+  "name": "My Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "customizations": {
+    "coder": {
+      "ignore": true
+    }
+  }
+}
+```
+
+When `ignore` is set to `true`:
+
+- The Dev Container won't appear in the Coder UI
+- Coder won't manage or monitor the container
+
+This is useful when you have Dev Containers in your repository that you don't
+want Coder to manage.
+
+### Per-Container Auto-Start
+
+Control whether individual Dev Containers should auto-start using the
+`autoStart` option:
+
+```json
+{
+  "name": "My Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "customizations": {
+    "coder": {
+      "autoStart": true
+    }
+  }
+}
+```
+
+**Important**: The `autoStart` option only applies when global auto-start is
+enabled via `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true`. If
+the global setting is disabled, containers won't auto-start regardless of this
+setting.
+
+When `autoStart` is set to `true`:
+
+- The Dev Container automatically builds and starts during workspace
+  initialization
+- Works on a per-container basis (you can enable it for some containers but not
+  others)
+
+When `autoStart` is set to `false` or omitted:
+
+- The Dev Container is discovered and shown in the UI
+- Users must manually start it via the UI
 
 ## Complete Template Example
 
-Here's a simplified template example that enables the dev containers
-integration:
+Here's a simplified template example that uses Dev Containers with manual
+configuration:
 
 ```terraform
 terraform {
@@ -107,18 +241,38 @@ resource "coder_devcontainer" "my-repository" {
   agent_id         = coder_agent.dev.id
   workspace_folder = "/home/coder/my-repository"
 }
+```
+
+### Alternative: Project Discovery Mode
 
+You can enable automatic starting of discovered Dev Containers:
+
+```terraform
 resource "docker_container" "workspace" {
   count = data.coder_workspace.me.start_count
   image = "codercom/oss-dogfood:latest"
   env = [
-    "CODER_AGENT_DEVCONTAINERS_ENABLE=true",
+    # Project discovery is enabled by default, but autostart is not.
+    # Enable autostart to automatically build and start discovered containers:
+    "CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true",
     # ... Other environment variables.
   ]
   # ... Other container configuration.
 }
 ```
 
+With this configuration:
+
+- Project discovery is enabled (default behavior)
+- Discovered containers are automatically started (via the env var)
+- The `coder_devcontainer` resource is **not** required
+- Developers can work with multiple projects seamlessly
+
+> [!NOTE]
+>
+> When using project discovery, you still need to install the devcontainers CLI
+> using the module or in your base image.
+
 ## Next Steps
 
 - [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
 
@@ -1,81 +1,69 @@
 # Dev Containers Integration
 
-> [!NOTE]
->
-> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature.
->
-> While functional for testing and feedback, it may change significantly before general availability.
-
-The dev containers integration is an early access feature that enables seamless
-creation and management of dev containers in Coder workspaces. This feature
-leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
+The Dev Containers integration enables seamless creation and management of Dev
+Containers in Coder workspaces. This feature leverages the
+[`@devcontainers/cli`](https://github.com/devcontainers/cli) and
 [Docker](https://www.docker.com) to provide a streamlined development
 experience.
 
 This implementation is different from the existing
-[Envbuilder-based dev containers](../../admin/templates/managing-templates/devcontainers/index.md)
+[Envbuilder-based Dev Containers](../../admin/templates/managing-templates/devcontainers/index.md)
 offering.
 
 ## Prerequisites
 
-- Coder version 2.22.0 or later
-- Coder CLI version 2.22.0 or later
+- Coder version 2.24.0 or later
+- Coder CLI version 2.24.0 or later
+- **Linux or macOS workspace**, Dev Containers are not supported on Windows
 - A template with:
-  - Dev containers integration enabled
+  - Dev Containers integration enabled
   - A Docker-compatible workspace image
 - Appropriate permissions to execute Docker commands inside your workspace
 
 ## How It Works
 
-The dev containers integration utilizes the `devcontainer` command from
-[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage dev
-containers within your Coder workspace.
-This command provides comprehensive functionality for creating, starting, and managing dev containers.
+The Dev Containers integration utilizes the `devcontainer` command from
+[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage Dev
+Containers within your Coder workspace.
+This command provides comprehensive functionality for creating, starting, and managing Dev Containers.
 
 Dev environments are configured through a standard `devcontainer.json` file,
 which allows for extensive customization of your development setup.
 
-When a workspace with the dev containers integration starts:
+When a workspace with the Dev Containers integration starts:
 
 1. The workspace initializes the Docker environment.
 1. The integration detects repositories with a `.devcontainer` directory or a
    `devcontainer.json` file.
-1. The integration builds and starts the dev container based on the
+1. The integration builds and starts the Dev Container based on the
    configuration.
-1. Your workspace automatically detects the running dev container.
+1. Your workspace automatically detects the running Dev Container.
 
 ## Features
 
 ### Available Now
 
-- Automatic dev container detection from repositories
-- Seamless dev container startup during workspace initialization
-- Integrated IDE experience in dev containers with VS Code
-- Direct service access in dev containers
-- Limited SSH access to dev containers
+- Automatic Dev Container detection from repositories
+- Seamless Dev Container startup during workspace initialization
+- Dev Container change detection and dirty state indicators
+- On-demand Dev Container recreation via rebuild button
+- Integrated IDE experience in Dev Containers with VS Code
+- Direct service access in Dev Containers
+- SSH access to Dev Containers
+- Automatic port detection for container ports
 
-### Coming Soon
+## Limitations
 
-- Dev container change detection
-- On-demand dev container recreation
-- Support for automatic port forwarding inside the container
-- Full native SSH support to dev containers
-
-## Limitations during Early Access
-
-During the early access phase, the dev containers integration has the following
-limitations:
+The Dev Containers integration has the following limitations:
 
+- **Not supported on Windows**
 - Changes to the `devcontainer.json` file require manual container recreation
-- Automatic port forwarding only works for ports specified in `appPort`
-- SSH access requires using the `--container` flag
-- Some devcontainer features may not work as expected
-
-These limitations will be addressed in future updates as the feature matures.
+  using the rebuild button
+- Some Dev Container features may not work as expected
 
 ## Comparison with Envbuilder-based Dev Containers
 
-| Feature        | Dev Containers (Early Access)          | Envbuilder Dev Containers                    |
+| Feature        | Dev Containers Integration             | Envbuilder Dev Containers                    |
 |----------------|----------------------------------------|----------------------------------------------|
 | Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder                           |
 | Target users   | Individual developers                  | Platform teams and administrators            |
@@ -84,15 +72,15 @@ These limitations will be addressed in future updates as the feature matures.
 | Requirements   | Docker access in workspace             | Compatible with more restricted environments |
 
 Choose the appropriate solution based on your team's needs and infrastructure
-constraints. For additional details on Envbuilder's dev container support, see
+constraints. For additional details on Envbuilder's Dev Container support, see
 the
-[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
+[Envbuilder Dev Container spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
 
 ## Next Steps
 
-- Explore the [dev container specification](https://containers.dev/) to learn
+- Explore the [Dev Container specification](https://containers.dev/) to learn
   more about advanced configuration options
-- Read about [dev container features](https://containers.dev/features) to
+- Read about [Dev Container features](https://containers.dev/features) to
   enhance your development environment
 - Check the
   [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)