coder · nickvigilante · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -41,3 +41,4 @@ site/src/api/typesGenerated.ts linguist-generated=true
 # AI Gateway prices
 coderd/aibridge/prices/data/prices.json linguist-generated=true
 site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/knownModelsGenerated.json linguist-generated=true
+docs/experiments.json linguist-generated=true
diff --git a/Makefile b/Makefile
@@ -144,6 +144,10 @@ _gen/bin/auditdocgen: $(wildcard scripts/auditdocgen/*.go) $(wildcard enterprise
 	@mkdir -p _gen/bin
 	go build -o $@ ./scripts/auditdocgen
 
+_gen/bin/experimentsdocgen: $(wildcard scripts/experimentsdocgen/*.go) codersdk/deployment.go | _gen
+	@mkdir -p _gen/bin
+	go build -o $@ ./scripts/experimentsdocgen
+
 _gen/bin/check-scopes: $(wildcard scripts/check-scopes/*.go) $(RBAC_GO_FILES) | _gen
 	@mkdir -p _gen/bin
 	go build -o $@ ./scripts/check-scopes
@@ -1017,6 +1021,7 @@ GEN_FILES := \
 	docs/admin/integrations/prometheus.md \
 	docs/reference/cli/index.md \
 	docs/admin/security/audit-logs.md \
+	docs/experiments.json \
 	docs/install/releases/feature-stages.md \
 	docs/admin/setup/configuration-reference.md \
 	coderd/apidoc/swagger.json \
@@ -1116,6 +1121,7 @@ gen/mark-fresh:
 		docs/admin/integrations/prometheus.md \
 		docs/reference/cli/index.md \
 		docs/admin/security/audit-logs.md \
+		docs/experiments.json \
 		docs/install/releases/feature-stages.md \
 		docs/admin/setup/configuration-reference.md \
 		coderd/apidoc/swagger.json \
@@ -1353,10 +1359,17 @@ docs/admin/security/audit-logs.md: node_modules/.installed coderd/database/queri
 		pnpm exec markdown-table-formatter "$$tmpfile" && \
 		mv "$$tmpfile" "$@" && rm -rf "$$tmpdir"
 
+# Every experiment this version knows about, with its display name, description,
+# and whether --experiments=* enables it. The feature-stages page renders its
+# experiments table from this file, and the docs engine validates experimental
+# content markers against it.
+docs/experiments.json: codersdk/deployment.go $(wildcard scripts/experimentsdocgen/*.go) | _gen _gen/bin/experimentsdocgen
+	_gen/bin/experimentsdocgen --source codersdk/deployment.go --out $@
+
 docs/install/releases/feature-stages.md: \
 	node_modules/.installed \
 	scripts/release/docs_update_feature_stages.sh \
-	codersdk/deployment.go \
+	docs/experiments.json \
 	docs/manifest.json | _gen
 	tmpdir=$$(mktemp -d -p _gen) && tmpfile=$$(realpath "$$tmpdir")/$(notdir $@) && cp "$@" "$$tmpfile" && \
 		./scripts/release/docs_update_feature_stages.sh "$$tmpfile" && \

diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/codersdk/deployment.go b/codersdk/deployment.go
@@ -5472,7 +5472,7 @@ type Experiment string
 const (
 	// Add new experiments here!
 	ExperimentExample                   Experiment = "example"                     // This isn't used for anything.
-	ExperimentAutoFillParameters        Experiment = "auto-fill-parameters"        // This should not be taken out of experiments until we have redesigned the feature.
+	ExperimentAutoFillParameters        Experiment = "auto-fill-parameters"        // Pre-fills a new workspace's parameter form with the values from the user's most recent build of that template.
 	ExperimentNotifications             Experiment = "notifications"               // Sends notifications via SMTP and webhooks following certain events.
 	ExperimentWorkspaceUsage            Experiment = "workspace-usage"             // Enables the new workspace usage tracking.
 	ExperimentOAuth2                    Experiment = "oauth2"                      // Enables OAuth2 provider functionality.
@@ -5501,6 +5501,8 @@ func (e Experiment) DisplayName() string {
 		return "OAuth2 Provider Functionality"
 	case ExperimentMCPServerHTTP:
 		return "MCP HTTP Server Functionality"
+	case ExperimentMCPToolSearch:
+		return "MCP Tool Search"
 	case ExperimentWorkspaceBuildUpdates:
 		return "Workspace Build Updates Channel"
 	case ExperimentNATSPubsub:

diff --git a/docs/experiments.json b/docs/experiments.json
diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md
@@ -38,33 +38,61 @@ staging deployment.
 
 <details><summary>To enable early access features:</summary>
 
-Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable early
-access features:
+Early access features are experiments, and each one has a flag.
+Coder marks each experiment as **safe** or **unsafe** for opting in; the Safety column in the table below shows which is which for this version.
 
-- Enable all early access features:
+- A safe experiment is ready for opt-in testing.
+  `--experiments=*` enables every safe experiment in this version and nothing else.
+- An unsafe experiment is not ready for general use and must be named exactly; the wildcard never enables it.
+  Enable unsafe experiments only on a staging deployment.
+
+Use the [Coder CLI](../../install/cli.md) `--experiments` flag on `coder server`:
+
+- Enable every safe experiment:
 
   ```sh
   coder server --experiments=*
   ```
 
-- Enable multiple early access features:
+- Enable specific experiments by flag, safe or unsafe:
 
   ```sh
-  coder server --experiments=feature1,feature2
+  coder server --experiments=flag-one,flag-two
   ```
 
-You can also use the `CODER_EXPERIMENTS`
-[environment variable](../../admin/setup/index.md).
+- Enable every safe experiment plus named unsafe ones in one flag:
+
+  ```sh
+  coder server --experiments=*,unsafe-flag-one,unsafe-flag-two
+  ```
 
-You can opt-out of a feature after you've enabled it.
+You can also set the `CODER_EXPERIMENTS` [environment variable](../../admin/setup/index.md) to the same value.
+You can opt out of a feature after you've enabled it by removing its flag and restarting the server.
 
 </details>
 
 ### Available early access features
 
+This table lists every experiment this version of Coder knows about.
+It is generated from the code, so it always matches the flags this version accepts.
+
 <!-- Code generated by scripts/release/docs_update_feature_stages.sh. DO NOT EDIT. -->
 <!-- BEGIN: available-experimental-features -->
-Currently no experimental features are available.
+| Feature                         | Flag                          | Description                                                                                                    | Safety |
+|---------------------------------|-------------------------------|----------------------------------------------------------------------------------------------------------------|--------|
+| Agent Lifecycle Hooks           | `agent-lifecycle-hooks`       | Enables chat lifecycle hook webhooks for agent chats.                                                          | Unsafe |
+| AI Gateway Seat Exclusion       | `ai-gateway-seat-exclusion`   | Excludes AI Gateway (AI Bridge) usage from AI Governance seat consumption.                                     | Unsafe |
+| Auto-fill Template Parameters   | `auto-fill-parameters`        | Pre-fills a new workspace's parameter form with the values from the user's most recent build of that template. | Unsafe |
+| Chat Advisor                    | `chat-advisor`                | Enables the advisor tool for root agent chats.                                                                 | Unsafe |
+| Chat Virtual Desktop            | `chat-virtual-desktop`        | Enables virtual desktop and computer use provider for agents.                                                  | Unsafe |
+| MCP HTTP Server Functionality   | `mcp-server-http`             | Enables the MCP HTTP server functionality.                                                                     | Unsafe |
+| MCP Tool Search                 | `mcp-tool-search`             | Defers MCP tool schemas behind a searchable catalog in agent chats.                                            | Unsafe |
+| NATS Pubsub                     | `nats_pubsub`                 | Enables embedded NATS pubsub.                                                                                  | Unsafe |
+| SMTP and Webhook Notifications  | `notifications`               | Sends notifications via SMTP and webhooks following certain events.                                            | Unsafe |
+| OAuth2 Provider Functionality   | `oauth2`                      | Enables OAuth2 provider functionality.                                                                         | Unsafe |
+| Workspace Build Updates Channel | `workspace-build-updates`     | Enables publishing workspace build updates to the all builds pubsub channel.                                   | Unsafe |
+| Workspace-Capable Licensing     | `workspace-capable-licensing` | Counts only users holding the workspace-create permission toward the license seat limit.                       | Unsafe |
+| Workspace Usage Tracking        | `workspace-usage`             | Enables the new workspace usage tracking.                                                                      | Unsafe |
 <!-- END: available-experimental-features -->
 
 ## Beta