fix(models): read model metadata from the live GonkaGate catalog

AGENTS.md

@@ -33,6 +33,12 @@ Current honest state:
 - the runtime collects the GonkaGate key before the model picker, calls
   `GET https://api.gonkagate.com/v1/models`, and writes every returned model
   into `provider.gonkagate.models`
+- model ids, display names, descriptions, context windows, and the default
+  model all come from that live response; the repository carries no model
+  catalog and no default model id
+- `name`, `description`, and `context_length` are optional on the wire, so a
+  gateway that returns only `id`, `object`, `created`, and `owned_by` still
+  completes setup
 - `moonshotai/kimi-k2.6` has MiMoCode validation proof for the current
   minimum-supported MiMoCode contract, but the public picker is now backed by
   the live GonkaGate model catalog rather than a hardcoded validated allowlist
@@ -96,6 +102,13 @@ change.
 - project config must not own the secret binding
 - public setup must fetch the model catalog after safe API-key intake instead
   of exposing a hardcoded model allowlist
+- model ids, display names, and context windows must never be checked in; they
+  are read from the live `/v1/models` response
+- the non-interactive default model is `data[0]` of the live response, in
+  response order; no client-side ranking, sorting, or preference heuristic
+- optional live metadata must degrade instead of failing: a missing `name`
+  falls back to the model id, a missing `description` is omitted, and a missing
+  `context_length` writes no MiMoCode `limit` block rather than a `0` limit
 - installer success must be based on effective MiMoCode config, not only file
   writes
 - raw `mimo --pure debug config` output must not be printed because `{file:...}`
@@ -212,11 +225,15 @@ results. The default public flow fetches the GonkaGate model catalog from
 ### `src/install/model-catalog.ts`
 
 Trust-boundary parser and fetch adapter for `GET /v1/models`. Keep it strict
-about response shape and redaction-safe about failures.
+about the required response shape, tolerant about optional per-model metadata,
+and redaction-safe about failures.
 
 ### `src/constants/`
 
 Package, provider, transport, path, and model-validation constants.
+`src/constants/models.ts` holds runtime model types only; model data belongs to
+the live catalog. `src/constants/model-validation.ts` is the MiMoCode workflow
+proof ledger and must never record a validation that did not happen.
 
 ### `.agents/skills/` and `.claude/skills/`
 

README.md

@@ -59,7 +59,8 @@ The happy path is:
 
 1. The CLI checks that `mimo` is installed and supported.
 2. It asks for your GonkaGate API key in a masked prompt.
-3. It calls `GET /v1/models` and offers every model returned by GonkaGate.
+3. It calls `GET /v1/models` and offers every model returned by GonkaGate,
+   labelled with the live model name and description.
 4. It asks whether GonkaGate should be activated for `user` or `project`
    scope.
 5. It writes the managed config, verifies the result, and tells you to go back
@@ -89,6 +90,9 @@ If you run non-interactively, pass `--scope` or `--yes`. In a git repository,
 the recommended default is usually `project`; outside a repo, it is usually
 `user`.
 
+Without `--model`, `--yes` selects the first model of the live `/v1/models`
+response. GonkaGate owns that order, so the CLI ships no default model id.
+
 ## Before You Run It
 
 You need:
@@ -182,13 +186,17 @@ The runtime is live-catalog-first:
 - the canonical base URL is `https://api.gonkagate.com/v1`
 - the setup model list is fetched from
   `https://api.gonkagate.com/v1/models` after safe API-key intake
+- model ids, display names, and context windows are read from that live
+  response; this repository ships no model catalog and no default model id
+- gateways that do not publish per-model metadata still work: the model id is
+  used as the display name and no context limit is written
 - the current provider package is `@ai-sdk/openai-compatible`
 - the current transport target is `chat_completions`
 - future migration should add `responses` support without renaming the product
 - the selected setup model remains the activation default through `model` and
   `small_model`
 - `provider.gonkagate.models` is generated from every model returned by
-  `/v1/models`
+  `/v1/models`, including the published context window when there is one
 - `docs/model-validation.md` tracks MiMoCode workflow proof separately from
   live catalog availability
 

docs/how-it-works.md

@@ -15,7 +15,9 @@ a hardcoded allowlist.
 3. Collect a GonkaGate API key through safe inputs only:
    `GONKAGATE_API_KEY`, masked interactive prompt, or `--api-key-stdin`.
 4. Fetch `https://api.gonkagate.com/v1/models` with Bearer auth and build the
-   setup picker from every returned model id.
+   setup picker from every returned model id, using the live `name`,
+   `description`, and `context_length` when the gateway publishes them. The
+   non-interactive default is the first model of the response.
 5. Store the secret under `~/.gonkagate/mimo-code/api-key`.
 6. Write user-level provider config for `provider.gonkagate`.
 7. Write only activation settings for project scope.
@@ -64,19 +66,15 @@ The intended managed provider shape is:
         "setCacheKey": false
       },
       "models": {
-        "moonshotai/kimi-k2.6": {
-          "name": "moonshotai/kimi-k2.6",
+        "<model-id-with-published-context>": {
+          "name": "<live catalog name>",
           "limit": {
-            "context": 0,
+            "context": "<live catalog context_length>",
             "output": 0
           }
         },
-        "minimaxai/minimax-m2.7": {
-          "name": "minimaxai/minimax-m2.7",
-          "limit": {
-            "context": 0,
-            "output": 0
-          }
+        "<model-id-without-published-context>": {
+          "name": "<model id>"
         }
       }
     }
@@ -86,7 +84,17 @@ The intended managed provider shape is:
 
 The concrete `models` object is generated from the live `/v1/models` response.
 The API model ids are also the MiMoCode model keys under
-`provider.gonkagate.models`.
+`provider.gonkagate.models`. This repository keeps no checked-in model catalog:
+ids, display names, and context windows are read from the live response on
+every run.
+
+Per-model metadata is optional on the wire, because a GonkaGate gateway may
+still return only `id`, `object`, `created`, and `owned_by`:
+
+- missing `name` falls back to the model id
+- missing `description` is omitted from the picker
+- missing `context_length` writes no `limit` block for that model, so MiMoCode
+  keeps its own default instead of being told the context window is `0`
 
 `setCacheKey` is disabled because live GonkaGate chat-completions requests
 reject the non-standard `promptCacheKey` parameter emitted by the AI SDK when

docs/model-validation.md

@@ -6,13 +6,13 @@ the MiMoCode workflow proof ledger.
 
 Current MiMoCode-validated workflow proof exists for:
 
-- `moonshotai/kimi-k2.6` - Kimi K2.6, 240K context.
+- `moonshotai/kimi-k2.6`, recorded in `src/constants/model-validation.ts`.
 
-The current public GonkaGate models page also lists:
-
-- `minimaxai/minimax-m2.7` - MiniMax M2.7, 180K context.
-- `qwen/qwen3-235b-a22b-instruct-2507-fp8` - Qwen3 235B A22B
-  Instruct 2507 FP8, 240K context.
+Which models exist, what they are called, and how large their context windows
+are is owned by the live `GET /v1/models` response. This repository keeps no
+copy of that catalog, so nothing here has to be edited when GonkaGate adds,
+renames, or retires a model. A model is named in this document because
+MiMoCode workflow proof exists for it, not because it is available.
 
 GonkaGate `/v1/models` availability is setup-catalog proof, not full MiMoCode
 workflow validation proof.
@@ -51,11 +51,14 @@ must prove:
 - docs and tests name the model as MiMoCode workflow-validated only after the
   proof exists
 
-The registry types already allow transport, adapter package, provider options,
-model options, model headers, limits, and migration metadata so MiMoCode-specific
-requirements can be added without changing the public shape later.
+The runtime model types in `src/constants/models.ts` already allow transport,
+adapter package, provider options, model options, model headers, limits, and
+migration metadata so MiMoCode-specific requirements can be added without
+changing the public shape later. Those types carry no model data; every value
+is filled in from the live catalog at setup time.
 
 Validation records are represented in `src/constants/model-validation.ts`.
-Contract tests reject any registry entry marked `validated` without a matching
-record. Additional live GonkaGate workflow proof is a gated validation activity
-and is not part of default CI.
+Contract tests check that each record is internally consistent with the
+provider package and transport this installer writes. A record may only be
+added after the proof above actually exists; live GonkaGate workflow proof is a
+gated validation activity and is not part of default CI.

docs/runtime-contract-map.md

@@ -24,9 +24,10 @@ update these surfaces together:
 - `CHANGELOG.md` - meaningful user-facing runtime changes.
 - `src/constants/contract.ts` - package identity, public implementation status,
   MiMoCode minimum version, and live catalog source.
-- `src/install/model-catalog.ts` - `/v1/models` fetch and response-shape
-  boundary.
-- `src/constants/models.ts` - model metadata and validation helper types.
+- `src/install/model-catalog.ts` - `/v1/models` fetch, response-shape boundary,
+  and the fallbacks for gateways that publish no per-model metadata.
+- `src/constants/models.ts` - runtime model shape types only; it must not carry
+  a checked-in catalog, context window, display name, or default model id.
 - `test/docs-contract.test.ts` and `test/package-contract.test.ts` - docs,
   constants, package metadata, and model registry agreement.
 - `test/cli.test.ts` - human and JSON CLI output semantics.

docs/specs/mimo-code-setup-prd/spec.md

@@ -418,9 +418,9 @@ the actual `models` entries generated from GonkaGate `/v1/models`:
       },
       "models": {
         "<provider-slug>/<model-slug>": {
-          "name": "<display name>",
+          "name": "<live catalog name, or the model id>",
           "limit": {
-            "context": 0,
+            "context": "<live catalog context_length>",
             "output": 0
           }
         }
@@ -430,6 +430,11 @@ the actual `models` entries generated from GonkaGate `/v1/models`:
 }
 ```
 
+`name` and `limit` are generated from the live `/v1/models` entry, never from
+a checked-in catalog. When the gateway does not publish `context_length` for a
+model, the installer writes no `limit` block for it at all and MiMoCode keeps
+its own default. Writing `"context": 0` would state a real but wrong limit.
+
 The installer should not write `provider.gonkagate.env` as a durable runtime
 dependency in v1. `GONKAGATE_API_KEY` is setup input, not the normal
 post-setup runtime path.
@@ -456,13 +461,26 @@ Runtime model source:
 
 - endpoint: `GET https://api.gonkagate.com/v1/models`
 - auth: `Authorization: Bearer <gp-key>`
-- expected response shape: `{ "object": "list", "data": [{ "id": "..."}] }`
+- required response shape: `{ "object": "list", "data": [{ "id": "..."}] }`
 - setup keys: every returned `data[].id`
+- optional per-model metadata: `name`, `description`, `context_length`
+
+The installer must not hardcode the public setup model list, model display
+names, or model context windows. It should parse the authenticated
+`/v1/models` response, preserve the returned order, dedupe duplicate ids, and
+write every returned model id under `provider.gonkagate.models`.
+
+Optional metadata is a compatibility surface, not a requirement. A gateway that
+publishes only `id`, `object`, `created`, and `owned_by` must still complete
+setup, so each optional field may be absent, `null`, or unusable:
+
+- `name` absent -> the model id is the display name
+- `description` absent -> no description is shown in the picker
+- `context_length` absent -> no `limit` block is written for that model
 
-The installer must not hardcode the public setup model list. It should parse
-the authenticated `/v1/models` response, preserve the returned order, dedupe
-duplicate ids, and write every returned model id under
-`provider.gonkagate.models`.
+The default model for non-interactive setup is `data[0]`, the first entry of
+the live response in response order. The installer must not rank, sort, or
+prefer models on its own, and must not carry a checked-in default model id.
 
 Model ids must map cleanly to MiMoCode's `provider/model` model-ref format.
 Because MiMoCode treats the first slash segment as provider id and rejoins the
@@ -729,8 +747,8 @@ The setup tool must not depend on a future `gonkagate doctor`.
 7. Future responses migration must not require a new package identity.
 8. Interactive setup should fetch the live model catalog before showing the
    model picker.
-9. Safe non-interactive setup may accept recommended defaults only when the
-   installer has enough information to do so without ambiguity.
+9. Safe non-interactive setup selects the first model of the live `/v1/models`
+   response, so the gateway owns the default instead of the installer.
 10. Diagnostics must be actionable without exposing secrets.
 11. Validation proof must be narrow enough to run locally but broad enough to
     cover the claimed MiMoCode behavior.
@@ -741,7 +759,7 @@ The setup tool must not depend on a future `gonkagate doctor`.
 - native MiMoCode `auth.json` integration, if a later product decision chooses
   to use it
 - richer post-setup live GonkaGate session verification
-- richer live catalog metadata, if `/v1/models` starts returning it
+- live catalog metadata beyond `name`, `description`, and `context_length`
 - cheaper validated `small_model` strategy
 - MiMoCode model-group integration
 - future `/v1/responses` migration

src/cli/contracts.ts

@@ -1,4 +1,4 @@
-import type { CuratedModelRegistry } from "../constants/models.js";
+import type { ModelRegistry } from "../constants/models.js";
 import type { InstallerDeps } from "../install/deps.js";
 
 export interface CliOptions {
@@ -17,7 +17,7 @@ export interface CliRunResult {
 
 export interface CliRunOptions {
   deps?: InstallerDeps;
-  registry?: CuratedModelRegistry;
+  registry?: ModelRegistry;
   stderr?: Pick<NodeJS.WriteStream, "write">;
   stdout?: Pick<NodeJS.WriteStream, "write">;
 }

src/cli/execute.ts

@@ -1,5 +1,5 @@
 import type { CliOptions, CliRunResult } from "./contracts.js";
-import type { CuratedModelRegistry } from "../constants/models.js";
+import type { ModelRegistry } from "../constants/models.js";
 import type { InstallerDeps } from "../install/deps.js";
 import { runInstaller } from "../install/index.js";
 import { renderInstallerJson, renderInstallerText } from "./render.js";
@@ -8,7 +8,7 @@ export async function executeCli(
   parsedOptions: CliOptions,
   streams: { stdout: Pick<NodeJS.WriteStream, "write"> },
   deps?: InstallerDeps,
-  registry?: CuratedModelRegistry,
+  registry?: ModelRegistry,
 ): Promise<CliRunResult> {
   const result = await runInstaller(
     {

src/constants/contract.ts

@@ -3,11 +3,10 @@ export const CONTRACT_METADATA = {
   legacyBinName: "gonkagate-mimo-code",
   binPath: "bin/gonkagate-mimo-code.js",
   cliVersion: "0.3.3", // x-release-please-version
-  curatedRegistryPublished: true,
   packageName: "@gonkagate/mimo-code-setup",
   publicEntrypoint: "npx @gonkagate/mimo-code-setup",
   publicState:
-    "Installer runtime fetches the available GonkaGate model catalog from /v1/models after safe API-key intake.",
+    "Installer runtime fetches the available GonkaGate models and their metadata from /v1/models after safe API-key intake.",
   mimoCode: {
     minVersion: "0.1.0",
     packageName: "@mimo-ai/cli",