> 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_38/prd_phase_38.md).

# PRD Phase 38: Claude OS v2.8.1 Semantic Port

**Status**: Complete **Sessions**: 10 (initial estimate) **Estimated Duration**: 20-40 hours

**Progress**: 10/10 sessions (100%)

**Created**: 2026-06-29 **Owner**: AI OS maintainers

***

## Overview

Phase 38 ports every relevant Claude OS v2.7 to v2.8.1 upstream change into the diverged AI OS tree. AI OS lives at `/home/aiwithapex/projects/aios` and was at `package.json` version `0.5.72` when this port plan was created. AI OS was forked from Claude OS v1, last manually applied Claude OS v2.7, and has since diverged into a modular, multi-product codebase covering games, videos, Trend Finder, scheduler, Knowledge Graph, Dream, Hermes, and other local operator surfaces.

This phase is a semantic feature port, not a file replacement. Upstream still keeps most logic in a few large flat files; AI OS has refactored the same domains into `scripts/lib/**`, `src/components/**`, setup helpers, bridge modules, Dream modules, scheduler modules, and route-level shells. Almost no upstream hunk applies cleanly with `git apply`. Each port item therefore records the upstream source, the AI OS target module, the adaptation rule, the verdict, and the required proof.

These Phase 38 artifacts are the canonical folded replacement for the former ongoing-projects port plan. The details needed for implementation are carried here and in the session stubs under this directory.

***

## Non-Negotiable Delivery Bar

Proper delivery means every shipped feature proves the user's intended outcome end to end in the product, with real execution, visible results, recovery paths, and tests. Scaffolding that merely looks complete is not done.

No Phase 38 item is complete until all five gates hold:

1. Real execution: the feature runs the actual code path against the real backend, CLI, or OS. Windows scheduling must truly register a task via `schtasks`; voice must truly drive `/__hermes_chat`; mocked happy paths do not stand in for shipped behavior.
2. Visible result: the outcome is observable in a product surface or generated artifact a user touches, such as a dashboard card, Hermes chat stream, setup wizard, or generated file on disk.
3. Recovery paths: failures are handled with actionable copy for cases such as missing auth, missing engine or CLI, offline provider, OS without scheduler support, private-mode `localStorage` failure, and rejected voice keys.
4. Tests: unit or integration tests cover the real path and at least one failure path under the matching `__tests__/` owner, such as `scripts/lib/__tests__/`, `src/components/**/__tests__/`, or `src/routes/__tests__/`.
5. Target-platform proof: Windows-facing work is exercised on Windows or a faithful harness and regression-checked on macOS/Linux; voice is exercised against a real Realtime session where credentials are available; `bun run lint` and `bun run build` are green or exact unrelated blockers are recorded.

Treat the DoD sections in each session stub as acceptance criteria, not suggestions.

***

## Progress Tracker

| Session | Name                                 | Status   | Est. Tasks | Validated  |
| ------- | ------------------------------------ | -------- | ---------- | ---------- |
| 01      | Tier 0 Parity Fixes                  | Complete | 18         | 2026-06-29 |
| 02      | Platform Foundation                  | Complete | 18         | 2026-06-29 |
| 03      | Aggregate and Dream Health           | Complete | 22         | 2026-06-29 |
| 04      | Dream Scheduling and Setup           | Complete | 20         | 2026-06-29 |
| 05      | Runtime Bridge Hardening             | Complete | 20         | 2026-06-29 |
| 06      | Policy, Docs, and Catalogs           | Complete | 20         | 2026-06-30 |
| 07      | Dream Engine Product Integration     | Complete | 20         | 2026-06-30 |
| 08      | Voice Broker                         | Complete | 20         | 2026-06-30 |
| 09      | Intelligence Portal                  | Complete | 25         | 2026-06-30 |
| 10      | Hunk Reconciliation and Release Gate | Complete | 22         | 2026-06-30 |

***

## Completed Sessions

* Session 01: Tier 0 Parity Fixes - Completed 2026-06-29.
* Session 02: Platform Foundation - Completed 2026-06-29.
* Session 03: Aggregate and Dream Health - Completed 2026-06-29.
* Session 04: Dream Scheduling and Setup - Completed 2026-06-29.
* Session 05: Runtime Bridge Hardening - Completed 2026-06-29.
* Session 06: Policy, Docs, and Catalogs - Completed 2026-06-30.
* Session 07: Dream Engine Product Integration - Completed 2026-06-30.
* Session 08: Voice Broker - Completed 2026-06-30.
* Session 09: Intelligence Portal - Completed 2026-06-30.
* Session 10: Hunk Reconciliation and Release Gate - Completed 2026-06-30.

***

## Upcoming Sessions

None. Phase 38 is complete and ready for phase-transition audit.

***

## Objectives

1. Port low-risk upstream correctness fixes for Memory counts, seed data, and Hermes graph/yolo chat semantics.
2. Add shared platform helpers and Windows-aware aggregate, Dream scheduling, setup, bridge, and runtime resolution behavior through AI OS modules.
3. Align license, docs, changelog, executable modes, and model catalogs with shipped behavior and resolved policy.
4. Add Dream engine selection, OpenAI Realtime voice broker support, and the Hermes Intelligence portal through existing AI OS product surfaces.
5. Close the phase with hunk-by-hunk reconciliation for every upstream changed path and full release-gate verification.

***

## Prerequisites

* Phase 37 completed.
* Upstream source comparison artifacts exist under `/home/aiwithapex/projects/claudeos/`.
* AI OS bridge, scheduler, Dream, Hermes, and Knowledge Graph guardrails remain the source of truth for adapted implementation.
* No open owner decisions remain. Resolved policy is recorded below.

***

## Planning Assumptions And Resolutions

### Working Assumptions

* The manual port plan supplied by the user is the intended source for Phase 38: `.spec_system/state.json` and `.spec_system/PRD/PRD.md` ended at completed Phase 37, while the plan contained a complete 10-session Claude OS v2.7 to v2.8.1 port scope. It is safe to proceed because the plan contains concrete objectives, dependencies, acceptance checks, and resolved policy decisions.
* All paths in the upstream comparison are machine-local absolute paths. They are still valid source references for implementation and hunk reconciliation.
* Session stubs deliberately preserve absolute AI OS target paths so future implementers do not have to recover mapping decisions from the deleted ongoing-projects file.

### Conflict Resolutions

* Master PRD and state did not list Phase 38: the port plan is the best supported source for the new phase; `state.json` and the master PRD were updated to current Phase 38.
* Upstream file layout conflicts with AI OS module ownership: do not apply upstream files wholesale. Use the AI OS modules named in the session stubs as targets, record superseded hunks in Session 10, and only copy policy/content where the resolved plan explicitly says `ADOPT`.
* Earlier "already present" assumptions were corrected: Dream health metadata, Dream engine selection, graph/yolo chat decoupling, dashboard Dream engine UX, request-time Hermes/Graphify Windows CLI resolution, Host-header validation, and model catalog additions are real port work.

***

## Resolved Decisions

1. LICENSE: adopt upstream v2.8.1 license terms. Preserve or update AI OS NOTICE boundaries for inherited and third-party materials.
2. Voice provider and cost: use upstream OpenAI Realtime as the default speech layer. Honor `OPENAI_BASE_URL` for OpenAI-compatible local or proxy endpoints and pass provider keys by environment only.
3. Config location: adapt to current AI OS settings and paths. Browser setup persists through `ai-os-config` with legacy migrations; private Dream files use the existing `~/.ai-os` primary root with `~/.claude-os` read compatibility; new engine settings must go through AI OS config helpers rather than upstream raw `claude-os.dream.engine`.
4. Dream engine ownership: keep AI OS setup/config and Dream runner modules as the source of truth. Port upstream setup and dashboard engine controls onto that same backing store.
5. Model catalog policy: keep AI OS defaults as active defaults. Add upstream model names as options where provider readiness can represent them; unavailable or unverified upstream names may appear only as disabled or explanatory options.

***

## Reference Material

The upstream comparison lives in `/home/aiwithapex/projects/claudeos/`.

| Artifact              | Path                                                                           |
| --------------------- | ------------------------------------------------------------------------------ |
| v2.7 full tree        | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/`                           |
| v2.8.1 full tree      | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/`                         |
| Full line patch       | `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.full.patch`       |
| Stat                  | `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.stat.txt`         |
| Name-status           | `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.name-status.txt`  |
| Summary               | `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.summary.txt`      |
| Human findings report | `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1_diff_findings.md` |

The full patch is 8,091 lines. All 39 changed paths are accounted for: 21 added, 18 modified, 0 deleted.

***

## Upstream Changed-Path Ledger

For added files, the v2.8.1 path is the whole-file source of truth. For modified files, the patch line identifies the start of the file diff in the full patch.

| Changed path                             | v2.7 source                                                                         | v2.8.1 source                                                                                | Patch line | Owner                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------: | -------------------------- |
| `.claude/launch.json`                    | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/.claude/launch.json`             | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/.claude/launch.json`                    |          1 | Session 06/08              |
| `.githooks/pre-commit`                   | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/.githooks/pre-commit`            | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/.githooks/pre-commit`                   |         18 | Session 06                 |
| `CHANGELOG.md`                           | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/CHANGELOG.md`                    | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/CHANGELOG.md`                           |         21 | Session 06                 |
| `CLAUDE.md`                              | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/CLAUDE.md`                       | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/CLAUDE.md`                              |         79 | Session 06                 |
| `INTEGRATION.md`                         | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/INTEGRATION.md`                         |        106 | Session 09 skip            |
| `LICENSE`                                | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/LICENSE`                         | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/LICENSE`                                |        164 | Session 06                 |
| `README.md`                              | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/README.md`                       | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/README.md`                              |        230 | Session 06                 |
| `docs/intelligence-view.md`              | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/docs/intelligence-view.md`              |        341 | Session 06/09              |
| `docs/local-voice-setup.md`              | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/docs/local-voice-setup.md`              |        406 | Session 06/08              |
| `package.json`                           | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/package.json`                    | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/package.json`                           |        521 | Sessions 01/06/08          |
| `scripts/aggregate.ts`                   | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/aggregate.ts`            | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/aggregate.ts`                   |        548 | Session 03                 |
| `scripts/graph-to-dashboard.sh`          | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/graph-to-dashboard.sh`   | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/graph-to-dashboard.sh`          |        999 | Session 06                 |
| `scripts/install-dream-cron.ts`          | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/install-dream-cron.ts`   | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/install-dream-cron.ts`          |       1002 | Session 04                 |
| `scripts/platform.ts`                    | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/platform.ts`                    |       1392 | Session 02                 |
| `scripts/run-dream.ts`                   | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/run-dream.ts`                   |       1468 | Session 07 audit/supersede |
| `scripts/seed-data.ts`                   | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/seed-data.ts`                   |       1740 | Session 01                 |
| `scripts/setup-graphify-brain.sh`        | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/setup-graphify-brain.sh` | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/setup-graphify-brain.sh`        |       1776 | Session 06                 |
| `scripts/setup.ts`                       | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/setup.ts`                | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/setup.ts`                       |       1779 | Session 04                 |
| `scripts/webp-file-type-art.sh`          | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/scripts/webp-file-type-art.sh`   | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/webp-file-type-art.sh`          |       1836 | Session 06                 |
| `src/components/agent-core-3d.tsx`       | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/agent-core-3d.tsx`       |       1839 | Session 09 skip            |
| `src/components/hermes-mind-3d.tsx`      | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/hermes-mind-3d.tsx`      |       2096 | Session 09                 |
| `src/components/intelligence-portal.tsx` | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/intelligence-portal.tsx` |       2427 | Session 09                 |
| `src/components/oracle-plasma.tsx`       | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-plasma.tsx`       |       3341 | Session 09                 |
| `src/components/oracle-rider.tsx`        | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-rider.tsx`        |       3788 | Session 09                 |
| `src/components/oracle-sonar.tsx`        | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-sonar.tsx`        |       3926 | Session 09                 |
| `src/components/oracle-waveform.tsx`     | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-waveform.tsx`     |       4414 | Session 09                 |
| `src/components/stage-aurora.tsx`        | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/stage-aurora.tsx`        |       4859 | Session 09                 |
| `src/components/stage-cosmos.tsx`        | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/stage-cosmos.tsx`        |       5088 | Session 09                 |
| `src/lib/mind-map.ts`                    | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/lib/mind-map.ts`                    |       5333 | Session 09                 |
| `src/lib/synthetic-voice.ts`             | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/lib/synthetic-voice.ts`             |       5395 | Session 09                 |
| `src/routes/agents.hermes.tsx`           | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/src/routes/agents.hermes.tsx`    | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/routes/agents.hermes.tsx`           |       5472 | Sessions 01/06/09          |
| `src/routes/index.tsx`                   | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/src/routes/index.tsx`            | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/routes/index.tsx`                   |       5840 | Sessions 06/07             |
| `src/routes/memory.tsx`                  | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/src/routes/memory.tsx`           | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/routes/memory.tsx`                  |       6307 | Session 01                 |
| `src/routes/setup.tsx`                   | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/src/routes/setup.tsx`            | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/routes/setup.tsx`                   |       6323 | Session 07                 |
| `vite.config.ts`                         | `/home/aiwithapex/projects/claudeos/claude-os-v2.7/vite.config.ts`                  | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/vite.config.ts`                         |       6506 | Sessions 01/05/06/08/07    |
| `voice-lab/.env.example`                 | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/voice-lab/.env.example`                 |       7661 | Session 08                 |
| `voice-lab/README.md`                    | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/voice-lab/README.md`                    |       7674 | Session 08/06              |
| `voice-lab/index.html`                   | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/voice-lab/index.html`                   |       7715 | Session 08 skip            |
| `voice-lab/server.ts`                    | added                                                                               | `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/voice-lab/server.ts`                    |       7946 | Session 08                 |

***

## Patch Extraction Offsets

Use these offsets to pull any modified file diff from the full patch. For new files, prefer the whole v2.8.1 file directly.

| Upstream file                   | Patch line | Upstream file                            | Patch line |
| ------------------------------- | ---------: | ---------------------------------------- | ---------: |
| `.claude/launch.json`           |          1 | `scripts/run-dream.ts`                   |       1468 |
| `CHANGELOG.md`                  |         21 | `scripts/seed-data.ts`                   |       1740 |
| `CLAUDE.md`                     |         79 | `scripts/setup.ts`                       |       1779 |
| `INTEGRATION.md`                |        106 | `src/components/agent-core-3d.tsx`       |       1839 |
| `LICENSE`                       |        164 | `src/components/hermes-mind-3d.tsx`      |       2096 |
| `README.md`                     |        230 | `src/components/intelligence-portal.tsx` |       2427 |
| `docs/intelligence-view.md`     |        341 | `src/components/oracle-plasma.tsx`       |       3341 |
| `docs/local-voice-setup.md`     |        406 | `src/components/oracle-rider.tsx`        |       3788 |
| `package.json`                  |        521 | `src/components/oracle-sonar.tsx`        |       3926 |
| `scripts/aggregate.ts`          |        548 | `src/components/oracle-waveform.tsx`     |       4414 |
| `scripts/install-dream-cron.ts` |       1002 | `src/components/stage-aurora.tsx`        |       4859 |
| `scripts/platform.ts`           |       1392 | `src/components/stage-cosmos.tsx`        |       5088 |
| `src/lib/mind-map.ts`           |       5333 | `src/routes/agents.hermes.tsx`           |       5472 |
| `src/lib/synthetic-voice.ts`    |       5395 | `src/routes/index.tsx`                   |       5840 |
| `src/routes/memory.tsx`         |       6307 | `src/routes/setup.tsx`                   |       6323 |
| `vite.config.ts`                |       6506 | `voice-lab/.env.example`                 |       7661 |
| `voice-lab/README.md`           |       7674 | `voice-lab/index.html`                   |       7715 |
| `voice-lab/server.ts`           |       7946 |                                          |            |

Example extraction:

```bash
awk 'NR>=6506 && NR<7661' \
  /home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.full.patch
```

***

## Divergence Reality Check

| File                            | AI OS | v2.7 | v2.8.1 | AI OS shape                                                                                                       |
| ------------------------------- | ----: | ---: | -----: | ----------------------------------------------------------------------------------------------------------------- |
| `scripts/aggregate.ts`          |    23 | 3548 |   3744 | Thin re-export over `scripts/lib/aggregate-orchestration.ts` plus about 50 `scripts/lib/*` modules                |
| `scripts/install-dream-cron.ts` |   352 |  352 |    571 | Still essentially v2.7, macOS `launchctl` only                                                                    |
| `scripts/setup.ts`              |   347 |  307 |    327 | Diverged independently                                                                                            |
| `src/routes/agents.hermes.tsx`  |    16 | 7581 |   7694 | Thin route to `src/components/hermes/hermes-read-only-page.tsx`, which actually hosts interactive chat plus admin |
| `src/routes/index.tsx`          |   400 | 4122 |   4519 | Refactored into components                                                                                        |
| `src/routes/setup.tsx`          |    36 | 3416 |   3572 | Thin route to `src/components/setup/setup-modal.tsx`                                                              |
| `src/routes/memory.tsx`         |   821 |  652 |    655 | Diverged independently                                                                                            |
| `vite.config.ts`                |  1277 | 3797 |   4623 | Reworked dev control plane with loopback guards                                                                   |

Two structural facts dominate the port:

1. AI OS Dream already exceeds upstream's `scripts/run-dream.ts`. AI OS has `scripts/lib/dream/` modules for execution, lifecycle, material readiness, request building, privacy, observability, plus `scripts/scheduler-runner.ts` and `scripts/dashboard-dream-run.ts`. Do not port `scripts/run-dream.ts` wholesale. Audit it for missing engine/readiness nuance and keep AI OS Dream runners as the execution source.
2. AI OS Hermes is already fully interactive and more mature than upstream's v2.8.1 baseline. `src/routes/agents.hermes.tsx` routes to a Hermes page with chat, composer, message list, thread sidebar, and admin panel. Chat executes through `/__hermes_chat` in `scripts/lib/hermes-admin-bridge.ts`, streams SSE output, handles provider auth, abort, timeout, and event parsing, and is exposed by `src/hooks/use-hermes-admin.ts` as `admin.chat`. Therefore the Intelligence/voice work wires into the existing chat stream; it is not a disconnected demo or replacement chat backend.

***

## Verdict Legend

* `PORT`: net-new in upstream, missing here, applies with light adaptation.
* `ADAPT`: port the idea into AI OS module layout; do not copy the file.
* `ADOPT`: accept upstream policy/content as the target and apply it to AI OS.
* `VERIFY`: mechanical parity check without new behavior unless evidence fails.
* `SKIP - present/superseded`: AI OS already has an equal or better version.
* `SKIP - N/A`: not applicable to this fork.

***

## Phase Scope Summary

### Tier 0 - Trivial Parity and Correctness

* 0.1 `PORT`: fix `src/routes/memory.tsx` hardcoded source count by replacing `sources: 3` with `ALL_SOURCES.length` so Pinecone-on and Pinecone-off states render real counts.
* 0.2 `PORT`: add cross-platform `scripts/seed-data.ts` and update `package.json` `seed:data` to use it, preserving `src/data/live-data.example.json` as the AI OS seed source.
* 0.3 `PORT`: decouple Hermes chat `graph` from `yolo` in `scripts/lib/hermes-admin-bridge.ts`, chat send options, hook payloads, and Knowledge Graph grounded chat.

### Tier 1 - Cross-Platform and Windows Core

* 1.1 `ADAPT`: create `scripts/lib/platform.ts`, optionally re-export `scripts/platform.ts`, and centralize `toPosix`, app-data path, CLI lookup, and venv binary helpers.
* 1.2 `ADAPT`: port Windows-aware aggregation into AI OS modules and surface `dream.healthStatus` plus `dream.fixHint` through live data from AI OS Dream observability.
* 1.3 `ADAPT`: add real Windows Task Scheduler support for Dream cron while scheduling AI OS runners, not upstream `scripts/run-dream.ts`.
* 1.4 `ADAPT`: add Windows setup scheduling and readiness-based headless-auth warnings to `scripts/setup.ts`.
* 1.5 `ADAPT`: harden request-time Hermes/Graphify CLI resolution and Vite Host-header validation.

### Tier 2 - Docs, License, Metadata

* 2.1 `ADOPT`: update `LICENSE`, `NOTICE`, and `package.json` to upstream v2.8.1 license posture while preserving required notices.
* 2.2 `ADAPT`: update README, AGENTS, CLAUDE, GEMINI, local voice docs, and privacy language to match AI OS behavior and real endpoints.
* 2.3 `ADAPT`: add a CHANGELOG or phase-log entry describing the AI OS port.
* 2.4 `PORT`: add `.claude/launch.json` voice-lab target with the voice broker.
* 2.5 `VERIFY`: ensure expected executable bits remain on upstream mode-change files and record missing `scripts/webp-file-type-art.sh` as no-op unless intentionally reintroduced.
* 2.6 `ADAPT`: keep AI OS defaults while adding upstream model names as optional supported or disabled/explanatory choices.

### Tier 3 - Dream, Voice, and Intelligence

* 3.1 `SKIP - superseded`: do not adopt upstream `scripts/run-dream.ts`; audit it for missing engine/readiness nuance.
* 3.2 `ADAPT`: add local OpenAI Realtime token broker in `voice-lab/server.ts`, `voice` script, `/__start_voice`, `.env.example`, and base URL support.
* 3.3 `ADAPT`: add Hermes Intelligence portal and visualizers under AI OS conventions, wired to real `admin.chat.send(...)` and `/__hermes_chat` SSE.
* 3.4 `ADAPT`: add dashboard Dream engine switcher and health-aware empty state keyed by live-data Dream health.
* 3.5 `PORT`: add setup Dream engine step after Dream cadence, persisted through AI OS config paths.

***

## Already Present Or Superseded

| Upstream v2.8.1 feature                        | Disposition in AI OS                                                                                                                |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `scripts/run-dream.ts` engine-agnostic runner  | Superseded by `scripts/lib/dream/**`, `scripts/scheduler-runner.ts`, and `scripts/dashboard-dream-run.ts`; audit only in Session 07 |
| Setup Dream cadence step                       | Present in `src/components/setup/step-dream.tsx`; this does not cover Dream engine selection                                        |
| Loopback-only privileged endpoints             | Already present in Vite local endpoint guards; Session 05 still adds Host-header hardening                                          |
| `X-Claude-OS-Token` gating                     | Already present in `vite.config.ts` token and write endpoint guards                                                                 |
| `/__run_dream` dashboard trigger               | Already present, but Session 07 must route engine selection through this AI OS execution path                                       |
| Dream health metadata                          | Not covered; real port in Sessions 03 and 07                                                                                        |
| Dream engine selection                         | Not covered; real port in Session 07                                                                                                |
| Hermes/Graphify runtime Windows CLI resolution | Not covered; real port in Session 05                                                                                                |
| `agent-core-3d.tsx`                            | Skip; obsolete/dead per upstream `INTEGRATION.md`                                                                                   |
| `INTEGRATION.md`                               | Skip; internal merge notes, not shippable                                                                                           |

***

## Technical Considerations

### Architecture

AI OS remains the durable architecture. Upstream v2.8.1 changes are routed into existing AI OS script libraries, setup/config helpers, scheduler runners, Vite middleware, Hermes chat/admin hooks, Dream observability modules, Knowledge Graph bridge modules, and component conventions. Upstream standalone demo surfaces are not product surfaces unless a session explicitly adapts them.

### Technologies

* Bun package manager, scripts, and tests.
* React 19 and TanStack Start routes.
* Vite 8 local middleware and loopback control-plane guards.
* AI OS scheduler and Dream runner modules.
* Hermes admin bridge and SSE chat stream.
* OpenAI Realtime token broker with `OPENAI_BASE_URL` override.
* Radix UI and existing AI OS component conventions.

### Risks

* Upstream divergence can hide real behavior gaps: mitigate with hunk-by-hunk reconciliation and target-module tests.
* Windows scheduling and CLI resolution can fail from quoting or path drift: mitigate with platform helper tests, mocked spawn argv coverage, and real Windows verification where possible.
* Voice broker adds a provider transfer path: mitigate with env-only keys, loopback and cross-origin guards, and docs that name the transfer clearly.
* Docs can overclaim features before implementation: mitigate with docs sweeps and reference-mode phrase tests during release closeout.
* New visual/voice surfaces can become demos instead of product behavior: mitigate by wiring all speech and visualizers to the real Hermes chat backend.

### Relevant Considerations

* \[P01] Old `claude-os-*` naming: preserve compatibility aliases and migrate settings through AI OS paths instead of copying raw upstream storage.
* \[P04] Hermes bridge guardrails must stay intact: keep loopback, token, admin, body-size, and path safety protections on all bridge changes.
* \[P11] Scheduler state/log privacy boundary: scheduled Dream and aggregate status surfaces may expose only bounded status metadata.
* \[P21] Claude OAuth material stays script-only: provider credentials and bearer headers must not enter browser state, generated data, or logs.
* \[P26] Knowledge Graph contract alignment: Graphify and Hermes grounding changes must move through the shared graph contract.
* \[P00] Stack conventions: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints.

***

## Completeness Audit Requirements

Path coverage is done at planning time: all 39 changed paths have an explicit source path and owner in this PRD.

Content coverage must be proven during implementation. The largest modified files cannot be guaranteed line-complete by feature-level reading alone:

* `vite.config.ts` +826 upstream lines.
* `src/routes/index.tsx` +397 upstream lines.
* `scripts/install-dream-cron.ts` +219 upstream lines.
* `scripts/aggregate.ts` +196 upstream lines.
* `src/routes/setup.tsx` +156 upstream lines.
* `src/routes/agents.hermes.tsx` +113 upstream lines.

Before closing each modified-file item, the implementer must extract that file's diff from the full patch and record a hunk-by-hunk disposition. Use only these statuses:

* `ported`
* `already-present`
* `superseded`
* `skipped-resolved-policy`
* `skipped-n/a`

Every `superseded` entry must name the AI OS replacement file by absolute path. Every `skipped-resolved-policy` entry must name the resolved policy that made the hunk unnecessary. Added files carry no hidden-hunk risk but still require a whole-file disposition of ported, superseded, or skipped.

Store the hunk reconciliation record next to these Phase 38 artifacts, in a PR description, or in the Session 10 closeout. Do not mark Phase 38 complete until all 39 changed paths have dispositions.

***

## Recommended Execution Order

1. Session 01, Tier 0: memory fix, seed data, graph/yolo chat semantics.
2. Session 02, Tier 1.1: shared platform helper to unblock later platform work.
3. Sessions 03 through 05, Tier 1.2 to 1.5: Windows aggregate, Dream scheduler, setup readiness, request-time bridge resolution, and Host-header guard.
4. Session 06, Tier 2: docs/license/metadata after behavior exists so docs are true; adopt upstream license, keep AI OS model defaults, add upstream model options where readiness supports them.
5. Session 07, Tier 3 Dream product work: dashboard engine/health UX and setup Dream engine selection before voice if engine choice affects scheduled runs.
6. Sessions 08 and 09, Tier 3 voice and Intelligence: Realtime token broker, then portal and visualizers wired to the live `/__hermes_chat` stream.
7. Session 10: hunk reconciliation and release gate.

Track ported items against the Suggested Test Checklist in `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1_diff_findings.md`, including cross-platform, macOS regression, Dream engine, docs sweep, voice, security, build, and lint checks. Run `bun run lint` and `bun run build` after each tier.

***

## Success Criteria

Phase complete when:

* [ ] All 10 sessions completed and validated.
* [ ] Every shipped feature satisfies the non-negotiable delivery bar for real execution, visible result, recovery path, tests, and platform proof.
* [ ] Tier 0 parity fixes, platform helpers, aggregate/Dream health, scheduling, setup, and runtime bridge hardening run through real AI OS paths.
* [ ] Resolved license, docs, voice, config-path, Dream ownership, and model catalog policies are implemented without open-decision markers.
* [ ] Voice and Intelligence portal behavior use the real Hermes chat backend and real Realtime broker path where configured.
* [ ] Every upstream changed path and relevant hunk has a recorded disposition.
* [ ] Final docs and product surfaces do not claim features that are not implemented and proven.
* [ ] `bun run lint`, `bun run build`, targeted tests, docs sweeps, security checks, and relevant browser checks pass or document exact non-port blockers.

***

## Dependencies

### Depends On

* Phase 37: AI Rogue Visual Asset Finishing.
* Claude OS v2.7 to v2.8.1 upstream comparison artifacts.

### Enables

* Next workflow command: `plansession`.
* Future scoped scheduler, AI tool parity, or release-hardening phases if Session 10 records follow-up work.


---

# 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_38/prd_phase_38.md?ask=<question>&goal=<endgoal>
```

`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.