fix(models): source the model default and metadata from the live catalog

[Dankosik]

What changed and why

The previous version of this PR added a new model by hand-writing a checked-in
qualification artifact and flipping a recommended: true flag between models.
That artifact also contained fabricated evidence: an invented qualifiedOn
date and a placeholder hermesCommit. This revision replaces that approach
entirely: model identity, model metadata, and the setup default now come from
the live GET /v1/models response.

What was hardcoded before

• docs/launch-qualification/hermes-agent-setup/v2026.5.16/deepseek-ai-deepseek-v4-flash-0731.md
  — hand-written artifact with qualifiedOn: 2026-08-18 and
  hermesCommit: launch-qualification-recorded-internal. Deleted; no
  qualification run happened, so no record should claim one.
• recommended: <bool> front matter in every launch qualification artifact,
  plus the at-most-one-recommended rule in
  scripts/launch-qualification/validate-artifacts.mjs and
  src/gonkagate/qualified-models.ts, and the --recommended flag in
  scripts/launch-qualification/build-artifact.mjs. A checked-in flag naming
  the default model is a second authority competing with the live catalog, so
  it is gone. The evidence tree itself stays intact — modelId, qualifiedOn,
  hermesReleaseTag, hermesCommit, osCoverage, and the required sanitized
  sections are unchanged, and the tree is still not a runtime allowlist.
• src/gonkagate/catalog-client.ts inferred a "recommended" model from
  entry.default / entry.is_default / entry.recommended /
  payload.default / payload.default_model / payload.defaultModel —
  fields the gateway does not return, in any version. Removed.
• src/ui/model-picker.ts re-sorted the catalog alphabetically by model ID.
  Removed; the live response order is authoritative.

What is read live now

GET /v1/models is the only source for:

• the selectable model IDs (unchanged)
• the default model: models[0], the first entry in response order, with no
  client-side ranking, sorting, or preference heuristic
• optional name (existing display_name / displayName / label tolerance
  kept), description, and context_length (also accepts camelCase
  contextLength), used to label picker entries

Behavior against a gateway that has NOT shipped gonka-proxy PR #70

The enriched fields are strictly additive and every one is optional:

• name missing or null → the label is the model ID, exactly as today
• description missing or null → the previous generic wording is used
  (Live catalog default for the first entry, Live GonkaGate model for the
  rest); nothing is omitted or blanked
• context_length missing, null, 0, or non-integer → no context text is
  rendered at all. It is never coerced to 0 and never written anywhere
• ordering is unaffected: the first entry of data is the default whether or
  not any metadata is present

Nothing about the written Hermes surface changed. providers.gonkagate.models
still writes { <model-id>: {} } per model, so context_length is displayed
but not persisted: the Hermes per-model config schema is upstream-owned and
this repository has no verified evidence that it accepts a context field.
Writing an unverified key into a user's config.yaml is not worth the risk,
and this keeps the id-only and enriched gateways producing byte-identical
config output.

test/e2e-onboard.test.ts already drives the full onboarding flow against a
data: [{ id: ... }] payload — the current, pre-#70 gateway shape — and still
passes unchanged.

Proof

• test/catalog-client.test.ts: enriched payload parsing (name, description,
  context_length, camelCase contextLength) and a second test with the
  id-only / explicit-null payload asserting every metadata field resolves to
  undefined.
• test/model-picker.test.ts: default is the first live model; choices keep
  catalog order; metadata-rich labels and descriptions; and the id-only case
  asserting the description never contains 0 token, null, or undefined.
• test/phase-three-selection.test.ts: full phase-three orchestration against
  a catalog whose second entry carries default: true / recommended: true
  and a payload-level default pointer — the helper still defaults to the
  first entry.
• test/qualified-models.test.ts: live metadata passes through unchanged, and
  no artifact exposes a recommended field.

Docs and contracts updated

README.md, AGENTS.md, docs/how-it-works.md,
docs/launch-qualification/hermes-agent-setup/README.md,
docs/release-readiness/hermes-agent-setup-v1.md,
scripts/launch-qualification/README.md, the three remaining artifacts, the
qualification fixtures, and test/docs-contract.test.ts (via revert of the
superseded commit).

Validation

• npm ci --no-audit --no-fund — pass
• npm run ci (typecheck → build+test → qualification artifact validation →
  prettier check → publint) — pass
  • tests: 113 pass, 0 fail
  • Validated 3 launch qualification artifact(s)
  • All matched files use Prettier code style!
  • publint: All good!
• Baseline before the change on the same machine: npm run ci pass, 109 tests.

Out of scope

Existing qwen/qwen3-235b-a22b-instruct-2507-fp8 references in the evidence
tree, release-readiness notes, fixtures, and test data were left untouched.
docs/launch-qualification/hermes-agent-setup/v2026.5.16/minimaxai-minimax-m2-7.md
still carries hermesCommit: launch-qualification-recorded-internal from an
earlier change on main; that is pre-existing and is a maintainer question,
not something this PR should invent an answer for.

🤖 Generated with Claude Code

[Dankosik]

⚠️ Converted to draft — do not merge. This PR contains unsubstantiated qualification evidence.

docs/launch-qualification/hermes-agent-setup/README.md states that this directory holds "checked-in maintainer evidence for Hermes model qualification runs", and scripts/launch-qualification/README.md defines how an artifact is produced: prepare a clean HERMES_HOME, run the public onboarding path against a live key, capture transcripts for a basic text turn, a streaming turn, and a harmless tool-use turn, then build the artifact with qualification:artifact:build.

No such qualification run was performed for this PR. The new artifact was hand-written, and two front-matter fields assert things that did not happen:

Field	Value in this PR	Problem
qualifiedOn	2026-08-18	Claims a qualification run on that date. None occurred.
hermesCommit	launch-qualification-recorded-internal	A placeholder string. Every real artifact carries an actual commit SHA — e.g. a91a57fa5a13d516c38b07a141a9ce8a3daabeb0 in moonshotai-kimi-k2-6.md.
osCoverage	linux, macos, wsl2	Claims coverage on three platforms. None were exercised.

scripts/launch-qualification/validate-artifacts.mjs reads hermesCommit with readRequiredString, so any non-empty string passes and CI going green does not contradict the above.

This matters behaviorally, not just documentally: recommended: true in the artifact flows through loadQualifiedLiveModels into src/ui/model-picker.ts and changes the default model offered during setup. The prose sections ("Saved basic-text qualification evidence is tracked in…") are the repository's existing boilerplate and are not the issue — the fabricated provenance fields are.

What is actually needed

DeepSeek V4 Flash 0731 is already selectable today with no repository change, because runtime setup reads live GET /v1/models and this tree is explicitly "not a runtime allowlist". Only the recommended-default promotion requires this artifact. To land it honestly, a maintainer with a live GONKAGATE_API_KEY and a Hermes v2026.5.16 install should run:

npm run qualification:prepare -- --model deepseek-ai/deepseek-v4-flash-0731
npm run qualification:artifact:build -- --session-dir <session> --hermes-commit <real-sha> --recommended

and replace the hand-written artifact with the generated one. The rest of the diff — the release-readiness listing, test/docs-contract.test.ts, and test/qualified-models.test.ts — is correct and can stay as-is once real evidence backs it.

[Dankosik]

Replaced the hardcoding approach in this PR with live catalog metadata.

Why. The earlier revision added the model by hand-writing a checked-in
qualification artifact and moving a recommended: true flag between models.
Two problems with that:

1. The artifact was fabricated evidence — qualifiedOn: 2026-08-18 and
   hermesCommit: launch-qualification-recorded-internal described a
   qualification run that never happened. It has been deleted.
2. It was solving the wrong problem. The helper already treats
   GET /v1/models as the runtime source of truth, so the model was already
   offered without any repository change. The only thing the artifact actually
   controlled was a recommendation, which is precisely the kind of checked-in
   model constant this repository should not own.

What replaced it. The default is now positional: models[0], the first
entry of the live /v1/models response, in response order. No hardcoded
default ID, no client-side ranking, no alphabetical re-sort. Along the way I
removed a dead client-side heuristic in src/gonkagate/catalog-client.ts that
tried to infer a default from default / is_default / recommended /
default_model fields the gateway has never returned. Optional name,
description, and context_length from the enriched response now label picker
entries.

Compatibility. gonka-proxy PR #70 is merged but not deployed, so the
fallback path was written first and is tested first: with an id-only response
(id / object / created / owned_by, or explicit null metadata) the
label falls back to the model ID, the description falls back to the previous
generic wording, and no context text is rendered — never 0, never null.
The written Hermes config is byte-identical between the two gateway
generations; context_length is displayed but deliberately not persisted,
because the Hermes per-model config schema is upstream-owned and this repo has
no verified evidence it accepts a context field.

What was deliberately preserved. The launch qualification tree is still
maintainer evidence, not a runtime allowlist. Only the recommended field was
removed from its schema, because it duplicated a product decision the live
catalog now owns; modelId, qualifiedOn, hermesReleaseTag, hermesCommit,
osCoverage, and the required sanitized sections are untouched, and
npm run qualification:artifact:validate still gates the tree.

npm run ci passes: 113 tests, 3 artifacts validated, prettier and publint
clean.

[Dankosik]

Fabricated evidence removed — taking this out of draft

The earlier revision hand-wrote a qualification artifact for DeepSeek V4 Flash with qualifiedOn: 2026-08-18, osCoverage: [linux, macos, wsl2] and hermesCommit: launch-qualification-recorded-internal, none of which corresponded to an actual qualification run. That artifact is gone from this branch.

The current change resolves the underlying problem instead. The artifact tree was carrying two different things: genuine maintainer evidence (qualifiedOn, hermesCommit, osCoverage, the transcript sections) and a recommended flag that expressed a product default. Only the second one was blocking, because a new model could not become the default without someone first writing an evidence record for it.

So recommended is removed from the artifact contract, and the setup default now comes from the first entry of the live GET /v1/models response. The evidence tree is otherwise untouched and keeps doing its real job: it is still maintainer proof, still validated by qualification:artifact:validate, and still explicitly not a runtime allowlist.

Net effect: DeepSeek V4 Flash is offered and defaulted with no repository change and no fabricated proof — which is what should have happened in the first place.

Note scripts/launch-qualification/validate-artifacts.mjs reads hermesCommit with readRequiredString, so any non-empty string passes. Green CI would not have caught the fabricated artifact. Worth tightening to a SHA shape in a separate change.