docs: document org-scoped admin configuration for agents - #28482

Rescope after #28482, which fixes the same stale navigation in
models.md, advisor.md, chat-debug-logging.md, and platform-controls/index.md
and standardizes breadcrumbs to Admin settings > AI. Revert those four pages
here and adopt the same breadcrumb convention on the three remaining pages.

Documents the organization scoping of Coder Agents admin configuration,
and corrects the navigation paths, access wording, and default-model
instructions that no longer matched the product. Documentation only, no
product code changes.

Follows #28473, which moved the organization model overrides into an
**Organization settings** section on **Admin settings > AI > Coder
Agents**. #28473 is merged, so this targets `main`.

Closes CODAGT-715

- **New page**
`docs/ai-coder/agents/platform-controls/organizations.md`, registered in
`docs/manifest.json`. Covers the deployment/organization scope split,
what an upgrade changes, how an organization without models or MCP
servers behaves, who configures each scope, and how model and MCP server
sharing works.
- **`models.md`**: models are organization-scoped while providers and
their credentials stay deployment-wide. Each organization has one
default model, and the first model added becomes it. Documents the
**Default** badge and the **Set as Coder Agents default model** form
option in place of the star action that no longer exists, and points
model overrides at **Organization settings**.
- **`getting-started.md`**: replaces the Owner-only claim with the
actual access model, adds an organization selection step, and uses the
**Add model** label.
- **`platform-controls/index.md`**: separates deployment-wide controls
from organization-scoped controls, documents personal model overrides
alongside the model configuration section rather than as an enforcement
caveat, and adds `--agents-allowed` plus the `agents-allowed:` search
filter.
- **`platform-controls/advisor.md`** and
**`platform-controls/virtual-desktop.md`**: the Advisor and Virtual
desktop settings are cards in the **Deployment settings** section of the
**Coder Agents** page, not sidebar entries. **Providers** is a sidebar
item, not a tab.
- **`platform-controls/mcp-servers.md`**: slug uniqueness is per
organization, the **Add server** label is correct, and the page is no
longer described as admin-only.
- **`architecture.md`**, **`index.md`**,
**`tasks-to-chats-migration.md`**: organization scope corrections and
organization-scoped model routes.
- Breadcrumbs standardized to **Admin settings > AI > ...**, verified
against `AdminSettings.tsx` and `AISettingsSidebarView.tsx`.

<details>
<summary>Review follow-ups</summary>

The first revision leaked implementation detail into user-facing pages
and contained several claims that did not match the UI. The follow-up
commit removed and corrected the following.

Removed as implementation detail:

- The `chat_model_config` RBAC resource, its actions, and the token
scopes.
- The `available`, `unavailable_reason`, and `unsupported_providers`
response fields, along with the `missing_api_key`, `fetch_failed`, and
`user_api_key_required` values.
- Role and permission tables, ACL storage mechanics, audit internals,
and JSON error bodies on the new organizations page.
- Migration mechanics with no effect on what a user does.

Corrected against the product:

- The star action does not exist. The list shows a **Default** badge and
the add/edit form offers **Set as Coder Agents default model**
(`ModelRow.tsx`, `ModelFormFields.tsx`).
- The first model added to an organization becomes its default
automatically (`coderd/exp_chats.go`). An organization without a stored
default does not fail every chat, so that claim is gone.
- Advisor and Virtual desktop are cards under **Deployment settings**
(`CoderAgentsPageView.tsx`).
- The MCP servers page does not require deployment configuration edit
permission (`AISettingsSidebarView.tsx`).
- Button labels: **Add model** and **Add server**.
- The organization query parameter is `org`, confirmed by
`modelOrganizationSearchParam`.

Left alone deliberately: pre-existing defects outside the introduced
text, including the `/api/v2/chats` route prefixes, create-chat examples
missing `organization_id`, and the pre-existing MCP permissions table.

</details>

- `pnpm run format-docs` and `pnpm run lint-docs` pass.
- `make lint/emdash` passes. No emdash or endash added.
- `grep -rn "Defaults & overrides" docs/` returns nothing.
- Every navigation path, button label, and access claim checked against
the corresponding file under `site/src/pages/AISettingsPage/` and
`site/src/modules/management/`.

---

This pull request was generated by Coder Agents on behalf of
@ethanndickson.

(cherry picked from commit 409049d)

## Summary

Fixes stale admin navigation on the three Coder Agents platform-controls
pages not covered by #28482: the retention pages pointed at tabs that do
not exist ("Behavior", the old Agents settings "Lifecycle" tab), and
template optimization pointed at the removed **Agents** > **Settings** >
**Manage Agents** navigation.

Breadcrumbs follow the **Admin settings** > **AI** > **Coder Agents**
convention established by #28482.

## Changes

- `docs/ai-coder/agents/platform-controls/chat-retention.md`: replace
the nonexistent **Behavior** tab with **Admin settings** > **AI** >
**Coder Agents** > **Lifecycle**.
- `docs/ai-coder/agents/platform-controls/chat-debug-retention.md`: same
page, same convention, aligned with chat-retention.md.
- `docs/ai-coder/agents/platform-controls/template-optimization.md`:
replace **Agents** > **Settings** > **Manage Agents** > **Templates**
with **Admin settings** > **AI** > **Coder Agents** > **Templates**.

## Scope note

The first revision also fixed `models.md`, `advisor.md`,
`chat-debug-logging.md`, and `platform-controls/index.md`. Those pages
are covered by #28482 with the same corrections, so this PR reverted
them to avoid conflicting edits and adopted that PR's breadcrumb
convention instead.

Linear: DOCS-715 https://linear.app/codercom/issue/DOCS-715

<details><summary>Analysis evidence</summary>

- `site/src/router.tsx` (~735-780):
`/ai/settings/{lifecycle,templates,coder-agents}` are the live routes;
`/agents/settings/{admin pages}` (~833-890) are `Navigate`-only
redirects.
- No "Behavior" tab exists in any router revision;
`RetentionPeriodSettings` and `DebugRetentionSettings` both render in
`LifecyclePageView.tsx`.
- Breadcrumb convention **Admin settings** > **AI** verified against
`AdminSettings.tsx` / `AISettingsSidebarView.tsx` in #28482.

</details>

Generated by Coder Agents on behalf of @nickvigilante.

#28584)

Cherry-pick of #28482

Original PR: #28482 — docs: document org-scoped admin configuration for
agents
Merge commit: 409049d
Requested by: @ethanndickson

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Ethan <[email protected]>
Co-authored-by: Ethan Dickson <[email protected]>

…le (#28594)

Agent-authored docs PRs kept leaking implementation detail into
user-facing pages: chat status enum values and `root_chat_id` on the
auto-archive page (#28570, flagged by reviewers), and RBAC resource
names and response fields in the first revision of #28482. The
correction pattern was the same each time: state the behavior in the
reader's terms.

This encodes that pattern as one canonical rule with citations in every
file that carries the exact-values instruction:

- `docs/.style/content-guidelines.md`: new guiding principle "Evidence
justifies a claim; it does not belong in the claim". The test is scoped
to the task the page documents, with a first-match ladder: exact value
where the reader types or receives it, visible product wording where the
screen shows it, plain reader's-terms prose otherwise. An identifier set
described as a set resolves at the lowest rung any member reaches.
Stripped identifiers are named (file and symbol) in the PR discussion as
a best-effort pointer for the reviewer. Cross-linked with
verify-exact-values, describe-current-version, the routing table, and
word-choice. Also repairs a pre-existing broken feature-stages link.
- `docs/.style/style-guide/word-choice.md`: the internal-references
section notes that implementation identifiers follow the (conditional)
canonical rule, covering the prose-edit route that AGENTS.md sends to
the prose style guide.
- `.claude/docs/DOCS_STYLE_GUIDE.md`: the Accuracy Standards section
head and Key Principles item 2 carry the same qualifier, since this
always-loaded file is where agents get the unqualified exact-values
instruction.
- `.claude/skills/write-docs/SKILL.md`: workflow step 1 marks copied
identifiers as verification inputs with a forward link; citation-only
"Evidence versus claim" section; matching anti-pattern bullet and a
checklist item that defers the stripped-identifier disclosure to the
canonical rule.
- `.claude/skills/doc-check/SKILL.md`: "Evidence versus claim" check
scoped to identifiers the change adds or touches, working from the diff
(doc-check does not police the disclosure, which it cannot see);
pre-existing violations on untouched pages are informational only.

The motivating page (`chat-auto-archive.md`) was fixed separately in
#28570 (DOCS-722, merged). Corpus sweep for other violations: DOCS-730.
Lint and link coverage for the `.claude` and `docs/.style` trees:
DOCS-729.

Linear: DOCS-728 https://linear.app/codercom/issue/DOCS-728

<details>
<summary>CI note (docs-only PR)</summary>

This PR changes only Markdown under `docs/.style/` and `.claude/` (no
`site/src` or other product code).

- The `ci` workflow's docs-relevant jobs pass on the head commit:
`changes`, `gen`, `lint`, `lint-docs`, `fmt`, `offlinedocs`, `required`.
Heavy build/test jobs are correctly skipped for a docs-only change.
(Run: https://github.com/coder/coder/actions/runs/32986743037)
- `Pixel / Review` (frontend visual snapshots) is unrelated to the
changed paths and is treated as an unrelated flake.

</details>

> This PR was created with AI assistance (Coder Agents).