> 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/phase38-session01-tier-0-parity-fixes/spec.md).

# Session Specification

**Session ID**: `phase38-session01-tier-0-parity-fixes` **Phase**: 38 - Claude OS v2.8.1 Semantic Port **Status**: Not Started **Created**: 2026-06-29

***

## 1. Session Overview

This session ports the Tier 0 Claude OS v2.8.1 parity fixes that are small in surface area but block later phase work from starting on an inaccurate baseline. It fixes the Memory source count, replaces the POSIX-only seed-data command with a cross-platform Bun script, and decouples Hermes chat Graphify toolset selection from the `--yolo` execution flag.

The work is next because the analyzer reports phase 38 has no active session and all phase 38 stubs are unstarted, while the phase PRD and session stubs list Session 01 as the first upcoming session. Later platform, aggregate, bridge, voice, and Intelligence sessions either depend on this baseline directly or should not inherit the current graph/yolo coupling.

The implementation must preserve AI OS architecture: route changes stay in the existing Memory route, script behavior stays under Bun scripts, and Hermes chat continues through the existing admin bridge, hook, chat types, and Knowledge Graph grounding path. No broader Tier 1, voice, Dream engine, or Intelligence portal work belongs in this session.

***

## 2. Objectives

1. Replace the hardcoded Memory source count with the real available source list length for Pinecone-off and Pinecone-on states.
2. Add a cross-platform `seed:data` implementation that creates `src/data/live-data.json` from the AI OS example only when missing.
3. Decouple Hermes chat `graph` and `yolo` payload semantics so all four boolean combinations produce the correct command arguments.
4. Prove the changed behavior with focused route, script, bridge, hook, and Knowledge Graph tests plus seed-data smoke verification.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase37-session06-g7-player-animation` - Completed Phase 37 and left Phase 38 ready to start.

### Required Tools Or Knowledge

* Bun 1.3.14 from `.bun-version` and `package.json` scripts.
* Vitest route, hook, bridge, and script test patterns.
* Upstream v2.8.1 references under `/home/aiwithapex/projects/claudeos/`.
* AI OS local admin bridge guardrails and Knowledge Graph grounding contract.

### Environment Requirements

* Work from `/home/aiwithapex/projects/aios`.
* Keep generated `src/data/live-data.json` local and gitignored.
* Use faithful platform harnesses where native Windows verification is not available for seed-data behavior.

***

## 4. Scope

### In Scope (MVP)

* Memory users see a source-count tile derived from `ALL_SOURCES.length` for both Pinecone-off and Pinecone-on states.
* Operators running `bun run seed:data` get cross-platform create-if-missing behavior, no-op existing-file behavior, and a clear missing-source failure.
* Hermes chat callers can request `graph` and `yolo` independently through validated payloads, typed send options, hook serialization, and bridge argv composition.
* Knowledge Graph grounded chat explicitly requests Graphify with `{ toolsets: "graphify", yolo: true, graph: true }`.
* Focused tests cover visible Memory count behavior, seed-data create/no-op and failure paths, invalid payloads, and all graph/yolo argv combinations.

### Out Of Scope (Deferred)

* Shared platform helper foundation - Reason: owned by Session 02.
* Windows aggregate, Dream health, or Dream scheduling work - Reason: owned by Sessions 03 and 04.
* Runtime Host-header hardening - Reason: owned by Session 05.
* Voice broker or Intelligence portal work - Reason: owned by Sessions 08 and 09.
* A general user-facing Graphify toggle in the Hermes composer - Reason: the stub keeps graph as a programmatic send option unless product scope intentionally adds a broader toggle.

***

## 5. Technical Approach

### Architecture

Update the smallest owning modules for each behavior. `src/routes/memory.tsx` already computes `ALL_SOURCES` from the Pinecone detection state, so the source tile should use that value directly. `package.json` should call a new `scripts/seed-data.ts` script that uses Node/Bun filesystem APIs instead of shell syntax. Hermes chat should add `graph?: boolean` alongside `yolo?: boolean` from type definition through hook payload serialization and bridge validation, then compose `--yolo` and `-s graphify` independently in the existing `/__hermes_chat` path.

### Design Patterns

* Existing owner modules: Keeps behavior where current callers already look for Memory, seed-data, Hermes chat, and Knowledge Graph grounding.
* Schema-validated bridge inputs: Mirrors `readStrictYolo` and `readChatToolsets` so bad `graph` values are rejected before command execution.
* Idempotent local script writes: Seed data should create the missing generated file and otherwise leave existing local data untouched.
* Behavior-first focused tests: Existing route, hook, bridge, and Knowledge Graph tests already exercise the relevant public contracts.

***

## 6. Deliverables

### Files To Create

| File                                      | Purpose                                                                          | Est. Lines |
| ----------------------------------------- | -------------------------------------------------------------------------------- | ---------- |
| `scripts/seed-data.ts`                    | Cross-platform seed-data script with create, no-op, and missing-source behavior. | \~90       |
| `scripts/lib/__tests__/seed-data.test.ts` | Focused tests for seed-data create/no-op/failure behavior.                       | \~130      |

### Files To Modify

| File                                                                               | Changes                                                                       | Est. Lines |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------- |
| `package.json`                                                                     | Replace POSIX shell `seed:data` command with the Bun script.                  | \~1        |
| `src/routes/memory.tsx`                                                            | Use `ALL_SOURCES.length` instead of hardcoded `3`.                            | \~1        |
| `src/routes/__tests__/memory.test.tsx`                                             | Assert Memory source count for Pinecone-off and Pinecone-on states.           | \~35       |
| `src/components/hermes/chat/chat-types.ts`                                         | Add `graph?: boolean` to `HermesChatSendOptions`.                             | \~1        |
| `src/hooks/use-hermes-admin.ts`                                                    | Serialize validated `graph` payload options.                                  | \~10       |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`                                    | Cover `graph` serialization and invalid graph option rejection.               | \~35       |
| `scripts/lib/hermes-admin-bridge.ts`                                               | Validate `graph` and compose graph/yolo argv independently.                   | \~25       |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts`                                | Cover invalid graph and all graph/yolo argv combinations.                     | \~90       |
| `src/lib/knowledge-graph-hermes-grounding.ts`                                      | Send explicit `graph: true` for grounded Knowledge Graph chat.                | \~1        |
| `src/lib/__tests__/knowledge-graph-hermes-grounding.test.ts`                       | Assert Knowledge Graph send options include `graph: true`.                    | \~5        |
| `.spec_system/specs/phase38-session01-tier-0-parity-fixes/implementation-notes.md` | Record implementation decisions and verification evidence during `implement`. | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Memory source tile renders the real available source count for Pinecone-off and Pinecone-on states.
* [ ] `bun run seed:data` creates `src/data/live-data.json` from `src/data/live-data.example.json` when missing.
* [ ] `bun run seed:data` is a no-op when `src/data/live-data.json` already exists.
* [ ] Missing or unreadable `src/data/live-data.example.json` exits nonzero with actionable error output.
* [ ] Hermes chat accepts `graph` and `yolo` as independent booleans and rejects invalid values.
* [ ] Knowledge Graph grounded chat keeps Graphify behavior explicit.

### Testing Requirements

* [ ] Route tests cover both Memory source-count modes.
* [ ] Script tests cover seed-data create, no-op, and missing-source behavior.
* [ ] Bridge tests cover graph off/yolo off, graph on/yolo off, yolo on/graph off, both graph/yolo on, and invalid graph payloads.
* [ ] Hook and Knowledge Graph tests cover typed payload serialization.
* [ ] Targeted verification commands are run and recorded.

### Non-Functional Requirements

* [ ] Seed-data behavior is cross-platform and does not depend on POSIX shell commands.
* [ ] Hermes bridge guardrails stay intact: loopback, token, body-size, and schema validation continue to run before command execution.
* [ ] Product-facing Memory and Hermes surfaces do not expose diagnostics or implementation-only copy.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.

***

## 8. Implementation Notes

### Working Assumptions

* Session 01 is the next executable session: the analyzer reported `current_session: null`, phase 38 is `not_started`, and the phase PRD lists Session 01 as the upcoming session. Planning can proceed because the session stub has concrete source items, target paths, and acceptance criteria.
* Keep `graph` programmatic in this session: the session stub explicitly says to preserve graph as a programmatic send option unless a general graph UI toggle is intentionally added. Existing `HermesChatGrounding.sendOptions` already supports programmatic per-send behavior, so no user arbitration is needed.
* Place seed-data tests in `scripts/lib/__tests__/seed-data.test.ts`: the conventions allow script tests under `scripts/lib/__tests__/` or an equivalent script owner, and no existing seed-data test owner exists.

### Key Considerations

* Preserve generated-data boundaries: `src/data/live-data.example.json` is committed fallback data, while `src/data/live-data.json` is generated local data.
* Preserve the Hermes admin bridge threat model by adding `graph` validation without weakening token, loopback, body-size, or path checks.
* Keep Knowledge Graph contract updates together across grounding, chat send options, hook serialization, and bridge behavior.

### Potential Challenges

* Seed-data tests could mutate local generated data: use temporary directories or dependency-injected paths to keep repository data untouched.
* Bridge argv assertions may be brittle: assert the spawned argv slices for the four relevant graph/yolo combinations rather than unrelated command details.
* Memory source-count tests need both Pinecone modes: mock live-data detection separately for Pinecone absent and Pinecone present states.

### Relevant Considerations

* \[P00] **Stack conventions**: Use Bun, TypeScript, Vite, React 19, and Vitest patterns already present in the repository.
* \[P04] **Hermes bridge guardrails must stay intact**: The graph/yolo change must preserve loopback, token, no-clobber, and disabled-by-default admin mode.
* \[P26] **Knowledge Graph contract alignment**: Graph grounding, send options, bridge payloads, and tests must move together.
* \[P21] **Claude OAuth material stays script-only**: Do not add token-shaped strings, bearer headers, or credential material to browser state, logs, or generated data.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Seed-data writes must be idempotent, avoid clobbering local generated data, and fail clearly when the committed example is unavailable.
* Hermes chat payload handling must schema-validate `graph` and `yolo` at the bridge boundary before command execution.
* User-facing Memory and Hermes surfaces must remain product-facing; diagnostics belong in tests and implementation notes.

***

## 9. Testing Strategy

### Unit Tests

* Extend `src/routes/__tests__/memory.test.tsx` for Pinecone-off and Pinecone-on source counts.
* Add `scripts/lib/__tests__/seed-data.test.ts` for create, no-op, and missing-source behavior.
* Extend `scripts/lib/__tests__/hermes-admin-bridge.test.ts` for invalid graph and all graph/yolo argv combinations.
* Extend `src/hooks/__tests__/use-hermes-admin.test.tsx` and `src/lib/__tests__/knowledge-graph-hermes-grounding.test.ts` for graph option serialization.

### Integration Tests

* Exercise `bun run seed:data` against the repository command path and a temporary generated-data scenario.
* Exercise the real `registerHermesAdminBridge` route handler with mocked spawn in `scripts/lib/__tests__/hermes-admin-bridge.test.ts`.

### Runtime Verification

* Run targeted Vitest files for Memory, seed-data, Hermes admin bridge, use-Hermes admin, and Knowledge Graph grounding.
* Run `bun run seed:data` after confirming it does not overwrite an existing `src/data/live-data.json`.
* Run `bun run lint` or record exact unrelated blockers if full lint cannot run in the implementation session.

### Edge Cases

* Pinecone detection absent, present through `pineconeIndexes`, and present through `hasKey`.
* Destination live-data file exists and must not be overwritten.
* Source example is missing or unreadable.
* `graph` is omitted, false, true, or an invalid non-boolean value.
* `graph` and `yolo` are requested independently in all four combinations.

***

## 10. Dependencies

### Other Sessions

* Depends on: Phase 37 completion and Phase 38 PRD/session stubs.
* Depended by: `phase38-session02-platform-foundation` and all later Phase 38 sessions that assume Tier 0 parity has landed.

***

## Next Steps

Run the `implement` workflow step to begin 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/phase38-session01-tier-0-parity-fixes/spec.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.