Linear: CODAGT-157.

Four small fixes in docs/ai-coder/agents/ that surfaced during the Beta-rollout audit. Each is a doc-vs-code mismatch I verified against main. No behavior change.

What changes

1. Drop paused and completed from the chat statuses table

chats-api.md lists both as user-visible chat states. They are defined in codersdk/chats.go (and in the database enum) but no production path on main ever transitions a chat into either status today. PR #24264 (April 17) removed them from this table for that reason; PR #24642 (April 24, auto-archive) unintentionally re-added them. This restores the corrected table.

 | `running`         | Agent is actively working.                                                   |
-| `paused`          | Agent is paused (for example, waiting for user input).                       |
-| `completed`       | Agent finished and the task is complete.                                     |
 | `error`           | Agent encountered an error.                                                  |

2. Add action_required to the watch event-kinds table

ChatWatchEventKindActionRequired = "action_required" (codersdk/chats.go:1410) is emitted when a chat enters the requires_action state, but the doc table had no row for it. Anyone driving UI off GET /api/experimental/chats/watch cannot use the event without it being documented.

+| `action_required`    | A chat is waiting for a tool result. |
 | `deleted`            | A chat was deleted.                  |

3. Correct the auto-archive default to 0 (disabled)

DefaultChatAutoArchiveDays int32 = 0 in codersdk/chats.go:801. The doc said 90, both in prose and in the curl-output example.

-exempt. `0` disables the feature; the default is 90.
+exempt. `0` disables the feature, which is the default.
 ...
-# { "auto_archive_days": 90 }
+# { "auto_archive_days": 0 }

platform-controls/chat-auto-archive.md was already correct on this point.

4. Add the attach_file built-in tool to the tool tables

Implemented in coderd/x/chatd/chattool/attachfile.go:27 with the description “Attach a workspace file to the current chat so the user can download it directly from the conversation.” The tool is missing from both tool-list tables.

  | `process_signal`   ... |
+ | `attach_file`      ... |
  | `spawn_agent` ...      |

Added to index.md (Built-in tools) and architecture.md (Workspace tools).

What was dropped from this PR

An earlier revision widened the file-uploads supported-formats line in chats-api.md to mention text/plain, text/markdown, text/csv, application/json, and application/pdf alongside the four image types, citing the server-side allowlist in coderd/x/chatfiles/mime.go. Per review, the chat UI is image-only end-to-end (file picker uses accept="image/*", drag-drop filters with f.type.startsWith("image/"), native paste filters the same way). Widening the doc would imply a UX surface that does not exist, so the bullet was reverted to the original image-only wording. The server allowlist will be revisited as a separate change once a UI surface for non-image attachments lands.

Files

• docs/ai-coder/agents/chats-api.md (3 of the 4 fixes)
• docs/ai-coder/agents/index.md (attach_file row)
• docs/ai-coder/agents/architecture.md (attach_file row)

The larger-than-expected architecture.md diff is the markdown table formatter re-padding column widths to accommodate the longer description in the new attach_file row. No content drift outside the new row.

Validation

• pnpm exec markdownlint-cli2 … → 0 errors
• pnpm exec markdown-table-formatter … → stable (re-run produces no diff)
• bash scripts/check_emdash.sh → OK
• Cross-checked each claim against main:
  • grep -n DefaultChatAutoArchiveDays codersdk/chats.go → const … int32 = 0
  • grep -n ChatWatchEventKindActionRequired codersdk/chats.go → "action_required"
  • grep -n attach_file coderd/x/chatd/chattool/attachfile.go → tool registered
  • grep -rn ChatStatusPaused\\|ChatStatusCompleted … | grep -v _test.go | grep -v models.go → only enum-listing call sites; no production setter on main

Proof

Docs-text change with no UI/UX impact. The visible-string diffs are above. If reviewers want rendered before/after, I can attach screenshots.

Coder Agent generated this PR on @david-fraley's behalf.