feat!: target latest Hermes contract

.agents/skills/hermes-compatibility-audit/SKILL.md

@@ -15,10 +15,11 @@ This is a read-only compatibility gate. The job is to compare official
 upstream Hermes behavior against the assumptions encoded in this repository and
 return a clear verdict, not to design or apply a migration.
 
-Treat the repository's current PRD baseline as a repository fact, not as
-current upstream truth. Today the PRD says its upstream verification baseline
-was `hermes-agent` `v2026.4.13` / `v0.9.0`; the audit must still verify
-whether latest stable upstream remains compatible with that plan.
+Treat the repository's current runtime baseline as a repository fact, not as
+current upstream truth. Today the shipped helper targets latest-only
+`hermes-agent` `v2026.5.16` / `v0.14.0` or newer; the historical PRD baseline
+was `v2026.4.13` / `v0.9.0`, but that legacy baseline is no longer the
+supported public runtime contract.
 
 ## Scope
 
@@ -31,9 +32,10 @@ Cover the repository's current and planned Hermes-facing contract, especially:
   `model.default`, `model.api_key`, `model.api`, and `model.api_mode`
 - model and provider selection assumptions around `hermes model`,
   `provider:model` syntax, curated model choice, and custom provider behavior
-- auth and secret-handling assumptions around `OPENAI_API_KEY`,
-  `OPENAI_BASE_URL`, `auth.json`, credential pools, and the repository's
-  decision to keep secrets in `~/.hermes/.env` rather than `config.yaml`
+- auth and secret-handling assumptions around `OPENAI_API_KEY`, unsupported
+  legacy endpoint env such as `OPENAI_BASE_URL`, `auth.json`, credential
+  pools, and the repository's decision to keep secrets in `~/.hermes/.env`
+  rather than `config.yaml`
 - workflow and CLI assumptions documented by this repository, such as
   `hermes model`, `hermes config set`, `hermes config path`,
   `hermes config env-path`, `hermes setup`, `hermes doctor`, and profile
@@ -172,9 +174,9 @@ For the target stable release, gather evidence for:
   `model.default`, `model.api_key`, `model.api`, and `model.api_mode`
 - whether current Hermes guidance still routes secrets to `.env` and non-secret
   config to `config.yaml`
-- whether `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `auth.json`, credential pools,
-  or `cron/jobs.json` remain active compatibility or conflict surfaces in the
-  stable release
+- whether unsupported legacy endpoint env such as `OPENAI_BASE_URL`,
+  `OPENAI_API_KEY`, `auth.json`, credential pools, or `cron/jobs.json` remain
+  active upstream surfaces that could affect the latest-only helper contract
 - whether managed installs or blocked-write modes remain relevant to a local
   mutation helper
 - whether Hermes added or removed CLI surfaces relevant to this repository's

.claude/skills/hermes-compatibility-audit/SKILL.md

@@ -15,10 +15,11 @@ This is a read-only compatibility gate. The job is to compare official
 upstream Hermes behavior against the assumptions encoded in this repository and
 return a clear verdict, not to design or apply a migration.
 
-Treat the repository's current PRD baseline as a repository fact, not as
-current upstream truth. Today the PRD says its upstream verification baseline
-was `hermes-agent` `v2026.4.13` / `v0.9.0`; the audit must still verify
-whether latest stable upstream remains compatible with that plan.
+Treat the repository's current runtime baseline as a repository fact, not as
+current upstream truth. Today the shipped helper targets latest-only
+`hermes-agent` `v2026.5.16` / `v0.14.0` or newer; the historical PRD baseline
+was `v2026.4.13` / `v0.9.0`, but that legacy baseline is no longer the
+supported public runtime contract.
 
 ## Scope
 
@@ -31,9 +32,10 @@ Cover the repository's current and planned Hermes-facing contract, especially:
   `model.default`, `model.api_key`, `model.api`, and `model.api_mode`
 - model and provider selection assumptions around `hermes model`,
   `provider:model` syntax, curated model choice, and custom provider behavior
-- auth and secret-handling assumptions around `OPENAI_API_KEY`,
-  `OPENAI_BASE_URL`, `auth.json`, credential pools, and the repository's
-  decision to keep secrets in `~/.hermes/.env` rather than `config.yaml`
+- auth and secret-handling assumptions around `OPENAI_API_KEY`, unsupported
+  legacy endpoint env such as `OPENAI_BASE_URL`, `auth.json`, credential
+  pools, and the repository's decision to keep secrets in `~/.hermes/.env`
+  rather than `config.yaml`
 - workflow and CLI assumptions documented by this repository, such as
   `hermes model`, `hermes config set`, `hermes config path`,
   `hermes config env-path`, `hermes setup`, `hermes doctor`, and profile
@@ -172,9 +174,9 @@ For the target stable release, gather evidence for:
   `model.default`, `model.api_key`, `model.api`, and `model.api_mode`
 - whether current Hermes guidance still routes secrets to `.env` and non-secret
   config to `config.yaml`
-- whether `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `auth.json`, credential pools,
-  or `cron/jobs.json` remain active compatibility or conflict surfaces in the
-  stable release
+- whether unsupported legacy endpoint env such as `OPENAI_BASE_URL`,
+  `OPENAI_API_KEY`, `auth.json`, credential pools, or `cron/jobs.json` remain
+  active upstream surfaces that could affect the latest-only helper contract
 - whether managed installs or blocked-write modes remain relevant to a local
   mutation helper
 - whether Hermes added or removed CLI surfaces relevant to this repository's

AGENTS.md

@@ -12,6 +12,8 @@ Current honest state:
 - the end-to-end public onboarding runtime is implemented
 - the PRD is present under `docs/specs/hermes-agent-setup-prd/spec.md`
 - CI, packaging, docs, contract tests, and mirrored skills are wired
+- the helper targets latest-only Hermes Agent `v2026.5.16` / `v0.14.0` or
+  newer, and fails older Hermes versions during preflight
 - the current CLI resolves the active Hermes context, classifies conflicts,
   prompts for a hidden GonkaGate key, fetches the live catalog, intersects it
   with checked-in launch qualification artifacts, writes the managed Hermes
@@ -36,7 +38,12 @@ Product invariants:
 - the canonical GonkaGate base URL is `https://api.gonkagate.com/v1`
 - secrets belong in `~/.hermes/.env`, not in `config.yaml`
 - curated model selection is product-owned
+- latest-only Hermes Agent `v2026.5.16` / `v0.14.0` or newer is the supported
+  runtime floor
 - shell profile mutation is out of scope
+- legacy endpoint paths such as `OPENAI_BASE_URL`, `LLM_MODEL`, root-level
+  `provider` / `base_url`, and legacy `custom_providers` are out of scope for
+  the public flow
 - arbitrary custom base URLs are out of scope for the public flow
 - v1 launch scope is Linux, macOS, and WSL2 only
 - public onboarding inherits current GonkaGate Terms availability boundaries;

README.md

@@ -35,6 +35,7 @@ OpenAI-compatible endpoint through `provider: custom` and
 You should also have:
 
 - `hermes-agent` available on your machine
+- Hermes Agent `v2026.5.16` / `v0.14.0` or newer
 - a GonkaGate API key
 - an interactive terminal
 - Linux, macOS, or WSL2
@@ -84,6 +85,9 @@ When setup succeeds, the helper writes only the GonkaGate-managed surface:
 The shipped helper intentionally stays narrow:
 
 - it does not replace `hermes setup`
+- it does not support legacy endpoint paths such as `OPENAI_BASE_URL`,
+  `LLM_MODEL`, root-level `provider` / `base_url`, or legacy
+  `custom_providers`
 - it does not accept arbitrary custom base URLs
 - it does not mutate shell profiles
 - it does not mutate `auth.json` credential pools
@@ -103,3 +107,4 @@ If you need general Hermes setup help or deeper product context first, start at
 - [How It Works](./docs/how-it-works.md)
 - [Security](./docs/security.md)
 - [Product Spec](./docs/specs/hermes-agent-setup-prd/spec.md)
+- [Latest Hermes Contract Adaptation](./docs/specs/hermes-latest-contract-adaptation/spec.md)

docs/README.md

@@ -20,6 +20,7 @@ This repository does not currently contain:
 ## Current Contract Documents
 
 - [Hermes Agent Setup PRD](./specs/hermes-agent-setup-prd/spec.md)
+- [Hermes Latest Contract Adaptation](./specs/hermes-latest-contract-adaptation/spec.md)
 - [How It Works](./how-it-works.md)
 - [Security](./security.md)
 
@@ -36,7 +37,8 @@ This repository does not currently contain:
 
 ## Notes
 
-- the PRD remains the main product contract
+- the PRD remains the historical v1 product contract; the latest-contract
+  adaptation records the current Hermes `v2026.5.16` runtime update
 - launch qualification artifacts are part of the shipped model-selection
   contract
 - historical documents must be labeled explicitly so scaffold-era planning

docs/how-it-works.md

@@ -19,20 +19,20 @@ Today the repository ships:
 - Hermes preconditions, path resolution, normalized reads, conflict
   classification, catalog access, model selection, write planning, backups,
   rollback, and success/error UX under `src/`
-- checked-in launch qualification artifacts for the pinned Hermes release
+- checked-in launch qualification artifacts for the latest-only Hermes release
 - docs, contract tests, and mirrored contributor skills
 
 ## Install Flow
 
-1. Check Node, TTY, supported platform, Hermes availability, and managed-write
-   blockers before prompting for anything.
+1. Check Node, TTY, supported platform, Hermes availability, Hermes version
+   floor, and managed-write blockers before prompting for anything.
 2. Resolve the active Hermes config context through `hermes config path`,
    `hermes config env-path`, and optional `--profile <name>`.
 3. Read `config.yaml`, `.env`, `auth.json`, and `cron/jobs.json`, then build a
-   release-pinned normalized Hermes view that includes `${VAR}` expansion and
-   legacy root-level `provider` / `base_url` migration into `model.*`.
-4. Classify shared `OPENAI_API_KEY`, `OPENAI_BASE_URL`, matching
-   `custom_providers` / `providers:`, and matching `auth.json` credential-pool
+   latest-only normalized Hermes view with `${VAR}` expansion for current
+   supported surfaces.
+4. Classify shared `OPENAI_API_KEY`, current `providers:` conflicts, legacy
+   `custom_providers` residue, and matching `auth.json` credential-pool
    conflicts before any secret prompt or write plan is built.
 5. Prompt for a hidden GonkaGate API key and validate the `gp-...` shape
    before any network call.
@@ -42,8 +42,8 @@ Today the repository ships:
 7. Pick one qualified live model. Interactive mode keeps the model picker
    visible; single-option flows may auto-select that one qualified model.
 8. Build one deterministic pre-write review that includes planned config
-   changes, planned `.env` cleanup, takeover confirmations, and matching
-   provider scrub actions.
+   changes and takeover confirmations. Legacy endpoint paths are not cleaned or
+   migrated by the helper.
 9. Create same-run backups, write `config.yaml` first, write `.env` second,
    and roll back `config.yaml` by pre-run state if the later `.env` write
    fails.
@@ -56,15 +56,17 @@ The helper intentionally stays narrow:
 
 - it owns the GonkaGate onboarding path, not general Hermes bootstrap
 - it manages only `model.provider`, `model.base_url`, `model.default`, and
-  `OPENAI_API_KEY`, plus conflict-only cleanup allowed by the PRD
+  `OPENAI_API_KEY`, plus current `model.api_key`, `model.api`, and
+  incompatible `model.api_mode` cleanup when those compete with the managed
+  main endpoint
 - it does not mutate `auth.json` credential pools
 - it does not mutate shell profiles
 - it does not accept arbitrary custom base URLs
 
 Matching custom credential pools remain a blocking manual-resolution case in
-v1. Matching provider entries are scrubbed only when one on-disk entry can be
-cleaned within the allowed field set and the user confirms the consolidated
-review.
+v1. Legacy `custom_providers` entries and current `providers:` entries with
+competing selectors are also blocking manual-resolution cases; the helper does
+not scrub provider registries.
 
 ## Qualification And Verification
 
@@ -74,9 +76,23 @@ The runtime is curated-model-first:
   `docs/launch-qualification/hermes-agent-setup/` are eligible
 - the helper still requires those models to remain visible in the live
   `/v1/models` catalog before offering them
+- live catalog entries without checked-in qualification artifacts are ignored
+  rather than exposed as ad hoc model choices
 - `GET /v1/models` is an auth plus live-catalog signal, not proof of prepaid
   balance or end-to-end readiness for the first billable request
 
+Current proof coverage for the catalog boundary:
+
+- `test/catalog-client.test.ts` verifies the canonical
+  `https://api.gonkagate.com/v1/models` URL, Bearer auth, malformed payload
+  rejection, terminal auth failures, retryable 5xx and 429 behavior, quota
+  shaped failures, and retry exhaustion.
+- `test/qualified-models.test.ts` verifies the intersection between the live
+  catalog and checked-in qualification artifacts, including the rule that
+  live-only unqualified entries are not selectable.
+- `test/e2e-onboard.test.ts` verifies catalog failures abort before Hermes
+  files are written.
+
 Use the maintainer scripts under `scripts/launch-qualification/` to prepare
 clean-home qualification runs, build the checked-in artifact, and validate the
 artifact tree.

docs/launch-qualification/hermes-agent-setup/README.md

@@ -8,8 +8,8 @@ Runtime policy:
 - only models with a checked-in artifact here may be considered allowlisted
 - the helper intersects those artifacts with the live GonkaGate `/v1/models`
   catalog before presenting any model choice
-- artifacts are pinned to the qualified Hermes release contract, currently
-  `v2026.4.13`
+- artifacts are pinned to the latest-only qualified Hermes release contract,
+  currently `v2026.5.16`
 - maintainer tooling for preparing sessions, building artifacts, and validating
   this tree lives under `scripts/launch-qualification/`
 

docs/launch-qualification/hermes-agent-setup/v2026.4.13/moonshotai-kimi-k2-6.md → docs/launch-qualification/hermes-agent-setup/v2026.5.16/moonshotai-kimi-k2-6.md

@@ -1,8 +1,8 @@
 ---
 modelId: moonshotai/kimi-k2.6
-qualifiedOn: 2026-04-29
-hermesReleaseTag: v2026.4.13
-hermesCommit: launch-qualification-recorded-internal
+qualifiedOn: 2026-05-24
+hermesReleaseTag: v2026.5.16
+hermesCommit: a91a57fa5a13d516c38b07a141a9ce8a3daabeb0
 osCoverage:
   - linux
   - macos
@@ -13,7 +13,7 @@ recommended: true
 # `moonshotai/kimi-k2.6`
 
 This record defines the checked-in allowlist entry consumed by the shipped
-runtime for the pinned Hermes release.
+runtime for the latest-only Hermes release contract.
 
 ## Sanitized Config Shape
 
@@ -38,9 +38,9 @@ qualification workflow and summarized by this checked-in allowlist record.
 ## Streaming Turn
 
 Saved streaming qualification evidence is tracked in the same release
-qualification workflow for the pinned Hermes release.
+qualification workflow for the latest-only Hermes release.
 
 ## Harmless Tool-Use Turn
 
 Saved harmless tool-use qualification evidence is tracked in the same release
-qualification workflow for the pinned Hermes release.
+qualification workflow for the latest-only Hermes release.

docs/launch-qualification/hermes-agent-setup/v2026.4.13/qwen-qwen3-235b-a22b-instruct-2507-fp8.md → docs/launch-qualification/hermes-agent-setup/v2026.5.16/qwen-qwen3-235b-a22b-instruct-2507-fp8.md

@@ -1,8 +1,8 @@
 ---
 modelId: qwen/qwen3-235b-a22b-instruct-2507-fp8
-qualifiedOn: 2026-04-15
-hermesReleaseTag: v2026.4.13
-hermesCommit: launch-qualification-recorded-internal
+qualifiedOn: 2026-05-24
+hermesReleaseTag: v2026.5.16
+hermesCommit: a91a57fa5a13d516c38b07a141a9ce8a3daabeb0
 osCoverage:
   - linux
   - macos
@@ -13,7 +13,7 @@ recommended: false
 # `qwen/qwen3-235b-a22b-instruct-2507-fp8`
 
 This record defines the checked-in allowlist entry consumed by the shipped
-runtime for the pinned Hermes release.
+runtime for the latest-only Hermes release contract.
 
 ## Sanitized Config Shape
 
@@ -38,9 +38,9 @@ qualification workflow and summarized by this checked-in allowlist record.
 ## Streaming Turn
 
 Saved streaming qualification evidence is tracked in the same release
-qualification workflow for the pinned Hermes release.
+qualification workflow for the latest-only Hermes release.
 
 ## Harmless Tool-Use Turn
 
 Saved harmless tool-use qualification evidence is tracked in the same release
-qualification workflow for the pinned Hermes release.
+qualification workflow for the latest-only Hermes release.

docs/release-readiness/hermes-agent-setup-v1.md

@@ -9,7 +9,8 @@ for the v1 Hermes contract:
 - installed bin: `hermes-agent-setup`
 - canonical integration path: `provider: custom`
 - canonical base URL: `https://api.gonkagate.com/v1`
-- pinned Hermes release for qualification artifacts: `v2026.4.13`
+- latest-only Hermes floor and qualification baseline: `v2026.5.16` /
+  `v0.14.0`
 
 The current checked-in allowlist includes these artifact-backed models:
 
@@ -30,8 +31,8 @@ Maintainer tooling for new or refreshed qualification evidence lives under:
 
 Current checked-in artifacts:
 
-- `docs/launch-qualification/hermes-agent-setup/v2026.4.13/moonshotai-kimi-k2-6.md`
-- `docs/launch-qualification/hermes-agent-setup/v2026.4.13/qwen-qwen3-235b-a22b-instruct-2507-fp8.md`
+- `docs/launch-qualification/hermes-agent-setup/v2026.5.16/moonshotai-kimi-k2-6.md`
+- `docs/launch-qualification/hermes-agent-setup/v2026.5.16/qwen-qwen3-235b-a22b-instruct-2507-fp8.md`
 
 ## FR Coverage Map
 
@@ -41,13 +42,19 @@ Launch Readiness section of the PRD:
 - FR0-FR3: public entrypoint, Node floor, platform guardrails, Hermes path
   resolution, and minimal managed config surface are implemented in `src/cli/`,
   `src/runtime/`, `src/hermes/`, and the CLI/runtime tests.
-- FR4-FR7: shared-key, `OPENAI_BASE_URL`, matching provider, auth-pool,
-  normalized-read, and review-plan behavior are implemented in `src/hermes/`,
-  `src/planning/`, `src/ui/`, and the conflict-classification tests.
+- FR4-FR7 plus the latest-only adaptation: shared-key, matching provider,
+  auth-pool, normalized-read, Hermes version floor, and review-plan behavior
+  are implemented in `src/hermes/`, `src/runtime/`, `src/planning/`,
+  `src/ui/`, and the conflict-classification tests. Legacy endpoint paths such
+  as `OPENAI_BASE_URL` are no longer managed or cleaned by the helper.
 - FR8-FR9: live catalog access, artifact-backed model qualification, hidden key
   prompt, model picker, config/env write planning, backups, rollback, and
   consolidated review are implemented in `src/gonkagate/`, `src/ui/`,
   `src/writes/`, `src/io/`, and the phase-three/phase-four/e2e tests.
+- The catalog proof covers the canonical `GET /v1/models` URL, Bearer auth,
+  response-shape validation, retryable 5xx/429 handling, quota-shaped terminal
+  failures, checked-in qualification intersection, ignoring unqualified live
+  entries, and pre-write aborts before Hermes file mutation.
 - FR10 and Launch Readiness: checked-in launch qualification artifacts,
   validation tooling, public docs, package/CLI truthfulness, mirrored skill
   sync, and contract tests now describe the shipped helper rather than a
@@ -58,8 +65,8 @@ Launch Readiness section of the PRD:
 - `npm run ci`
 - `npm pack --dry-run`
 - `npm run qualification:artifact:validate`
-- confirm the current checked-in allowlist still matches the pinned Hermes
-  release and live GonkaGate catalog
+- confirm the current checked-in allowlist still matches the latest-only Hermes
+  baseline and live GonkaGate catalog
 - confirm Linux, macOS, and WSL2 evidence is recorded in the artifact or that
   an explicit signed-off exception exists before GA
 - confirm `README.md`, `AGENTS.md`, `docs/`, `package.json`,