> 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-session01-visual-system-shell-status-pill/spec.md).

# Session Specification

**Session ID**: `phase17-session01-visual-system-shell-status-pill` **Phase**: 17 - Hermes Shell And Core Writes **Status**: Complete **Created**: 2026-06-02

***

## 1. Session Overview

This session ports the v2.3 Hermes cinematic shell into the existing AI OS Hermes surface and makes the global Hermes status pill part of the application top bar. It is the first Phase 17 session because the later Chat and Pantheon write sessions depend on the refreshed page shell, shared visual vocabulary, and status affordances.

The implementation stays focused on read-only visual and status behavior. It extends the current modular Hermes page instead of importing the V23 monolith, uses the already-copied banner asset, preserves the existing top-level tab IA decision from Phase 16, and keeps all bridge interaction on the existing `/__hermes_status` read endpoint.

The session also resolves the current status pill placement mismatch: the real implementation should live with the Hermes components under `src/components/hermes/`, while the current top-level pill path can remain as a compatibility export if needed by existing imports.

***

## 2. Objectives

1. Extend Hermes page primitives and route skin with v2.3 visual tokens, typography hooks, 0px border treatment, amber halo, banner crop, and the bar glyph language.
2. Rework the Hermes read-only page hero into the cinematic shell while keeping demo, setup-required, loading, offline, and endpoint-error states explicit.
3. Upgrade the status-card row treatment for version, model, memory, and activity summaries without adding new write behavior.
4. Add a colocated global Hermes status pill that polls `/__hermes_status`, renders nothing when Hermes is not installed, and is mounted in the app top bar.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the architecture and IA decision to keep the Hermes tabs shell and add future surfaces as top-level tabs.
* [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides the expanded Hermes endpoint foundation, including `/__hermes_status`.
* [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed hooks, demo fixtures, and Phase 16 closeout validation.

### Required Tools/Knowledge

* V23 source anchors in `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx` for theme tokens, shell states, banner, and status cards.
* V23 status pill source at `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-status-pill.tsx`.
* Existing React Query, TanStack Router, Tailwind CSS 4, and Vitest component test patterns.

### Environment Requirements

* Bun 1.3.14 runtime from `.bun-version`.
* Existing AI OS dev server and local bridge behavior; real Hermes installation is not required because tests can mock `/__hermes_status`.
* Banner asset already present at `src/assets/hermes-art/00-banner-wide.png`.

***

## 4. Scope

### In Scope (MVP)

* The operator can view a cinematic Hermes shell using v2.3 visual tokens, display/mono typography hooks, amber halo, 0px border styling, and the existing banner asset - implemented through scoped Hermes primitives and route CSS.
* The operator can still understand demo, setup-required, loading, offline, and endpoint-error states - preserved through existing mode handling and upgraded support components.
* The operator can see version, model, memory, and activity status summaries in a v2.3-inspired status-card row - implemented without adding new endpoints or write paths.
* The operator can use a global Hermes top-bar status pill that links to `/agents/hermes`, polls `/__hermes_status`, handles offline/error states quietly, and renders nothing when Hermes is absent.

### Out of Scope (Deferred)

* Chat tab, image upload, and chat send writes - *Reason: owned by Phase 17 Session 02.*
* Pantheon template UI and GitHub sync write - *Reason: owned by Phase 17 Session 03 and still carries the GitHub sync auth question.*
* Memory edit, Obsidian write, Mnemosyne, Mission Control, Documents Gallery, Connections, and long-tail parity surfaces - *Reason: owned by later phases.*
* New server endpoints, bridge write behavior, or admin-gated mutations - *Reason: this session is read-only UI/status work.*

***

## 5. Technical Approach

### Architecture

Keep the existing modular AI OS Hermes route as the target architecture. Shared visual tokens and small UI primitives stay in `src/components/hermes/hermes-page-primitives.tsx`, scoped route skin remains in `src/styles.css` under `.hermes-agent-route`, and page composition remains in `src/components/hermes/hermes-read-only-page.tsx`.

The status pill becomes a Hermes-owned component at `src/components/hermes/hermes-status-pill.tsx`. The existing `src/components/hermes-status-pill.tsx` path should become a thin re-export or be otherwise reconciled so there is only one real implementation. The root top bar should import the colocated component and preserve existing top-bar overflow and focus behavior.

### Design Patterns

* Scoped route skin: Keeps Hermes-specific tokens from leaking into Trend Finder, OpenClaw, or host cockpit pages.
* Read-only bridge query: Uses React Query with abort signals, no retries, a bounded polling interval, and explicit hidden-on-missing behavior.
* Compatibility wrapper: Keeps the current top-level status pill path stable while moving implementation ownership under `src/components/hermes/`.
* State-first rendering: Preserves loading, setup-required, demo, offline, endpoint-error, and empty states before visual polish.

### Technology Stack

* React 19 with TypeScript.
* TanStack Router for the `/agents/hermes` link and root route composition.
* TanStack Query 5 for `/__hermes_status` polling.
* Tailwind CSS 4 and scoped CSS custom properties in `src/styles.css`.
* Vitest 4 with happy-dom and Testing Library for component tests.

***

## 6. Deliverables

### Files to Create

| File                                                          | Purpose                                                                         | Est. Lines |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-status-pill.tsx`                | Colocated global status pill implementation polling `/__hermes_status`          | \~120      |
| `src/components/hermes/__tests__/hermes-status-pill.test.tsx` | Ready, setup, missing, offline, and error behavior coverage for the status pill | \~140      |

### Files to Modify

| File                                                       | Changes                                                                                            | Est. Lines |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-page-primitives.tsx`         | Add visual tokens, typography helpers, card/shell helpers, and state-safe primitives               | \~80       |
| `src/styles.css`                                           | Add scoped Hermes cinematic skin, banner/card styling, reduced-motion guards, and typography hooks | \~160      |
| `src/components/hermes/hermes-read-only-page.tsx`          | Rework hero/page shell, banner, demo CTA/banner, loading state, and layout spacing                 | \~160      |
| `src/components/hermes/hermes-status-bar.tsx`              | Upgrade status-card row treatment for version, model, memory, and activity                         | \~180      |
| `src/components/hermes-status-pill.tsx`                    | Replace legacy implementation with compatibility export or import forwarding                       | \~10       |
| `src/routes/__root.tsx`                                    | Mount the colocated Hermes status pill in `AppTopBar`                                              | \~5        |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Extend shell/status-card mode coverage                                                             | \~80       |
| `src/routes/__tests__/root-component.test.tsx`             | Add or adjust root/top-bar coverage if needed for the new import path                              | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hermes route renders the cinematic banner, v2.3 visual tokens, amber halo, demo support state, loading state, and status-card row.
* [ ] Status pill appears in the top bar when Hermes is installed and links to `/agents/hermes`.
* [ ] Status pill renders nothing when Hermes is missing, the browser is offline, or the status endpoint fails.
* [ ] Existing Hermes tabs and read-only sections continue to render in demo, live, setup-required, offline, and endpoint-error modes.

### Testing Requirements

* [ ] Focused Hermes component tests cover the upgraded shell states and status cards.
* [ ] Status pill tests cover ready, setup-required, missing, offline, and malformed/error responses.
* [ ] Root/top-bar coverage is updated if import or mount behavior changes.
* [ ] `bun run typecheck` and relevant Vitest tests pass.

### Non-Functional Requirements

* [ ] No new dependencies are added.
* [ ] No new bridge write path or sensitive data exposure is introduced.
* [ ] Banner and logo imports stay within the existing media and bundle budget policy.
* [ ] Responsive and reduced-motion behavior is preserved for the shell, banner, and top-bar pill.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Status polling uses abortable fetch and does not retry or spam failing local endpoints.

***

## 8. Implementation Notes

### Key Considerations

* The Phase 16 IA decision says to keep the existing top-level tab shell. This session should change the shell and status layer, not restructure tabs.
* The status pill is read-only and should stay quiet on errors so every route does not surface bridge noise.
* The banner asset is already present as `00-banner-wide.png`; do not import additional oversized assets.
* The existing top-level `src/components/hermes-status-pill.tsx` already has useful parsing and offline behavior. Reuse the behavior but move ownership under `src/components/hermes/`.

### Potential Challenges

* Route shell visual changes can cause overflow on small screens: mitigate with fixed aspect-ratio constraints, wrapping tabs, and root top-bar truncation.
* Status-card polish can accidentally create nested-card composition: mitigate by using one card layer per repeated status item and keeping page sections unframed where possible.
* Polling `/__hermes_status` globally can produce noisy failures: mitigate with retry disabled, offline gating, and render-null behavior on missing/error.
* V23 references include monolithic route logic: mitigate by porting visual behavior and small support components only.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: This session only polls the existing read-only status endpoint and must not add admin writes or expose private runtime details.
* \[P01] **Bundle budget watch on 3D vendor chunks**: This session must avoid new heavy dependencies and use the already-copied banner/logo assets.
* \[P01] **Old `claude-os-*` naming in code identifiers**: Preserve compatibility headers and token names where they are existing bridge contracts; do not start a naming migration in this session.
* \[P00] **Stack conventions**: Stay within Bun, Vite, TanStack Start, React 19, Tailwind CSS 4, and existing Radix/local UI conventions.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Global status polling can run on every route, so it must handle offline, missing, malformed, and failed endpoint states without user-visible churn.
* Cinematic shell changes can regress mobile layout, focus behavior, or reduced motion expectations.
* Status summaries consume external endpoint contracts, so enum/status handling should be exhaustive and parser-backed.

***

## 9. Testing Strategy

### Unit Tests

* Test `HermesStatusPill` with mocked status responses for ready, unconfigured/setup, missing, offline, endpoint error, and malformed payloads.
* Extend Hermes section tests to assert the cinematic shell support states, banner identity, demo/live toggles, and upgraded status-card labels.

### Integration Tests

* Update root route/top-bar coverage if the import path or mount behavior needs explicit protection.
* Run focused Vitest files for Hermes components and root route tests.

### Manual Testing

* Open `/agents/hermes` in desktop and mobile widths and verify banner crop, cards, tabs, top-bar pill, and footer do not overlap.
* Mock or run local bridge states for installed ready, installed unconfigured, missing, offline, and endpoint error.

### Edge Cases

* `/__hermes_status` returns non-JSON, malformed JSON, or a non-ok response.
* Browser is offline before the first query or becomes offline while mounted.
* Hermes is installed but missing default model/provider values.
* Long version/model/provider strings appear inside compact cards or the top bar.
* Reduced-motion preference is enabled.

***

## 10. Dependencies

### External Libraries

* None new.

### Other Sessions

* **Depends on**: `phase16-session01-guardrails-architecture-parity-baseline`, `phase16-session02-backend-endpoint-parity-write-safety`, `phase16-session03-data-layer-demo-fixtures`.
* **Depended by**: `phase17-session02-chat-tab-write`, `phase17-session03-pantheon-upgrade-write`, later Hermes Memory, Mission, Documents, Mnemosyne, Connections, and parity sign-off phases.

***

## 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-session01-visual-system-shell-status-pill/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.