> 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/phases/phase_17/prd_phase_17.md). # PRD Phase 17: Hermes Shell And Core Writes **Status**: Complete **Sessions**: 3 (initial estimate) **Estimated Duration**: 4-6 days **Source Code Roots**: `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`. **Progress**: 3/3 sessions (100%) *** ## Overview Phase 17 builds the cinematic visual shell and lands the first two core write features on top of the Phase 16 foundation: the global status pill and visual system, the Chat tab, and the Pantheon upgrade. Chat send and the Pantheon create/edit/delete/install/validate writes are already wired server-side; this phase adds the client mutations and UI, plus the new image-upload and GitHub-sync writes. **Master reference:** the Phase 16 PRD (`.spec_system/PRD/phase_16/PRD_phase_16.md`) holds the code-reference legend, full v2.3 component inventory, the Write-Path Safety Contract, the Complete Write Operation Inventory, the security model, dependencies, assets, validation strategy, non-goals, and completion criteria. This phase references that contract for every write. **Code reference roots:** `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`. Anchors are "start reading here," not exact positions. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ----------------------------------------------------------- | --------- | ---------- | --------- | | 01 | Visual System, Cinematic Shell And Global Status Pill | Completed | \~14-18 | Yes | | 02 | Chat Tab (Write: Send + Image Upload) | Completed | \~16-22 | Yes | | 03 | Pantheon Upgrade (Write: Edit/Delete/Templates/GitHub Sync) | Completed | \~16-22 | Yes | *** ## Completed Sessions * Session 01: Visual System, Cinematic Shell And Global Status Pill - completed 2026-06-02 * Session 02: Chat Tab (Write: Send + Image Upload) - completed 2026-06-02 * Session 03: Pantheon Upgrade (Write: Edit/Delete/Templates/GitHub Sync) - completed 2026-06-02 *** ## Upcoming Sessions None in Phase 17. Phase 17 is 3/3 complete as of 2026-06-02. Sessions 01 through 03 are validated and complete. *** ## Objectives 1. Extend the aios Hermes visual vocabulary with v2.3's cinematic system (theme consts, Fraunces/Courier kickers, amber halo, banner crop), preserve the demo banner/CTA/loading states and status-card source anchors, and mount the global Hermes status pill in the app top bar. 2. Add the Chat tab as a modular write feature: client send mutation (server already wired), thread reads, and image attach via the new image-upload endpoint. 3. Upgrade the Pantheon tab: persona templates read, plus the GitHub-sync write (the remaining unported Pantheon write); create/edit/delete/install/validate are already wired. *** ## Prerequisites * Phase 16 completed (foundation: endpoints, hooks, types, demo fixtures, and the write-safety contract helpers all in place). * Image-upload, GitHub-sync, and all read endpoints registered in Phase 16 Session 02; their hook queries/mutations added in Phase 16 Session 03. *** ## Technical Considerations ### Architecture New tabs are added to `AIOS/src/components/hermes/hermes-read-only-page.tsx` (TabsList `:150`, TabsContent blocks `:177-189`). New surface components live under `AIOS/src/components/hermes/`. All writes route through `useHermesAdmin`; UI write affordances are disabled with an "admin mode required" hint when the token is absent. ### Source -> Target (per session) **Session 01 (Visual System & Shell):** * Extend `AIOS/src/components/hermes/hermes-page-primitives.tsx` (`HERMES_ACCENT` `:15`) with v2.3's visual vocabulary -- theme consts at V23 `agents.hermes.tsx:615-621` (`CREAM`/`BG`/`BG_GRADIENT`), Fraunces/Courier kickers, amber halo, the bar glyph, 0px borders, banner crop (`HermesPage` banner block V23 `:980+`). * Preserve/port shell support states from V23 route anchors: `HermesDemoBanner` `agents.hermes.tsx:1080`, `HermesDemoCTA` `:1163`, `HermesLoading` `:1198`. * Preserve/upgrade status-card anchors from V23 route anchors: `HermesStatusBar` `agents.hermes.tsx:1584`, `StatusChip` `:2077`, `VersionCard` `:1630`, `ModelCard` `:1836`, `MemoryCard` `:1751`, `ActivityCard` `:1978`. * Add the cinematic banner (`AIOS/src/assets/hermes-art/00-banner-wide.png`, already copied) to the hero. * Port `V23/src/components/hermes-status-pill.tsx` (91 lines, read-only, polls `/__hermes_status`, global top-bar dot + "Hermes" indicator) -> new `AIOS/src/components/hermes/hermes-status-pill.tsx`, mounted in `AIOS/src/routes/__root.tsx` `AppTopBar` (`:167`, header `:194`); renders nothing when Hermes is not installed. **Session 02 (Chat tab, write feature):** * Source: `HermesChat` V23 `:2114`, `HermesChatActive` `:2141`, `ChatSidebar` `:2825`, `SessionPill` `:3010`, `ChatBubble` `:3100`, `UserAvatar` `:3144`, `HermesAvatar` `:3199`, `ChatTyping` `:3224`, `ChatEmptyState` `:3074`. * Target: new `AIOS/src/components/hermes/chat/` (+ new `Chat` tab). * Send is **already wired server-side** (`hermes-admin-bridge.ts:660`) -- add the client mutation in `use-hermes-admin.ts`; read threads via `/__hermes_sessions` * `/__hermes_session`; image attach via the new `/__hermes_image_upload` (Write Inventory #6: body-size cap, content-type check, confined cache dir). v2.3 client send `agents.hermes.tsx:2394`; client image upload `agents.hermes.tsx:2175`. **Session 03 (Pantheon upgrade, write feature):** * Source: `PantheonCatalog` V23 `:3488`, `PersonaCard` `:3975`, `PersonaEditModal` `:4084` *(write)*, `AddPersonaTile` `:3576` *(write, templates)*, `HermesPantheonGitHubSync` `:4752` *(write, sync)*, `GHSyncStepCard` `:4792`, `GH_SYNC_STEPS` `:4662`, `ModelDropdown` `:4544`, `SyncBadge` `:4492`, `PANTHEON_AVATARS` `:175`, `HermesProfileTemplates` `:3414`. * Target: extend `AIOS/src/components/hermes/hermes-pantheon.tsx` (`:59`). * create/edit/delete/install/validate are **already wired** (`hermes-admin-bridge.ts:781`/`816`/`851`/`908`); add templates read (`/__hermes_pantheon_templates`) + GitHub-sync write (Write Inventory #12: net + exec, args-array git, no shell interpolation of refs, confirm). ### Risks * **GitHub sync executes git + touches the network** (Write Inventory #12, highest-risk): Mitigation -- args-array git only, no shell interpolation of refs, confirm step, dedicated security tests. See Open Question 4 (auth). * **Image upload accepts arbitrary bytes**: Mitigation -- body-size cap + content-type check + confined cache dir (enforced in the Phase 16 endpoint; the client must respect the cap). * **Status pill polling on every route**: Mitigation -- read-only poll of `/__hermes_status`; render nothing when not installed. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: writes stay behind loopback + token + admin mode; UI disables write affordances without the token. * \[P01] **Bundle/asset budget**: reuse the already-copied `.webp`/banner assets; do not import superseded `.png`/`.jpg`. ### Open Questions Owned By This Phase * **GitHub sync auth (Session 03):** does Pantheon<->GitHub sync rely on the user's ambient `git`/`gh` credentials, or should aios manage a scoped token? Resolve before shipping the sync write. *** ## Success Criteria Phase complete when: * [ ] All 3 sessions completed and validated. * [ ] The cinematic visual system, banner, demo states, loading state, and status cards are applied; the global status pill is mounted in the top bar and renders nothing when Hermes is absent. * [ ] The Chat tab sends (admin-gated), reads threads, and attaches images via the confined upload endpoint. * [ ] The Pantheon tab reads templates and performs GitHub sync (admin-gated, git args-array, confirmed) with passing security tests. * [ ] Mode matrix (demo/live/setup-required/offline/endpoint-error) renders for each surface; typecheck, lint, and tests pass. *** ## Dependencies ### Depends On * Phase 16: Hermes v2.3 Port Foundation ### Enables * Phase 18: Hermes Memory And Visualization * Phase 19: Hermes Orchestration And Documents --- # 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/phases/phase_17/prd_phase_17.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.