> 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-session01-demo-mode-foundation/spec.md). # Session Specification **Session ID**: `phase31-session01-demo-mode-foundation` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24 *** ## 1. Session Overview This session establishes the public demo build-mode foundation for Phase 31. It gives the application and build configuration one explicit `VITE_AI_OS_PUBLIC_DEMO` signal, keeps that signal separate from the existing `isExample` fallback-data flag, and prepares `demo-pages` mode to produce static Pages-compatible output instead of the normal Cloudflare Worker bundle. The work is first because every later public-demo session depends on this boundary. Snapshot export, route mutation guards, extension route hardening, Pages headers, and release QA all need a reliable way to detect hosted frozen-demo mode before they can avoid local bridge calls or consume committed `/demo/*` assets. Normal local development and Worker deployment remain the control path. `bun run build` must continue to include the Cloudflare Worker environment and emit the existing `dist/client` plus `dist/server` shape, while `vite build --mode demo-pages` must skip the Worker plugin and enable TanStack Start static SPA output as the first implementation path. *** ## 2. Objectives 1. Add a shared public-demo mode helper that parses `VITE_AI_OS_PUBLIC_DEMO` for browser code and build configuration. 2. Preserve the distinct meaning of `isExample` as bundled fallback data, not hosted public demo state. 3. Force all registered client extensions visible in public demo mode without changing normal env-controlled extension enablement. 4. Branch `vite.config.ts` for `demo-pages` so Worker build behavior is preserved outside demo mode and static TanStack output is enabled inside demo mode. *** ## 3. Prerequisites ### Required Sessions * [x] `phase30-session10-quality-gates-and-enablement` - Provides the completed Phase 30 baseline, AI Rogue opt-in posture, Worker build gates, and release evidence this phase must preserve. ### Required Tools Or Knowledge * Bun 1.3.14 project scripts from `package.json`. * Current TanStack Start plugin options from `@tanstack/react-start`. * Existing extension registry, setup env config, and extension enablement tests. * Current `vite.config.ts` Worker build path and local bridge middleware shape. ### Environment Requirements * Local environment can run Bun, Vitest, TypeScript, Vite build, and existing Worker build checks. * No external credentials, billing, or Cloudflare dashboard action is required for this session. * Demo-pages smoke verification can run with `VITE_AI_OS_PUBLIC_DEMO=1 VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all vite build --mode demo-pages`. *** ## 4. Scope ### In Scope (MVP) * Maintainer can set hosted public demo mode explicitly - Add shared `VITE_AI_OS_PUBLIC_DEMO` detection for app code and `vite.config.ts`. * App code can distinguish fallback data from public demo mode - Keep `isExample` unchanged and test that demo mode does not require or rewrite it. * All registered extensions are visible in public demo mode - Make the static registry return every registered extension when public demo mode is active, independently of `.env.local`. * Demo-pages build does not use Worker SSR deployment plumbing - Skip the `cloudflare()` plugin and enable TanStack Start static SPA output when `mode === "demo-pages"` or the public-demo flag is active for the build. * Normal Worker build remains unchanged - Keep `bun run build` on the existing Worker/client output path with the Cloudflare plugin included. ### Out Of Scope (Deferred) * Snapshot exporter and committed `/demo/*` fixtures - Reason: Session 02 owns the public snapshot boundary and redaction tests. * App data fetch conversion from `/__live-data` to `/demo/live-data.snapshot.json` - Reason: Session 03 owns runtime data and mutation boundaries. * Agent, Knowledge Graph, Trend Finder, and AI Rogue route-specific demo hardening - Reason: Session 04 owns route behavior. * Pages `_headers`, `_redirects`, build scripts, preview scripts, and deployment docs - Reason: Session 05 owns Pages deployment scaffolding. * Public visual polish, mobile review, and release documentation - Reason: Session 07 owns polish and release closeout. *** ## 5. Technical Approach ### Architecture Add one small public-demo helper that exposes deterministic boolean parsing for both browser code and build configuration. Browser code should read `import.meta.env.VITE_AI_OS_PUBLIC_DEMO`; `vite.config.ts` should read loaded Vite env plus process env and mode. The helper should accept only explicit true values such as `1`, `true`, `yes`, or `on`, and treat absent or invalid values as false. Update the extension registry at the boundary where enabled extensions are derived. In public demo mode, the registry returns every statically registered extension in registry order. Outside public demo mode, it keeps the existing `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` behavior, including `all`, `none`, empty, and unknown-ID filtering. Update `vite.config.ts` so `demo-pages` mode skips `cloudflare({ viteEnvironment: { name: "ssr" } })` and configures TanStack Start static SPA output. Keep the existing Worker server entry and import-protection settings for normal builds. If the installed TanStack Start version also needs `src/start.ts` `defaultSsr: false`, wire it only for public-demo mode and keep the existing error middleware intact. ### Design Patterns * Narrow feature flag: Public demo behavior is controlled by one explicit flag, not by `isExample` or route-specific inference. * Static registry first: Demo visibility uses the existing compile-time extension list and does not introduce dynamic loading. * Build-mode branching: Vite config chooses Worker or static output from mode/env before plugins are assembled. * Gate-led verification: Focused unit tests prove flag parsing and extension enablement; build checks prove normal Worker output and demo-pages static output remain separated. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------- | | `src/lib/public-demo.ts` | Shared public-demo flag parser and browser-mode helper. | \~70 | | `src/lib/__tests__/public-demo.test.ts` | Focused tests for demo flag parsing and `isExample` separation. | \~110 | | `.spec_system/specs/phase31-session01-demo-mode-foundation/implementation-notes.md` | Session evidence, command outcomes, repairs, and residual risk. | \~120 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/registry.ts` | Force all registered extensions visible when public demo mode is active while preserving normal env parsing. | \~25 | | `src/lib/setup-config.ts` | Surface public-demo extension enablement consistently for setup/status code without changing normal env locks. | \~35 | | `src/vite-env.d.ts` | Add public-demo Vite env typing if needed by strict TypeScript checks. | \~20 | | `vite.config.ts` | Branch on `demo-pages` mode/public-demo flag, skip Cloudflare Worker plugin for demo builds, and enable static TanStack output. | \~70 | | `src/start.ts` | Add demo-only static SSR default only if the installed TanStack Start version requires it. | \~15 | | `src/lib/__tests__/extension-registry.test.ts` | Add public-demo registry coverage and preserve existing `all`, `none`, empty, and unknown-ID cases. | \~60 | | `src/lib/__tests__/setup-config-extensions.test.ts` | Add setup-config coverage for public-demo forced extension visibility. | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `VITE_AI_OS_PUBLIC_DEMO` has a shared parser used by app code and build config. * [ ] Public demo mode does not read, rewrite, or overload `LiveData.isExample`. * [ ] `getEnabledExtensions()` returns all registered extensions in public demo mode even when `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` is unset. * [ ] Normal extension enablement still honors empty, `none`, explicit IDs, `all`, and unknown-ID filtering outside public demo mode. * [ ] `vite build --mode demo-pages` skips the Cloudflare Worker plugin and enables static TanStack output. * [ ] Normal `bun run build` keeps the Cloudflare Worker build path and existing output shape. ### Testing Requirements * [ ] Focused public-demo helper tests written and passing. * [ ] Focused extension registry and setup-config tests written and passing. * [ ] TypeScript check passes after env typing and config changes. * [ ] Normal Worker build and demo-pages build checks are run and recorded. ### Non-Functional Requirements * [ ] No hosted collection, local bridge, setup write, scheduler, admin, upload, chat, or source mutation behavior is introduced. * [ ] No dynamic extension loading, eval, remote code, analytics, external media, or Cloudflare Pages Functions are introduced. * [ ] Demo visibility does not imply AI Rogue default enablement outside public demo mode. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Public-demo product surfaces remain deferred; this session adds build and registry foundations only. *** ## 8. Implementation Notes ### Working Assumptions * SPA output is the first implementation path: `.spec_system/PRD/phase_31/PRD_phase_31.md` and the Session 01 stub choose Pages `/* /index.html 200` fallback behavior and identify TanStack Start SPA output as the preferred static shape. Planning can proceed because prerender remains a documented fallback if route coverage later requires explicit HTML files. * Public demo mode must not reuse `isExample`: the PRD defines `VITE_AI_OS_PUBLIC_DEMO` as hosted frozen snapshot mode, while `src/lib/validate-live-data.ts`, `src/lib/live-data-provenance.ts`, and route code already use `isExample` for bundled fallback data. Planning can proceed because a separate helper avoids changing existing fallback semantics. * Extension `all` behavior already exists but is not enough by itself: `src/extensions/registry.ts` and related tests support `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all`, while the phase requires public demo mode to force all registered extensions independently of `.env.local`. Planning can proceed by adding a public-demo override at registry/setup boundaries. ### Key Considerations * Preserve the existing Worker deployment path in `wrangler.jsonc` and `bun run build`. * Keep public-demo mode as a static build foundation; route data loading and mutation hardening are later sessions. * Treat any TanStack static-output limitation as implementation evidence and keep prerender as a fallback rather than widening this session into Pages deployment scaffolding. ### Potential Challenges * TanStack Start SPA option compatibility: Verify the installed version's plugin behavior during implementation and record whether `src/start.ts` also needs demo-only `defaultSsr: false`. * Vite config side effects: Keep public-demo build branching near plugin assembly so local dev middleware remains unchanged. * Existing dirty worktree: Scope edits to planned files and avoid reverting unrelated Phase 31 or AI Rogue changes already present. ### Relevant Considerations * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility shape the build-mode plan. * \[P02] **Static extension registry requires code changes**: Demo extension visibility must use compile-time registration, not dynamic loading. * \[P02] **Extension payloads and labels stay bounded**: Later sessions will use this flag to preserve fixture, fallback, degraded, blocked, unavailable, and browser-local labels. * \[P30] **AI Rogue default enablement deferred**: Public demo visibility must not imply normal default enablement outside demo mode. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Public demo flag accidentally couples hosted demo mode to fallback `isExample` data. * Demo-pages build accidentally keeps Worker SSR plumbing or normal Worker build loses it. * Registered extensions remain hidden in hosted demo mode or AI Rogue appears default-enabled in normal local mode. *** ## 9. Testing Strategy ### Unit Tests * Test public-demo flag parsing for true, false, invalid, missing, and case/whitespace variants. * Test public-demo mode does not depend on a `LiveData.isExample` value. * Test extension registry returns all registered extensions in public demo mode and preserves existing env behavior outside demo mode. * Test setup env config reports public-demo forced extension visibility without weakening normal extension locks. ### Integration Tests * Run focused Vitest suites for public-demo helper, extension registry, and setup config. * Run TypeScript to verify import paths, Vite env typing, and config changes. ### Runtime Verification * Run normal `bun run build` and verify Worker/client output shape still includes `dist/client` and `dist/server/wrangler.json`. * Run `VITE_AI_OS_PUBLIC_DEMO=1 VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all bunx vite build --mode demo-pages` or the equivalent Vite build command and verify the Cloudflare Worker environment is absent and static HTML is emitted or a concrete prerender fallback is recorded. ### Edge Cases * Empty, unset, invalid, `none`, explicit IDs, and `all` extension env values outside public demo mode. * Public-demo true with extension env unset. * Public-demo true with extension env set to `none`. * Normal build with `mode` values other than `demo-pages`. * Build command invoked with mode `demo-pages` but missing `VITE_AI_OS_PUBLIC_DEMO`; mode should still select the static demo build path. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase30-session10-quality-gates-and-enablement` * Depended by: `phase31-session02-snapshot-exporter-and-fixtures`, `phase31-session03-app-data-and-mutation-boundary`, `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-session01-demo-mode-foundation/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.