> 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-session14-ministry-builder-and-pantheon/spec.md). # Session Specification **Session ID**: `phase40-session14-ministry-builder-and-pantheon` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 5ae3af6a28fcde03999183b43ed1644fe7d0dac5 *** ## 1. Session Overview This session adds the Ministry builder to the existing Hermes Pantheon tab. It gives AI OS users a product-facing MoA composition surface with model cards, council seats, provider logos, a visual hero, analytics and save/copy shells, and keyboard-friendly seat assignment without changing the current persona CRUD and sync flows. This is the next executable Phase 40 session because the analyzer reports sessions 1 through 13 complete and session 15 depends on the builder created here. Sessions 09 and 10 already provide browser-safe Ministry model intelligence rows, pricing provenance, provider logo lookup, and the optimized Ministry hero asset. The work stays inside the existing AI OS Hermes component boundaries. The builder consumes current browser-safe data only, keeps draft lineup state in the UI, and defers valid MoA config generation, final analytics, and direct admin save behavior to Session 15. *** ## 2. Objectives 1. Create Ministry UI components under `src/components/hermes/ministry/` for the builder card, model palette, council seats, analytics shell, save/copy shell, and provider logo rendering. 2. Integrate the Ministry builder into the Pantheon tab as the first product section without nesting decorative cards or regressing persona workflows. 3. Implement pointer, click, and keyboard-friendly seat assignment with duplicate prevention, max expert enforcement, removal, Escape cancel, and recommended reset behavior. 4. Add focused tests for builder interactions, provider logo usage, existing Pantheon persona workflows, and mobile route stability. *** ## 3. Prerequisites ### Required Sessions * [x] `phase40-session09-model-intelligence-and-pricing` - Browser-safe Ministry model intelligence rows, ranking helpers, pricing provenance, demo fixtures, and hook plumbing are available. * [x] `phase40-session10-assets-and-media-compliance` - Hermes provider logos and the optimized `src/assets/ministry-hero.webp` metadata are available through browser-safe helpers. * [x] `phase40-session11-chat-model-selector-and-context-meter` - MoA presets and model catalog metadata are already represented in Hermes model data. * [x] `phase40-session13-command-ux-and-slash-actions` - Current Pantheon and route tests are complete before this UI integration begins. ### Required Tools Or Knowledge * Existing Hermes Pantheon owner in `src/components/hermes/hermes-pantheon.tsx`. * Model intelligence and ranking contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-model-intelligence.ts`. * Provider asset helpers in `src/lib/hermes-provider-assets.ts`. * React 19 component state, pointer events, keyboard events, and Testing Library interaction patterns. ### Environment Requirements * Repository dependencies installed with the pinned Bun version. * No live provider credentials are required for component tests. * Demo/public mode must remain fixture-safe and read-only. *** ## 4. Scope ### In Scope (MVP) * AI OS users can see a Ministry builder inside Pantheon - Add the builder as the first full-width Pantheon section before existing persona catalog content. * AI OS users can inspect Ministry lineup candidates - Render model intelligence rows with model labels, role labels, safe pricing/metric provenance, and approved provider logo assets where available. * AI OS users can compose a council lineup - Support drag to seat, click model then click seat, remove seat, Escape to cancel armed model, and reset to recommended lineup. * AI OS users cannot create invalid draft lineups - Enforce one core seat, bounded expert seats, no duplicate model in core/expert seats, and clear disabled states when max experts are filled. * AI OS users can preview Ministry shells without save claims - Render analytics and save/copy shells with product-facing current-state copy while direct MoA config generation and direct save stay deferred. * Existing Pantheon persona workflows remain intact - Preserve create, edit, delete, install defaults, validation, template seeding, model selection, and GitHub mirror sync behavior. * Browser-facing UI remains safe - Use `HERMES_MINISTRY_HERO_ASSET` and `getHermesProviderAsset` instead of path guessing or raw asset metadata. ### Out Of Scope (Deferred) * Generating final Hermes v0.17 MoA YAML or save payloads - Reason: Session 15 owns valid config generation and YAML quoting. * Direct save to the MoA endpoint - Reason: Session 15 owns admin-gated save UX and model refresh after save. * Final cost, speed, and intelligence analytics behavior - Reason: Session 15 owns analytics completion and static-versus-live provenance sorting. * Changing existing Pantheon persona storage, validation, sync, or default install contracts - Reason: this session adds Ministry alongside existing workflows. * Documentation updates - Reason: Session 17 documents shipped Ministry behavior after implementation and tests exist. *** ## 5. Technical Approach ### Architecture Create a small Ministry component cluster under `src/components/hermes/ministry/`. Keep durable state out of storage for this session: `ministry-lineup.ts` should own pure helpers for recommended lineup derivation, core/expert seat changes, duplicate checks, max expert checks, and reset behavior, while React components own the active drag/armed model state. Extend `HermesPantheon` to accept `modelIntelligence: HermesQueryView` and pass that view from `HermesReadOnlyPage`, which already resolves demo and live model-intelligence data. The builder should render explicit loading, empty, error, offline, token-failure, and demo-safe states using product copy and the existing Hermes panel primitives. Use `getHermesProviderAsset` and `HERMES_MINISTRY_HERO_ASSET` for vendor logo and hero rendering. Provider logos should be optional: uncovered providers render stable label fallback states instead of broken images or duplicated paths. The UI should avoid nested decorative card structures by using a full-width Ministry section with internal controls, not a card wrapped inside another card. ### Design Patterns * Pure lineup helpers: keep seat rules testable without React DOM coupling. * Existing query-view contract: consume `HermesQueryView` instead of re-fetching or parsing inside components. * Browser-safe asset registry: use Session 10 helpers for provider logos and hero metadata. * Reopenable context reset: reset armed/drag state when the model-intelligence body changes, when the Pantheon tab remounts, and after recommended reset. * Product-only copy: keep diagnostics, source paths, and debug wording out of the visible builder. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/ministry/ministry-types.ts` | Shared Ministry seat, draft, and component prop types derived from Hermes model intelligence rows. | \~90 | | `src/components/hermes/ministry/ministry-lineup.ts` | Pure recommended lineup, seat assignment, duplicate prevention, max expert, removal, and reset helpers. | \~220 | | `src/components/hermes/ministry/provider-logo.tsx` | Safe provider logo renderer with text fallback and accessible labels. | \~90 | | `src/components/hermes/ministry/model-palette.tsx` | Model palette rows/cards with drag handles, click select state, metrics, and safe provider assets. | \~220 | | `src/components/hermes/ministry/council-seats.tsx` | Core/expert seat targets with drag/drop, click assignment, remove controls, focus handling, and empty states. | \~260 | | `src/components/hermes/ministry/ministry-analytics-shell.tsx` | Current-state analytics shell using bundled model metrics without final Session 15 claims. | \~150 | | `src/components/hermes/ministry/ministry-save-copy-shell.tsx` | Deferred save/copy shell that previews current lineup state without direct save wiring. | \~140 | | `src/components/hermes/ministry/ministry-builder.tsx` | Full builder section that composes hero, palette, seats, analytics shell, save/copy shell, and query states. | \~320 | | `src/components/hermes/ministry/index.ts` | Minimal Ministry component exports. | \~20 | | `src/components/hermes/ministry/__tests__/ministry-lineup.test.ts` | Unit tests for pure lineup and seat rule helpers. | \~190 | | `src/components/hermes/ministry/__tests__/ministry-builder.test.tsx` | Component interaction tests for open/close, click, keyboard, drag-style events, duplicate prevention, reset, and safe assets. | \~300 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-pantheon.tsx` | Add Ministry builder props and render the builder before existing persona catalog content while preserving current persona state. | \~80 | | `src/components/hermes/hermes-read-only-page.tsx` | Pass live/demo model-intelligence view into `HermesPantheon`. | \~10 | | `src/components/hermes/__tests__/hermes-sections.test.tsx` | Update Pantheon fixtures and add regression coverage for Ministry plus existing persona workflows. | \~180 | | `tests/e2e/hermes-agent.spec.ts` | Add Pantheon route smoke coverage for Ministry visibility and mobile layout stability. | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Pantheon renders a Ministry builder section before the existing persona catalog and sync workflows. * [ ] Ministry model palette renders all available model-intelligence rows with safe provider logos or stable label fallbacks. * [ ] Recommended reset restores a valid lineup based on the available Ministry rows. * [ ] Drag-to-seat assignment works for core and expert seats. * [ ] Click model then click seat assignment works for core and expert seats. * [ ] Escape cancels an armed model without changing existing seats. * [ ] Seat remove controls clear the target seat and return the model to assignable state. * [ ] Duplicate core/expert assignment is prevented with clear disabled state. * [ ] Max expert count is enforced with clear disabled state. * [ ] Existing persona create, edit, delete, install defaults, validate, model selection, template seeding, and sync behaviors still work. * [ ] The builder handles loading, empty, error, offline, token-failure, live, and demo states with product-facing copy. ### Testing Requirements * [ ] Pure lineup helper tests cover recommended lineup, core assignment, expert assignment, duplicate prevention, max expert enforcement, removal, reset, and stable ordering. * [ ] Component tests cover click assignment, Escape cancel, remove, reset, drag/drop event paths, loading/error states, logo fallback, and hero alt text. * [ ] Pantheon regression tests cover existing persona workflows after Ministry is present. * [ ] E2E route smoke covers Pantheon tab Ministry visibility on desktop and mobile viewports. ### Non-Functional Requirements * [ ] Ministry layout remains usable on mobile and desktop without text overlap or layout-shifting controls. * [ ] Interactive controls include accessible labels, focus management, keyboard support, and input support. * [ ] Browser-facing UI exposes only safe labels, safe asset metadata, bounded model metrics, and product-facing copy. * [ ] No generated private data, raw home paths, auth JSON paths, API keys, tokens, account IDs, raw prompts, transcripts, or raw bridge diagnostics are introduced. * [ ] No decorative card is nested inside another decorative card. ### 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 * The recommended lineup can derive from current model-intelligence rows and the existing MoA preset metadata: `HERMES_DEMO_MODELS.mixtures` names `claude-opus-4.8` as the aggregator, the bundled rows contain four Ministry candidates, and Session 14 can proceed without persistence because Session 15 owns final config and save. * Ministry draft state should stay browser-local in Session 14: the session stub explicitly excludes direct MoA save wiring, while Session 15 depends on this builder before adding config generation and admin save behavior. * `HermesPantheon` should receive model intelligence as a prop rather than fetching it: `HermesReadOnlyPage` already resolves demo/live model intelligence and this keeps data ownership aligned with other Pantheon inputs. ### Conflict Resolutions * Phase 40 objective 5 groups Ministry integration, valid MoA config, analytics, and save UX together, while the session stubs split builder work into Session 14 and config/save/analytics completion into Session 15. The selected interpretation follows the executable session stubs: Session 14 builds composition and shells; Session 15 implements final config, analytics, and save. * Session 14 prerequisites allow temporary fallback media if Session 10 assets were not validated, but Session 10 is complete and exposes `HERMES_MINISTRY_HERO_ASSET` plus provider asset helpers. This plan uses the validated assets and does not introduce temporary fallback media. ### Key Considerations * Keep Ministry inside the Pantheon tab and do not move persona CRUD ownership to new files. * Keep direct MoA writes out of the browser UI until Session 15 wires the existing admin-gated endpoint. * Treat model metrics and pricing as bounded product context, not live benchmark claims. * Use provider logo fallbacks for uncovered providers, especially OpenRouter and local-style providers. * Preserve demo/public behavior by using bundled fixtures and avoiding new local bridge calls. ### Potential Challenges * Pointer and keyboard assignment can diverge if they use separate state paths: route both through the pure lineup helper operations. * Drag/drop events can be brittle in tests: keep click assignment as a first-class accessible path and test drag/drop at the component event boundary. * Adding a large section above personas can crowd mobile Pantheon: use stable responsive grids, minimum control dimensions, and compact text. * Provider logo assets may not cover every row: render label fallback states instead of guessing asset paths. ### Relevant Considerations * \[P38] **Upstream ports are semantic, not wholesale**: Translate Ministry into existing AI OS Hermes owners instead of copying upstream route or middleware files. * \[P38] **Local control-plane gates are defense in depth**: Do not add new write paths or bridge calls in this UI-only builder session. * \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Keep visible builder state limited to safe model labels, roles, metrics, and asset metadata. * \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Demo/public mode must stay fixture-only and static-safe. * \[P00] **Stack conventions**: Stay within Bun, Vite 8, TanStack Start, React 19, Radix UI, Tailwind CSS 4, and existing local component conventions. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A model could be assigned twice across core and expert seats if click and drag paths do not share duplicate checks. * Rapid pointer, keyboard, or reset interactions could leave armed/drag state stale after lineup changes. * A new Ministry section could regress existing persona write controls or mobile Pantheon layout. *** ## 9. Testing Strategy ### Unit Tests * Add `src/components/hermes/ministry/__tests__/ministry-lineup.test.ts` for recommended lineup derivation, stable ordering, core assignment, expert assignment, duplicate prevention, max expert enforcement, removal, reset, and unavailable-row handling. ### Integration Tests * Add `src/components/hermes/ministry/__tests__/ministry-builder.test.tsx` for rendering, query states, click-to-seat, Escape cancel, remove, reset, drag/drop event paths, logo fallback, hero alt text, and product copy boundaries. * Extend `src/components/hermes/__tests__/hermes-sections.test.tsx` for Pantheon integration and existing persona workflow regressions after Ministry is rendered. ### Runtime Verification * Extend `tests/e2e/hermes-agent.spec.ts` to smoke the Pantheon tab with Ministry on desktop and mobile viewports. * Run focused Vitest coverage for Ministry helpers, Ministry builder, Hermes sections, model intelligence helpers, provider assets, and admin hook regressions. * Run typecheck and ASCII/LF validation for new spec and source files. ### Edge Cases * Empty model-intelligence lineup. * Missing provider logo for a valid provider row. * Duplicate assignment from click and drag paths. * Escape after arming a model but before selecting a seat. * Reset after manual removals and duplicate attempts. * Demo mode with fixture rows and write-gated Pantheon controls. * Mobile viewport with long model names such as `deepseek/deepseek-v4-pro`. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase40-session09-model-intelligence-and-pricing`, `phase40-session10-assets-and-media-compliance`, `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session13-command-ux-and-slash-actions` * Depended by: `phase40-session15-ministry-config-analytics-and-save-ux`, `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-session14-ministry-builder-and-pantheon/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.