From 5818cfb80fa5a89f2f7f678f08de1b0df2fdc0af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rouzbeh=E2=80=A0?=
 <78313022+rqzbeh@users.noreply.github.com>
Date: Sun, 23 Aug 2026 02:37:11 +0330
Subject: [PATCH] docs(cli): update opencode.ts JSDoc to reflect 128k context
 fallback (#11035) (#11157)

Cherry-picked the JSDoc commit onto the current tip (authorship preserved), stripping the stale generated-count noise files. Focused: opencode-v2-config-11070 2/2. Comments now match the 128k fallback shipped in #11035/#11054. Thank you @rqzbeh!
---
 .../cli-helper/config-generator/opencode.ts    | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/lib/cli-helper/config-generator/opencode.ts b/src/lib/cli-helper/config-generator/opencode.ts
index a2329968ab..e65206dc55 100644
--- a/src/lib/cli-helper/config-generator/opencode.ts
+++ b/src/lib/cli-helper/config-generator/opencode.ts
@@ -280,10 +280,9 @@ function buildModelEntry(
   }
 
   // Resolve the context window. Honor an explicit user override, then fall
-  // back to the catalog. We do NOT synthesize a default — if the catalog
-  // is unaware of a model's window, the opencode.json will simply omit
-  // `limit.context` for that model and OpenCode's own heuristics apply.
-  // (OpenCode v1 defaults to 128K when `limit.context` is missing.)
+  // back to the catalog. If the catalog is unaware of a model's window, we
+  // fall back to a safe default (128K) so OpenCode's v1 provider schema
+  // validator never rejects the config with a missing key error (#11035).
   const userLimit = existing?.limit?.context;
   const catalogLimit = catalog ? resolveContextLength(catalog) : undefined;
   const context = typeof userLimit === "number" && userLimit > 0 ? userLimit : catalogLimit;
@@ -292,9 +291,6 @@ function buildModelEntry(
   // Use the catalog's max_output_tokens when available; otherwise fall
   // back to the user's existing `limit.output` and finally to a small
   // default (8K) so OpenCode never errors on a totally missing output cap.
-  // We do NOT default context — context is a property of the model and
-  // we have no business guessing. Output is a per-request setting and a
-  // small default is harmless when truly unknown.
   const userOutput = existing?.limit?.output;
   const catalogOutput =
     catalog && typeof catalog.max_output_tokens === "number" && catalog.max_output_tokens > 0
@@ -411,7 +407,7 @@ export interface GenerateOpencodeOptions {
   /**
    * If `true` (default), the generator fetches the live `/v1/models` catalog
    * so every model entry has an explicit `limit.context`. The catalog is the
-   * single source of truth for context windows; we never invent defaults.
+   * primary source of truth for context windows, falling back to 128K when unknown.
    *
    * When the catalog request fails, the generator throws — opencode.json must
    * not be emitted with stale or fabricated values. The CLI can catch the
@@ -426,7 +422,7 @@ export interface GenerateOpencodeOptions {
 
 /**
  * Generate a full `opencode.json` document for OmniRoute. The catalog is the
- * single source of truth for context windows — we never hardcode values.
+ * primary source of truth for context windows, with a 128K fallback when unknown.
  *
  * Behavior:
  *  - Preserves the user's existing provider name, npm, options, and
@@ -436,8 +432,8 @@ export interface GenerateOpencodeOptions {
  *  - For each catalog model id the user did NOT have, a new entry is
  *    added with `limit.context` populated when the catalog has it.
  *  - If the catalog has no context for a model AND the user has no
- *    override, the model is emitted WITHOUT a `limit.context` field.
- *    OpenCode's own heuristic (typically 128K) applies.
+ *    override, a safe default (128K) is emitted so OpenCode's schema validator
+ *    does not reject the model.
  *  - Throws if the catalog fetch fails — the user must fix the upstream
  *    before we can generate a reliable opencode.json.
  */