> 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/phase16-session03-data-layer-demo-fixtures/spec.md).

# Session Specification

**Session ID**: `phase16-session03-data-layer-demo-fixtures` **Phase**: 16 - Hermes v2.3 Port Foundation **Status**: Complete **Created**: 2026-06-02

***

## 1. Session Overview

This session completes the Phase 16 client foundation for the expanded Hermes port. Session 02 added the missing bridge endpoints and write-safety machinery; this session makes those endpoints consumable from the AI OS client data layer with typed parsers, React Query hooks, admin mutation wrappers, and demo fixtures.

The work intentionally stays below the UI layer. It does not add new tabs, cards, modals, visual shell changes, or route composition. Instead, it gives Phases 17-20 a reliable contract for connections, profiles, Pantheon templates, mission state, documents, chat thread detail, image upload, mission writes, Pantheon sync, document writes, and Obsidian memory bridging.

The result should preserve the existing AI OS Hermes architecture: bridge payloads are parsed in `src/lib`, read state is exposed through `useHermes`, write state is exposed only through `useHermesAdmin`, and demo mode has bounded fixture data that can render the future expanded page with no local bridge.

***

## 2. Objectives

1. Add typed client read payloads and parsers for every new Session 02 read endpoint.
2. Add typed admin write payloads and parsers for every new Session 02 write endpoint.
3. Extend `useHermes` with React Query state for the new reads while preserving loading, offline, setup-required, endpoint-error, token-failure, and empty behavior.
4. Extend `useHermesAdmin` with admin-token mutation wrappers for the new writes, including duplicate-trigger prevention and scoped query invalidation.
5. Expand Hermes demo fixtures for the planned v2.3 domains without exposing private paths, prompts, credentials, or unbounded payloads.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the architecture decision, parity baseline, and guardrails for the v2.3 port.
* [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides the read and write bridge endpoints plus the write-safety contract this client data layer consumes.

### Required Tools/Knowledge

* Bun 1.3.14 through the repo-local `package.json` scripts.
* React 19.2.0 and `@tanstack/react-query` 5.100.10.
* Existing Hermes hooks in `src/hooks/use-hermes.ts` and `src/hooks/use-hermes-admin.ts`.
* Existing Hermes parser style in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`.
* Phase 16 PRD and Session 03 stub under `.spec_system/PRD/phase_16/`.

### Environment Requirements

* The AI OS repo is available at `/home/aiwithapex/projects/aios`.
* The v2.3 source root is readable at `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`.
* No dev server is required for this session; focused Vitest, typecheck, lint, and ASCII checks are enough.

***

## 4. Scope

### In Scope (MVP)

* The local operator can consume Hermes connections from the client data layer - add typed `connections` parsing and query state without exposing secret values.
* The local operator can consume Hermes profiles after token approval - add typed `profiles` parsing and token-gated query state.
* The local operator can consume Pantheon templates - add typed template parsing and demo fixtures aligned with the install/create model.
* The local operator can consume mission state - add typed mission parsing, query state, demo fixtures, and admin mutation response handling.
* The local operator can consume document state - add typed document list and trash parsing, a file access helper, demo fixtures, and admin mutation response handling.
* The local operator can consume chat thread detail - add typed session-detail parsing and demo fixture support for future Chat tab rendering.
* The local operator can use all write paths only through `useHermesAdmin` - image upload, mission create/optimize/tick/clear, Pantheon sync, document delete/restore/purge, and Obsidian bridge wrappers.
* The next UI sessions can rely on tests - add parser and hook coverage for malformed payloads, token gating, offline behavior, duplicate writes, and cache invalidation.

### Out of Scope (Deferred)

* Hermes visual shell, global status pill, tabs, cards, modals, and layout - *Reason: owned by Phases 17-20.*
* Backend bridge endpoint handlers or security primitive changes - *Reason: Session 02 already landed this layer.*
* Mnemosyne 3D memory derivation and rendering - *Reason: owned by Phase 18 Session 02.*
* Production availability for local Hermes admin writes - *Reason: local admin bridge remains dev-only and explicitly gated.*
* Public Trend Finder source collection or extension data work - *Reason: unrelated to Hermes local-agent telemetry.*

***

## 5. Technical Approach

### Architecture

Extend the existing Hermes data layer in place. Read response interfaces and runtime parsers belong in `src/lib/hermes-types.ts`; admin write request and response interfaces plus parsers belong in `src/lib/hermes-admin-types.ts`. `useHermes` owns browser read state and uses React Query query keys for cache identity. `useHermesAdmin` owns all write operations and is the only hook that holds the local token for admin-gated mutation calls.

Demo fixtures stay in `src/lib/hermes-demo-data.ts` and should use the same typed payloads as live data. Demo values must be clearly fixture-only, bounded, and sanitized so later UI sessions can render complete surfaces without requiring a Hermes install or bridge.

### Design Patterns

* Existing parser helpers: Reuse `readRecord`, `readArray`, `readString`, `readNumber`, `readBoolean`, and literal readers instead of adding a second validation framework.
* React Query query views: Preserve the existing `HermesQueryView<T>` state mapping for loading, empty, error, offline, token-failure, and idle states.
* Admin mutation views: Extend `HermesAdminMutationView<T>` and domain action groups instead of exposing raw mutation objects to UI components.
* Success-only invalidation: Avoid optimistic cache mutation for local admin writes; invalidate affected read queries only after successful mutation responses.

### Technology Stack

* React 19.2.0
* `@tanstack/react-query` 5.100.10
* TypeScript 6.0.3
* Vitest 4.1.6 with happy-dom
* Bun 1.3.14

***

## 6. Deliverables

### Files to Create

| File                                     | Purpose                                                           | Est. Lines |
| ---------------------------------------- | ----------------------------------------------------------------- | ---------- |
| `src/lib/__tests__/hermes-types.test.ts` | Focused parser and demo fixture tests for expanded read payloads. | \~180      |

### Files to Modify

| File                                            | Changes                                                                                                                  | Est. Lines |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `src/lib/hermes-types.ts`                       | Add read payload types and parsers for connections, profiles, templates, session detail, missions, documents, and trash. | \~260      |
| `src/lib/hermes-admin-types.ts`                 | Add admin write request/response types and parsers for image, mission, sync, document, and Obsidian writes.              | \~220      |
| `src/hooks/use-hermes.ts`                       | Add query keys, options, result fields, read queries, token gating, and document file helper.                            | \~220      |
| `src/hooks/use-hermes-admin.ts`                 | Add domain mutation groups, duplicate-trigger prevention, and query invalidation for new writes.                         | \~280      |
| `src/lib/hermes-demo-data.ts`                   | Add bounded fixture data for expanded domains and export it through `HERMES_DEMO_DATA`.                                  | \~240      |
| `src/lib/__tests__/hermes-admin-types.test.ts`  | Cover new admin parsers and malformed payload rejection.                                                                 | \~140      |
| `src/hooks/__tests__/use-hermes.test.tsx`       | Cover new read queries, token gating, offline states, and malformed payloads.                                            | \~180      |
| `src/hooks/__tests__/use-hermes-admin.test.tsx` | Cover new admin actions, duplicate prevention, invalidation, and disabled/token/offline states.                          | \~220      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Every Session 02 read endpoint has a typed parser and a `useHermes` query or helper.
* [ ] Token-gated reads do not execute until the token handshake succeeds.
* [ ] Every Session 02 write endpoint has a typed parser and a `useHermesAdmin` mutation wrapper.
* [ ] All writes remain unavailable when offline, token-missing, or admin disabled.
* [ ] Demo fixtures include connections, profiles, templates, missions, documents, document trash, and chat thread detail.

### Testing Requirements

* [ ] Parser tests reject malformed read and write payloads.
* [ ] Hook tests cover loading/success/empty/error/offline/token-failure states for new reads.
* [ ] Hook tests cover duplicate write prevention and success-only query invalidation for new writes.
* [ ] Focused Vitest commands pass.

### Non-Functional Requirements

* [ ] No secret values, auth payloads, raw prompts, private transcripts, command output, credentials, or unredacted local paths are introduced into demo fixtures.
* [ ] Query keys are deterministic and bounded.
* [ ] Admin writes do not optimistically mutate cached read data.
* [ ] Existing Hermes read-only behavior remains compatible.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `bun run typecheck` passes.
* [ ] Focused Vitest coverage passes for Hermes parser and hook tests.
* [ ] `bun run lint` passes or any unrelated existing lint failures are documented.

***

## 8. Implementation Notes

### Key Considerations

* The bridge payload shapes in `scripts/lib/hermes-dev-bridge.ts` and `scripts/lib/hermes-admin-bridge.ts` are the target contract for this session.
* Keep `useHermesAdmin` as the only sanctioned write path. UI code in later sessions should not call bridge write endpoints directly.
* Treat document file access separately from JSON queries because `/__hermes_documents/file` streams file bytes, not JSON.
* Preserve existing query state semantics so current Hermes sections do not regress while new fields are added.

### Potential Challenges

* Read sensitivity mismatch: Some new reads are public bridge reads and others are token-gated. Mitigation: model each query's `enabled` state explicitly and test that sensitive calls wait for token success.
* Mutation group sprawl: The admin hook can become hard to scan. Mitigation: group actions by domain and keep request builders small and typed.
* Demo fixture overreach: v2.3 demo data includes rich local-agent examples. Mitigation: keep data bounded, clearly demo-only, and free of real-looking secrets or private path details.
* Cache staleness after writes: Later UI sessions depend on fresh reads. Mitigation: invalidate only affected query keys after successful mutation responses.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: All new write wrappers must call admin-gated endpoints through `useHermesAdmin` with the local token.
* \[P08] **Local agent privacy/readiness boundary**: Browser data must not expose raw paths, prompts, transcripts, logs, credentials, command output, or auth payloads.
* \[P02] **Extension payloads and demo labels stay bounded**: Although this is a host Hermes session, the same bounded fixture discipline applies to demo payloads.
* \[P01] **Extract pure functions, then test, then wire**: Add parser/type coverage before relying on hook state.
* \[P00] **Stack conventions**: Stay within Bun, Vite, TanStack Start, React, and local testing conventions.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Sensitive reads accidentally run before token success or while offline.
* Admin writes can be double-triggered or leave stale query data after success.
* Demo fixtures can accidentally look like private local data or grow without bounds.
* Parser failures can collapse whole hook state without explicit error mapping.

***

## 9. Testing Strategy

### Unit Tests

* Add read parser tests for valid and malformed connections, profiles, templates, session detail, missions, documents, and trash payloads.
* Extend admin parser tests for image upload, mission write/clear, Pantheon sync, document delete/restore/purge, and Obsidian responses.
* Validate the expanded demo data parses through the same parser functions used for bridge payloads.

### Integration Tests

* Extend `useHermes` hook tests to verify query enablement, token-gated reads, offline state, empty state, and malformed payload error mapping.
* Extend `useHermesAdmin` hook tests to verify action availability, duplicate prevention, success-only invalidation, and disabled/token/offline states.

### Manual Testing

* Inspect the expanded `HERMES_DEMO_DATA` export for fixture-only labels and no private path leakage.
* Confirm the existing Hermes route still renders current read-only sections after hook result shape expansion.

### Edge Cases

* Missing token after ready status.
* Offline browser before any query runs.
* Empty profiles, missions, documents, and trash lists.
* Malformed mission goal, document, and admin response payloads.
* Duplicate admin actions while a mutation is in flight.
* Document filenames requiring URL encoding for file access.

***

## 10. Dependencies

### External Libraries

* `@tanstack/react-query`: Existing query and mutation state layer.
* `@testing-library/react`: Existing hook test harness.
* `vitest`: Existing unit test runner.

### Internal Dependencies

* `scripts/lib/hermes-dev-bridge.ts` - Source of truth for read payload shapes.
* `scripts/lib/hermes-admin-bridge.ts` - Source of truth for admin response shapes and write endpoint behavior.
* `src/hooks/use-hermes.ts` - Existing read hook extension point.
* `src/hooks/use-hermes-admin.ts` - Existing write hook extension point.
* `src/lib/hermes-demo-data.ts` - Existing demo fixture extension point.

### Other Sessions

* **Depends on**: `phase16-session01-guardrails-architecture-parity-baseline`, `phase16-session02-backend-endpoint-parity-write-safety`
* **Depended by**: Phase 17 Session 01, Phase 17 Session 02, Phase 17 Session 03, Phase 18, Phase 19, and Phase 20 Hermes parity sessions.

***

## Next Steps

Run the `implement` workflow step to begin AI-led implementation. After a successful `plansession` run, `implement` is always the next workflow command.


---

# 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/phase16-session03-data-layer-demo-fixtures/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.