> 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/phase31-session03-app-data-and-mutation-boundary/spec.md).

# Session Specification

**Session ID**: `phase31-session03-app-data-and-mutation-boundary` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24

***

## 1. Session Overview

This session makes the shared AI OS app runtime safe for the public Cloudflare Pages demo. The app must read committed frozen demo assets instead of local dev middleware, and the shared controls that can refresh, run, save, set up, poll, or administer local systems must become read-only or unavailable before they can request any `/__*` bridge endpoint.

It is next because Session 01 added the public-demo flag and demo-pages build branch, and Session 02 added the committed `/demo/*` snapshot assets that this session must consume. Without this boundary, the real route tree can still mount shared hooks that try to call loopback-only middleware on a public static host.

The implementation stays in the host data, identity, setup, status, and shared mutation-control layer. Deep agent-route conversion, Knowledge Graph route polish, Trend Finder asset previews, AI Rogue route verification, Pages output packaging, and broad no-bridge browser QA remain later Phase 31 sessions.

***

## 2. Objectives

1. Load public demo LiveData from `/demo/live-data.snapshot.json` with fallback validation and no `/__live-data` request in public demo mode.
2. Use public demo identity and setup behavior that does not read private env, localStorage, `/__operator-photo`, or `/__just-installed`.
3. Disable shared aggregate, Dream, Trend Finder run, Creator Lens save, scheduler/source-setup, and status-pill bridge paths before any `/__token` or other `/__*` request can happen.
4. Add focused assertions proving public demo mode does not call the shared host bridge endpoints covered by this session.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase31-session01-demo-mode-foundation` - Provides `isBrowserPublicDemoMode()`, public-demo env parsing, extension visibility, and demo-pages build mode.
* [x] `phase31-session02-snapshot-exporter-and-fixtures` - Provides `demo-website/public/demo/live-data.snapshot.json`, snapshot metadata, graph fixtures, and privacy scan evidence.

### Required Tools Or Knowledge

* Public demo helper and tests in `src/lib/public-demo.ts` and `src/lib/__tests__/public-demo.test.ts`.
* LiveData validation in `src/lib/validate-live-data.ts`.
* React Query patterns in `src/lib/use-live-data.ts` and existing route tests.
* Public demo fixture boundary in `demo-website/README.md`.

### Environment Requirements

* Bun 1.3.14 project toolchain.
* `node_modules` installed.
* `demo-website/public/demo/live-data.snapshot.json` present and committed.

***

## 4. Scope

### In Scope (MVP)

* Public demo users can browse host routes from frozen snapshot data - update shared data loading and identity helpers.
* Public demo users see setup, refresh, run, source, scheduler, and admin actions as unavailable or browser-local only - guard shared hooks and visible shared controls.
* Public demo routes avoid local host bridge calls - add focused tests for the `/__live-data`, `/__time-saved-config`, `/__just-installed`, `/__operator-photo`, `/__token`, `/__refresh_data`, `/__refresh_status`, and `/__run_dream` set.
* Trend Finder top-bar run controls are safe before route-specific work - return a disabled demo-only state from shared run context before token fetches.
* Status pills mounted in the global header are safe - avoid Hermes/OpenClaw bridge polling in public demo mode.

### Out Of Scope (Deferred)

* Extension-specific route data polish beyond shared mutation boundaries - Reason: Session 04 owns agent, Knowledge Graph, Trend Finder asset, and AI Rogue route conversion.
* Pages output packaging, `_headers`, `_redirects`, and deployment docs - Reason: Session 05 owns static output packaging and Pages scaffold.
* Full route matrix no-bridge Playwright coverage - Reason: Session 06 owns broad browser QA and privacy verification.
* Release copy polish and mobile tuning - Reason: Session 07 owns final public polish and documentation.
* New hosted collection, scraping, scheduler, chat, upload, or admin behavior - Reason: public demo v1 is static and read-only.

***

## 5. Technical Approach

### Architecture

Extend the existing public-demo helper as the single browser flag source. Keep the normal local and Worker behavior unchanged when `VITE_AI_OS_PUBLIC_DEMO` is absent or invalid. Shared data hooks should branch early in public demo mode, before constructing bridge requests, so React Query, button click handlers, polling intervals, and route mount effects cannot contact loopback-only endpoints.

`useLiveData()` should fetch `/demo/live-data.snapshot.json` in public demo mode and continue validating through `validateLiveData()`. If the committed snapshot cannot load or parse, it should fall back to `DEFAULT_LIVE_DATA` through the same error-resilient React Query behavior without retrying a private bridge endpoint.

Shared mutation hooks should expose disabled/demo states that existing buttons can render without changing their shape. Where a route uses direct setup or identity helpers, public demo mode should resolve to explicit public values and browser-local or unavailable behavior rather than private env or persisted local operator values.

### Design Patterns

* Early public-demo guard: Prevents bridge URLs from being requested at all.
* Parser-backed data boundary: Keeps snapshot loading aligned with existing LiveData validation.
* Existing hook return shapes: Lets buttons and route components render safe states without route-wide rewrites.
* Product-facing unavailable copy: Makes hosted limitations clear without showing diagnostics as the product experience.

***

## 6. Deliverables

### Files To Create

| File                                                                                          | Purpose                                      | Est. Lines |
| --------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------- |
| `.spec_system/specs/phase31-session03-app-data-and-mutation-boundary/implementation-notes.md` | Implementation evidence log for this session | \~120      |

### Files To Modify

| File                                                          | Changes                                                                                      | Est. Lines |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
| `src/lib/public-demo.ts`                                      | Add public demo endpoint, identity, and unavailable-control helpers                          | \~60       |
| `src/lib/use-live-data.ts`                                    | Fetch `/demo/live-data.snapshot.json` in public demo mode and avoid `/__live-data`           | \~45       |
| `src/lib/time-saved.ts`                                       | Skip `/__time-saved-config` in public demo mode and keep browser-local/default overlays only | \~30       |
| `src/lib/operator-profile.ts`                                 | Resolve public demo identity without private env, localStorage, or `/__operator-photo`       | \~45       |
| `src/components/app-sidebar.tsx`                              | Render public demo identity copy from the shared helper                                      | \~25       |
| `src/components/setup/use-setup-gating.ts`                    | Suppress auto-open and `/__just-installed` checks in public demo mode                        | \~40       |
| `src/components/setup/setup-modal.tsx`                        | Replace setup write flow with a public-demo unavailable/read-only state                      | \~50       |
| `src/routes/setup.tsx`                                        | Ensure direct `/setup` visits use the public-demo setup state                                | \~25       |
| `src/lib/use-aggregate-refresh.ts`                            | Return disabled demo-only aggregate controls before `/__token` or `/__refresh_data`          | \~45       |
| `src/lib/use-dream-run.ts`                                    | Return disabled demo-only Dream controls before `/__token` or `/__run_dream`                 | \~45       |
| `src/components/aggregate-refresh-button.tsx`                 | Render product-facing public demo unavailable copy                                           | \~20       |
| `src/components/dream-run-button.tsx`                         | Render product-facing public demo unavailable copy                                           | \~20       |
| `src/components/hermes/hermes-status-pill.tsx`                | Skip Hermes status polling in public demo mode                                               | \~35       |
| `src/components/openclaw-status-pill.tsx`                     | Skip OpenClaw status polling in public demo mode                                             | \~35       |
| `src/extensions/trend-finder/trend-finder-run-provider.tsx`   | Provide disabled demo-only run/lens controls before token fetch paths                        | \~50       |
| `src/extensions/trend-finder/hooks/use-trend-finder-run.ts`   | Add a public-demo disabled state or option that bypasses `/__token` and refresh polling      | \~70       |
| `src/extensions/trend-finder/hooks/use-creator-lens-draft.ts` | Keep Creator Lens edits browser-local or disabled in public demo mode without posting        | \~60       |
| `src/extensions/trend-finder/use-scheduler-status.ts`         | Support public demo no-autoload/no-mutation scheduler controls                               | \~45       |
| `src/extensions/trend-finder/source-setup.ts`                 | Add public demo unavailable source-setup behavior before token fetches                       | \~35       |
| `src/lib/__tests__/use-live-data.test.tsx`                    | Assert public demo snapshot fetch and no `/__live-data`                                      | \~60       |
| `src/lib/__tests__/time-saved-hook.test.tsx`                  | Assert no `/__time-saved-config` in public demo mode                                         | \~45       |
| `src/lib/__tests__/operator-profile.test.ts`                  | Assert public demo identity avoids env, storage, and `/__operator-photo`                     | \~50       |
| `src/components/setup/__tests__/use-setup-gating.test.ts`     | Assert no `/__just-installed` and no auto-open in public demo mode                           | \~55       |
| `src/lib/__tests__/use-aggregate-refresh.test.tsx`            | Assert aggregate controls do not fetch token or refresh endpoints in public demo mode        | \~50       |
| `src/lib/__tests__/use-dream-run.test.tsx`                    | Assert Dream controls do not fetch token or run endpoints in public demo mode                | \~50       |
| `src/routes/__tests__/root-component.test.tsx`                | Assert header status pills and Trend Finder top-bar run are no-bridge in public demo mode    | \~80       |
| `src/components/__tests__/aggregate-refresh-button.test.tsx`  | Assert public demo unavailable button copy and disabled state                                | \~35       |
| `src/components/__tests__/dream-run-button.test.tsx`          | Assert public demo unavailable button copy and disabled state                                | \~35       |
| `src/lib/__tests__/trend-finder-dashboard.test.tsx`           | Assert Trend Finder run/lens controls are disabled before `/__token` in public demo mode     | \~75       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Public demo mode fetches `/demo/live-data.snapshot.json` and does not fetch `/__live-data`.
* [ ] Public demo mode never calls `/__time-saved-config`, `/__just-installed`, `/__operator-photo`, `/__token`, `/__refresh_data`, `/__refresh_status`, or `/__run_dream` through shared host boundaries.
* [ ] Home, skills, settings/setup, shared status UI, and Trend Finder top-bar run controls render from snapshot/default state or disabled demo-only state.
* [ ] Public demo identity uses explicit public demo copy and assets instead of private env or localStorage values.
* [ ] User-facing copy distinguishes hosted unavailable actions from broken controls.

### Testing Requirements

* [ ] Focused unit and route tests cover public demo data loading, identity, setup gating, time-saved overlays, aggregate/Dream controls, status pills, and Trend Finder run controls.
* [ ] Focused no-bridge assertions cover the host endpoint set in this session.
* [ ] TypeScript check passes.
* [ ] Targeted formatting and lint checks pass for touched files.

### Non-Functional Requirements

* [ ] Normal local/Worker behavior remains unchanged when public demo mode is off.
* [ ] Public demo disabled controls prevent duplicate triggers while in-flight by never entering an in-flight local mutation state.
* [ ] Public demo mode keeps browser-local controls local and does not read private host state.

### 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

* Shared boundaries are Session 03 scope; deep route conversion is Session 04 scope: the Phase 31 PRD assigns this session to host data loading, setup suppression, identity, shared mutation controls, and status surfaces, while Session 04 owns agent routes, Knowledge Graph route behavior, Trend Finder assets, and AI Rogue route verification. Planning can proceed because the globally mounted header/status/top-bar hooks must be safe before route-specific work.
* Direct `/setup` visits should render a public-demo unavailable/read-only state instead of the normal setup wizard: the phase requires hosted setup and credential flows to be hidden or unavailable, and `SetupModal` currently persists draft and installed config to localStorage. Planning can proceed by replacing writes in public demo mode while keeping normal setup untouched.

### Conflict Resolutions

* Phase 31 lists agent pages in Session 04 but also requires status pills to avoid loopback endpoints in Session 03: choose header status pills for Session 03 because `HermesStatusPill` and `OpenClawStatusPill` are mounted globally from `src/routes/__root.tsx`; leave the full agent page routes to Session 04.
* Session 03 mentions source setup and scheduler writes, while Session 04 handles Trend Finder route polish: choose shared hook/client guards in Session 03 and leave view-specific copy and asset behavior for Session 04.

### Key Considerations

* Public demo mode must stay separate from `isExample`; `isExample` remains bundled fallback data only.
* The snapshot path is committed and browser-safe; raw `src/data/live-data.json` remains private and must not be read in Pages builds.
* Button disabled states must be established before click handlers can call token or mutation endpoints.
* React Query polling must be disabled before a query function can build a bridge request.

### Potential Challenges

* Hidden bridge calls from mounted providers: Add route-level tests around `RootComponent` and Trend Finder top-bar state.
* Normal local behavior regressions: Keep existing tests for local aggregate, Dream, setup, and Trend Finder run paths and add public-demo-specific tests rather than replacing local assertions.
* Product copy drift: Keep unavailable copy concise and hosted-demo-specific, with diagnostics in tests and implementation notes.

### Relevant Considerations

* \[P00] **Stack conventions**: Use existing Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare-compatible patterns.
* \[P02] **Extension payloads and labels stay bounded**: Keep explicit demo, fallback, unavailable, and degraded states instead of implying live hosted behavior.
* \[P04] **Hermes bridge guardrails must stay intact**: Do not weaken loopback/token/admin protections while disabling public demo access.
* \[P21] **Claude OAuth material stays script-only**: No token-bearing fields, bearer headers, or credential-shaped strings may reach browser state.
* \[P30] **Closeout cannot widen feature posture**: Do not introduce hosted collectors, remote loading, storage, credential, runtime, or admin-write surfaces.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* A public demo route mounts and fetches a `/__*` bridge endpoint before the UI disables the related control.
* A disabled public demo control still calls a local mutation handler on click or re-entry.
* Public identity or setup state leaks private env/localStorage values into the hosted demo.

***

## 9. Testing Strategy

### Unit Tests

* `src/lib/__tests__/use-live-data.test.tsx`: public demo snapshot endpoint, validation fallback, and no `/__live-data`.
* `src/lib/__tests__/time-saved-hook.test.tsx`: public demo skips file overlay bridge and still uses defaults/browser-local values.
* `src/lib/__tests__/operator-profile.test.ts`: public demo identity ignores env, storage, and dev proxy avatar.
* `src/lib/__tests__/use-aggregate-refresh.test.tsx` and `src/lib/__tests__/use-dream-run.test.tsx`: public demo disabled controls do not fetch token or mutation endpoints.
* Trend Finder hook tests: public demo run/lens/scheduler/source setup controls do not fetch token or write endpoints.

### Integration Tests

* `src/routes/__tests__/root-component.test.tsx`: public demo root/header render does not call Hermes/OpenClaw status endpoints or Trend Finder run token paths.
* `src/routes/__tests__/settings-share-setup.test.tsx`, `src/routes/__tests__/home.test.tsx`, and `src/routes/__tests__/skills.test.tsx`: public demo setup, refresh, Dream, and time-saved controls render safely from snapshot/default data.

### Runtime Verification

* Run focused Vitest suites for touched hooks, components, and routes.
* Run `bun run typecheck`.
* Run targeted Prettier and ESLint for touched files.

### Edge Cases

* Snapshot fetch fails or returns malformed JSON: app falls back safely without trying `/__live-data`.
* Browser offline: public demo disabled states remain stable and do not switch into local retry paths.
* Public demo flag is invalid or absent: normal local bridge behavior remains unchanged.
* Re-entering setup or Trend Finder routes: controls reset to public demo disabled/browser-local states without token fetches.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase31-session01-demo-mode-foundation`, `phase31-session02-snapshot-exporter-and-fixtures`
* Depended by: `phase31-session04-extensions-and-agent-routes`, `phase31-session05-pages-build-and-deployment-scaffold`, `phase31-session06-demo-qa-and-privacy-verification`, `phase31-session07-release-polish-and-documentation`

***

## 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/phase31-session03-app-data-and-mutation-boundary/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.