docs: fix chat status names and auto-archive behavior claims - #28570
Merged
nickvigilante merged 2 commits intoAug 26, 2026
Merged
Conversation
Contributor
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
Contributor
Author
|
CI note for @nickvigilante: Pixel / Review reports 1 failed visual test (https://pixel.coder.com/@coder/coder/builds/11425). This check runs on the changed paths (rendered docs), so the diff likely reflects this PR's intended text changes and needs a human approval on the Pixel dashboard rather than a code fix. Generated by Coder Agents on behalf of @nickvigilante. |
Clarify language regarding chat auto-archive eligibility and behavior.
ethanndickson
approved these changes
Aug 26, 2026
nickvigilante
deleted the
vigilante/docs-722-fix-nonexistent-chat-statuses-and-auto-archive
branch
August 26, 2026 15:36
nickvigilante
added a commit
that referenced
this pull request
Sep 8, 2026
…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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two Coder Agents pages describe chat statuses that no longer exist and attribute auto-archive to the wrong subsystem. The valid status set is
waiting,running,error,requires_action,interrupting.architecture.md: a submitted prompt marks the chatrunning, notpending; there is no queued state.chat-auto-archive.md: the excluded status set isrunning,interrupting,requires_action.chat-auto-archive.md: the job runs in the chatd chat worker on an hourly tick, not indbpurge.chat-auto-archive.md: documents the dashboard control at AI Settings > Coder Agents > Lifecycle, and the 25-title cap on the digest notification.API paths on the auto-archive page are intentionally untouched; a separate PR fixes the
/api/v2to/api/experimentaldrift.Linear: DOCS-722 https://linear.app/codercom/issue/DOCS-722
Analysis evidence
codersdk/chats.go:ChatStatusconstants arewaiting,running,error,requires_action,interrupting. Nopending,paused, orcompleted.coderd/x/chatd/chatstate/transitions.go:sendMessageQueueAndSetStatusand the send paths applydatabase.ChatStatusRunning, so a submitted prompt isrunningimmediately.docs/ai-coder/agents/tasks-to-chats-migration.mdalready states that chats have no separate queued state.coderd/database/queries/chats.sql,GetAutoArchiveInactiveChatCandidates:status NOT IN ('running', 'interrupting', 'requires_action'), plusarchived = false,pin_order = 0,parent_chat_id IS NULL.coderd/x/chatd/auto_archive.go:archiveLoopruns fromcoderd/x/chatd/worker.goonopts.ArchiveInterval;coderd/x/chatd/options.gosetsdefaultArchiveInterval = time.Hour. Nothing indbpurgeperforms chat auto-archive.coderd/x/chatd/auto_archive.go:chatAutoArchiveDigestMaxChats = 25;buildAutoArchiveDigestDatatruncates to 25 titles and reports the remainder asadditional_archived_count.coderd/x/chatd/options.go:defaultArchiveBatchSize = int32(1000), so the existing "up to 1,000 root chats" claim stands.site/src/pages/AISettingsPage/LifecyclePage/LifecyclePageView.tsxmountsAutoArchiveSettings;site/src/modules/management/AISettingsSidebarView.tsxplaces the Lifecycle sub-nav item under Coder Agents.Validation:
pnpm run format-docs(no changes) andpnpm run lint-docs(0 errors).Generated by Coder Agents on behalf of @nickvigilante.