> 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/phase20-session01-connections-stats-long-tail/spec.md). # Session Specification **Session ID**: `phase20-session01-connections-stats-long-tail` **Phase**: 20 - Hermes Long-Tail And Parity Sign-off **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session ports the remaining read-only and low-risk Hermes v2.3 long-tail sections into the existing AI OS Hermes page. It adds modular AIOS components for Connections, live stats, upgraded Skills, upgraded Sessions, Roles, Activity, CLI cheatsheet, and the terminal setup card without copying the v2.3 route monolith. The work matters because Phases 16-19 already delivered the safety foundation, hook contracts, write surfaces, Memory, Mnemosyne, Mission Control, and Documents Gallery. Phase 20 Session 01 fills the remaining visible feature gaps needed before the final cleanup and parity sign-off session can certify the Hermes v2.3 port. The implementation must keep the Phase 16 architecture decision intact: port features into focused AIOS modules, consume `useHermes` and typed props, preserve demo/live parity, and avoid any raw component-owned fetch, polling, or write path. *** ## 2. Objectives 1. Add the long-tail Connections and live stats surfaces through typed Hermes query views and existing logo assets. 2. Upgrade the Skills and Sessions sections to match the v2.3 long-tail detail while preserving current read-state handling. 3. Add read-only Roles, Activity, CLI cheatsheet, and terminal setup components as focused AIOS modules. 4. Wire the new sections into `/agents/hermes` tabs or panels with mode-matrix tests for live, demo, setup, offline, empty, error, and token-failure states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the modular port decision, tab IA, and v2.3 inventory. * [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides the read endpoints, write-safety foundation, loopback checks, and admin gates. * [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed hooks, parser coverage, and bounded demo fixtures for expanded Hermes domains. * [x] `phase17-session01-visual-system-shell-status-pill` - Provides the cinematic Hermes route skin and global status affordance. * [x] `phase17-session02-chat-tab-write` - Provides the chat tab and admin write pattern that must not be duplicated by long-tail surfaces. * [x] `phase17-session03-pantheon-upgrade-write` - Provides persona and template surfaces used by role/profile context. * [x] `phase18-session01-memory-upgrade-write` - Provides memory/profile read composition and Obsidian admin gating. * [x] `phase18-session02-mnemosyne-constellation-readonly` - Provides the lazy read-only 3D pattern and bundle isolation lessons. * [x] `phase19-session01-mission-control-write` - Provides Mission Control and mission write boundaries. * [x] `phase19-session02-documents-gallery-write` - Provides Documents Gallery, document polling, and bounded destructive-write feedback. ### Required Tools/Knowledge * React 19, TanStack Query, TanStack Router, Tailwind CSS 4, Radix Tabs, lucide icons, and Vitest/happy-dom component testing. * V23 source anchors in `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx`. * AIOS Hermes hooks, types, demo data, route primitives, and tests. ### Environment Requirements * Bun 1.3.14 from `.bun-version`. * Existing local test commands from `package.json`: `bun run test`, `bun run typecheck`, `bun run lint`, and focused Vitest file runs. * No live Hermes bridge is required; demo fixtures and mocked query views must cover the plan. *** ## 4. Scope ### In Scope (MVP) * Operator can inspect Hermes connections in AIOS - port `HERMES_LOCAL_LOGOS`, `HermesConnectionsStrip`, `ConnectionsModeToggle`, `ConnectionLogo`, and `ProviderLogoChip` into focused component/data modules using existing assets, deterministic fallbacks, and explicit loading, empty, error, offline, and demo states. * Operator can inspect live stats - derive sessions, messages, models, last active, connected integrations, profile counts, and skill counts from existing Hermes query views with deterministic ordering and no raw fetches. * Operator can use richer Skills and Sessions sections - upgrade `hermes-skills.tsx` and `hermes-sessions.tsx` with v2.3-inspired tiles, platform/provider chips, collapse/expand behavior, bounded text, and state resets on demo/live re-entry. * Operator can inspect role and activity surfaces - add read-only role cards, recent activity summaries, and capability meters using static v2.3-derived constants plus existing sessions/skills/profiles data where available. * Operator can copy CLI commands - add the v2.3 CLI cheatsheet with accessible copy buttons, copied-state reset, keyboard/focus support, and no browser command execution. * Operator can see terminal setup guidance when Hermes is missing or unconfigured - add a terminal card that offers copyable setup commands while preserving setup-required/demo/live mode separation. * Hermes page wiring exposes the new long-tail sections through tabs or panels chosen to keep the existing shell scannable and avoid duplicating Chat, Mission, Documents, Memory, Mnemosyne, Pantheon, or Admin write controls. * Tests cover parser/demo fixture alignment if data contracts change, component state matrices, tab wiring, copy interactions, and no component-owned fetch or timer regressions. ### Out of Scope (Deferred) * New write endpoints or write UI - Reason: this session is read-only/low-risk long-tail parity. * Final cleanup, dead-code removal, docs, and side-by-side parity sign-off - Reason: owned by Phase 20 Session 02. * Reworking Chat, Pantheon, Memory, Mnemosyne, Mission Control, or Documents - Reason: those surfaces already have owning sessions; only integration fixes needed for long-tail layout are allowed. * Raw v2.3 monolith copy or route replacement - Reason: Phase 16 requires AIOS modular architecture and typed hooks. * New 3D, Recharts, or heavy visual dependencies - Reason: bundle budget and lazy vendor isolation remain active concerns. * Direct component calls to bridge endpoints, raw `setInterval` polling, or writes through anything except existing hooks - Reason: this violates the Phase 16 and Phase 19 safety model. *** ## 5. Technical Approach ### Architecture Create small focused components under `src/components/hermes/` and keep `src/routes/agents.hermes.tsx` as a thin route. `HermesReadOnlyPage` remains the composition owner for demo/live mode, hook invocation, tab placement, and admin hook wiring. New long-tail components receive `HermesQueryView` props or static readonly data and do not call `fetch`, `setInterval`, or admin mutations. Connections should normalize `HermesConnectionsBody` into display rows with local logo assets under `src/assets/logos/`, verified Simple Icons slugs only if the existing pattern is acceptable, and an initial-letter fallback that cannot render broken images. Stats, activity, and roles should derive from the existing `sessions`, `connections`, `profiles`, `skills`, `models`, and `status` views, falling back to explicit state blocks when data is unavailable. The CLI cheatsheet and role constants should live in a typed data module so copy and display components stay small and testable. The terminal card should be a passive copy surface only; it should never execute commands from the browser. ### Design Patterns * Prop-driven section components: Keeps data ownership in `useHermes` and page composition, matching current Hermes modules. * Parser-first only when needed: If missing data projections are discovered, extend `hermes-types.ts`, `use-hermes.ts`, `hermes-demo-data.ts`, and tests before UI wiring. * Existing Hermes primitives: Reuse `SectionPanel`, `StateBlock`, `HermesStatusChip`, `MetricTile`, `ClipText`, `MetaLine`, and `TextButton` instead of adding another visual system. * Derived display models: Keep stats, capability meters, and activity summaries deterministic and browser-safe. * Accessibility by default: Use real buttons for toggles/copy actions, preserve focus rings, expose `aria-live` only for loading/copy feedback where useful, and ensure icon-only affordances have text or labels. ### Technology Stack * React 19 and TypeScript. * TanStack Query through `useHermes`. * Radix Tabs via local `Tabs` wrappers. * Tailwind CSS 4 and scoped Hermes route CSS in `src/styles.css`. * lucide-react icons. * Vitest with happy-dom and Testing Library. * No new external libraries. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------- | ---------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-long-tail-data.ts` | Typed role, CLI, logo, platform, and display constants | \~180 | | `src/components/hermes/hermes-connections.tsx` | Connections strip, mode toggle, logo chip, and state handling | \~220 | | `src/components/hermes/hermes-live-stats.tsx` | Derived stats ledger and activity sparkline cells | \~170 | | `src/components/hermes/hermes-roles.tsx` | Read-only role cards and capability summaries | \~170 | | `src/components/hermes/hermes-activity.tsx` | Recent activity panels derived from sessions and skills | \~160 | | `src/components/hermes/hermes-cli-cheatsheet.tsx` | CLI category grid, command rows, copy state, terminal setup card | \~220 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-read-only-page.tsx` | Wire long-tail sections into tabs/panels and pass demo/live query views | \~100 | | `src/components/hermes/hermes-skills.tsx` | Upgrade skill tiles, collapse/expand behavior, state handling, and bounded copy | \~120 | | `src/components/hermes/hermes-sessions.tsx` | Upgrade recent session rows, platform/provider chips, sorting, and empty/error states | \~130 | | `src/components/hermes/hermes-page-primitives.tsx` | Add only small shared helpers if repeated long-tail UI needs them | \~40 | | `src/lib/hermes-demo-data.ts` | Add or tune bounded demo fixtures only if long-tail projections need more data | \~40 | | `src/lib/hermes-types.ts` | Add parser/type fields only if implementation discovers missing hook-layer projections | \~60 | | `src/hooks/use-hermes.ts` | Add hook projections only if parser/type changes are required | \~50 | | `src/components/hermes/__tests__/hermes-sections.test.tsx` | Extend component and mode-matrix coverage for long-tail tabs and demo transitions | \~220 | | `src/lib/__tests__/hermes-types.test.ts` | Extend fixture/parser coverage if data contracts change | \~60 | | `src/hooks/__tests__/use-hermes.test.tsx` | Extend hook coverage if new projections are added | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Connections, stats, skills, recent sessions, roles, activity, CLI, and terminal setup guidance are reachable from `/agents/hermes`. * [ ] Long-tail components consume `useHermes` outputs, typed props, static constants, or demo fixtures only; no direct raw bridge fetches. * [ ] Existing Skills and Sessions behavior remains compatible while gaining the v2.3 long-tail detail. * [ ] Demo mode renders populated long-tail sections without reading local files or enabling writes. * [ ] Setup-required, offline, empty, error, and token-failure states remain explicit rather than collapsing into blank panels. ### Testing Requirements * [ ] Focused component tests cover long-tail live/demo rendering and state matrices. * [ ] Copy interactions for CLI and terminal card are tested with state reset. * [ ] Existing Hermes hook and parser tests remain passing. * [ ] Manual or browser validation checks that tab content does not overflow or overlap on desktop and mobile. ### Non-Functional Requirements * [ ] No new bundle-heavy dependencies or non-lazy 3D/vendor imports. * [ ] No raw component-owned polling, timers, direct fetches, or write paths. * [ ] Browser-visible copy does not expose private local paths beyond existing sanitized demo/operator placeholders. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test src/components/hermes/__tests__/hermes-sections.test.tsx` passes. * [ ] `bun run test src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx` passes if hook/type projections change. * [ ] `bun run typecheck` passes. * [ ] `bun run lint` passes or any unrelated pre-existing failures are documented. *** ## 8. Implementation Notes ### Key Considerations * Use AIOS architecture as the source of truth; v2.3 anchors are feature references, not files to copy wholesale. * Keep new long-tail surfaces read-only and passive. CLI commands and terminal setup are copy affordances only. * Preserve the current route shell, status bar, demo controls, and footer safety language. * Avoid nested cards and oversized hero patterns; these are dense operator surfaces inside an existing dashboard. * If a tab list becomes too crowded, group long-tail sections into a single `Overview` or `Long-tail` tab rather than spreading one tab per minor section. ### Potential Challenges * Crowded tab IA: Group low-risk sections into a long-tail panel if top-level tabs no longer scan well. * Data gaps for stats/activity: Derive from existing typed views first; only add hook/type fields if the existing bridge payload cannot represent the needed browser-safe projection. * Logo drift: Use existing local assets and deterministic fallbacks so missing external brand icons do not produce broken UI. * Copy-state leaks between demo/live transitions: Reset copied/expanded state on component re-entry where the view changes materially. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: This session adds no direct write paths and keeps sensitive reads behind existing token-gated hook views. * \[P01] **Bundle budget watch on 3D vendor chunks**: Do not add new heavy visual dependencies or import lazy 3D surfaces into the base route path. * \[P09] **Provider-neutral helpers should remain the single UI projection layer**: Keep local-agent projections typed and shared rather than route-local raw parsing. * \[P18] **Lazy 3D surfaces must stay isolated**: New long-tail components must not affect Mnemosyne lazy loading or SSR safety. * \[P19] **Remaining Hermes long-tail tabs should reuse the existing safety pattern**: Hook-layer data and demo/live parity remain mandatory. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * New sections accidentally hide setup/offline/token failures behind empty UI. * Copy and expanded/collapsed controls keep stale state after demo/live transitions. * Ported v2.3 snippets introduce raw fetches, timers, remote icon breakage, or write affordances outside existing hook/admin contracts. *** ## 9. Testing Strategy ### Unit Tests * Render each new long-tail component with success, demo, empty, loading, error, offline, and token-failure query views. * Verify stats and activity derivations are deterministic with null models, equal timestamps, empty arrays, and malformed optional fields. * Verify CLI and terminal copy buttons update copied state, expose accessible names, and reset predictably. * Verify logo and platform fallbacks render when slugs are missing or unsupported. ### Integration Tests * Extend `HermesReadOnlyPage` tests to verify long-tail tab or panel wiring in live and demo modes. * If hook/type projections change, extend parser/demo fixture tests and `useHermes` tests to prove the new projections stay gated correctly. * Verify no sensitive read queries run when token handshake fails. ### Manual Testing * Open `/agents/hermes` in demo mode and confirm all long-tail sections render without local bridge access. * Toggle back to live/setup-required mode and confirm terminal guidance appears without enabling write controls. * Check desktop and mobile widths for tab wrapping, card text overflow, copy chip alignment, and no overlapping content. ### Edge Cases * No connections, no skills, no sessions, or no profiles. * Connections with unknown kind, slug, or status. * Sessions with null model/platform/timestamps and tied `lastUpdatedMs` values. * Very long skill names, command strings, local paths, or first-user-message previews. * Offline browser state, malformed endpoint payloads, and failed token handshake. * Demo mode entered after a live tab with copied/expanded state. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Internal Dependencies * `src/hooks/use-hermes.ts` * `src/lib/hermes-types.ts` * `src/lib/hermes-demo-data.ts` * `src/components/hermes/hermes-page-primitives.tsx` * `src/components/hermes/hermes-read-only-page.tsx` * `src/components/hermes/hermes-skills.tsx` * `src/components/hermes/hermes-sessions.tsx` * `src/styles.css` * `src/assets/logos/*` ### 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`, `phase17-session03-pantheon-upgrade-write`, `phase18-session01-memory-upgrade-write`, `phase18-session02-mnemosyne-constellation-readonly`, `phase19-session01-mission-control-write`, `phase19-session02-documents-gallery-write` * Depended by: `phase20-session02-cleanup-parity-signoff` *** ## 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/phase20-session01-connections-stats-long-tail/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.