> 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_20/prd_phase_20.md). # PRD Phase 20: Hermes Long-Tail And Parity Sign-off **Status**: Complete **Sessions**: 2 (initial estimate) **Estimated Duration**: 3-5 days **Source Code Roots**: `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`. **Progress**: 2/2 sessions (100%) *** ## Overview Phase 20 completes the long-tail Hermes surfaces and performs the full parity sign-off against v2.3. Session 01 ports Connections, stats, skills, sessions, roles, activity, CLI, and supporting cards. Session 01 is complete as of 2026-06-02. Session 02 removes dead scaffolding, checks that no raw fetch/polling/write path bypasses the hook/admin layers, updates docs, and validates side-by-side feature parity. Session 02 is complete as of 2026-06-02. **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, backend endpoint inventory, Write-Path Safety Contract, Complete Write Operation Inventory, validation strategy, non-goals, open questions, and whole-port completion criteria. **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 | Connections, Stats And Long-Tail Sections | Complete | \~16-22 | 2026-06-02 | | 02 | Cleanup, Dead-Code Removal And Full Parity Sign-off | Complete | \~16-22 | 2026-06-02 | *** ## Completed Sessions 1. `phase20-session01-connections-stats-long-tail` - Connections, Stats And Long-Tail Sections, completed 2026-06-02 2. `phase20-session02-cleanup-parity-signoff` - Cleanup, Dead-Code Removal And Full Parity Sign-off, completed 2026-06-02 *** ## Upcoming Sessions * None. Phase 20 is complete. *** ## Objectives 1. Port the remaining read-only/low-risk v2.3 Hermes sections into modular aios components: Connections, stats, skills, recent sessions, roles, activity, CLI, run-in-terminal, and shared long-tail cells/cards. 2. Complete the full parity sign-off: dead-code cleanup, no hook/admin bypasses, write-gate verification, docs/README/changelog updates, and side-by-side visual/behavioral comparison with v2.3. *** ## Prerequisites * Phases 16-19 completed: endpoints, hooks, types, demo fixtures, visual shell, Chat, Pantheon, Memory, Mnemosyne, Mission Control, and Documents Gallery are implemented and validated. * Open Questions 1-4 from the Phase 16 PRD resolved or explicitly recorded in the owning phase/session notes. *** ## Technical Considerations ### Architecture Long-tail surfaces remain modular components under `AIOS/src/components/hermes/`. They consume only the Phase 16 hook layer and demo fixtures. Cleanup verifies the entire Hermes surface obeys the same contracts: reads through `useHermes`, writes through `useHermesAdmin`, sensitive reads token-gated, and no raw polling/fetch paths that bypass the data layer. ### Source -> Target (per session) **Session 01 (Connections, stats and long-tail sections):** * Source: `HERMES_LOCAL_LOGOS` V23 `agents.hermes.tsx:90`, `HermesConnectionsStrip` `:1335`, `ConnectionsModeToggle` `:1476`, `ConnectionLogo` `:1523`, `ProviderLogoChip` `:1246`. * Source: `HermesStatsSection` V23 `:3257`, `HermesLiveStats` `:5716`, `RichStatCell` `:5896`, `LiveStatCell` `:5935`, `HermesClaudeOsBridgeCard` `:6000`, `StatTile` `:7214`. * Source: `HermesLiveSkills` V23 `:6165`, `SkillTile` `:6386`, `HermesSkillsSection` `:7005`, `SectionHead` `:6521`. * Source: `HermesRecentSessions` V23 `:6565`, `SessionRow` `:6691`, `PlatformBadge` `:6661`, `PlatformBadgeIcon` `:6623`. * Source: `HermesRolesSection` V23 `:6794`, `RoleCell` `:6830`, `ROLES` `:6743`. * Source: `HermesActivityPanels` V23 `:6909`, `Capability` `:6981`. * Source: `HermesCliCheatsheet` V23 `:7118`, `CliCategoryCell` `:7139`, `CliCommandRow` `:7162`, `CLI_CATEGORIES` `:7061`, `RunInTerminalCard` `:7262`. * Targets: upgrade `AIOS/src/components/hermes/hermes-skills.tsx` (`:59`) and `AIOS/src/components/hermes/hermes-sessions.tsx` (`:52`); add small focused components per section under `AIOS/src/components/hermes/`; add/extend tabs or panels through `AIOS/src/components/hermes/hermes-read-only-page.tsx`. **Session 02 (Cleanup and parity sign-off):** * Delete dead v2.3-only scaffolding and unused temporary porting code. * Ensure no `setInterval`/raw-fetch path bypasses the hook layer; polling must go through React Query/hook-owned refetch. * Confirm every write path is admin-gated through `useHermesAdmin`; no sensitive read bypasses the token. * Run the full parity checklist from the Phase 16 PRD against v2.3 side by side. * Update `AIOS/README.md` with the aios Hermes surface and `~/.hermes/` layout, and update `AIOS/docs/CHANGELOG.md` with the port record. ### Risks * **Long-tail scope creep**: Mitigation -- port source sections as small focused components and keep each behavior read-only unless already classified as a write in the Phase 16 inventory. * **Bypass drift from copied v2.3 code**: Mitigation -- Session 02 explicitly searches for raw fetch, raw polling, direct mutation, and ungated write paths. * **Documentation overclaims**: Mitigation -- docs describe implemented behavior only and keep AI OS host/Hermes local-agent language separate from Trend Finder public-source evidence. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: all write and sensitive read paths keep loopback + token/admin gates. * \[P01] **Bundle budget tight on 3D vendor chunks**: confirm lazy-loaded heavy surfaces stay out of the base bundle. * \[P09] **Provider-neutral helpers should remain the UI projection layer**: host local-agent surfaces should consume shared view models where available. *** ## Success Criteria Phase complete when: * [x] Both sessions completed and validated. * [x] Connections, stats, skills, recent sessions, roles, activity, CLI, and run-in-terminal surfaces render through modular aios components. * [x] Every v2.3 Hermes feature listed in the Phase 16 inventory is reachable from `/agents/hermes` or the global status pill. * [x] All missing endpoints from Phase 16 exist and are gated as required; no write bypasses `useHermesAdmin`; no sensitive read bypasses the token. * [x] Demo mode renders the entire page with no bridge running. * [x] README and changelog document the completed port and local Hermes layout. * [x] Typecheck, lint, test suite, mode matrix, bundle budget, and side-by-side visual parity checks pass. *** ## Dependencies ### Depends On * Phase 16: Hermes v2.3 Port Foundation * Phase 17: Hermes Shell And Core Writes * Phase 18: Hermes Memory And Visualization * Phase 19: Hermes Orchestration And Documents ### Enables * Final Hermes v2.3 feature parity certification. --- # 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_20/prd_phase_20.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.