> 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_31/session_01_demo_mode_foundation.md).

# Session 01: Demo Mode Foundation

**Session ID**: `phase31-session01-demo-mode-foundation` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add the public demo build-mode foundation without changing the normal local or Worker deployment path.

***

## Scope

### In Scope (MVP)

* Add shared `VITE_AI_OS_PUBLIC_DEMO` mode detection.
* Keep public demo mode separate from the existing `isExample` fallback-data concept.
* Configure `vite.config.ts` to branch on `--mode demo-pages`.
* Skip the Worker `cloudflare()` plugin in demo-pages mode.
* Enable TanStack Start SPA output for the demo build as the first implementation path.
* Preserve prerender/SSG as a fallback if route coverage requires explicit HTML files.
* Force demo mode to enable all registered extensions independently of `.env.local`.
* Add focused tests for public demo flag behavior and extension enablement.
* Prove normal Worker build behavior remains unchanged.

### Out of Scope

* Snapshot export implementation.
* Route-specific mutation guard work.
* Pages `_headers`, `_redirects`, and deployment documentation.
* Public visual polish.
* Migrating root `wrangler.jsonc` into a Pages configuration.

***

## Folded Source Details

AI OS is not a plain Vite SPA. The normal build uses the `@tanstack/react-start` Vite plugin plus:

```
cloudflare({ viteEnvironment: { name: "ssr" } })
```

The normal `bun run build` currently runs `seed:data` plus `vite build` and emits:

* `dist/client/`: hashed assets and `favicon.svg`, with no top-level `index.html`.
* `dist/server/`: the Workers SSR bundle and generated `wrangler.json`.

The Pages demo cannot deploy `dist/client` as-is because Cloudflare Pages needs static HTML, including a top-level `index.html`. Demo-pages mode must emit static HTML by either:

* SPA mode: `tanstackStart({ spa: { enabled: true } })`, optionally paired with `src/start.ts` `defaultSsr: false` for demo mode if the installed version requires it.
* Prerender mode: `tanstackStart({ prerender: { enabled: true, ... } })` with an explicit route list when link crawling cannot discover dynamic extension paths.

SPA mode is the default working assumption because Phase 31 uses a Pages `/* /index.html 200` fallback. Prerender remains a fallback, not the initial target.

Public demo mode flags:

```
VITE_AI_OS_PUBLIC_DEMO=1
VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all
```

`VITE_AI_OS_PUBLIC_DEMO` means "hosted public frozen snapshot." It must not reuse `isExample`, which means "bundled fallback data."

***

## Prerequisites

* [ ] Phase 31 PRD and session stubs exist.
* [ ] Current `vite.config.ts` Worker build behavior is understood.
* [ ] Extension registry behavior for `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all` is verified.
* [ ] Current TanStack Start version supports SPA mode or has a documented equivalent.

***

## Deliverables

1. Public demo mode helper usable by app code and build configuration.
2. Demo-pages Vite/TanStack Start configuration that emits static HTML.
3. Worker build path preserved for normal `bun run build`.
4. Extension registry behavior that treats all registered extensions as visible in public demo mode.
5. Tests or assertions for:
   * public demo mode flag parsing,
   * no `isExample` overload,
   * all registered extension enablement in public demo mode,
   * normal Worker plugin inclusion outside demo-pages mode,
   * Worker plugin exclusion in demo-pages mode.

***

## Success Criteria

* [ ] Normal `bun run build` still emits the existing Worker/client output shape.
* [ ] Demo-pages build configuration does not include the Cloudflare Worker environment.
* [ ] Demo-pages mode can emit a top-level static `index.html` through SPA mode or has a documented prerender fallback.
* [ ] All registered extension routes are considered enabled in public demo mode.
* [ ] Public demo mode does not overload or change the meaning of `isExample`.
* [ ] Root `wrangler.jsonc` remains the Worker deployment contract.


---

# 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_31/session_01_demo_mode_foundation.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.