> 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-session09-model-intelligence-and-pricing/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase40-session09-model-intelligence-and-pricing` **Started**: 2026-07-03 04:31 **Last Updated**: 2026-07-03 05:55

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 20 / 20 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Task Log

### 2026-07-03 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

***

### Task T001 - Verify Session 08 artifacts, Session 09 scope, worktree cleanliness, and Hermes owner files

**Started**: 2026-07-03 04:31 **Completed**: 2026-07-03 04:31 **Duration**: 1 minute

**Notes**:

* Confirmed the required Session 08 validation artifact reports PASS and records completed bridge, parser, hook, fixture, and component ownership.
* Confirmed Session 09 scope targets Hermes-scoped model intelligence and pricing contracts without a repo-level model intelligence data file.
* Confirmed the active worktree is not clean before implementation because `.spec_system/state.json` is modified and the current Session 09 spec directory is untracked. These are current workflow artifacts and were preserved.
* Read the primary Hermes owner files before implementation: bridge, browser parser types, hook, and demo fixture.

**Files Changed**:

* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - initialized the session log and recorded setup verification evidence.

**Verification**:

* Command/check: `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.11-codex/skills/apex-spec/scripts/analyze-project.sh --json; fi`
  * Result: PASS - current session resolved to `phase40-session09-model-intelligence-and-pricing`; session directory exists; repo is not detected as a monorepo.
  * Evidence: JSON output reported `current_session_dir_exists: true`, `current_phase: 40`, and `monorepo: null`.
* Command/check: `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/check-prereqs.sh --json --env; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.11-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env; fi`
  * Result: PASS - spec system, jq, and git prerequisites are available.
  * Evidence: checker returned `overall: pass` with no issues.
* Command/check: `sed -n '1,240p' .spec_system/specs/phase40-session08-catalog-and-context-metadata/validation.md`
  * Result: PASS - Session 08 validation reports PASS.
  * Evidence: validation summary records code review resolved, 20/20 tasks complete, focused tests passed, and type/lint gates passed.
* Command/check: `git status --short`
  * Result: PASS - worktree state captured before implementation.
  * Evidence: output showed `M .spec_system/state.json` and `?? .spec_system/specs/phase40-session09-model-intelligence-and-pricing/`.
* Command/check: targeted inspection of `scripts/lib/hermes-dev-bridge.ts`, `src/lib/hermes-types.ts`, `src/hooks/use-hermes.ts`, and `src/lib/hermes-demo-data.ts`
  * Result: PASS - existing Hermes bridge, parser, hook, and fixture owners are present and readable.
  * Evidence: files define current `/__hermes_models` bridge contracts, browser parser contracts, React Query hook plumbing, and bundled demo fixtures.
* UI product-surface check: N/A - setup verification changed no user-facing route or component.
* UI craft check: N/A - setup verification changed no user-facing route or component.

### Task T002 - Capture focused baseline tests for Hermes bridge, parser, hook, and sections

**Started**: 2026-07-03 04:31 **Completed**: 2026-07-03 04:32 **Duration**: 1 minute

**Notes**:

* Captured the required pre-implementation baseline for the Hermes bridge, parser, hook, and section test files.
* The baseline passed before model-intelligence code changes.

**Files Changed**:

* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded baseline test evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T002 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run 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`
  * Result: PASS - 4 test files passed.
  * Evidence: Vitest reported 137/137 tests passed in 2.72s.
* UI product-surface check: N/A - baseline test capture changed no user-facing route or component.
* UI craft check: N/A - baseline test capture changed no user-facing route or component.

### Task T003 - Confirm no repo-level model-intelligence data file exists and record the Hermes-scoped contract boundary

**Started**: 2026-07-03 04:32 **Completed**: 2026-07-03 04:32 **Duration**: 1 minute

**Notes**:

* Confirmed `src/data/model-intel.json` is absent.
* Confirmed no existing `src/data` model-intelligence file should be extended for this session.
* Recorded the contract boundary: Session 09 data stays in Hermes bridge/script owners, browser parser/helper owners, hook plumbing, and demo fixtures.

**Files Changed**:

* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded repo-level data boundary evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T003 complete after evidence was recorded.

**Verification**:

* Command/check: `test ! -e src/data/model-intel.json && printf 'absent\n'`
  * Result: PASS - the disallowed repo-level model intelligence file does not exist.
  * Evidence: command printed `absent`.
* Command/check: `rg --files src/data | rg 'model-intel|model-intelligence' || true`
  * Result: PASS - no model-intelligence file is present under `src/data`.
  * Evidence: command produced no matching files.
* Command/check: `find src/data -maxdepth 2 -type f | sort`
  * Result: PASS - current data files are live-data and graph fixtures only.
  * Evidence: output listed `src/data/graphs/ai-os.json`, `src/data/graphs/index.json`, `src/data/live-data.example.json`, and generated `src/data/live-data.json`.
* UI product-surface check: N/A - data-boundary verification changed no user-facing route or component.
* UI craft check: N/A - data-boundary verification changed no user-facing route or component.

### Task T004 - Create Hermes-scoped Ministry model rows with required default lineup metrics and no live benchmark claims

**Started**: 2026-07-03 04:33 **Completed**: 2026-07-03 04:40 **Duration**: 7 minutes

**Notes**:

* Added the Hermes-scoped model intelligence owner with the default Ministry lineup rows for Claude Opus 4.8, GPT-5.5, GLM 5.2, and DeepSeek V4 Pro.
* Each row includes safe provider presentation metadata, aliases, role, bundled static benchmark score, bundled static speed estimate, and explicit non-live metric provenance.
* Kept the data out of `src/data` and scoped to `scripts/lib/hermes-model-intelligence.ts`.

**Files Changed**:

* `scripts/lib/hermes-model-intelligence.ts` - created the default Ministry lineup rows and metric contracts.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T004 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T004 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript compiled with the new model intelligence owner.
  * Evidence: `tsc --noEmit -p tsconfig.scripts.json` completed with exit code 0.
* Command/check: targeted inspection of `scripts/lib/hermes-model-intelligence.ts`
  * Result: PASS - default lineup contains exactly the four required Ministry models and uses `bundled-static` metric labels.
  * Evidence: rows include `anthropic/claude-opus-4.8`, `openai/gpt-5.5`, `zai/glm-5.2`, and `deepseek/deepseek-v4-pro`; benchmark and speed metric labels are bundled/static and do not claim live benchmark data.
* UI product-surface check: N/A - script-side data owner changed no user-facing route or component.
* UI craft check: N/A - script-side data owner changed no user-facing route or component.

### Task T005 - Add bundled pricing snapshot and OpenRouter model-pricing parser with bounded values and malformed-field fallback

**Started**: 2026-07-03 04:40 **Completed**: 2026-07-03 04:41 **Duration**: 1 minute

**Notes**:

* Added bundled snapshot pricing for the four default Ministry rows.
* Added `parseOpenRouterModelPricing` to consume the public OpenRouter model-list shape, match only known Ministry model aliases, convert per-token prompt/completion prices into per-million values, and ignore unknown or malformed rows.
* Added bounded price parsing so impossible, negative, missing, or oversized price fields cannot override snapshot pricing.

**Files Changed**:

* `scripts/lib/hermes-model-intelligence.ts` - added bundled snapshot pricing, OpenRouter alias matching, price bounds, and parser export.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T005 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T005 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript compiled with the parser and pricing contracts.
  * Evidence: `tsc --noEmit -p tsconfig.scripts.json` completed with exit code 0.
* Command/check: targeted inspection of `scripts/lib/hermes-model-intelligence.ts`
  * Result: PASS - bundled pricing exists for all default rows, parser is alias-limited, and malformed pricing rows fall through to snapshot behavior by omission.
  * Evidence: `BUNDLED_PRICING`, `OPENROUTER_ALIAS_TO_MODEL_ID`, `parsePricePerToken`, and `parseOpenRouterModelPricing` are present and scoped to known Ministry rows.
* UI product-surface check: N/A - script-side pricing parser changed no user-facing route or component.
* UI craft check: N/A - script-side pricing parser changed no user-facing route or component.

### Task T006 - Implement local-live pricing overlay with timeout, retry/backoff, 30-minute stale cache, and bundled fallback provenance

**Started**: 2026-07-03 04:41 **Completed**: 2026-07-03 04:42 **Duration**: 1 minute

**Notes**:

* Added `resolveHermesModelIntelligence` with optional keyless OpenRouter live pricing, bounded timeout, one retry with backoff, and 30-minute stale-time cache semantics.
* Added explicit snapshot fallback behavior for disabled live pricing, missing fetch support, failed live fetches, malformed/empty live payloads, and partial OpenRouter coverage.
* Added cache reset export for focused tests.

**Files Changed**:

* `scripts/lib/hermes-model-intelligence.ts` - added live overlay resolver, timeout/retry/backoff behavior, cache, and provenance summaries.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T006 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T006 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript compiled with the live overlay resolver.
  * Evidence: `tsc --noEmit -p tsconfig.scripts.json` completed with exit code 0.
* Command/check: targeted inspection of `scripts/lib/hermes-model-intelligence.ts`
  * Result: PASS - resolver uses a timeout, retry delay, cache stale time, and bundled fallback provenance.
  * Evidence: `fetchWithTimeout`, `fetchOpenRouterPricing`, `HERMES_MODEL_INTELLIGENCE_STALE_TIME_MS`, and `snapshotBody`/`liveBody` paths are present.
* UI product-surface check: N/A - script-side live overlay changed no user-facing route or component.
* UI craft check: N/A - script-side live overlay changed no user-facing route or component.

### Task T007 - Extend browser contract types and parser for model intelligence rows, pricing provenance, and missing-metric fallback semantics

**Started**: 2026-07-03 04:43 **Completed**: 2026-07-03 04:48 **Duration**: 5 minutes

**Notes**:

* Added browser-safe model intelligence types for rows, metrics, pricing, ranking, provenance, and live-pricing state.
* Added `parseHermesModelIntelligenceResponse` and validation helpers for provider tints, row roles, metric provenance, pricing provenance, stale-time values, and missing-metric fallback semantics.
* Preserved parser-owned bridge contracts so hooks and components do not consume raw response shapes.

**Files Changed**:

* `src/lib/hermes-types.ts` - added model intelligence contracts and parser validation.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T007 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T007 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled with the expanded browser contracts.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* Command/check: targeted inspection of `src/lib/hermes-types.ts`
  * Result: PASS - parser validates row, metric, pricing, provenance, live summary, and ranking structures before browser use.
  * Evidence: `parseHermesModelIntelligenceResponse`, `parseModelMetric`, `parseModelPricing`, `parseModelPricingProvenance`, and `parseModelLivePricingSummary` are present.
* UI product-surface check: N/A - parser contract changed no rendered user-facing route or component.
* UI craft check: N/A - parser contract changed no rendered user-facing route or component.

### Task T008 - Create browser ranking helpers for benchmark, cost, and speed with deterministic ordering and missing-metric fallback behavior

**Started**: 2026-07-03 04:49 **Completed**: 2026-07-03 04:51 **Duration**: 2 minutes

**Notes**:

* Added pure browser ranking helpers for benchmark, cost, and speed metrics.
* Sorting uses metric value, explicit fallback preference, display name, and stable row id so order does not drift across runs.
* Missing benchmark/speed/pricing values use declared fallback/rank values and expose `usedFallback` for analytics surfaces.

**Files Changed**:

* `src/lib/hermes-model-intelligence.ts` - created ranking value and sorted ranking helpers.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T008 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T008 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled with the new ranking helper.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* Command/check: targeted inspection of `src/lib/hermes-model-intelligence.ts`
  * Result: PASS - helper supports `benchmark`, `cost`, and `speed` rankings with deterministic tie-breakers and fallback metadata.
  * Evidence: `rankHermesModelIntelligenceRows`, `getHermesModelRankingIds`, and `getHermesModelRankingValue` are present.
* UI product-surface check: N/A - ranking helper changed no rendered user-facing route or component.
* UI craft check: N/A - ranking helper changed no rendered user-facing route or component.

### Task T009 - Register `/__hermes_model_intelligence` as a public local Hermes read with schema-safe response assembly and explicit error mapping

**Started**: 2026-07-03 04:52 **Completed**: 2026-07-03 05:55 **Duration**: 3 minutes

**Notes**:

* Registered `/__hermes_model_intelligence` in the existing Hermes endpoint table as a public, non-sensitive local read.
* The endpoint uses the existing bridge handler, preserving loopback checks, Host-header guard, GET-only behavior, no-store JSON responses, and safe bridge error paths.
* Added explicit internal error mapping for unexpected resolver failures.

**Files Changed**:

* `scripts/lib/hermes-dev-bridge.ts` - registered the public endpoint and added `readHermesModelIntelligence`.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T009 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T009 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript compiled with the bridge endpoint registration.
  * Evidence: `tsc --noEmit -p tsconfig.scripts.json` completed with exit code 0.
* Command/check: targeted inspection of `scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - endpoint is registered as `sensitive: false` and uses the central bridge handler plus safe `internal_error` fallback.
  * Evidence: `ENDPOINTS` includes `/__hermes_model_intelligence`; `readHermesModelIntelligence` returns `model intelligence unavailable` on unexpected resolver failure.
* UI product-surface check: N/A - bridge endpoint changed no rendered user-facing route or component.
* UI craft check: N/A - bridge endpoint changed no rendered user-facing route or component.

### Task T010 - Assemble the model intelligence bridge body from bundled rows, configured/catalog aliases, and optional live pricing overlay without exposing credentials or local paths

**Started**: 2026-07-03 04:55 **Completed**: 2026-07-03 04:56 **Duration**: 1 minute

**Notes**:

* Wired the bridge read to `resolveHermesModelIntelligence`, which assembles bundled Ministry rows, safe provider presentation, model aliases, snapshot pricing, live OpenRouter pricing when available, rankings, and provenance.
* Added bridge-level live-pricing enablement via `HERMES_MODEL_INTELLIGENCE_LIVE_PRICING`; the resolver never reads provider keys, auth JSON, local paths, prompts, or transcripts.
* Preserved public local read behavior while allowing tests to inject model-intelligence resolver options.

**Files Changed**:

* `scripts/lib/hermes-dev-bridge.ts` - delegated endpoint body assembly to the Hermes-scoped resolver and added live-pricing option plumbing.
* `scripts/lib/hermes-model-intelligence.ts` - provides the resolver used by the bridge body.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T010 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T010 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript compiled with resolver option plumbing.
  * Evidence: `tsc --noEmit -p tsconfig.scripts.json` completed with exit code 0.
* Command/check: targeted inspection of `scripts/lib/hermes-dev-bridge.ts` and `scripts/lib/hermes-model-intelligence.ts`
  * Result: PASS - bridge body is assembled from bundled rows plus optional keyless OpenRouter pricing; no credential, auth JSON, local path, prompt, transcript, or raw private payload is read for this endpoint.
  * Evidence: bridge passes `now`, live-pricing options, and resolver settings only; model-intelligence module fetches only the public OpenRouter models URL with an `Accept` header.
* UI product-surface check: N/A - bridge body assembly changed no rendered user-facing route or component.
* UI craft check: N/A - bridge body assembly changed no rendered user-facing route or component.

### Task T011 - Add bundled-snapshot demo model intelligence fixture with live pricing disabled and product-safe provenance labels

**Started**: 2026-07-03 04:57 **Completed**: 2026-07-03 05:01 **Duration**: 4 minutes

**Notes**:

* Added `HERMES_DEMO_MODEL_INTELLIGENCE` with bundled snapshot rows for the default Ministry lineup.
* Fixture marks live pricing disabled, attempted false, and uses product-safe bundled provenance labels.
* Demo ranking arrays are static and match the bundled benchmark, cost, and speed values.

**Files Changed**:

* `src/lib/hermes-demo-data.ts` - added model-intelligence fixture and small demo metric/pricing helpers.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T011 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T011 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled with the new demo fixture.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* Command/check: targeted inspection of `src/lib/hermes-demo-data.ts`
  * Result: PASS - demo fixture contains bundled snapshot pricing only and disables live pricing.
  * Evidence: `HERMES_DEMO_MODEL_INTELLIGENCE.livePricing` has `enabled: false`, `attempted: false`, and `status: "disabled"`; pricing provenance source is `bundled`.
* UI product-surface check: N/A - fixture data changed no rendered user-facing route or component.
* UI craft check: N/A - fixture data changed no rendered user-facing route or component.

### Task T012 - Expose model intelligence from `useHermes` with explicit loading, empty, error, offline, and demo-safe query states

**Started**: 2026-07-03 05:02 **Completed**: 2026-07-03 05:06 **Duration**: 4 minutes

**Notes**:

* Added a public model-intelligence query key and fetch path for `/__hermes_model_intelligence`.
* Exposed `modelIntelligence` from `UseHermesResult` using the shared query-view states for live loading, empty, error, and offline handling.
* Demo mode returns `HERMES_DEMO_MODEL_INTELLIGENCE` with `state: "demo"` and does not enable the live endpoint.

**Files Changed**:

* `src/hooks/use-hermes.ts` - added query key, parser import, stale time, query, result field, empty-state mapping, and demo fixture state.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T012 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T012 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled with the expanded hook result.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* Command/check: targeted inspection of `src/hooks/use-hermes.ts`
  * Result: PASS - model intelligence uses public read gating in live mode and bundled fixture state in demo mode.
  * Evidence: `HERMES_QUERY_KEYS.modelIntelligence`, `modelIntelligenceQuery`, `HERMES_MODEL_INTELLIGENCE_STALE_TIME_MS`, and the demo `modelIntelligence` result are present.
* UI product-surface check: N/A - hook plumbing changed no rendered user-facing route or component.
* UI craft check: N/A - hook plumbing changed no rendered user-facing route or component.

### Task T013 - Thread the new model intelligence view through Hermes read-only data plumbing only where needed by existing demo/live boundaries

**Started**: 2026-07-03 05:07 **Completed**: 2026-07-03 05:14 **Duration**: 7 minutes

**Notes**:

* Added the read-only page demo/live boundary for model intelligence: demo mode uses the bundled fixture and live mode uses the hook result.
* Threaded the view into the existing status bar model summary as a compact product signal rather than adding a new debug surface.
* Preserved existing route layout and tabs.

**Files Changed**:

* `src/components/hermes/hermes-read-only-page.tsx` - added demo/live `modelIntelligence` view plumbing and status-bar prop.
* `src/components/hermes/hermes-status-bar.tsx` - included model-intelligence count and pricing provenance in the existing model summary.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T013 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T013 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled with the read-only page and status-bar plumbing.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* Command/check: `bunx vitest run src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - Hermes section tests passed with the new status-bar prop.
  * Evidence: 1 test file passed; 89/89 tests passed.
* UI product-surface check: PASS - targeted inspection of the rendered-copy path in `src/components/hermes/hermes-status-bar.tsx`.
  * Evidence: new copy is product-facing (`Ministry intelligence rows use snapshot/live pricing`) and does not expose endpoint names, cache details, debug labels, local paths, tokens, or scaffold text.
* UI craft check: PASS - targeted component structure inspection.
  * Evidence: summary stays inside the existing Model status-card detail text and does not add a new card, tab, or layout pressure.

### Task T014 - Update Hermes section mocks and fixture expectations for the expanded hook result without adding debug-only UI copy

**Started**: 2026-07-03 05:14 **Completed**: 2026-07-03 05:16 **Duration**: 2 minutes

**Notes**:

* Updated the Hermes section test fixture to include the expanded `modelIntelligence` hook result.
* Updated direct `HermesStatusBar` renders to pass the new query view.
* Added a product-facing expectation for the Ministry summary copy, without adding debug-only endpoint, cache, or scaffolding labels to the UI.

**Files Changed**:

* `src/components/hermes/__tests__/hermes-sections.test.tsx` - added model-intelligence fixture wiring and a status-bar expectation.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T014 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T014 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - section mocks and expectations are aligned with the expanded hook result.
  * Evidence: 1 test file passed; 89/89 tests passed.
* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled after test fixture updates.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* UI product-surface check: PASS - status-bar assertion covers product-safe Ministry summary copy.
  * Evidence: test expects `4 Ministry intelligence rows use snapshot pricing`; no debug-only endpoint/cache/scaffold copy was added.
* UI craft check: PASS - no new visible controls or sections were added for this fixture update.
  * Evidence: section test still passes existing route-shell reachability and status-card assertions.

### Task T015 - Preserve public-demo static behavior by ensuring demo mode uses bundled fixtures and never calls the live model intelligence endpoint

**Started**: 2026-07-03 05:17 **Completed**: 2026-07-03 05:19 **Duration**: 2 minutes

**Notes**:

* Confirmed the read-only page substitutes `HERMES_DEMO_MODEL_INTELLIGENCE` for model intelligence when `demoMode` is active.
* Confirmed the hook's live endpoint path is gated behind `liveQueriesEnabled && hasInstalledHermes`, and `liveQueriesEnabled` is false in demo mode.
* Public/demo behavior remains fixture-only and static for model intelligence.

**Files Changed**:

* `src/components/hermes/hermes-read-only-page.tsx` - demo/live model-intelligence boundary.
* `src/hooks/use-hermes.ts` - demo-safe fixture state and live endpoint gating.
* `src/lib/hermes-demo-data.ts` - bundled demo fixture with live pricing disabled.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T015 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T015 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "HERMES_DEMO_MODEL_INTELLIGENCE|modelIntelligence|__hermes_model_intelligence|demoMode" src/components/hermes/hermes-read-only-page.tsx src/hooks/use-hermes.ts src/lib/hermes-demo-data.ts`
  * Result: PASS - demo fixture substitution and live endpoint gating are present in the expected owners.
  * Evidence: read-only page uses `demoView(HERMES_DEMO_MODEL_INTELLIGENCE)` in demo mode; hook fetch path is `/__hermes_model_intelligence`; hook returns fixture state when `isDemoMode` is true.
* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript compiled after the demo/static boundary changes.
  * Evidence: `tsc --noEmit` completed with exit code 0.
* UI product-surface check: PASS - targeted inspection of the normal route copy.
  * Evidence: demo mode uses bundled product fixture data and does not add live-fetch diagnostics or endpoint labels to the primary UI.
* UI craft check: PASS - no new layout or responsive surface was added for the demo/static boundary.
  * Evidence: existing status-card integration remains unchanged except for the product-safe Model detail.

### Task T016 - Add script-side unit tests for default lineup coverage, OpenRouter parser success, live failure fallback, cache stale time, and sanitized output

**Started**: 2026-07-03 05:20 **Completed**: 2026-07-03 05:25 **Duration**: 5 minutes

**Notes**:

* Added focused tests for the script-side model intelligence owner.
* Covered default lineup rows, bundled static metrics, OpenRouter parser conversion, malformed-field skip behavior, live pricing success, fresh-cache reuse, disabled live pricing, stale failure fallback, and no-secret output.

**Files Changed**:

* `scripts/lib/__tests__/hermes-model-intelligence.test.ts` - created script-side model-intelligence tests.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T016 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T016 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-model-intelligence.test.ts`
  * Result: PASS - script-side model intelligence tests passed.
  * Evidence: 1 test file passed; 5/5 tests passed.
* UI product-surface check: N/A - script-side tests changed no user-facing route or component.
* UI craft check: N/A - script-side tests changed no user-facing route or component.

### Task T017 - Add browser parser and ranking tests for valid payloads, invalid payloads, stable sorting, and missing-metric fallback behavior

**Started**: 2026-07-03 05:26 **Completed**: 2026-07-03 05:30 **Duration**: 4 minutes

**Notes**:

* Added browser-side tests for the model intelligence parser and ranking helper.
* Covered valid demo fixture parsing, invalid shape rejection, invalid pricing source rejection, invalid missing-metric provenance, deterministic sorting, and fallback ranking metadata.

**Files Changed**:

* `src/lib/__tests__/hermes-model-intelligence.test.ts` - created browser parser/ranking tests.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T017 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T017 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run src/lib/__tests__/hermes-model-intelligence.test.ts`
  * Result: PASS - browser model-intelligence tests passed.
  * Evidence: 1 test file passed; 4/4 tests passed.
* UI product-surface check: N/A - parser/ranking tests changed no user-facing route or component.
* UI craft check: N/A - parser/ranking tests changed no user-facing route or component.

### Task T018 - Extend Hermes bridge, parser, and hook tests for endpoint registration, no-token reads, live pricing labels, bundled fallback labels, demo-disabled live pricing, and query states

**Started**: 2026-07-03 05:31 **Completed**: 2026-07-03 05:39 **Duration**: 8 minutes

**Notes**:

* Extended bridge tests for endpoint registration, public no-token reads, live OpenRouter provenance, bundled snapshot provenance, no-store response headers, and sanitized output.
* Extended parser fixture alignment coverage for `HERMES_DEMO_MODEL_INTELLIGENCE`.
* Extended hook tests for successful live model-intelligence query state, public no-token reads, empty state mapping, and demo-disabled live pricing.
* Kept section tests aligned with the expanded hook result.

**Files Changed**:

* `scripts/lib/__tests__/hermes-dev-bridge.test.ts` - added endpoint registration/public-read coverage and model-intelligence endpoint tests.
* `src/lib/__tests__/hermes-types.test.ts` - added demo model-intelligence fixture parser alignment.
* `src/hooks/__tests__/use-hermes.test.tsx` - added live/demo/empty/no-token hook coverage for model intelligence.
* `src/components/hermes/__tests__/hermes-sections.test.tsx` - included expanded hook result fixture and status summary assertion.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T018 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T018 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run 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`
  * Result: PASS - bridge, parser, hook, and section integration tests passed.
  * Evidence: 4 test files passed; 138/138 tests passed.
* UI product-surface check: PASS - section test assertion covers product-facing status summary copy.
  * Evidence: no debug-only endpoint, cache, scaffold, local path, or token copy was added.
* UI craft check: PASS - existing route-shell and status-card tests still pass.
  * Evidence: 89 Hermes section tests passed within the focused integration command.

### Task T019 - Run focused automated checks for all touched Hermes model-intelligence owners

**Started**: 2026-07-03 05:40 **Completed**: 2026-07-03 05:42 **Duration**: 2 minutes

**Notes**:

* Ran the exact focused Vitest command required by the task list.
* The command covered script-side owner tests, bridge tests, browser ranking/parser tests, Hermes parser tests, hook tests, and section tests.

**Files Changed**:

* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T019 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T019 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-model-intelligence.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-model-intelligence.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - focused model-intelligence Vitest command passed.
  * Evidence: 6 test files passed; 147/147 tests passed.
* UI product-surface check: PASS - focused section tests included the status-bar product summary.
  * Evidence: Hermes section test file passed as part of the focused command.
* UI craft check: PASS - focused section tests retained existing route-shell and status-card behavior.
  * Evidence: no layout-affecting test regression in the Hermes section suite.

### Task T020 - Run type, lint, and encoding gates and update implementation notes with validation evidence

**Started**: 2026-07-03 05:43 **Completed**: 2026-07-03 04:55 **Duration**: 12 minutes

**Notes**:

* Ran the required typecheck, script typecheck, and lint gates.
* Fixed a script test type mismatch by narrowing the model-intelligence fetch option to the callable fetch shape the module actually uses.
* Ran Prettier on touched TypeScript files after lint identified formatting-only issues, then reran the final gates successfully.
* Ran ASCII/LF checks over changed and untracked files; file output reported ASCII text/source, CRLF scan produced no matches, and corrected non-ASCII scan produced no matches.

**Files Changed**:

* `scripts/lib/hermes-model-intelligence.ts` - narrowed the injectable fetch option type and retained resolver behavior.
* Touched TypeScript files - formatted with Prettier where needed.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/implementation-notes.md` - recorded T020 evidence.
* `.spec_system/specs/phase40-session09-model-intelligence-and-pricing/tasks.md` - marked T020 and completion checklist complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck && bun run typecheck:scripts && bun run lint`
  * Result: PASS - app typecheck, script typecheck, and lint passed after formatting/type cleanup.
  * Evidence: final rerun completed with exit code 0.
* Command/check: `bunx prettier --write scripts/lib/hermes-model-intelligence.ts scripts/lib/hermes-dev-bridge.ts scripts/lib/__tests__/hermes-model-intelligence.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/hermes-model-intelligence.ts src/lib/hermes-types.ts src/lib/hermes-demo-data.ts src/lib/__tests__/hermes-model-intelligence.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/use-hermes.ts src/hooks/__tests__/use-hermes.test.tsx src/components/hermes/hermes-read-only-page.tsx src/components/hermes/hermes-status-bar.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - touched TypeScript files were formatted.
  * Evidence: Prettier completed successfully; several files were unchanged and formatted files were rewritten.
* Command/check: `files=$(printf '%s\n' $(git diff --name-only --diff-filter=ACMRTUXB) $(git ls-files --others --exclude-standard)); if [ -z "$files" ]; then printf 'no files\n'; exit 0; fi; printf '%s\n' "$files" | xargs file; printf '%s\n' "$files" | xargs grep -l $'\r' || true`
  * Result: PASS - changed and untracked files are ASCII text/source and no CRLF matches were printed.
  * Evidence: `file` reported ASCII text/source for changed and untracked files; CRLF scan produced no file output.
* Command/check: `files=$(printf '%s\n' $(git diff --name-only --diff-filter=ACMRTUXB) $(git ls-files --others --exclude-standard)); if [ -z "$files" ]; then printf 'no files\n'; exit 0; fi; printf '%s\n' "$files" | while IFS= read -r file; do LC_ALL=C grep -n '[^[:print:][:space:]]' "$file" && printf 'non-ascii-or-control: %s\n' "$file"; done`
  * Result: PASS - no non-ASCII/control-character matches were printed.
  * Evidence: corrected scan produced no output; the no-match grep status is expected.
* UI product-surface check: PASS - final lint/type gates retained the status-bar product summary without debug-only copy.
  * Evidence: final focused tests and lint passed after formatting.
* UI craft check: PASS - no new layout issues were introduced by final formatting/type cleanup.
  * Evidence: no component code behavior changed after the passing focused tests; only formatting and fetch option typing were adjusted.


---

# 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-session09-model-intelligence-and-pricing/implementation-notes.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.