> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session08-catalog-and-context-metadata/spec.md).

# Session Specification

**Session ID**: `phase40-session08-catalog-and-context-metadata` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: cc0cc299cc28efd1c2f51c244f52fa4c2690508b

***

## 1. Session Overview

This session refreshes the Hermes model catalog and context metadata that later chat selector, context meter, Ministry builder, and Ministry analytics work will consume. Session 02 established the expanded `/__hermes_models` response shape, configured-provider filtering, aliases, MoA preset summaries, and safe browser parser behavior; this session turns that foundation into a richer catalog contract with provider presentation metadata, context fallback rules, snapshot provenance, and explicit upstream 2.10.1 model coverage.

The session is next because the Phase 40 state marks Sessions 01-07 complete, and Session 08 is the first unfinished candidate. Sessions 09, 11, 14, and 15 depend on the catalog decisions here, so the work must stay durable, typed, and demo-safe instead of hardcoding display labels or context values in later UI surfaces.

Implementation stays within the existing AI OS split Hermes owners. Static catalog data remains bundled and deterministic; no live model-catalog refresh, pricing fetch, benchmark claim, upstream monolithic route copy, or browser exposure of local config, auth JSON, env values, private paths, or tokens is in scope.

***

## 2. Objectives

1. Expand the Hermes model catalog contract with provider labels, provider tint metadata, context fallback rules, and bundled snapshot provenance.
2. Refresh `HERMES_MODEL_CATALOG` for upstream 2.10.1 provider groups and model IDs while preserving AI OS aliases and configured-provider filtering.
3. Add explicit `anthropic/claude-sonnet-5` coverage with the expected context fallback and no regression to existing OpenAI, Gemini, OpenRouter, OpenAI Codex, xAI, local, and AI OS provider aliases.
4. Add focused parser, bridge, provider metadata, hook, demo fixture, and Pantheon model-option tests so later selector and Ministry sessions can consume one stable catalog source.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session02-models-and-provider-readiness` - Provides expanded Hermes model response parsing, configured-provider derivation, provider aliases, MoA preset summaries, and no-leak tests for `/__hermes_models`.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Current Hermes public read owner in `scripts/lib/hermes-dev-bridge.ts`.
* Current provider alias and label helper owner in `scripts/lib/hermes-provider-readiness.ts`.
* Current browser contract owner in `src/lib/hermes-types.ts`.
* Current demo fixture owner in `src/lib/hermes-demo-data.ts`.
* Current Hermes model consumers in `src/hooks/use-hermes.ts` and `src/components/hermes/hermes-pantheon.tsx`.

### Environment Requirements

* Local checkout with dependencies installed or installable through `bun install`.
* No live Hermes install, provider credentials, OpenRouter network access, third-party dashboard access, or upstream checkout mutation required.
* Tests must use bundled fixtures and temp Hermes homes only.

***

## 4. Scope

### In Scope (MVP)

* AI OS exposes bundled Hermes catalog metadata with provider labels, provider tints, context fallback behavior, and a visible bundled snapshot provenance for the static upstream 2026-06-30 data.
* `HERMES_MODEL_CATALOG` includes upstream 2.10.1 provider groups and model IDs needed by Phase 40 while retaining existing AI OS aliases and local provider rows.
* `anthropic/claude-sonnet-5` is present in the OpenRouter-compatible catalog path with an expected context fallback.
* Configured-provider filtering remains alias-aware for `googlegemini`, `google`, `gemini`, `openai-codex`, `xai-oauth`, `openrouter`, local, and retained AI OS provider names.
* Parser and hook consumers preserve compatibility with old expanded Session 02 bodies while accepting the richer catalog metadata.
* Demo fixtures use the same safe catalog metadata without implying live refresh, live pricing, or local configured-provider summaries.
* Pantheon model options can use provider labels and context/provenance text without adding diagnostics to the product surface.

### Out Of Scope (Deferred)

* Live model-catalog refresh job - Reason: the Session 08 stub permits a static bundled snapshot and requires labeling unless a live path is implemented.
* Live OpenRouter pricing and Ministry model analytics - Reason: Session 09 owns pricing provenance, bundled price fallback, and Ministry model rows.
* Chat selector and context meter UI - Reason: Session 11 owns the product selector and meter components after the catalog contract is stable.
* Ministry builder and save UX - Reason: Sessions 14 and 15 own Pantheon integration, generated MoA config, analytics, and save UX.
* Removing existing AI OS provider aliases - Reason: the Phase 40 stub requires compatibility with retained aliases.

***

## 5. Technical Approach

### Architecture

Keep catalog ownership in the current split Hermes architecture. The static catalog rows and `/__hermes_models` response assembly stay in `scripts/lib/hermes-dev-bridge.ts`; provider normalization, labels, and tint presentation helpers stay in `scripts/lib/hermes-provider-readiness.ts`; browser-facing model types and parsers stay in `src/lib/hermes-types.ts`; demo fixtures stay in `src/lib/hermes-demo-data.ts`; hook state remains in `src/hooks/use-hermes.ts`; and Pantheon consumes the richer contract without becoming the source of catalog metadata.

The implementation should add metadata as additive fields so existing clients that only read `provider`, `models`, `name`, `tier`, and `context` remain valid. Context fallback should be explicit and deterministic, and bundled provenance should travel with the model response rather than living only in comments.

### Design Patterns

* Additive browser contract: Extend model group and model entry metadata while preserving Session 02 parser compatibility.
* Alias-first catalog filtering: Normalize provider aliases before filtering so valid provider groups do not disappear.
* Presentation metadata at the data boundary: Provider labels and tints are derived centrally, not duplicated in UI components.
* Bundled snapshot provenance: Static model data is labeled as bundled upstream 2026-06-30 data until a separate live refresh path exists.
* Demo-safe projection: Demo data mirrors the contract but never implies local configured-provider state or live network data.

***

## 6. Deliverables

### Files To Create

| File                                                      | Purpose                                                      | Est. Lines |
| --------------------------------------------------------- | ------------------------------------------------------------ | ---------- |
| `scripts/lib/__tests__/hermes-provider-readiness.test.ts` | Focused tests for provider labels, tints, aliases, and keys. | \~120      |

### Files To Modify

| File                                                       | Changes                                                                                                 | Est. Lines |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-dev-bridge.ts`                         | Refresh catalog rows, add snapshot provenance, add context fallback metadata, and preserve filters.     | \~180      |
| `scripts/lib/hermes-provider-readiness.ts`                 | Export provider presentation metadata helpers for labels, aliases, and tints.                           | \~90       |
| `src/lib/hermes-types.ts`                                  | Extend model catalog types and parser validation for metadata and fallback context fields.              | \~120      |
| `src/lib/hermes-demo-data.ts`                              | Update demo model catalog with safe metadata and bundled snapshot provenance.                           | \~60       |
| `src/hooks/use-hermes.ts`                                  | Preserve model query empty-state behavior with richer catalog response metadata.                        | \~20       |
| `src/components/hermes/hermes-pantheon.tsx`                | Display provider-aware model option labels and context/provenance copy without diagnostics.             | \~80       |
| `scripts/lib/__tests__/hermes-dev-bridge.test.ts`          | Add bridge tests for Sonnet 5, snapshot provenance, context fallback, aliases, filtering, and no leaks. | \~180      |
| `src/lib/__tests__/hermes-types.test.ts`                   | Add parser tests for additive metadata, invalid metadata, and compatibility with Session 02 bodies.     | \~140      |
| `src/hooks/__tests__/use-hermes.test.tsx`                  | Add hook fixture coverage for richer model response metadata and empty catalog behavior.                | \~60       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Add Pantheon model-option coverage for provider labels, context fallback, and snapshot copy.            | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `/__hermes_models` includes catalog-level bundled snapshot provenance for the static upstream 2026-06-30 data.
* [ ] Catalog groups expose friendly provider labels and provider tint metadata from shared provider helpers.
* [ ] Context metadata is explicit for rows with known context and deterministic for rows that rely on fallback values.
* [ ] `anthropic/claude-sonnet-5` appears with expected context fallback.
* [ ] Configured-provider filtering preserves AI OS aliases and does not remove valid Google/Gemini, OpenAI Codex, xAI OAuth, OpenRouter, or local rows.
* [ ] Demo model data uses the same safe contract without live refresh or local configured-provider claims.

### Testing Requirements

* [ ] Provider readiness tests cover labels, tints, alias expansion, key names, and unknown-provider fallback behavior.
* [ ] Bridge tests cover catalog rows, Sonnet 5, snapshot provenance, context fallback, configured filtering, and no raw local output leakage.
* [ ] Parser tests cover additive metadata, invalid metadata, context fallback, and Session 02 compatibility.
* [ ] Hook and Pantheon tests cover richer catalog fixtures and product-facing model labels.
* [ ] Focused checks pass: `bunx vitest run scripts/lib/__tests__/hermes-provider-readiness.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`.
* [ ] `bun run typecheck` and `bun run typecheck:scripts` pass.

### Non-Functional Requirements

* [ ] Catalog data remains bounded, deterministic, browser-safe, and ASCII-encoded.
* [ ] Public/demo mode remains fixture-backed and does not fetch live model or pricing data.
* [ ] No model response, fixture, test output, or UI copy exposes raw config, auth JSON, env values, private paths, account IDs, tokens, or secret-shaped strings.
* [ ] User-facing surfaces contain product-facing copy only.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] No upstream monolithic route or Vite middleware file copied

***

## 8. Implementation Notes

### Working Assumptions

* Static snapshot provenance should be carried in the browser model contract, not only in source comments: the Session 08 stub says static catalog data must be labeled as bundled or snapshot unless a live refresh path exists, and no live refresh path is in scope. This lets later UI sessions display honest provenance without duplicating catalog knowledge.
* Provider labels and tints should be exported from provider readiness helpers: Session 02 already centralized aliases and labels in `scripts/lib/hermes-provider-readiness.ts`, and current Pantheon code only reads the model response. Planning can proceed by extending that owner instead of creating component-local provider maps.

### Key Considerations

* Keep the catalog refresh semantic. Do not copy upstream route or middleware files into AI OS.
* Preserve `configuredDefault`, `default`, `catalog`, `mixtures`, and `configured` compatibility from Session 02.
* Ensure metadata additions remain optional at parser boundaries so older expanded bodies still parse.
* Keep user-visible wording focused on bundled snapshot provenance, not debug internals.

### Potential Challenges

* Upstream model names may not map one-to-one to AI OS providers: use retained aliases and explicit provider normalization tests.
* Context values may be missing for some rows: use deterministic fallback metadata and test both direct and fallback context paths.
* UI option labels can become too long: keep Pantheon copy compact and test the exact product-facing strings rather than exposing raw metadata.

### Relevant Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Map catalog behavior to AI OS owners and keep skipped upstream file layout out of source.
* \[P38] **Local control-plane gates are defense in depth**: Preserve safe browser projection and avoid exposing raw local data through model reads.
* \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Demo fixtures must remain static and free of live bridge or local runtime claims.
* \[P00] **Stack conventions**: Use Bun, Vite 8, TanStack Start, React 19, TypeScript, and existing test placement.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Parser drift could reject existing Session 02 model bodies after metadata is added.
* Configured-provider filtering could hide alias-matched providers needed by chat selector and Ministry sessions.
* User-facing catalog copy could imply live refresh, live pricing, or local provider access when only bundled snapshot data is available.

***

## 9. Testing Strategy

### Unit Tests

* Test provider labels, tints, alias expansion, key names, and unknown-provider fallback in `scripts/lib/__tests__/hermes-provider-readiness.test.ts`.
* Test parser acceptance and rejection paths in `src/lib/__tests__/hermes-types.test.ts`.

### Integration Tests

* Test `/__hermes_models` bridge output in `scripts/lib/__tests__/hermes-dev-bridge.test.ts` with temp Hermes homes, configured aliases, bundled catalog rows, and leakage assertions.
* Test hook and Pantheon consumers in `src/hooks/__tests__/use-hermes.test.tsx` and `src/components/hermes/__tests__/hermes-sections.test.tsx`.

### Runtime Verification

* Run focused Vitest files for catalog, parser, hook, and Pantheon behavior.
* Run `bun run typecheck` and `bun run typecheck:scripts`.

### Edge Cases

* Missing Hermes config still returns a full bundled catalog with provenance.
* Malformed Hermes config still fails softly and does not suppress static catalog rows.
* Unknown provider IDs receive safe label/tint fallbacks.
* Alias-only configured providers still retain the matching canonical catalog group.
* Fallback context values are deterministic and do not override explicit row contexts.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session02-models-and-provider-readiness`
* Depended by: `phase40-session09-model-intelligence-and-pricing`, `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session14-ministry-builder-and-pantheon`, `phase40-session15-ministry-config-analytics-and-save-ux`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session08-catalog-and-context-metadata/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.