> 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-session02-antigravity-usage-consumers/spec.md). # Session Specification **Session ID**: `phase22-session02-antigravity-usage-consumers` **Phase**: 22 - Non-Hermes Multi-Agent Detection And Home Surfaces **Status**: Complete **Created**: 2026-06-02 *** ## 1. Session Overview This session consumes the Antigravity detection and usage contract delivered by Phase 22 Session 01. It makes Antigravity visible in the existing usage panel as a free local coding-agent signal, then includes `usage.savedEquivalent` in the home subscription ROI strip with a gated attribution chip. The work is the natural next step because the scanner, browser live-data type, validator defaults, example payload, and fixtures now expose a safe `detection.apps.antigravity` shape. The UI should consume that validated shape directly without adding new scanner behavior, hardcoded ROI values, or route level parsing. This session must preserve the existing separation between Claude, ChatGPT, Codex, and OpenRouter usage semantics. Antigravity is a free local-agent row with no quota window, not a paid subscription, and its ROI contribution is an additive saved-equivalent value only when validated usage supports it. *** ## 2. Objectives 1. Add an Antigravity service row to `UsagePanel` from validated `detection.apps.antigravity` usage data. 2. Preserve existing Claude, ChatGPT, Codex, and OpenRouter rows, including the Codex split from ChatGPT. 3. Include positive `antigravity.usage.savedEquivalent` values in the home subscription ROI calculation through a pure selector. 4. Render a gated Antigravity attribution chip only when saved-equivalent value is positive. 5. Add focused UI and transform tests for present, absent, zero, and existing service-row states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-pricing-daily-activity-accuracy` - Provides stable pricing and daily activity base contracts. * [x] `phase21-session02-project-windows-skill-roi-defaults` - Provides stable home ROI defaults and price override behavior. * [x] `phase21-session03-authoritative-claude-usage-oauth` - Provides the current usage-panel source-badge and quota-window patterns. * [x] `phase22-session01-antigravity-detection-data-contract` - Provides the typed and validated Antigravity `surfaces` and `usage` contract. ### Required Tools/Knowledge * React 19 and TypeScript UI component conventions. * `UsagePanel` service-row model in `src/components/usage-panel.tsx`. * Home ROI component boundary in `src/components/home/subscription-strip.tsx`. * Pure transform conventions in `src/lib/home-transforms.ts`. * Existing focused Vitest and Testing Library patterns. ### Environment Requirements * No local Antigravity install is required for tests. * Browser-visible output must use only validated live-data fields. * Existing local price override storage behavior must remain unchanged. *** ## 4. Scope ### In Scope (MVP) * AI OS shows Antigravity as a free local-agent service row - Use validated conversation usage and last-active metadata from `detection.apps.antigravity.usage`. * AI OS preserves existing paid and local usage rows - Keep Claude, ChatGPT, Codex, and OpenRouter rendering behavior intact. * AI OS adds Antigravity saved-equivalent value to the home subscription ROI strip - Use a pure helper so the UI does not parse nested data ad hoc. * AI OS renders an Antigravity attribution chip - Show it only when `usage.savedEquivalent` is positive and finite. * AI OS keeps Antigravity as a non-billable free agent - Do not add it to flat monthly spend or editable subscription prices. * AI OS tests present, absent, zero, and regression states for usage and ROI consumers. ### Out of Scope (Deferred) * Creating or changing Antigravity detection data - *Reason: Session 01 owns scanner, type, validator, and example data changes.* * Setup wizard Hermes card - *Reason: Session 03 owns setup wizard work.* * Dream source-status strip - *Reason: Session 03 owns the home source strip.* * New generated private data or new aggregate behavior - *Reason: this session is browser-consumer only.* * Repricing Claude, ChatGPT, Codex, or OpenRouter - *Reason: preserve Phase 21 usage accuracy semantics.* *** ## 5. Technical Approach ### Architecture Keep the implementation additive and local to existing UI boundaries. `src/components/usage-panel.tsx` builds service rows from `LiveData`; it should add an Antigravity row only when the validated Antigravity object contains a real signal such as positive conversations, positive saved-equivalent value, or detected surfaces. `src/components/home/subscription-strip.tsx` owns the ROI summary line, so it should include the saved-equivalent contribution there instead of moving logic into `src/routes/index.tsx`. Add pure helpers in `src/lib/home-transforms.ts` for Antigravity usage and ROI projection. These helpers should accept `LiveData`, coerce only finite non-negative numbers, and return explicit absent/zero states. Component tests then verify rendering while transform tests verify math and default behavior. ### Design Patterns * Additive consumer: Add Antigravity without changing existing service semantics. * Pure selector before UI rendering: Centralize nested contract parsing in `home-transforms`. * Gated attribution: Hide the ROI chip when Antigravity data is absent or `savedEquivalent` is zero. * Typed degradation over throws: Invalid or missing nested values resolve to zero/absent UI states. ### Technology Stack * React 19 for usage and home components. * TypeScript 6.0.3 for typed live-data consumers. * Vitest 4.1.6 and Testing Library for component and transform tests. * Existing logo assets in `src/assets/logos/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------- | --------------------------------------------------------------------- | ---------- | | `src/components/home/__tests__/subscription-strip.test.tsx` | Focused tests for Antigravity ROI attribution and zero/absent states. | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- | | `src/components/usage-panel.tsx` | Add Antigravity service type, logo mapping, row construction, no-quota metrics, and typed guards. | \~80 | | `src/components/__tests__/usage-panel.test.tsx` | Cover Antigravity present, absent, zero, and existing service-row regression states. | \~90 | | `src/lib/home-transforms.ts` | Add pure Antigravity usage and ROI contribution selectors. | \~55 | | `src/lib/__tests__/home-transforms.test.ts` | Cover selector math, absent data, zero value, and finite-number guards. | \~70 | | `src/components/home/subscription-strip.tsx` | Include positive saved-equivalent value in ROI and render gated attribution chip. | \~55 | | `src/components/home/logo-map.ts` | Add Antigravity local logo mapping for home surfaces. | \~5 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Antigravity usage row appears only when validated live data supports it. * [ ] Antigravity row communicates free/no-quota semantics without a paid cap. * [ ] Existing Claude, ChatGPT, Codex, and OpenRouter rows remain visible under their current conditions. * [ ] Home subscription ROI includes positive Antigravity `usage.savedEquivalent` values. * [ ] Antigravity attribution chip is hidden for absent or zero saved-equivalent values. * [ ] Antigravity is not counted as flat monthly spend or an editable subscription price. ### Testing Requirements * [ ] Usage-panel tests cover absent, present, zero, and existing service row states. * [ ] Home-transform tests cover saved-equivalent selector behavior. * [ ] Subscription-strip tests cover ROI math and gated chip rendering. * [ ] Focused test suites pass. ### Non-Functional Requirements * [ ] Browser output exposes only safe labels, counts, timestamps, and numeric saved-equivalent values. * [ ] UI remains responsive without adding route-level parsing or broad route changes. * [ ] No new network calls, credential reads, generated private data, or scanner behavior are introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test -- src/components/__tests__/usage-panel.test.tsx src/components/home/__tests__/subscription-strip.test.tsx src/lib/__tests__/home-transforms.test.ts` passes. * [ ] `bun run typecheck` passes. *** ## 8. Implementation Notes ### Key Considerations * `DEFAULT_LIVE_DATA` now includes an Antigravity default shape, so UI gating must not render a row merely because the object exists. * The Antigravity row should be visually consistent with existing service rows and reuse the existing local logo asset. * ROI contribution should be additive to the API-equivalent value, not to flat monthly spend. * Keep `src/routes/index.tsx` as a mount point. The route should not parse Antigravity data directly. ### Potential Challenges * Default Antigravity usage may look present: Gate on meaningful signal, not object existence. * ROI math can double count if applied in multiple places: Keep the contribution in the subscription strip summary only. * Component tests may need localStorage mocks through `usePriceOverrides`: Prefer mocking the hook in the focused subscription-strip test. * Logo handling differs by component: Add Antigravity to shared home logo map and usage-panel local logo mapping. ### Relevant Considerations * \[P08] **Local agent privacy boundary**: Render only safe aggregate fields from validated Antigravity usage. * \[P09] **Provider-neutral helpers stay the UI projection layer**: Route ROI parsing through `home-transforms` rather than route-specific logic. * \[P02] **Typed degradation over throws**: Missing or malformed Antigravity values must produce zero/absent UI states. * \[P21] **Additive live-data changes stay safest when scanner, validator, example payload, and transforms move together**: This session completes the consumer side of the Session 01 contract. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Default Antigravity data could accidentally show a false active row. * ROI attribution could be shown for zero or invalid saved-equivalent values. * Existing usage rows could regress while adding a new service type. *** ## 9. Testing Strategy ### Unit Tests * Extend `src/lib/__tests__/home-transforms.test.ts` for Antigravity saved-equivalent selector math and finite-number guards. * Add `src/components/home/__tests__/subscription-strip.test.tsx` with mocked price overrides to verify ROI text and chip rendering. ### Integration Tests * Extend `src/components/__tests__/usage-panel.test.tsx` to render the full `UsagePanel` with Antigravity present, absent, and zero/default data. * Include a regression test where Claude, ChatGPT, Codex, OpenRouter, and Antigravity can render together. ### Manual Testing * Run the home page with example data and confirm no false Antigravity chip appears for default zero usage. * Inject positive Antigravity usage in test data and confirm the row and chip render without overlapping adjacent usage content. ### Edge Cases * `usage` missing entirely. * `usage.conversations` is zero while surfaces are detected. * `usage.savedEquivalent` is zero, negative, `NaN`, or unbounded. * `usage.lastActiveAgo` missing or empty. * Existing service rows render without Antigravity data. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase22-session01-antigravity-detection-data-contract` * **Depended by**: `phase22-session03-setup-wizard-dream-sources-strip` *** ## 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-session02-antigravity-usage-consumers/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.