docs: define AI provider migration language#25411
Conversation
Docs preview📖 View docs preview for |
|
/coder-agents-review |
There was a problem hiding this comment.
The Flagged ambiguities section at the end of CONTEXT.md is genuine work: naming three specific terms that could cause confusion and resolving each. The audit decision for user keys is consistent with existing code.
5 P2, 5 P3, 1 P4, 2 Nit.
The central issue is that several definitions contradict committed artifacts in the same repository. The AI Bridge relationship claim contradicts the ai_providers table comment (7 of 10 reviewers flagged this independently). "Provider Kind" uses a term and example values that don't match the target schema. BYOK is described as deployment-wide while the code implements per-provider control. "Central API key" and "provider type" are told to be avoided while being the active terms in code, database, and shipped documentation.
As Zoro put it: "A terminology document that names a concept differently from every layer of the codebase that implements it will force every reader to maintain a mental translation table."
For a document whose purpose is to be the source of truth for downstream migration PRs, these contradictions are likely to produce the exact confusion the document aims to prevent.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
The R1 commit addressed 4 of 15 findings: DEREM-3 (AI Bridge contradiction reframed), DEREM-4 (Provider Kind renamed to Provider Type), DEREM-6 (BYOK now acknowledges both levels), DEREM-7 (Central API key migration path noted).
11 findings remain silent with no author response or code changes. Further review is blocked until these are addressed, acknowledged, or contested.
Silent P2:
- DEREM-5: Provider Type examples still list
bedrockandopenai-compat, which do not exist in theai_provider_typeenum. The rename from "Kind" to "Type" targeted DEREM-4 but did not fix the invalid enum values.
Silent P3:
- DEREM-1: CONTEXT.md still unreferenced by any file.
- DEREM-2: ADR still not in
docs/manifest.json;docs/adr/has no index. - DEREM-8: ADR still packs 5+ decisions into two paragraphs.
- DEREM-9: Example dialogue still uses present tense for a future capability (model configs referencing by ID).
- DEREM-10: Agents definition still mentions chatd then says to avoid it.
- DEREM-11: User AI Provider Key still has no target table in schema.
- DEREM-12: ADR still names only one of five legacy tables.
Silent P4/Nit:
- DEREM-13: "model config" still used but undefined.
- DEREM-14: ADR audit decision still justified by precedent only.
- DEREM-15: ADR tense still mixes present and future.
The ADR file was not modified at all in the R1 commit. If these findings are intentionally out of scope, a brief response on the threads would unblock the next review round.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
14 of 15 findings now addressed across two commits. The R2 commit tackled the remaining 10 open findings from R1: CONTEXT.md is now linked from AGENTS.md (DEREM-1), docs/adr/ has a README (DEREM-2), the ADR is restructured with Status/Context/Decision/Consequences (DEREM-8), temporal framing uses future tense (DEREM-9, DEREM-15), the Agents definition no longer leaks chatd (DEREM-10), User AI Provider Key is marked target-state (DEREM-11), legacy scope is explicit (DEREM-12), Model Config is defined (DEREM-13), and the audit decision has threat-model reasoning (DEREM-14).
1 finding remains silent:
- DEREM-5 (P2): Provider Type examples still list
bedrockandopenai-compat, which do not exist in theai_provider_typeenum (onlyopenaiandanthropic). This line was not touched in either commit and has no author response. A brief acknowledgment or fix would unblock the panel review.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
1 similar comment
|
/coder-agents-review |
There was a problem hiding this comment.
All 15 R1 findings resolved. The document is substantially improved: schema references verified, temporal framing consistent, ADR structured, discoverability addressed.
1 P2, 2 Nit new this round.
The DEREM-6 fix (BYOK granularity) introduced a new factual claim about chatd behavior that three reviewers independently disproved: chatd has zero references to the deployment BYOK setting. As Pariston noted: "The deployment AllowBYOK is a global gate at the AI Bridge middleware, and the per-provider key policy columns are independent controls on chat_providers that chatd reads directly." The same unverified-claim pattern that caused several R1 findings.
🤖 This review was automatically generated with Coder Agents.
There was a problem hiding this comment.
No new commits since R4 (head unchanged at 32f176a). All 3 open findings remain silent.
- DEREM-17 (P2): BYOK definition claims chatd maps the deployment BYOK setting into per-provider capability. Chatd has zero references to AllowBYOK. A fix or acknowledgment is needed.
- DEREM-18 (Nit): ADR says events "will remain unaudited" then calls them "audit records."
- DEREM-19 (Nit): "SDK" should read "generated database types" since AIProviderType is not in codersdk.
Further review is blocked until the author responds or pushes fixes.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
Responses to the remaining docs review findings:
|
|
/coder-agents-review |
There was a problem hiding this comment.
All 18 findings resolved across 6 rounds. No new findings from the R6 panel (10 reviewers, 0 findings). Multiple reviewers independently verified every schema reference, temporal framing marker, and code claim against the codebase.
As Mafu-san observed: "Three iterations on the BYOK definition, each more precise, each grounded in what the code actually shows. That is genuine convergence, not mechanical compliance."
The document lands in a solid state: terminology anchored to real schema objects, target-state language clearly distinguished from current behavior, ADR structured with context and consequences, and discoverability addressed via AGENTS.md.
🤖 This review was automatically generated with Coder Agents.
There was a problem hiding this comment.
Head unchanged from R6 (80702c7). The R6 panel (10 reviewers, 0 findings) already approved this exact code. All 18 findings resolved. The R6 APPROVE still stands.
🤖 This review was automatically generated with Coder Agents.
Stack Context
This stack migrates Agents chat provider configuration from legacy chat provider tables to the unified AI provider tables used by the AI provider administration surface.
What?
Defines the migration language and records the core source-of-truth decisions for AI providers, provider-scoped keys, user BYOK keys, and Agents as the consuming feature area.
Why?
The later schema, API, runtime, frontend, and cleanup PRs are easier to review with the terminology and trade-offs captured first.