Adds two new documentation pages under platform controls for Coder
Agents:
- **Git Providers** (`git-providers.md`) — documents the `API_BASE_URL`
configuration required for self-hosted GitHub Enterprise deployments.
Positions it as an extension of the existing [external
auth](https://coder.com/docs/admin/external-auth) setup to support Coder
Agents features that need richer git host API access: the in-chat diff
viewer and PR Insights.
- **PR Insights** (`pr-insights.md`) — documents the PR analytics
dashboard, requirements for PR data to appear, and troubleshooting.
Links to git-providers for GHE setup.
Also updates the platform controls index and docs manifest.
---
> PR generated with Coder Agents
> This PR was authored by Mux on behalf of Mike.
## Summary
- add persistent plan mode for chats and the chat-specific plan file
flow
- add structured planning tools such as `ask_user_question` and
`propose_plan`
- keep `write_file` and `edit_files` constrained to the chat-specific
plan file during plan turns
- allow shell exploration in plan mode, including subagents, via
`execute` and `process_output`
- block implementation-oriented, provider-native, MCP, dynamic, and
computer-use tools during plan turns
- update the chat UI, tests, and docs for the new planning flow
Fixes several documentation gaps and inaccuracies in the Coder Agents
docs identified during a deep review against the current product state.
## BYOK (User API Keys)
`models.md` stated *"Developers cannot add their own providers, models,
or API keys"* — this has been incorrect since the provider key policy
system shipped (Apr 2, #23751/#23781).
- Added **Key policy** section documenting the three admin toggles
(`central_api_key_enabled`, `allow_user_api_key`,
`allow_central_api_key_fallback`) with a truth table showing all
resolution outcomes
- Added **User API keys (BYOK)** section covering the developer-facing
key management page, status indicators, selection priority, and key
removal
- Updated `platform-controls/index.md` to reference BYOK instead of
claiming keys are admin-only
## Reasoning effort enum fixes
- **OpenAI**: removed `none` — code accepts `minimal, low, medium, high,
xhigh`
- **OpenRouter**: narrowed to `low, medium, high` per
`ReasoningEffortFromChat` in `chatprovider.go`
## Tool table completeness
- Added `spawn_computer_use_agent`, `read_skill`, `read_skill_file` to
`index.md` tool table
- Added "Workspace extension tools" section to `architecture.md` for
`read_skill`/`read_skill_file`
- Fixed orchestration restriction note to list all 5 gated tools instead
of just `spawn_agent`
- Added conditional availability notes for desktop and skills tools
## Platform controls
Three admin-only settings existed in the Behavior tab with no
documentation:
- **Virtual desktop** — admin toggle, Anthropic + portabledesktop
requirements
- **Workspace autostop fallback** — default TTL for agent workspaces
without template-defined autostop
- **Data retention** — moved `chat-retention.md` into
`platform-controls/` since it's admin-only, fixed nav path
---
> PR generated with Coder Agents
Adds three new documentation pages for major shipped features that had
no docs, and updates the platform controls index to reflect current
state.
## New pages
### Extending Agents (`extending-agents.md`)
Covers two workspace-level extension mechanisms:
- **Skills** — `.agents/skills/<name>/SKILL.md` directory structure,
frontmatter format, auto-discovery, `read_skill`/`read_skill_file`
tools, size limits, lazy loading
- **Workspace MCP tools** — `.mcp.json` format, stdio and HTTP
transports, tool name prefixing, discovery lifecycle and caching
### MCP Servers (`platform-controls/mcp-servers.md`)
Admin MCP server configuration:
- CRUD via **Agents** > **Settings** > **MCP Servers**
- Four auth modes: none, OAuth2 (with auto-discovery), API key, custom
headers
- Availability policies: `force_on`, `default_on`, `default_off`
- Tool governance via allow/deny lists
- Permission model and secret redaction
### Usage & Insights (`platform-controls/usage-insights.md`)
Three admin dashboards:
- **Usage limits** — spend caps with per-user and per-group overrides,
priority hierarchy, enforcement behavior
- **Cost tracking** — per-user rollup with token breakdowns, date
filtering, per-model and per-chat drill-down
## Updated files
- **`platform-controls/index.md`** — Moved MCP servers, usage limits,
and analytics from "Where we are headed" into "What platform teams
control today" with links to the new pages. Removed the tool
customization roadmap section (now covered by MCP servers page).
- **`manifest.json`** — Added nav entries for all three new pages.
## Resulting nav hierarchy
```
Coder Agents
├── Getting Started
├── Early Access
├── Architecture
├── Models
├── Platform Controls
│ ├── Template Optimization
│ ├── MCP Servers ← NEW
│ └── Usage & Insights ← NEW
├── Extending Agents ← NEW
└── Chats API
```
---
*PR generated with Coder Agents*
Addresses five documentation gaps identified from an internal agents
briefing Q&A, specifically around what permissions an agent inherits
from the user:
1. **No privilege escalation** — Added explicit statement that the agent
has the exact same permissions as the user. No escalation, no shared
service account.
2. **Cross-user workspace isolation** — Added statement that agents
cannot access workspaces belonging to other users.
3. **Default-state warning** — Added WARNING callouts that agent
workspaces inherit the user's full network access unless templates
explicitly restrict it.
4. **Tool boundary statement** — Added explicit statement that the agent
cannot act outside its defined tool set and has no direct access to the
Coder API.
5. **Template visibility scoped to user RBAC** — Clarified that template
selection respects the user's role and permissions.
Changes across 3 files:
- `docs/ai-coder/agents/index.md`
- `docs/ai-coder/agents/architecture.md`
- `docs/ai-coder/agents/platform-controls/template-optimization.md`
---
PR generated with Coder Agents
Renames the page title from "Template Routing" to "Template
Optimization" in both the markdown H1 header and the docs manifest
entry.
---
PR generated with Coder Agents
Add a new docs page under /docs/ai-coder/agents/ covering best practices
for creating templates that are discoverable and useful to Coder Agents.
Covers template descriptions, dedicated agent templates, network
boundaries, credential scoping, parameter design, pre-installed tooling,
and prebuilt workspaces for reducing provisioning latency.
<!--
If you have used AI to produce some or all of this PR, please ensure you
have read our [AI Contribution
guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
before submitting.
-->
Matt Vollmer