> 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/phase22-session03-setup-wizard-dream-sources-strip/spec.md). # Session Specification **Session ID**: `phase22-session03-setup-wizard-dream-sources-strip` **Phase**: 22 - Non-Hermes Multi-Agent Detection And Home Surfaces **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session completes Phase 22 by tightening the setup wizard Hermes Agent card and adding a Dream source-status strip to the AI OS home dashboard. The strip shows the seven source categories Dream reads from: Claude Code, Antigravity, Memory, Skills, Integrations, Automations, and Hermes. The work follows Phase 22 Sessions 01 and 02. Antigravity is now available as a validated browser-safe local-agent signal, and its usage consumers are already wired into the usage panel and home ROI strip. Session 03 uses that validated state alongside existing memory, skills, integration, automation, and Hermes data to produce a small source-readiness surface without adding scanner, scheduler, or Dream runtime behavior. The implementation should fit the current AI OS extraction pattern. Route files should remain mount points, while source derivation lives in pure home transforms and rendering lives in focused home components. *** ## 2. Objectives 1. Update the Hermes Agent setup wizard card to use the planned default path `~/.hermes/hermes-agent` while preserving detection-driven state. 2. Add a typed pure selector that derives Dream source tiles from validated `LiveData` without exposing raw local paths, prompts, transcripts, or credential material. 3. Create a focused `DreamSourcesStrip` home component that renders all seven source categories with live, optional, and missing states. 4. Mount the source strip on the home dashboard near the Dream surface without adding route-level parsing. 5. Add focused setup, transform, and component tests for fully live, partially missing, absent Antigravity, absent Hermes, and example-data states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-pricing-daily-activity-accuracy` - Provides stable home dashboard usage and activity contracts. * [x] `phase21-session02-project-windows-skill-roi-defaults` - Provides the current home transform and ROI extraction pattern. * [x] `phase21-session03-authoritative-claude-usage-oauth` - Provides the current usage and local-agent privacy boundary. * [x] `phase22-session01-antigravity-detection-data-contract` - Provides the typed and validated Antigravity surfaces and usage data. * [x] `phase22-session02-antigravity-usage-consumers` - Provides the Antigravity home selector pattern and additive UI consumer behavior. ### Required Tools/Knowledge * React 19 and TypeScript component conventions. * Existing setup wizard constants, detection helpers, and modal tests. * Existing `home-transforms`, `useHomeData`, and home component extraction pattern. * v2.3 Dream source strip reference in `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx`. ### Environment Requirements * No local Hermes or Antigravity install is required for tests. * Browser-visible output must be derived from validated live data and bounded summary fields only. * No new network calls, scheduler jobs, scanner reads, or generated private data writes belong in this session. *** ## 4. Scope ### In Scope (MVP) * AI OS displays the Hermes Agent setup card with default path `~/.hermes/hermes-agent` - Preserve existing detection-driven selected and missing states. * AI OS derives Dream source tiles from home data - Use a pure selector over `LiveData` rather than route-level parsing. * AI OS renders Claude Code, Antigravity, Memory, Skills, Integrations, Automations, and Hermes tiles - Show safe labels, counts, and status pills only. * AI OS distinguishes live, optional, and missing source states - Antigravity can be optional when installed without activity, and missing sources must not break the dashboard. * AI OS keeps the strip compact and scannable - Use current dark dashboard component patterns and accessible interactive controls. * AI OS tests selector and component behavior for complete, partial, absent, and example-data states. ### Out of Scope (Deferred) * New Dream runtime behavior or scheduler changes - *Reason: this session is a browser source-status surface only.* * Raw prompt, transcript, protobuf, path, credential, or private automation details in the browser - *Reason: violates the local agent privacy boundary.* * New Antigravity detection fields - *Reason: Session 01 owns the data contract.* * New usage-panel or ROI changes - *Reason: Session 02 owns those consumers.* * Depending on Hermes Phases 16-20 being fully present at runtime - *Reason: the tile must degrade safely from current data.* *** ## 5. Technical Approach ### Architecture Keep setup work narrow by updating the existing `TOOLS` Hermes entry in `src/components/setup/constants.ts` and regression-testing the card/default path behavior. The setup route already renders `SetupModal`, and current setup tests already cover Hermes detected and missing states, so the implementation should refine existing wiring rather than introduce a new setup path. For the home strip, add a typed `DreamSourceTileData` model in the home type layer and a `deriveDreamSources(ld)` selector in `src/lib/home-transforms.ts`. The selector should use existing helpers such as finite non-negative counts, Antigravity usage projection, and Hermes local signal projection where useful. It should return all seven rows every time, with deterministic ordering and safe detail strings. Render those derived rows through a new `DreamSourcesStrip` component under `src/components/home/`. `useHomeData()` should expose the derived rows, and `src/routes/index.tsx` should only mount the component near `DreamHero` without parsing nested `LiveData` directly. ### Design Patterns * Pure selector before UI rendering: Keep source derivation testable in `home-transforms`. * Fixed source inventory: Always render the same seven source categories in deterministic order. * Typed degradation over throws: Missing or malformed source inputs become optional or missing states. * Additive setup refinement: Keep current Hermes detection behavior while correcting the default path. * Route as mount point: Home route consumes `useHomeData()` output and avoids ad hoc data parsing. ### Technology Stack * React 19 for home and setup components. * TypeScript 6.0.3 for live-data and transform types. * Tailwind CSS 4 for existing dashboard styling conventions. * lucide-react 1.16.0 and existing local image assets for source icons. * Vitest 4.1.6 and Testing Library for transform and component tests. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | ---------- | | `src/components/home/dream-sources-strip.tsx` | Focused Dream source-status strip and source tile renderer. | \~170 | | `src/components/home/__tests__/dream-sources-strip.test.tsx` | Component coverage for source counts, statuses, toggle behavior, and safe labels. | \~150 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | | `src/components/setup/constants.ts` | Update Hermes Agent default path while preserving detection mapping. | \~5 | | `src/routes/__tests__/setup-modal.test.tsx` | Add or update Hermes setup card default-path and missing/detected regression coverage. | \~40 | | `src/components/home/types.ts` | Add Dream source tile data/status types. | \~20 | | `src/lib/home-transforms.ts` | Add Dream source derivation selector and expose it in `HomeData`. | \~130 | | `src/lib/__tests__/home-transforms.test.ts` | Cover fully live, partial, absent Antigravity, absent Hermes, and example-data source states. | \~120 | | `src/lib/use-home-data.ts` | Include derived Dream source rows in the home data object. | \~10 | | `src/routes/index.tsx` | Mount the source strip near `DreamHero` using derived props only. | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Setup wizard shows Hermes Agent with default path `~/.hermes/hermes-agent` when no detected path overrides it. * [ ] Setup wizard still reflects `detection.apps.hermes` detected and missing states. * [ ] Dream source strip renders all seven source categories in deterministic order. * [ ] Antigravity tile uses validated surfaces and usage to distinguish live, optional, and missing states. * [ ] Hermes tile lights up from current Hermes snapshot or detection state and degrades safely when absent. * [ ] Memory, Skills, Integrations, and Automations tiles show bounded safe counts/statuses only. * [ ] Home route remains a mount point and does not parse nested live data. ### Testing Requirements * [ ] Setup tests cover Hermes default path and detection-driven state. * [ ] Home-transform tests cover fully live, partially missing, no Antigravity, no Hermes, and example data states. * [ ] Component tests cover source count labels, status pills, toggle behavior, and safe detail rendering. * [ ] Focused test suites pass. ### Non-Functional Requirements * [ ] Browser-visible details expose no raw prompts, transcripts, local conversation filenames, credentials, or private automation payloads. * [ ] The strip is responsive and text does not overlap in mobile or desktop layouts. * [ ] No new scanner, scheduler, network, generated-data, or third-party dependency behavior is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test -- src/routes/__tests__/setup-modal.test.tsx src/lib/__tests__/home-transforms.test.ts src/components/home/__tests__/dream-sources-strip.test.tsx` passes. * [ ] `bun run typecheck` passes. *** ## 8. Implementation Notes ### Key Considerations * Current AI OS already has a Hermes Agent setup entry, but its default path is `~/.hermes`; the v2.3 source requires `~/.hermes/hermes-agent`. * `src/routes/index.tsx` has already been reduced to prop/mount behavior for home sections. Keep the new strip out of route-level data parsing. * `DEFAULT_LIVE_DATA` contains absent Antigravity and Hermes shapes; the strip must not treat object existence as live signal. * Antigravity can be installed without conversations. That state should be optional, not live. * Hermes may appear through either the Hermes snapshot or detection app state, and both must stay browser-safe. ### Potential Challenges * The v2.3 reference uses loose route-local data access: Port the behavior, not the `any`-heavy route-global implementation. * Default/example data can accidentally look like real source coverage: Gate on meaningful counts and detected flags. * Detail strings can leak local paths if they reuse detection metadata directly: Format detail from counts/status only. * Collapsible UI can become inaccessible if implemented as visual-only state: Use a real button with clear expanded state. ### Relevant Considerations * \[P08] **Local agent privacy boundary**: Render sanitized metadata only and keep readiness scans read-only. * \[P09] **Provider-neutral helpers stay the UI projection layer**: Source projection belongs in shared home transforms, not route-specific parsing. * \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep the strip component focused and prop-driven. * \[P21] **Additive live-data changes stay safest when the scanner, validator, example payload, and transforms move together**: Reuse the additive Antigravity contract delivered by Session 01. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Missing optional sources could produce false live status or break the home dashboard. * Source details could accidentally expose local paths or private content. * Collapsible/tile interactions could be inaccessible or lose state predictability. *** ## 9. Testing Strategy ### Unit Tests * Extend `src/lib/__tests__/home-transforms.test.ts` for deterministic source ordering, live/optional/missing status derivation, finite count guards, and absence handling. * Add setup regression coverage for Hermes Agent default path and detection override behavior. ### Integration Tests * Add `src/components/home/__tests__/dream-sources-strip.test.tsx` to render the strip with derived rows and verify labels, status pills, source count summary, and toggle behavior. * Exercise the `useHomeData` output indirectly through transform/component tests rather than adding route-level parsing assertions. ### Manual Testing * Run the home page with example data and confirm all seven source categories render without false live states or overlapping text. * Inject positive Antigravity and Hermes data in test data and confirm the strip shows live/optional/missing states correctly. * Open the setup wizard and confirm Hermes Agent default path and detected path behavior. ### Edge Cases * `detection.apps.antigravity` missing or present with zero usage. * Antigravity IDE or CLI detected with no conversation usage. * `hermes` snapshot missing while `detection.apps.hermes` is detected. * Memory, skill, integration, or automation arrays are absent, empty, or malformed. * Example data with no live source coverage. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase22-session01-antigravity-detection-data-contract`, `phase22-session02-antigravity-usage-consumers` * **Depended by**: Phase 22 closeout and Phase 23 planning *** ## 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/phase22-session03-setup-wizard-dream-sources-strip/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.