> 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-session15-ministry-config-analytics-and-save-ux/spec.md). # Session Specification **Session ID**: `phase40-session15-ministry-config-analytics-and-save-ux` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 3af25ba69902c9208e493d415bb12d7d41f06b33 *** ## 1. Session Overview This session finishes the Ministry builder that Session 14 mounted in the Hermes Pantheon tab. The current builder can compose a draft council, but the config export, final analytics, and direct MoA save controls are still intentionally disabled. The next product slice is to turn that draft into a valid Hermes v0.17 MoA preset. The implementation should generate a strict save payload, produce copyable YAML with safe quoting for provider and model identifiers, show cost/speed/intelligence analytics with clear static-versus-live provenance, and save only through the existing local admin-gated MoA endpoint. This is the next executable Phase 40 session because the analyzer reports Sessions 06, 09, 11, and 14 complete. Those sessions provide the MoA save endpoint, model intelligence and pricing rows, model selector refresh path, and Ministry builder shell required by this work. *** ## 2. Objectives 1. Generate a valid Hermes v0.17 MoA request and YAML preview from the Ministry draft. 2. Complete Ministry analytics with stable cost, speed, benchmark, and provenance summaries. 3. Enable copy fallback and admin-gated direct save states in the Ministry save/copy shell. 4. Prove saved presets refresh model data so MoA presets can appear in the chat model selector after save. *** ## 3. Prerequisites ### Required Sessions * [x] `phase40-session06-moa-save-endpoint` - The admin-gated `/__hermes_moa_save` route, strict payload parser, safe errors, and hook action are available. * [x] `phase40-session09-model-intelligence-and-pricing` - Ministry model intelligence rows, pricing provenance, live-pricing overlay labels, and ranking helpers are available. * [x] `phase40-session11-chat-model-selector-and-context-meter` - The Hermes chat model selector consumes refreshed `/__hermes_models` mixtures. * [x] `phase40-session14-ministry-builder-and-pantheon` - The Pantheon Ministry builder, draft lineup, analytics shell, and disabled save/copy shell are available. ### Required Tools Or Knowledge * Existing `js-yaml` dependency for YAML generation. * Existing `UseHermesAdminResult.moa.savePreset` action in `src/hooks/use-hermes-admin.ts`. * Existing Hermes model and model-intelligence contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`. * Existing Ministry component cluster under `src/components/hermes/ministry/`. ### Environment Requirements * Repository dependencies installed with the pinned Bun version. * No live provider credentials are required for unit and component tests. * Live direct save remains disabled unless `HERMES_DASHBOARD_ADMIN=1` and the local per-run token are available. *** ## 4. Scope ### In Scope (MVP) * AI OS users can generate a Hermes v0.17 MoA preset from the Ministry draft - Build `reference_models`, `aggregator`, temperatures, `max_tokens`, and enabled state from selected rows. * AI OS users can copy YAML safely - Use `js-yaml` or a tested quoting helper so OpenRouter-style IDs containing `/`, `:`, quotes, and whitespace roundtrip. * AI OS users without writes still have a fallback - Keep copyable prompt/config available when admin writes are disabled, offline, token-gated, or demo-only. * AI OS users with local admin mode can save - Wire the shell to `admin.moa.savePreset` with duplicate-trigger prevention while in-flight. * The UI shows explicit save states - Cover setup-required, admin-disabled, demo-disabled, validation-failure, pending, safe success, and safe error copy. * Saved MoA presets refresh model data - Preserve or extend the existing model query invalidation so newly saved presets can appear in the chat selector. * Ministry analytics become useful - Show cost, speed, benchmark, seat coverage, role coverage, and intelligence summaries with stable sorting and static-versus-live provenance. ### Out Of Scope (Deferred) * Writing config without the explicit local admin gate - Reason: the Phase 40 control-plane boundary requires token, loopback, Host-header, and admin checks. * Claiming live benchmark data - Reason: Session 09 provides bundled benchmark rows and optional live pricing only. * Adding unrelated Pantheon persona changes - Reason: this session completes Ministry and should not change persona CRUD or sync behavior. * Browser persistence for Ministry drafts - Reason: current draft state is session-local and no persistent storage requirement exists. * Documentation updates - Reason: Session 17 documents shipped behavior after implementation and validation exist. *** ## 5. Technical Approach ### Architecture Add small pure Ministry helpers rather than embedding config and analytics rules inside JSX. `ministry-config.ts` should own conversion from `MinistryDraft` plus `HermesModelIntelligenceRow` data into a `HermesMoaSaveRequest`, validation results, copy prompt text, and YAML preview. `ministry-analytics.ts` should own stable sorted summaries and provenance labels for the component shell. Update `MinistryBuilder` and `MinistrySaveCopyShell` to receive the existing `UseHermesAdminResult` from `HermesPantheon`. The shell should use the current admin mutation view to render write readiness, disabled states, pending state, safe success copy, and parser/write failures without exposing paths or raw bridge diagnostics. Use the current `useHermesAdmin` MoA action for direct saves. That hook already invalidates `HERMES_QUERY_KEYS.models` on success, which is the query consumed by the chat model selector for MoA mixtures; add or strengthen tests around that refresh contract instead of introducing another fetch path in the Ministry component. ### Design Patterns * Pure config builder: keep MoA payload, YAML, and validation deterministic and unit-testable. * Existing admin mutation contract: route direct saves through `admin.moa.savePreset` only. * Product-facing state copy: render useful local operator states without raw endpoint names, private paths, auth JSON, or secret-shaped errors. * Stable sort helpers: sort analytics deterministically by score/cost/speed, fallback usage, display name, then ID. * Reopenable state handling: reset or revalidate save feedback when the draft changes, when copied content changes, or when a save completes. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/ministry/ministry-config.ts` | Build and validate MoA save payloads, YAML preview, and copy prompt text from Ministry drafts. | \~220 | | `src/components/hermes/ministry/ministry-analytics.ts` | Pure analytics summary, stable sorting, and provenance helpers for selected Ministry rows. | \~180 | | `src/components/hermes/ministry/__tests__/ministry-config.test.ts` | Unit tests for payload generation, validation failures, YAML quoting, and copy text. | \~220 | | `src/components/hermes/ministry/__tests__/ministry-analytics.test.ts` | Unit tests for cost, speed, benchmark, provenance, fallback, and stable sorting behavior. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/ministry/ministry-types.ts` | Add config, analytics, save/copy, and admin action prop types. | \~80 | | `src/components/hermes/ministry/ministry-analytics-shell.tsx` | Replace draft-only stats with completed analytics and live-vs-snapshot provenance labels. | \~140 | | `src/components/hermes/ministry/ministry-save-copy-shell.tsx` | Enable YAML/prompt copy, admin-gated save, disabled/demo/setup states, pending, success, and safe errors. | \~260 | | `src/components/hermes/ministry/ministry-builder.tsx` | Build config/analytics inputs from the draft, pass admin state, and reset feedback on draft changes. | \~120 | | `src/components/hermes/ministry/index.ts` | Export new config and analytics helpers as needed by tests. | \~20 | | `src/components/hermes/hermes-pantheon.tsx` | Pass the existing Hermes admin result into the Ministry builder without changing persona workflows. | \~20 | | `src/components/hermes/ministry/__tests__/ministry-builder.test.tsx` | Cover integrated save/copy shell states, validation failure, copy fallback, and product copy boundaries. | \~260 | | `src/hooks/__tests__/use-hermes-admin.test.tsx` | Prove successful MoA save invalidates the Hermes models query for selector refresh. | \~60 | | `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` | Keep or extend selector coverage proving refreshed mixtures render as MoA options. | \~70 | | `tests/e2e/hermes-agent.spec.ts` | Add a light Pantheon smoke for enabled Ministry controls and demo/read-only save boundaries. | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Generated MoA save payload uses `reference_models`, `aggregator`, `reference_temperature`, `aggregator_temperature`, `max_tokens`, and `enabled` in the Hermes v0.17 shape. * [ ] YAML preview roundtrips provider and model IDs containing `/`, `:`, quotes, and whitespace. * [ ] Missing core, missing references, duplicate rows, and unknown row IDs produce product-facing validation states without direct save attempts. * [ ] Copy remains available when admin writes are disabled, token-gated, offline, or demo-disabled. * [ ] Direct save is available only when live local admin mode and token are ready. * [ ] Save clicks are disabled or ignored while a save is in flight. * [ ] Successful save shows safe success copy and preserves no raw config path. * [ ] Failed save shows safe recovery copy and no raw local path, auth JSON, or secret-shaped string. * [ ] Successful save refreshes Hermes model data so MoA mixtures can appear in the chat model selector. * [ ] Analytics distinguish bundled snapshot pricing from live OpenRouter pricing without claiming live benchmark data. ### Testing Requirements * [ ] Unit tests written and passing for MoA config generation and YAML quoting. * [ ] Unit tests written and passing for Ministry analytics sorting and provenance helpers. * [ ] Component tests written and passing for save/copy states and safe UI copy. * [ ] Hook or selector test proves model refresh after save. * [ ] E2E smoke updated for Pantheon Ministry save/copy controls. ### Non-Functional Requirements * [ ] Browser-visible output contains only safe labels, redacted errors, and product-facing recovery copy. * [ ] No provider keys, bearer tokens, auth JSON paths, raw local paths, or generated private data are introduced. * [ ] UI controls keep stable dimensions and no text overlap on mobile and desktop. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * `js-yaml` is the preferred YAML generator: `package.json` already includes `js-yaml` and `@types/js-yaml`, Session 15 explicitly calls for `js-yaml` or a tested quoting helper, and using the existing dependency avoids package metadata churn. * The Ministry save name can default to `ministry`: Session 06 and existing hook tests already use a `ministry` MoA preset, Session 15 does not request a naming form, and this keeps the MVP focused on generating a valid preset. * Model selector refresh is owned by the existing hook invalidation: `useHermesAdmin` invalidates `HERMES_QUERY_KEYS.models` after MoA save, and the chat selector derives MoA options from refreshed `models.mixtures`. ### Conflict Resolutions * Session 15 says "direct save" while Phase 40 control-plane rules forbid ungated writes. The chosen interpretation is admin-gated direct save through `/__hermes_moa_save` only, because Session 06 created that endpoint and the phase requires loopback, Host-header, token, admin, schema, timeout, and safe-error gates. ### Key Considerations * The visible UI must not expose raw endpoint internals, local config paths, or bridge diagnostics. * Demo/public mode must stay read-only and must not imply live pricing. * Existing Pantheon persona create/edit/delete/install/sync flows should remain unchanged. ### Potential Challenges * YAML generation in browser code: use the existing `js-yaml` dependency and keep a pure helper test suite that parses its own output. * Admin save failure states: map mutation states to bounded product copy rather than displaying raw thrown errors. * Analytics labels: use `pricingProvenance` and row-level pricing sources so live pricing and bundled snapshot pricing are visible without overclaiming. ### Relevant Considerations * \[P38] **Local control-plane gates are defense in depth**: Preserve loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error expectations for the MoA save path. * \[P38] **Upstream ports are semantic, not wholesale**: Translate the Ministry save and analytics behavior into current AI OS component and hook owners. * \[P21] **Claude OAuth material stays script-only**: Keep auth-shaped material out of browser state, logs, docs, and generated data. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Save and copy controls are state-mutating actions and must prevent duplicate triggers while in-flight. * Admin save touches a local write boundary and must rely on existing authorization, schema validation, and safe-error mapping. * The Ministry section is a user-facing dashboard surface and must keep loading, empty, error, offline, demo, and success states product-facing. *** ## 9. Testing Strategy ### Unit Tests * Test `buildMinistryMoaConfig`, validation failures, YAML dump/parse roundtrip, and copy prompt content in `src/components/hermes/ministry/__tests__/ministry-config.test.ts`. * Test analytics rollups, role coverage, fallback metrics, live-vs-snapshot pricing labels, and stable sorting in `src/components/hermes/ministry/__tests__/ministry-analytics.test.ts`. ### Integration Tests * Extend `ministry-builder.test.tsx` for admin-disabled, demo-disabled, missing-config, validation-failure, copy success/fallback, save pending, save success, and safe error states. * Extend `use-hermes-admin.test.tsx` to assert the models query is invalidated after a successful MoA save. * Keep or extend chat selector tests for MoA mixture options after model data changes. ### Runtime Verification * Run focused Vitest suites for Ministry, Hermes admin hook, and chat selector. * Run `bun run typecheck`. * Run the Hermes Pantheon E2E smoke when browser dependencies are available. ### Edge Cases * Provider/model IDs with `/`, `:`, quotes, leading/trailing whitespace, and embedded spaces. * Empty draft, missing core, no references, unknown row IDs, and duplicate rows. * Offline browser, missing local token, admin disabled, demo mode, pending save, parser failure, and route safe-error response. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase40-session06-moa-save-endpoint`, `phase40-session09-model-intelligence-and-pricing`, `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session14-ministry-builder-and-pantheon` * Depended by: `phase40-session17-docs-metadata-and-gitignore-closeout`, `phase40-session18-full-validation-and-handoff` *** ## 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-session15-ministry-config-analytics-and-save-ux/spec.md?ask=&goal= ``` `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.