> 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/phase17-session03-pantheon-upgrade-write/spec.md).

# Session Specification

**Session ID**: `phase17-session03-pantheon-upgrade-write` **Phase**: 17 - Hermes Shell And Core Writes **Status**: Not Started **Created**: 2026-06-02

***

## 1. Session Overview

This session upgrades the Hermes Pantheon tab from a read-only persona card grid into the v2.3 parity surface for persona templates, rich catalog management, edit flows, and the high-risk GitHub sync write. Phase 16 already landed the local bridge endpoints, typed parsers, demo data, hook query for templates, admin mutations for persona writes, and the Pantheon sync mutation. This session consumes those contracts in the user-facing Pantheon surface instead of duplicating bridge or hook behavior.

The implementation keeps Hermes local-agent data separate from Trend Finder extension data and preserves the loopback, token, and admin-mode guardrails. The sync flow must make the existing GitHub auth model explicit before enabling the action: the current bridge executes git through args-array commands in the local environment, so the UI must require confirmation, show admin gating, and surface failure states without exposing command output or private paths.

The session completes Phase 17's remaining feature work. After this plan, the next workflow step is `implement`; validation and PRD updates happen only after implementation is complete.

***

## 2. Objectives

1. Render a richer Pantheon catalog with persona metadata, model/tone/file badges, template affordances, and resilient empty/error/offline/token states.
2. Move persona create/edit/delete/install/validate controls into the Pantheon workflow using the existing `useHermesAdmin().personas` contract.
3. Add the GitHub sync panel with explicit confirmation, duplicate-trigger prevention, admin-gated disabled states, and clear pending/success/error feedback.
4. Extend focused component and hook coverage for mode matrix behavior, template reads, persona write affordances, and sync confirmation.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the Hermes v2.3 guardrail baseline and write-safety contract.
* [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides Pantheon templates and sync endpoints with loopback/token/admin protections.
* [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed hook contracts and demo fixtures for templates and sync.
* [x] `phase17-session01-visual-system-shell-status-pill` - Provides the cinematic shell and Hermes primitives used by this surface.
* [x] `phase17-session02-chat-tab-write` - Establishes current admin write UI patterns and chat tab wiring.

### Required Tools/Knowledge

* React 19, TanStack Query, TanStack Router, Tailwind CSS 4, Radix UI wrappers, and lucide-react.
* Existing Hermes contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`.
* Existing hooks in `src/hooks/use-hermes.ts` and `src/hooks/use-hermes-admin.ts`.
* Existing component patterns in `src/components/hermes/hermes-page-primitives.tsx` and `src/components/hermes/chat/`.

### Environment Requirements

* Bun 1.3.14 project environment.
* Local dev bridge behavior remains dev-only and loopback/admin gated.
* No live Hermes or GitHub credentials are required for automated tests; tests should use fixtures/mocks.

***

## 4. Scope

### In Scope (MVP)

* User can inspect Pantheon personas in a richer catalog - implement in `src/components/hermes/hermes-pantheon.tsx` with metadata, fallbacks, bounded text, and mode states.
* User can start from templates - read `hermes.pantheonTemplates`, show template tiles, and seed persona YAML drafts.
* User can create, edit, delete, install, and validate personas - use `admin.personas` actions with admin disabled hints, duplicate-trigger prevention, and state reset on selection/reopen.
* User can run Pantheon GitHub sync - use `admin.pantheonSync.syncMirror` with a typed confirmation step, optional mirror-root input, pending/success/error copy, and no command output exposure.
* Maintainer can verify behavior - update component/hook tests and run focused checks for the Pantheon surface and existing sync mutation.

### Out of Scope (Deferred)

* Memory, Mission Control, Documents, Mnemosyne, Connections, and non-Hermes v2.3 surfaces - Reason: owned by later phases.
* Rewriting bridge endpoint security or git execution internals - Reason: Phase 16 already implemented and tested those endpoints.
* Adding a managed scoped GitHub token flow - Reason: the current bridge contract uses the local git environment; a token-management feature would require a separate threat model.
* Broad visual redesign outside the Pantheon tab - Reason: Phase 17 Session 01 already established the shell and primitives.

***

## 5. Technical Approach

### Architecture

Keep the implementation centered on `src/components/hermes/hermes-pantheon.tsx`, with `HermesReadOnlyPage` passing the already-available `hermes.pantheonTemplates`, `models`, and `admin` objects into the Pantheon tab. The component should remain controlled by hook-provided `HermesQueryView` and `UseHermesAdminResult` contracts, avoiding new data fetching or bridge calls inside the view layer.

Persona edits should use local component state for selected persona, selected template, YAML draft, optional model choice, confirmation state, and sync mirror-root input. Mutating actions must call the existing admin methods and disable repeated triggers while the corresponding mutation is pending. Reopenable contexts must reset or revalidate state when the user changes selected persona/template or closes the edit surface.

### Design Patterns

* Contract-first UI: consume existing hook/parser types instead of ad hoc endpoint calls.
* Local guarded writes: disable actions when demo mode, admin mode, token, or offline state prevents writes.
* Explicit confirmation: require a user confirmation state before GitHub sync can run.
* Exhaustive states: preserve loading, empty, error, offline, token-failure, success, and demo render paths.
* Fixture-first tests: mock hooks/actions in component tests and avoid live local Hermes or GitHub dependencies.

### Technology Stack

* React 19 with TypeScript.
* TanStack Query through existing Hermes hooks.
* Tailwind CSS 4 and existing Hermes primitives.
* Radix UI wrappers from `src/components/ui/`.
* Vitest and Testing Library for focused component/hook coverage.

***

## 6. Deliverables

### Files to Create

No new source files are expected for MVP scope.

### Files to Modify

| File                                                                                  | Changes                                                                                            | Est. Lines |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-pantheon.tsx`                                           | Rich catalog, templates, edit/write controls, GitHub sync panel, mode states, accessibility labels | \~350      |
| `src/components/hermes/hermes-read-only-page.tsx`                                     | Pass templates, models, and admin contracts into Pantheon                                          | \~20       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx`                            | Add Pantheon catalog, template, write gating, sync, and mode coverage                              | \~180      |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`                                       | Add or confirm sync confirmation/duplicate-trigger coverage if missing                             | \~40       |
| `.spec_system/specs/phase17-session03-pantheon-upgrade-write/implementation-notes.md` | Capture GitHub auth decision, tests run, and implementation notes                                  | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Pantheon renders persona catalog metadata with bounded fallbacks and no layout breakage for missing provider/model/tone/file fields.
* [ ] Pantheon templates render from `hermes.pantheonTemplates` and seed persona YAML drafts.
* [ ] Persona validate/create/update/delete/install actions use existing admin methods and disable while pending.
* [ ] GitHub sync requires confirmation, is admin-gated, disables while pending, and renders success/error states without raw command output.
* [ ] Demo, live, setup-required, offline, endpoint-error, token-failure, empty, and loading states remain explicit.

### Testing Requirements

* [ ] Component tests cover rich catalog, template selection, write disabled states, mutation calls, sync confirmation, and error/success rendering.
* [ ] Hook/admin tests cover sync confirmation payload and duplicate-trigger prevention when not already covered.
* [ ] Focused tests pass for Hermes components and admin hooks.
* [ ] Typecheck and lint pass or any unrelated pre-existing failures are documented.

### Non-Functional Requirements

* [ ] Local bridge writes remain loopback, token, and admin gated.
* [ ] UI does not expose raw command output, credentials, private path fragments beyond existing sanitized labels, or repo diffs.
* [ ] Interactions are keyboard-accessible and have labels for buttons, inputs, dialogs, and destructive/sync actions.
* [ ] Text remains bounded and scannable on mobile and desktop.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new global `findtrend` identifiers.
* [ ] No generated private data or credentials committed.

***

## 8. Implementation Notes

### Key Considerations

* The low-level template query and Pantheon sync mutation already exist; this session should wire UI to them rather than reimplementing endpoint clients.
* `HermesAdminPanel` currently contains persona controls. The Pantheon tab can become the primary persona workflow, while any admin-panel copy/duplication should be handled conservatively.
* GitHub sync is the highest-risk write path because it touches the network and executes git. The UI must show clear confirmation and error states while relying on the existing bridge security tests for args-array git behavior.

### Potential Challenges

* Duplicating persona controls across Admin and Pantheon: Keep shared contracts consistent and avoid changing bridge behavior.
* YAML draft correctness: Generate drafts from existing template/persona fields, validate through `admin.personas.validateYaml`, and keep user edits local until submitted.
* Sync auth ambiguity: Document the implementation-time decision in `implementation-notes.md`; keep sync action visibly admin gated and failure-tolerant.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: Every write remains behind loopback, token, and explicit admin mode; the UI disables write affordances without those conditions.
* \[P01] **Bundle budget watch on 3D vendor chunks**: This session should not add new heavy dependencies or media assets.
* \[P09] **Legacy alias migration is still additive**: Preserve existing `X-Claude-OS-Token` and related compatibility contracts.
* \[P03] **Read-only first**: The existing read contracts stay usable even when admin writes are unavailable.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* State-mutating persona and sync actions can be double-triggered if buttons are not disabled while pending.
* Reopenable edit/template contexts can leak stale YAML or validation state between personas.
* Sync failures can expose too much local command/path detail unless error rendering stays bounded.
* Offline, token-failure, and admin-disabled states can appear as broken UI if not handled explicitly.

***

## 9. Testing Strategy

### Unit Tests

* Extend `src/components/hermes/__tests__/hermes-sections.test.tsx` with Pantheon rendering, templates, edit actions, disabled states, and sync state assertions.
* Extend `src/hooks/__tests__/use-hermes-admin.test.tsx` only if current coverage misses sync confirmation payloads or duplicate-trigger prevention.

### Integration Tests

* Run focused Vitest coverage for Hermes section components, `useHermes`, `useHermesAdmin`, Hermes admin types, and existing bridge sync tests.
* Use existing mocked fetch and mocked admin actions; do not require live Hermes or GitHub.

### Manual Testing

* Visit `/agents/hermes`, open the Pantheon tab in demo mode and live/setup-required modes.
* Verify admin-disabled, token-missing, offline, pending, success, error, empty, and loaded states.
* Verify keyboard focus and labels for template selection, edit controls, destructive delete, and sync confirmation.

### Edge Cases

* Empty persona list with non-empty templates.
* Missing model provider/name/tone/file fields.
* Template list endpoint empty or failed while persona catalog succeeds.
* Admin gate disabled or token missing after read data loaded.
* Sync pending, sync error, and sync success with zero files synced.

***

## 10. Dependencies

### External Libraries

* No new external libraries expected.

### Internal Dependencies

* `src/hooks/use-hermes.ts` for `pantheon`, `pantheonTemplates`, and `models` views.
* `src/hooks/use-hermes-admin.ts` for persona mutations and `pantheonSync`.
* `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts` for parser-backed contracts.
* `src/components/hermes/hermes-page-primitives.tsx` for visual/status primitives.

### Other Sessions

* Depends on: `phase16-session01-guardrails-architecture-parity-baseline`, `phase16-session02-backend-endpoint-parity-write-safety`, `phase16-session03-data-layer-demo-fixtures`, `phase17-session01-visual-system-shell-status-pill`, `phase17-session02-chat-tab-write`.
* Depended by: Phase 18 Hermes Memory And Visualization, Phase 19 Hermes Orchestration And Documents, Phase 20 Hermes Long-Tail And Parity Sign-off.

***

## Next Steps

Run the `implement` workflow step to begin AI-led 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/phase17-session03-pantheon-upgrade-write/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.