> 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_23/prd_phase_23.md). # PRD Phase 23: Non-Hermes Routes, Polish And Closeout **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/`; diff reference = `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/`. **Progress**: 3/3 sessions (100%) *** ## Overview Phase 23 completed the non-Hermes v2.3 migration by adding the Claude Code agent route after Hermes Mission Control exists, applying small UI polish, recording optional housekeeping, and validating the final non-Hermes parity state. It also preserves every skip/no-action decision from the old `docs/ongoing-projects/v2_3-port-remaining.md` so that document can be deleted without losing audit history. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ---------------------------------------- | -------- | ---------- | ---------- | | 01 | Claude Code Agent Route | Complete | \~12-18 | 2026-06-02 | | 02 | UI Polish And Optional Local Tooling | Complete | \~14-22 | 2026-06-02 | | 03 | Non-Hermes Parity Documentation Closeout | Complete | \~14-20 | 2026-06-02 | *** ## Completed Sessions * Session 01: Claude Code Agent Route * Session 02: UI Polish And Optional Local Tooling *** ## Upcoming Sessions * Session 03: Non-Hermes Parity Documentation Closeout *** ## Objectives 1. Add the Claude Code agent route that reuses Hermes Mission Control with the `agent="claude-code"` configuration and a blue skin. 2. Apply the small v2.3 UI polish items that are independent of Hermes parity: skill-card hover sheen and sticky sidebar. 3. Record and optionally port local housekeeping items without treating generated route trees, already-copied assets, attribution, or prompt wording as feature gaps. 4. Run the non-Hermes validation strategy and leave a final parity record. *** ## Prerequisites * Phase 21 complete. * Phase 22 complete. * Phase 19 complete before Session 01, because `HermesMissionControl` is the required reusable component for the Claude Code route. * Hermes Phase 20 closeout should own README Hermes surface documentation and `~/.hermes/` layout notes; Session 03 verifies that this cross-reference is not lost. *** ## Technical Considerations ### Session Source Map **Session 01: C** * v2.3 route source: [V23/src/routes/agents.claude-code.tsx:1](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.claude-code.tsx:1) through `:153`. * aios missing target route: `AIOS/src/routes/agents.claude-code.tsx`. * aios reusable dependency: `AIOS/src/components/hermes-mission-control.tsx`, delivered by Hermes Phase 19. * Sidebar target: [AIOS/src/components/app-sidebar.tsx:108](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/app-sidebar.tsx:108). * Home placement source: [V23/src/routes/index.tsx:16251](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx:16251). **Session 02: D and optional E tooling** * Skill-card hover sheen CSS source: [V23/src/styles.css:278](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/styles.css:278) through `:310`. * Home skill tile usage: [V23/src/routes/index.tsx:16262](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/index.tsx:16262) through `:16270`. * Skills page usage: [V23/src/routes/skills.tsx:402](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/skills.tsx:402) through `:411`. * Sticky sidebar source: [V23/src/components/app-sidebar.tsx:2050](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/app-sidebar.tsx:2050). * Sticky sidebar target: `AIOS/src/components/app-sidebar.tsx`. * Optional VS Code launch config: [V23/.claude/launch.json:1](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/.claude/launch.json:1) through `:11`; absent in aios and should use aios's dev port if added. * Optional asset-regeneration tooling: `V23/scripts/gen-hermes-file-type-art.ts` and `V23/scripts/webp-file-type-art.sh`; outputs already exist under `AIOS/src/assets/hermes-art/file-types/*.webp`. **Session 03: validation and no-action preservation** * Route tree generated file: `src/routeTree.gen.ts` is generated by TanStack Router after route files are added. Do not hand-edit it. * README Hermes documentation: v2.3 README Hermes page and `~/.hermes/` layout sections belong to Hermes Phase 20 sign-off, not standalone non-Hermes work. * Image prompt wording: skip the "Ghibli/miyazaki" to "painterly anime" wording change unless art is regenerated. * Attribution/licensing: already done in aios through `LICENSE`, `NOTICE`, and `README.md`, while keeping aios's own `author: "Operator"`, `ai-os`, and `UNLICENSED` package identity. * Lockfile and n8n asset trivia: `bun.lock` churn is already covered by existing `js-yaml` dependencies, and `AIOS/src/assets/logos/n8n.svg` is already present. ### Relevant Considerations * \[P04] Hermes bridge guardrails must stay intact: Claude Code route reuse must not create bypasses around Mission Control safety. * \[P01] Bundle budget watch: polish and route additions must not pull heavy assets into the base bundle. * \[P00] Do not document planned features as implemented: final closeout docs should separate implemented behavior from deferred or optional tooling. *** ## Resolved And No-Action Audit Items These details are intentionally preserved here so the old ongoing-project document is no longer required: * Attribution / licensing is done. `AIOS/LICENSE` replaced the vague upstream paragraph with the named "Claude OS - Personal & Commercial Use License with Attribution" and concrete obligations: visible attribution to "Claude OS by Jack Roberts", no redistribution, no repackaging, no sale, no SaaS, and a pointer to NOTICE. aios's proprietary terms apply only to aios's own work; nothing relicenses upstream materials. * `AIOS/NOTICE` is new and adapted from [V23/NOTICE:1](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/NOTICE:1/README.md) through `:91`: upstream Claude OS license, Hermes/Nous Research, Anthropic "Claude" trademark, other agent integrations including OpenClaw/Codex/ Antigravity, Simple Icons brand marks, Kie.ai/Higgsfield AI artwork, local data, and skills. * `AIOS/README.md:335-343` now states upstream attribution and no-redistribution obligations and links `LICENSE` and `NOTICE`. * Do not adopt v2.3's `author: "Jack Roberts"` or homepage in `package.json`. aios keeps `author: "Operator"`, `ai-os`, and `license: "UNLICENSED"`. Attribution is satisfied through LICENSE/NOTICE/README. This is compliance scaffolding, not legal advice. * Image-generation prompt wording changes in `gen-dream-images.ts`, `gen-cadence-images.ts`, and `batch-generate.ts` are skipped unless assets are regenerated. The relevant v2.3 prompt wording anchors are [V23/scripts/gen-dream-images.ts:1404](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/gen-dream-images.ts:1404) and [V23/scripts/gen-dream-images.ts:1413](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/scripts/gen-dream-images.ts:1413). * New v2.3 asset-generation tooling is optional because its output is already present in aios: `V23/scripts/gen-hermes-file-type-art.ts` generates ten Kie.ai file-type cards (`pdf`, `html`, `markdown`, `text`, `data`, `video`, `audio`, `archive`, `code`, `other`), and `V23/scripts/webp-file-type-art.sh` re-encodes PNG to 800px webp. Port those scripts only if regeneration parity is wanted. * `src/routeTree.gen.ts` is auto-generated. v2.3's extra lines are generated TanStack Router output for added routes. Add route files and let codegen update the tree. * README Hermes documentation folds into Hermes Phase 20 because it documents the Hermes page surface and `~/.hermes/` layout (`config.yaml`, `pantheon/personas/*.yaml`, etc.). The README license paragraph is separate and already handled. Hermes Phase 20 should also update `AIOS/docs/CHANGELOG.md` with the completed port record. * Already-resolved trivia: `bun.lock` churn is from `js-yaml` and `@types/js-yaml`, which aios already has; `AIOS/src/assets/logos/n8n.svg` is already present from the completed asset move. *** ## Validation Strategy * Every aggregator field added in Phases 21-22 must extend `AIOS/src/lib/live-data-types.ts`, `AIOS/src/lib/validate-live-data.ts`, and `AIOS/src/data/live-data.example.json`. * Extend existing tests under `AIOS/scripts/lib/__tests__/` and `AIOS/src/routes/__tests__/`; do not bypass them. * A2 OAuth is a merge-gate item: unit-test credential reads for file and Keychain paths, null on missing, token never logged, silent fallback on non-200/timeout, and correct `source` switching between `oauth` and `estimate`. * A1 must test exact hit, date-suffixed family fallback, old 3.x name, and unknown model as `null` or uncounted rather than zero. * Run the existing aggregate and home-transform test suites green before and after changes. * Final closeout should run typecheck, script typecheck, lint, format check, relevant Vitest suites, route smoke tests as available, and production build. *** ## Non-Goals * Re-porting anything in the already-done table preserved in Phase 21. * Adopting stale v2.3 Opus pricing. * Anything owned by Hermes Phases 16-20: Hermes components, bridge, assets, skin CSS, fonts, Pantheon/personas content, and Hermes README feature docs. * Image-generation prompt rewording unless art is regenerated. * Hand-editing `src/routeTree.gen.ts`. *** ## Success Criteria Phase complete when: * [ ] All three sessions completed and validated. * [ ] Claude Code route exists after Hermes Mission Control is available and is linked from the sidebar without bypassing Mission Control safety. * [ ] Skill-card sheen and sticky sidebar polish are applied without layout or bundle regressions. * [ ] Optional tooling is either ported with a documented reason or explicitly left deferred. * [ ] No-action and skip decisions are preserved in durable spec/docs artifacts. * [ ] Final non-Hermes validation passes or records actionable residual gaps. *** ## Dependencies ### Depends On * Phase 21: Non-Hermes v2.3 Usage Accuracy * Phase 22: Non-Hermes Multi-Agent Detection And Home Surfaces * Phase 19: Hermes Orchestration And Documents, for Session 01 only ### Enables * Deletion of `docs/ongoing-projects/v2_3-port-remaining.md` after review. * Final non-Hermes v2.3 migration certification. *** ## Deletion-Safety Original Backlog Snapshot This appendix is an ASCII-normalized snapshot of `docs/ongoing-projects/v2_3-port-remaining.md` captured during the Phase 21-23 phasebuild audit. It exists so that deleting the old ongoing-project document does not lose any semantic detail. Unicode status symbols and punctuation from the original were transliterated to satisfy the spec-system ASCII rule: `[done]`, `[todo]`, `WARNING`, `->`, `<->`, `--`, and `section`. The implementation-ready phase sections and session stubs above preserve the same work as scoped sessions with clickable absolute `V23/` and `AIOS/` source anchors. This snapshot is the deletion-safety backstop. ```markdown # v2.3 Port -- Remaining (Non-Hermes) Work > **Status:** Planned > **Source:** `claude-os-v2.3` -> `aios` (`AI OS`) > **Companion specs:** the Hermes feature port (the _bulk_ of the v1->v2.3 diff) > now lives in the spec system under > [`phase_16/PRD_phase_16.md`](../../.spec_system/PRD/phase_16/PRD_phase_16.md) > through `archive/phases/phase_20/`, with direct `V23/` and `AIOS/` > source-code anchors. > **This doc covers everything else** -- the non-Hermes improvements that landed > in v2.3 and have not yet been ported into aios. > > This is the third and final tranche of the migration: > > 1. [done] **Media assets** copied into aios (`hermes-art/`, portraits, `mission-claude.mp4`, etc.). > 2. [done] **Hermes feature specs** folded into `.spec_system/PRD/phase_16/` through > `.spec_system/archive/phases/phase_20/`. > 3. [todo] **This doc** -- comprehensive sweep of everything left in the diff. ## Code Reference Legend All file references use these two roots (paste-able / clickable): - **`V23/`** = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/` -- the source. - **`AIOS/`** = `/home/aiwithapex/projects/aios/` -- the target (this repo). - **Diff source of truth:** `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/` (`full.diff`, `SUMMARY.md`, `changed-text.txt`, `added-text.txt`). `file:line` anchors are accurate as of this writing; treat them as "start reading here," not exact post-edit positions. --- ## Method & Headline I walked **every** non-binary file in the v1->v2.3 diff and classified each as _Hermes_ (-> companion doc), _already-done in aios_, or _genuine remaining gap_. The big surprise: **aios has already ported most of the non-Hermes v2.3 improvements** -- it diverged forward (it has Opus 4.8 pricing, Codex, OpenClaw, extensions, a scheduler, and a fully modular `scripts/lib/` aggregator that v2.3 never had). So the remaining list is **focused, not a re-do of the diff.** ### Already done in aios -- do NOT re-port (verified) | v2.3 improvement | V23 source | aios state (done) | | -------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | Hermes filesystem snapshot (`gatherHermes`) | `V23/scripts/aggregate.ts:978` | `AIOS/scripts/lib/hermes-scanner.ts:233`, emitted `AIOS/scripts/lib/aggregate-orchestration.ts:1132` | | Hermes app detection (`hermes: AppDetection`) | `V23/scripts/aggregate.ts:916` | `AIOS/scripts/lib/app-detection.ts:63,114-130` | | Dream cron resolves `claude` abs path (`CLAUDE_BIN`) + warns | `V23/scripts/install-dream-cron.ts:52,219` | `AIOS/scripts/install-dream-cron.ts:54,63,220,287` | | `copyPersonasSkill` into `~/.hermes/skills/` | `V23/scripts/setup.ts:96,212` | `AIOS/scripts/setup.ts:98,233` (aios variant: "only if absent") | | Dream SKILL.md: plan-aware cost framing + Hermes signal source | `V23/skills/dream/SKILL.md:76,25` | `AIOS/skills/dream/SKILL.md:38,90` | | `js-yaml` + `@types/js-yaml` deps | `V23/package.json:60,68` | `AIOS/package.json:101,133` | | Global `HermesStatusPill` in top bar | `V23/src/routes/__root.tsx:146` | `AIOS/src/routes/__root.tsx:16,217` | | Removed dead `poll-existing.ts` | `V23` (deleted) | absent in aios [done] | | `recentProjects[].sessions` = real unique-session count | `V23/scripts/aggregate.ts:1306` | `AIOS/scripts/lib/aggregate-orchestration.ts:1118` (Set at `session-scanner.ts:447`) | | usage-panel product names (Codex split from ChatGPT) | `V23/src/components/usage-panel.tsx:90` | `AIOS/src/components/usage-panel.tsx:23` (has `Codex`) | ### Covered by the Hermes Phase 16-20 specs -- cross-reference, not duplicated here `hermes-mission-control.tsx`, `hermes-mnemosyne.tsx`, `hermes-documents-gallery.tsx`, `hermes-status-pill.tsx`, all `agents.hermes.tsx` features, the `vite.config.ts` Hermes bridge, `hermes-art/` assets, the `personas/SKILL.md` content, the `.hermes-skin` CSS block, and the Fraunces/Courier-Prime web-fonts are owned by the Hermes specs in `.spec_system/PRD/phase_16/` through `.spec_system/archive/phases/phase_20/`. The Phase 16 PRD is the cross-phase master reference and points directly to `V23/`, `AIOS/`, and the diff artifacts. Where a _remaining_ item below depends on one of these (e.g. the Claude Code route needs `HermesMissionControl`), it is flagged **`depends on Hermes specs`**. --- ## Remaining Workstreams Ordered by value/independence. Each item: what v2.3 added (with `V23` anchor), aios's current state (with `AIOS` anchor), the gap, and any caveat. ### A -- Usage & ROI accuracy The v2.3 cluster that made the dashboard's money/usage numbers _honest_. aios shares the same data-layer shape, so these are surgical. #### A1. Pricing robustness -- family fallback + older-gen rows + null-for-unknown [todo] - **v2.3:** `priceForModel()` adds a two-layer lookup -- exact table, then `claude-{opus,sonnet,haiku}-*` family fallback -- plus 3.x rows, and returns **`null`** (uncounted) for genuinely unknown models instead of `$0`. `V23/scripts/aggregate.ts:463-522` (table+fallback), `:560` (`computeCost` uses it). _Rationale in-source:_ any model not in the exact table silently undercounted spend -> dashboards didn't match Anthropic invoices. - **aios now:** exact-match only. `AIOS/scripts/lib/session-scanner.ts:6-12` (4.x table incl. `claude-opus-4-8`), unknown -> `return 0` at `AIOS/scripts/lib/session-scanner.ts:112`. - **Gap:** add a `priceForModel()` helper (family fallback + 3.x rows + null-for-unknown) and route `computeCost` through it. - **WARNING CAVEAT -- do NOT copy v2.3's numbers.** v2.3's Opus rate is `$15/$75`; aios's is `$5/$25` (current Opus 4.8 era, `session-scanner.ts:7`). The family-fallback rates must be derived from **aios's** current table, not pasted from `V23`. Porting the _mechanism_, not the _prices_. #### A2. Authoritative Claude usage via OAuth `/usage` [todo] _(largest net-new)_ - **v2.3:** fetches the same server-side numbers Claude Code's `/usage` TUI shows -- `GET https://api.anthropic.com/api/oauth/usage` with the stored OAuth token + a UA pinned to live `claude --version`. Reads the credential from `~/.claude/.credentials.json` then macOS Keychain. Returns `null` on any failure -> the existing local-log heuristic stays as fallback. The dashboard then prefers authoritative `pct` and badges rows `live` vs `estimate`. - `V23/scripts/aggregate.ts:588-755` (`ClaudeAuthoritativeUsage`, `readClaudeCredential`, `detectClaudeCodeVersion`, `fetchClaudeOAuthUsage`) - wired at `V23/scripts/aggregate.ts:1153` (call) and the `claudeWindow` rebuild `V23/scripts/aggregate.ts:1191-1267` (`source`, `resetsAt`, `authoritative` payload). - **aios now:** **absent.** No `oauth/usage` / `readClaudeCredential` anywhere (`grep` clean across `scripts/lib/`, `src/lib/`). aios builds the Claude usage window from local-log heuristics only (`AIOS/scripts/lib/usage-assembly.ts`, `AIOS/scripts/lib/subscription-detection.ts`). - **Gap:** new `AIOS/scripts/lib/claude-oauth-usage.ts` module (credential read - fetch, fully null-safe), called from `aggregate-orchestration.ts`, merged into the Claude usage window with `source: "oauth"|"estimate"` + `resetsAt`. Surface a "live" badge in `AIOS/src/components/usage-panel.tsx`. - **[done] DECISION -- platform scope: full (credentials file -> macOS Keychain), matching aios's own convention.** aios is cross-platform with first-class macOS support, and it _already_ reads Claude credentials from both the file and the Keychain elsewhere -- `AIOS/scripts/lib/subscription-detection.ts:40-61` (`countKeychainCredentials`) is the canonical reference: `IS_MACOS` guard -> `Bun.spawn(["security", ...])` -> 2 s timeout race, plus the `readSafe*` validators at `:67-89`. The new module must follow that exact pattern (use `Bun.spawn` + `IS_MACOS`, not `execSync`/`process.platform === "darwin"` as in the v2.3 source) so it's idiomatic to aios. Read `~/.claude/.credentials.json` first, then Keychain (`security find-generic-password -s "Claude Code-credentials" -a "$USER" -w`), null on any miss. - **WARNING Safety:** read-only outbound to Anthropic's own API with the operator's own token; **redact** the token from all logs, short timeout (6 s), silent fallback. Add it to the secret-redaction set used by the bridges. Treat the credential read with the same care as the Hermes-plan Write-Path contract. #### A3. Real per-day session counts (kill the `messages/6` heuristic) [todo] - **v2.3:** `dayBucket[day].sessions` is a `Set` of JSONL file paths -> emits a true unique-session count per day; the home chart consumes `daily[].sessions` directly and falls back to the heuristic only for old data. - `V23/scripts/aggregate.ts:535,553` (Set), `:1283` (emit `sessions: v.sessions.size`) - consumer `V23/src/routes/index.tsx:16115-16168` (`computeDailyActivity`) - **aios now:** per-day bucket has **no** session Set (`AIOS/scripts/lib/session-scanner.ts:568`), so `daily[]` (`AIOS/scripts/lib/aggregate-orchestration.ts:1094`) carries no `sessions`, and the home transform still derives sessions from messages -- `sessionsFromMessages(messages)` at `AIOS/src/lib/home-transforms.ts:373`. - **Gap:** add `sessions: Set` to the day bucket (mirror the per-project Set already at `session-scanner.ts:447`), emit `daily[].sessions = set.size`, then prefer it in `home-transforms.ts:computeDailyActivity` with the message heuristic as fallback. Update `AIOS/src/lib/live-data-types.ts` (DailyEntry) + `AIOS/src/lib/validate-live-data.ts`. #### A4. `recentProjects` = true 7-day window, plus `allProjects[]` [todo] - **v2.3:** `recentProjects` strictly filtered to "modified within last 7 days" (uncapped, so the count matches disk), and a separate `allProjects` (top 30) for long-tail history. `V23/scripts/aggregate.ts:1288-1323`. _Rationale in-source:_ the old "top-10 ever, labelled 7d" silently included 17-28-day-old projects. - **aios now:** `recentProjects` = top-10 all-time, no 7-day filter, no `allProjects`. `AIOS/scripts/lib/aggregate-orchestration.ts:1112-1122`. - **Gap:** add the 7-day cutoff filter to `recentProjects`, add an uncapped (or top-30) `allProjects`. Extend `live-data-types.ts` + `validate-live-data.ts`. #### A5. Per-skill default minutes-per-run (no more `$0 saved`) [todo] - **v2.3:** `getDefaultMinutes(name)` returns defensible per-skill defaults via a prefix-regex table (e.g. `html-presentation`->30, `bitly`->1), generic fallback 5. `V23/src/lib/time-saved.ts:8-89`. Home wires it into skill rows: `V23/src/routes/index.tsx:16088,16108`. - **aios now:** `getDefaultMinutes(_name)` **returns 0** (`AIOS/src/lib/time-saved.ts:23`); it's already imported/used at `AIOS/src/lib/time-saved.ts:91`, so just the body needs the table. - **Gap:** port the `SKILL_MINUTE_DEFAULTS` table + generic fallback. - **[done] DECISION -- port v2.3's table verbatim as the starting point; no hand-tuning.** Only change an individual default if it is _objectively_ wrong for the corresponding aios skill (e.g. the skill doesn't exist, or the estimate is plainly indefensible). The prefix-regex matcher already degrades gracefully to the generic fallback for any skill not in the table, so an unported aios-only skill simply gets the sane default -- no per-skill curation required. #### A6. usage-panel: Antigravity row [todo] _(depends on B1 data)_ - **v2.3:** adds an Antigravity "free - no quota" service row + logo. `V23/src/components/usage-panel.tsx:143-179` (row), `:301-305` (logo map). - **aios now:** services are `Claude | ChatGPT | Codex | OpenRouter` (`AIOS/src/components/usage-panel.tsx:23`) -- no Antigravity. - **Gap:** add the Antigravity row + logo once B1 populates `detection.apps.antigravity.usage`. (aios already split Codex, so only the Antigravity row is missing.) #### A7. "Free via Antigravity" ROI chip on home [todo] _(depends on B1 data)_ - **v2.3:** adds `antigravity.usage.savedEquivalent` into the ROI/"Tokens used" headline + a purple attribution chip. `V23/src/routes/index.tsx:16560-16600`. - **aios now:** ROI strip lives in `AIOS/src/routes/index.tsx` / `AIOS/src/lib/home-transforms.ts` with no free-agent contribution. - **Gap:** add `savedEquivalent` into the ROI math + the chip, gated on B1. ### B -- Multi-agent detection surfaces #### B1. Antigravity dual-surface (IDE + CLI) + usage + savedEquivalent [todo] - **v2.3:** detects the `.app` **and** the `antigravity` CLI independently, scans `~/.gemini/antigravity/conversations/*.pb|.json` for conversation count - last-active, exposes `surfaces.{ide,cli}` + `usage.savedEquivalent`. `V23/scripts/aggregate.ts:769-790` (types), `:807-905` (`detectApps` body). - **aios now:** `.app`-only boolean, no CLI, no usage, no surfaces. `AIOS/scripts/lib/app-detection.ts:207-210`. - **Gap:** extend `app-detection.ts` to mirror the dual-surface + usage scan; extend the `AppDetection` type, `live-data-types.ts`, `validate-live-data.ts`, and the example/demo data. This is the data prerequisite for A6 + A7 + B3's Antigravity tile. #### B2. Hermes card in the setup wizard [todo] _(small; aligns with Hermes specs)_ - **v2.3:** adds a "Hermes Agent" tool card to the setup wizard (`defaultPath: ~/.hermes/hermes-agent`, detect-driven). `V23/src/routes/setup.tsx:198-207` (card), `:102,265,326` (type/detection wiring). - **aios now:** app-detection already exposes `hermes` (`AIOS/scripts/lib/app-detection.ts:63`) but the **wizard has no Hermes card** (`grep hermes AIOS/src/routes/setup.tsx` -> none; `AIOS/src/components/setup/constants.ts` is the tool-card list). - **Gap:** add the Hermes tool card to `AIOS/src/components/setup/constants.ts` (+ `setup.tsx` types) so detection surfaces in the wizard. #### B3. `DreamSourcesStrip` on the home dashboard [todo] - **v2.3:** a collapsible "Sources -- N of M streams live" strip showing every feed Dream reads (Claude Code, Antigravity, Memory, Skills, Integrations, Automations, Hermes), each with a live/optional/missing pill. `V23/src/routes/index.tsx:16278-16542` (`DreamSourcesStrip` + `DreamSourceTile`), mounted at `:16241`. - **aios now:** absent in `AIOS/src/routes/index.tsx`. - **Gap:** port as a small aios component (its own file + a `home-transforms` selector), reading aios's `detection.apps` + `hermes` blocks (which already exist). The Hermes + Antigravity tiles light up once B1/Hermes data is wired. ### C -- Claude Code agent route [todo] _(depends on Hermes specs)_ - **v2.3:** `agents.claude-code.tsx` -- a thin (153-line) route that reuses `HermesMissionControl` with `agent="claude-code"` and its own blue skin. `V23/src/routes/agents.claude-code.tsx:1-153`. - **aios now:** no `AIOS/src/routes/agents.claude-code.tsx`; and `AIOS/src/components/hermes-mission-control.tsx` does **not exist yet** (it's a deliverable of the Hermes specs). - **Gap:** after `HermesMissionControl` lands (Hermes specs), add the route + a sidebar nav entry next to Hermes (`AIOS/src/components/app-sidebar.tsx:108`). Mission Control also wants a home-page placement (`V23/src/routes/index.tsx:16251`). ### D -- UI polish [todo] - **Skill-card hover sheen:** keyframe + `.skill-card-sheen` / `.group:hover` rule. Source CSS `V23/src/styles.css:278-310`; used in two places -- home skill tiles `V23/src/routes/index.tsx:16262-16270` and the Skills page `V23/src/routes/skills.tsx:402-411`. Target: `AIOS/src/styles.css` + the equivalent card markup in `AIOS/src/routes/index.tsx` and `AIOS/src/routes/skills.tsx`. - **Sticky sidebar:** v2.3 made the sidebar `sticky top-0 h-screen overflow-y-auto` (`V23/src/components/app-sidebar.tsx:2050`/diff). aios's sidebar (`AIOS/src/components/app-sidebar.tsx`) isn't sticky -- one-line class change. ### E -- Minor / housekeeping - **`.claude/launch.json`** [todo] -- optional VS Code launch config (`bun run dev`, port 8081). `V23/.claude/launch.json:1-11`. Absent in aios; trivial, optional. Adjust port to aios's dev port if added. - **Attribution / licensing** [done] **DONE** -- required compliance, completed ahead of the feature port (it is independent of the code). aios keeps its own closed-source proprietary stance for its **own** contributions, while now precisely honouring the upstream license that v2.3 put in force: - `AIOS/LICENSE` -- replaced the vague "subject to their own terms" upstream paragraph with the named **"Claude OS -- Personal & Commercial Use License with Attribution"** and its concrete obligations (visible attribution to "Claude OS by Jack Roberts" + no redistribution/repackaging/sale/SaaS), and a pointer to NOTICE. aios's proprietary terms still apply only to aios's own work; nothing relicenses the upstream materials. - `AIOS/NOTICE` -- **new file** (aios had none), adapted from `V23/NOTICE:1-91`: upstream Claude OS license (section 0), Hermes/Nous Research (section 1), Anthropic "Claude" trademark (section 2), other agent integrations incl. OpenClaw/Codex/Antigravity (section 3, aios-specific), Simple Icons brand marks (section 4), Kie.ai/Higgsfield AI artwork (section 5), local-only data (section 6), skills (section 7). - `AIOS/README.md:335-343` -- License section now states the upstream attribution + no-redistribution obligations and links `LICENSE` + `NOTICE`. - **Not adopted:** v2.3's `author: "Jack Roberts"` / `homepage` in `package.json` (aios keeps its own identity: `author: "Operator"`, `ai-os`, `license: "UNLICENSED"`). Attribution is satisfied via LICENSE/NOTICE/README, which is the correct channel for a private derivative. CHANGELOG is aios's own (`AIOS/docs/CHANGELOG.md`). - **Note:** this is compliance scaffolding, not legal advice -- the operator should have counsel review if aios is ever distributed beyond authorized private access. - **Image-gen prompt wording** -- _skip._ `gen-dream-images.ts` / `gen-cadence-images.ts` / `batch-generate.ts` only reworded prompts ("Ghibli/miyazaki" -> "painterly anime", a trademark-hygiene tweak; `V23/scripts/gen-dream-images.ts:1404,1413`). Cosmetic; the generated assets are already copied. No action unless regenerating art. - **New v2.3 asset-gen tooling** [todo] _(optional -- assets already copied)_ -- v2.3 added two _new_ scripts that generate the Documents Gallery file-type placeholder cards: `V23/scripts/gen-hermes-file-type-art.ts` (10 Kie.ai cards: pdf/html/markdown/text/data/video/audio/archive/code/other) and `V23/scripts/webp-file-type-art.sh` (PNG->800px webp re-encode). **Their output is already present in aios** -- `AIOS/src/assets/hermes-art/file-types/*.webp` (all 10). So porting the scripts is optional regen tooling, only needed if the file-type art is ever regenerated. The Documents Gallery itself is owned by the Hermes specs (Phase 19) and consumes those existing assets -- no gen step required to ship it. Copy the two scripts only if you want regeneration parity. - **`src/routeTree.gen.ts`** -- _no action (auto-generated)._ v2.3's +21 lines are the TanStack Router codegen output for its added routes. aios regenerates this file automatically when the dev server / build runs after a `createFileRoute` is added (e.g. the Claude Code route in **C**, or new Hermes routes). Do **not** hand-edit it; just add the route file and let codegen update the tree. - **README Hermes documentation** -- _folds into the Hermes port._ v2.3's README also gained descriptive sections documenting the Hermes page surface and the `~/.hermes/` on-disk layout (`config.yaml`, `pantheon/personas/*.yaml`, etc.). This is documentation that should follow the feature: update `AIOS/README.md` to document aios's Hermes surface as part of the Hermes specs' sign-off, not as a standalone task here. (The README's _license_ paragraph is the separate compliance change handled above.) - **Already-resolved trivia (no action):** `bun.lock` (+4) is lockfile churn for the `js-yaml` / `@types/js-yaml` deps that aios already has (see the "done" table) -- it regenerates from `package.json`, nothing to port. `src/assets/logos/n8n.svg` is **already present** in aios (`AIOS/src/assets/logos/n8n.svg`) from the completed asset move. Listed here only so the diff sweep is provably exhaustive. --- ## Suggested Sequencing 1. **A1 + A3 + A4** (aggregator accuracy -- pure data-layer, no UI risk, high trust value). 2. **B1** (Antigravity data) -> unlocks **A6, A7, B3** (UI consumers). 3. **A5** (skill minutes), **B2** (setup card), **D** (polish) -- independent, low-risk. 4. **A2** (OAuth `/usage`) -- highest value but most sensitive; do it deliberately with redaction + tests (see Validation). 5. **C** (Claude Code route) -- **after** the Hermes specs ship `HermesMissionControl`. ## Validation Strategy - **Type/contract:** every aggregator field added (A1/A3/A4, B1) must extend `AIOS/src/lib/live-data-types.ts` **and** `AIOS/src/lib/validate-live-data.ts`, with the demo/example data updated (`AIOS/src/data/live-data.example.json`). aios already has tests for these surfaces (`AIOS/scripts/lib/__tests__/`, `AIOS/src/routes/__tests__/`) -- extend them, don't bypass. - **A2 (OAuth) is the merge-gate item:** unit-test credential read (file + keychain paths, null on missing), assert the token is **never** logged (redaction test), assert silent fallback to heuristic on non-200/timeout, and assert `source` flips `oauth`<->`estimate` correctly. - **No silent undercount regressions (A1):** test `priceForModel` for an exact hit, a date-suffixed variant (family fallback), an old 3.x name, and an unknown name (-> `null`/uncounted, not `$0`). - Run the existing aggregate + home-transform test suites green before/after. ## Non-Goals - Re-porting anything in the "already done in aios" table. - Adopting v2.3's stale Opus pricing (A1 caveat). - Anything owned by the Hermes Phase 16-20 specs (the Hermes components, bridge, assets, skin CSS, fonts, Pantheon/personas content). - Image-gen prompt rewording (cosmetic). ## Resolved Decisions No outstanding decisions -- all settled and baked into the relevant sections above. 1. **Attribution / license (E):** [done] **Done now.** aios keeps its own closed-source identity (`author: "Operator"`, `UNLICENSED`) and honours the upstream "Claude OS -- Personal & Commercial Use License with Attribution" via updated `LICENSE`, a new `NOTICE`, and the `README` License section. Not adopting v2.3's `package.json` author/homepage. (Compliance scaffolding, not legal advice.) 2. **A2 OAuth scope:** [done] **Full scope -- credentials file -> macOS Keychain**, implemented with aios's own `Bun.spawn` + `IS_MACOS` pattern (`subscription-detection.ts:40-61`), because aios is cross-platform with first-class macOS support and already reads Claude credentials this way. 3. **A5 per-skill minutes:** [done] **Port v2.3's table verbatim**; change a default only if objectively wrong for an aios skill. The regex matcher's generic fallback covers aios-only skills automatically -- no hand-tuning needed. ``` --- # 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_23/prd_phase_23.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.