Updates `docs/ai-coder/index.md`, `docs/ai-coder/best-practices.md`, and
`docs/ai-coder/ai-governance.md` to point readers at Coder Agents and
the AI Governance Add-On instead of Coder Tasks and Agent Firewall
(CODAGT-157).
## Changes
- `docs/ai-coder/index.md`:
- Rename `## Agents with Coder Tasks` to `## Coder Agents`. Drop the
Devin / ChatGPT Codex name-drops and the Tasks pitch. New copy points at
`./agents/index.md`, names the agent loop in the control plane, and
notes that workspaces can be completely network isolated. Image swapped
from `tasks-ui.png` to `agents-hero-image.png` (the hero shot added in
#24915).
- Replace the `## Secure Your Workflows with Agent Firewall` section
with `## Govern AI activity with the AI Governance Add-On`. The new
section opens with adoption-first framing (visibility, guardrails, cost)
and links to `./ai-governance.md`, with bulleted callouts for AI
Gateway, Agent Firewall, and the expanded Agent Workspace Build
allowance the add-on bundles.
- `docs/ai-coder/best-practices.md`:
- In the use-case table, swap `[Tasks](./tasks.md)` to `[Coder
Agents](./agents/index.md)` for the developer-led-investigation and
prototyping rows, and swap the "Tasks API *(in development)*" cell to
`[Coder Agents API](./agents/chats-api.md)` for the background-jobs row.
Retitle the Security section link from "securing agents with Coder
Tasks" to "securing AI agents" since `security.md` does not actually
mention Tasks. Re-ran `markdown-table-formatter` to repad column widths.
- In `## Provide Agents with Proper Context`, add a paragraph describing
how context is provided in Coder Agents (admin-configured system
prompts, centrally registered MCP servers, and skills shipped from repos
or templates under `.agents/skills/`), with a transition line clarifying
that the existing Memory and Tools subsections cover BYO-agent patterns.
- `docs/ai-coder/ai-governance.md`: drop the "Additional Tasks Use (via
Agent Workspace Builds)" bullet from the intro feature list and the
"Expanding the use of Coder Tasks for AI-driven background work" bullet
from the audience list. The `## How Coder Tasks usage is measured`
section and the rest of the Tasks-related prose on this page are
intentionally left for a follow-up PR.
## Notes for the reviewer
- The `[Coder Agents API](./agents/chats-api.md)` link in
`best-practices.md` will need to be retargeted if #24830 (which replaces
`agents/chats-api.md` with auto-generated `reference/api/chats.md`)
lands first.
- This is the first slice of the Tasks-references audit. Remaining files
(`tasks-core-principles.md`, `tasks-lifecycle.md`, `tasks-migration.md`,
`cli.md`, `github-to-tasks.md`, `agent-compatibility.md`, the rest of
`ai-governance.md`, `custom-agents.md`,
`ai-gateway/clients/claude-code.md`, `manifest.json`,
`reference/api/tasks.md`, the `task*` CLI references, the ESR upgrade
guide, `feature-stages.md`, `workspace-scheduling.md`,
`shared-workspaces.md`) will land in follow-up PRs against the same
Linear ticket. Open PRs #24831, #24833, and #24841 cover separate slices
and do not touch any file in this PR.
- Validation: `markdownlint-cli2`, `markdown-table-formatter`,
`scripts/check_emdash.sh`, and `make pre-commit-light` all pass.
PR generated with Coder Agents.
david-fraley