coder · ethanndickson · Aug 25, 2026 · Aug 24, 2026 · Aug 24, 2026 · Aug 25, 2026
diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md
@@ -290,12 +290,12 @@ plane, not from the workspace's network.
 
 ### Centralized enforcement
 
-Administrators control which models are available, the system prompt, and tool
-configuration from the control plane. Developers can select from the set of
-admin-enabled models when starting or continuing a chat, but cannot add their
-own providers or override system prompts or tool permissions. When an
-administrator removes a model or modifies the system prompt, the change applies
-to all agent sessions immediately.
+Administrators control which models are available, the system prompt, and tool configuration from the control plane.
+The system prompt and the tool configuration are deployment-wide.
+The model list belongs to an organization, so a chat can only use the models of its own organization.
+Developers can select from the set of admin-enabled models when starting or continuing a chat, but cannot add their own providers or override system prompts or tool permissions.
+When an administrator removes a model or modifies the system prompt, the change applies to all affected agent sessions immediately.
+Refer to [Organization scope](./platform-controls/organizations.md) for the settings that belong to each scope.
 
 ### User identity on every action
 

diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md
@@ -1,4 +1,4 @@
 # Getting Started

 This guide walks platform teams and administrators through setting up Coder
 Agents, preparing your deployment, and running your first Coder Agent.
@@ -17,6 +17,9 @@
   [descriptive name and description](./platform-controls/template-optimization.md)
   for the agent to select when provisioning workspaces.
 - **Admin access** to the Coder deployment for configuring providers.
+- **Access to configure models** in each organization where you configure models.
+  The **Organization Admin** role and the **Owner** role include this access.
+  A custom role with model configuration access also works.
 - **Coder Agents User role** assigned to each user who needs to interact with Coder Agents.
   This role is granted **per organization**. Owners and organization admins can
   assign it from **Admin settings** > **Organizations** > _[your organization]_ >
@@ -26,19 +29,29 @@
 ## Step 1: Configure an LLM provider and model
 
 > [!IMPORTANT]
-> Configuring providers, models, and system prompts requires the
-> **Owner** role (Coder administrator). Non-admin users cannot access the
-> admin Settings panel or modify deployment-level Agents configuration.
+> Deployment administrators configure providers and deployment settings.
+> Users with model configuration access in an organization configure that organization's models.
+> Coder enables the edit controls for the organization that you select.
+> Coder shows the deployment settings only to deployment administrators.
+> Users with model access can view the relevant Models and Coder Agents pages.
+> Users with MCP server access can open the MCP servers page.
 
 To configure Coder Agents:
 
 1. Navigate to **Admin settings** > **AI** and select **Providers**.
 1. Add or update a provider with its credentials and upstream endpoint, then
    save it.
 1. Navigate to **Admin settings** > **AI** > **Models**.
-1. Click **Add** and configure at least one model with its identifier, display
-   name, and context limit.
-1. Click the **star icon** next to a model to set it as the default.
+1. Select the correct organization.
+   Coder shows the organization picker when you can access more than 1 organization.
+1. Select **Add model** and configure at least one model with its identifier, display name, and context limit.
+
+Coder makes the first model of an organization the default model.
+To change the default later, open a model and select **Set as Coder Agents default model**.
+
+Each organization has its own model list and its own default model.
+Repeat the model steps in every organization that uses Coder Agents.
+Refer to [Organization scope](./platform-controls/organizations.md) for the settings that stay deployment-wide.
 
 Detailed instructions for each provider and model option are in the
 [Models](./models.md) documentation.
@@ -189,7 +202,7 @@
 - Required review processes before merging.
 - Any guardrails specific to your environment.
 
-Configure the system prompt from **AI Settings** > **Coder Agents** > **Instructions**
+Configure the system prompt from **Admin settings** > **AI** > **Coder Agents** > **Instructions**
 or via the API at `PUT /api/v2/chats/config/system-prompt`.
 See [Platform Controls](./platform-controls/index.md) for details.
 
@@ -303,7 +316,7 @@
 to maintain a pool of ready-to-use workspaces. The agent gets assigned an
 already-running workspace instead of provisioning from scratch.

 ## Providing feedback

 Coder Agents is a collaborative evaluation between your team and Coder.
 Share feedback — workflow observations, feature requests, bugs, performance

diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md
@@ -14,9 +14,9 @@ Your browser does not support the video tag.
 
 ## What Coder Agents is and isn't
 
-It is a standalone agent written in Go that implements standard
-agentic patterns — sub-agent delegation, context compaction, file editing, and
-shell execution — and works with any LLM provider you configure.
+It is a standalone agent written in Go.
+It implements standard agentic patterns, such as sub-agent delegation, context compaction, file editing, and shell execution.
+It works with any LLM provider you configure.
 
 It is not a wrapper around third-party agent tools like Claude Code
 or Codex.
@@ -90,6 +90,8 @@ creates a workspace automatically. Template visibility is scoped to the user's r
 Platform teams control template routing by writing clear template descriptions.
 For example, a description like "Use this template for Python backend services
 in the payments repo" helps the agent select the correct infrastructure.
+Administrators can also block agents on a template, which hides it from the agent completely.
+Refer to [Platform Controls](./platform-controls/index.md#template-routing) for that setting.
 
 **Examples of what triggers workspace creation:**
 
@@ -166,7 +168,7 @@ entirely:
   else. The workspace never needs to reach the internet for AI functionality.
 - **Centralized, enforced control.** Platform teams configure models, system
   prompts, and tool permissions from the control plane. These settings are
-  enforced server-side — they are not user preferences that developers can
+  enforced server-side, so they are not user preferences that developers can
   override.
 - **User identity is always attached.** Every action the agent takes — PRs
   opened, code pushed, commands run — is tied to the user who submitted the
@@ -217,8 +219,10 @@ and models from the Coder dashboard or API. Supported providers include:
 Most providers support custom base URLs, which allows integration with
 enterprise LLM proxies, self-hosted model endpoints, and internal gateways.
 
-Administrators can configure multiple providers simultaneously and set a default
-model. Developers select from enabled models when starting a chat.
+Administrators can configure multiple providers simultaneously and set a default model in each organization.
+Developers select from enabled models when starting a chat.
+Providers are deployment-wide, and models belong to an organization.
+Refer to [Organization scope](./platform-controls/organizations.md) for details.
 
 <img src="../../images/guides/ai-agents/llm-providers.png" alt="Screenshot of the provider/model configuration in the Agents settings">
 

diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md
@@ -1,10 +1,10 @@
 # Models
 
-Administrators configure LLM providers from **Admin settings** > **AI** and
-Coder Agents models from **Admin settings** > **AI** > **Models**. Providers,
-models, and centrally managed credentials are deployment-wide settings managed
-by platform teams. Developers select from the set of models that an administrator has
-enabled.
+Administrators configure LLM providers from **Admin settings** > **AI** and Coder Agents models from **Admin settings** > **AI** > **Models**.
+Providers and centrally managed credentials are deployment-wide settings managed by platform teams.
+Each model belongs to an organization. Each organization has its own model list.
+Developers select from the set of models that an administrator has enabled in their organization.
+Refer to [Organization scope](./platform-controls/organizations.md) for the split between deployment-wide and organization-scoped settings.
 
 Optionally, administrators can enable AI Gateway Bring Your Own Key (BYOK)
 so developers can supply personal API keys for providers. See
@@ -43,8 +43,8 @@
 
 ### Add a provider
 
-LLM providers are managed from the deployment AI settings, not from the Agents
-settings page.
+LLM providers are managed from the deployment AI settings, not from the Agents settings page.
+A provider is deployment-wide, whilst the models that reference it are organization-scoped.
 
 1. Navigate to **Admin settings** > **AI**.
 1. Select **Providers**.
@@ -55,9 +55,9 @@
    [endpoint/base URL](#endpointbase-url-for-openai-compatible-providers).
 1. Click **Save**.
 
-After saving a provider, add an Agents model for it from **Admin settings** >
-**AI** > **Models**. For provider-specific setup, including AWS Bedrock, see
-[AI Gateway provider configuration](../ai-gateway/providers.md#provider-types).
+After saving a provider, add an Agents model for it from **Admin settings** > **AI** > **Models**.
+Select the organization that should own the new model before you add it.
+For provider-specific setup, including AWS Bedrock, refer to [AI Gateway provider configuration](../ai-gateway/providers.md#provider-types).
 
 ## Endpoint/base URL for OpenAI-compatible providers
 
@@ -102,8 +102,8 @@
 
 ## Credential selection
 
-Coder Agents use the AI providers configured by administrators. Provider API
-keys entered by administrators are centralized credentials for the deployment.
+Coder Agents use the AI providers configured by administrators.
+Provider API keys entered by administrators are centralized credentials for the deployment.
 
 BYOK for Coder Agents is controlled by the
 [global AI Gateway BYOK setting](../ai-gateway/auth.md#bring-your-own-key-byok),
@@ -137,19 +137,19 @@
 Coder shows model fields as read-only unless the member also has update permission.
 Create, update, delete, and share permissions control their corresponding actions independently.
 
-### Share a model
+### Manage model permissions
 
-Members with model share permission can grant model read access to members and groups in the selected organization.
+Members with model share permission can let members and groups in the selected organization use the model.
 
 1. Navigate to **Admin settings** > **AI** > **Models**.
 2. Select the organization that owns the model.
 3. Select the model.
-4. Open **Model actions** and select **Share model**.
+4. Open **Model actions** and select **Manage permissions**.
 5. Add or remove organization members and groups.
-6. Select **Save**.
+6. Select **Save permissions**.
 
 Coder applies the member and group changes when you save.
-Removing all entries clears the model's access list, so members without another read grant lose access on their next request.
+Removing all entries clears the model's access list, so members without another access grant cannot use the model on their next request.
 
 ### Model visibility and runtime availability
 
@@ -158,23 +158,23 @@
 
 The Agents model selector includes the model only when its exact provider configuration has usable credentials for that member.
 Coder evaluates providers by provider UUID, so 2 providers of the same type can have different availability.
-An unavailable provider can remain visible with a redacted reason while its models are omitted from the selector.
+An unavailable provider can remain visible while its models are omitted from the selector.
 
 Model APIs identify each configured model with a UUID.
 The provider's model identifier, such as `gpt-5.3-codex`, doesn't replace this model UUID.
 
 ### Add a model
 
 1. Navigate to **Admin settings** > **AI** > **Models**.
-1. Click **Add** and select the provider for the new model.
+1. Select **Add model** and select the provider for the new model.
 1. Enter the **Model Identifier**, the exact model string your provider
    expects (e.g., `claude-opus-4-6`, `gpt-5.3-codex`).
 1. Set a **Display Name** so developers see a human-readable label in the model
    selector.
 1. Set the **Context Limit**, the maximum number of tokens in the model's
    context window (e.g., `200000` for Claude Sonnet).
 1. Configure any provider-specific options (see below).
-1. Click **Save**.
+1. Select **Save**.
 
 <img src="../../images/guides/ai-agents/models-list.png" alt="Screenshot of the models list in the Agents settings">
 
@@ -188,9 +188,18 @@
 
 ### Set a default model
 
-Click the **star icon** next to a model in the models list to make it the
-default. The default model is pre-selected when developers start a new chat.
-Only one model can be the default at a time.
+Each organization has one default model.
+The first model that you add to an organization becomes that organization's default model.
+The models list marks the current default with a **Default** badge.
+The default model is pre-selected when developers start a new chat in the organization.
+
+To change the default model:
+
+1. Navigate to **Admin settings** > **AI** > **Models**.
+1. Select the organization that owns the model.
+1. Open the model, or click **Add model** to create a new one.
+1. Select **Set as Coder Agents default model**.
+1. Click **Save**.
-1. Click **Save**.
+1. Select **Save**.
-1. Click **Save**.
+1. Select **Save**.
 
 ### Models with a missing or disabled provider
 
@@ -280,15 +289,14 @@
 
 ## How developers select models
 
-Developers see a model selector dropdown when starting or continuing a chat on
-the Agents page. The selector shows only models from providers that have valid
-credentials configured. Models are grouped by provider if multiple providers
-are active.
+Developers see a model selector dropdown when starting or continuing a chat on the Agents page.
+The selector shows only models in the chat's organization that come from providers with valid credentials.
+Models are grouped by provider if multiple providers are active.
 
 The model selector uses the following precedence to pre-select a model:
 
 1. **Last used model**, stored in the browser's local storage.
-1. **Admin-designated default**, the model marked with the star icon.
+1. **Organization default**, the model marked with the **Default** badge.
 1. **First available model**, if no default is set and no history exists.
 
 Developers cannot add their own providers or models. If no models are
@@ -297,19 +305,20 @@
 
 ## Model overrides
 
-Beyond the chat-level model picker, Coder Agents supports two override
-layers. Both are stored per organization and resolve from the chat's
-organization:
+Beyond the chat-level model picker, Coder Agents supports two override layers.
+Both are stored per organization and resolve from the chat's organization:
+
+- **Admin overrides** (per organization): Pin specific contexts to a particular model.
+  Configure them in the **Organization settings** section of **Admin settings** > **AI** > **Coder Agents**.
+  Coder shows an organization picker in that section when you can access more than 1 organization.
+- **Personal overrides** (per user and organization, opt-in by admin): Let users override the model for their own root chats and delegated subagents.
+  Admins enable the deployment-wide toggle in the **Deployment settings** section of the same page.
+  Once the toggle is on, each user sees an **Agents** tab in their personal **Agents** > **Settings**.
+  Users in more than one organization pick which organization to configure.
 
-- **Admin overrides** (per organization): Pin specific contexts to a
-  particular model. Configure them on the **Defaults & overrides** tab
-  under **AI Settings** > **Models** for the selected organization.
-- **Personal overrides** (per user and organization, opt-in by admin):
-  Let users override the model for their own root chats and delegated
-  subagents. Admins enable the deployment-wide toggle under
-  **AI Settings** > **Coder Agents**; once on, each user sees an
-  **Agents** tab in their personal **Agents** > **Settings**. Users in
-  more than one organization pick which organization to configure.
+The **Coder Agents** page is visible to deployment admins and to organization members with model access.
+To change an organization override, you need permission to edit that organization's models.
+The **Deployment settings** section is visible only to deployment admins.
 
 > [!IMPORTANT]
 > When a deployment upgrades from the older deployment-wide override
@@ -360,7 +369,7 @@
 enabled, developers can supply personal API keys for any enabled AI provider
 from the Agents settings page.

 ### Managing personal API keys

 1. Navigate to the **Agents** page in the Coder dashboard.
 1. Open **Settings** and select the **API Keys** tab.
@@ -377,14 +386,14 @@
 used for deployment-managed provider secrets. The dashboard never displays a
 saved key, only whether one is set.

 ### Removing a personal key

 Click **Remove** on the provider card in the API Keys settings tab. Subsequent
 requests use deployment-managed credentials when they are configured for that
 provider. If no deployment-managed credential is available, add a new personal
 key before you use models from that provider.

 ## Using an LLM proxy

 Organizations that route LLM traffic through a centralized proxy, such as
 LiteLLM or an internal gateway, can point a provider's **Endpoint** or **Base

diff --git a/docs/ai-coder/agents/platform-controls/advisor.md b/docs/ai-coder/agents/platform-controls/advisor.md
@@ -30,19 +30,17 @@ after repeated failures, or risk reduction before a destructive operation.
 ## Configuration
 
 Once the experiment is enabled, configure the advisor's runtime limits
-under **AI Settings** > **Coder Agents** > **Advisor**. These limits apply
-deployment-wide.
+under **Admin settings** > **AI** > **Coder Agents** > **Deployment settings**.
+Use the **Advisor** card. These limits apply deployment-wide.
 
 | Field             | Default              | Notes                                                                                                                   |
 |-------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------|
 | Max uses per turn | `0` (unlimited)      | Caps how many times the root agent can call the advisor in a single chat turn. Must be a non-negative integer.          |
 | Max output tokens | `0` (server default) | Caps the advisor model's response length. `0` uses the server default of 16,384 tokens. Must be a non-negative integer. |
 
-The advisor model and its reasoning effort are organization-scoped
-[model overrides](../models.md#model-overrides). Configure them on the
-**Defaults & overrides** tab under **AI Settings** > **Models** for the
-selected organization. When no override is set, the advisor reuses the
-root agent's model.
+The advisor model and its reasoning effort are organization-scoped [model overrides](../models.md#model-overrides).
+Configure them in the **Organization settings** section of **Admin settings** > **AI** > **Coder Agents** for the selected organization.
+When no override is set, the advisor reuses the root agent's model.
 
 The advisor is not available in plan mode or to subagents.
 Failed advisor invocations refund the per-turn budget.

diff --git a/docs/ai-coder/agents/platform-controls/chat-debug-logging.md b/docs/ai-coder/agents/platform-controls/chat-debug-logging.md
@@ -11,7 +11,7 @@ Off by default. Three layers control whether it runs for a given chat:
    on for every chat. The runtime admin and user toggles become read-only.
 1. **Runtime admin gate.** With the deployment override unset, the
    *Let users record chat debug logs* toggle decides whether users can opt
-   in. Configure it under **AI Settings** > **Lifecycle**, or at
+   in. Configure it under **Admin settings** > **AI** > **Coder Agents** > **Lifecycle**, or at
    `GET/PUT /api/v2/chats/config/debug-logging`.
 1. **Per-user toggle.** Users with the admin gate enabled can turn debug
    logging on for their own chats from **Agents** > **Settings** > **General**