> 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/prd_phase_31.md). # PRD Phase 31: Cloudflare Pages Public Demo **Status**: Complete **Sessions**: 7 (initial estimate) **Estimated Duration**: 7-14 days **Progress**: 7/7 sessions (100%) *** ## Overview Phase 31 creates a public-safe Cloudflare Pages demo for AI OS. The demo reuses the real React/TanStack Start UI and route tree, but replaces local runtime reads with curated, committed, browser-safe snapshot assets captured at one moment in time. The goal is read-only public exploration of the current AI OS surfaces, including every registered app and extension surface, without publishing private local runtime data or depending on loopback-only dev middleware. The first version is static-only. It must not use Pages Functions, SSR, local bridges, scheduled jobs, server-side collection, hosted "run" actions, hosted "refresh" actions, hosted "render" actions, ingest, upload, chat, or admin-write actions. When a feature cannot safely run on a public static host, the page stays visible and renders the relevant controls as read-only, unavailable, or browser-local only. Do not exclude the surface from the demo. Target shape: ``` existing src/ UI -> demo build mode -> frozen browser-safe JSON/assets -> static Cloudflare Pages output ``` `demo-website/` is the Pages artifact and documentation boundary, not a forked React app. Forking the UI would create a second product surface that drifts from AI OS immediately. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ----------------------------------- | -------- | ---------- | ---------- | | 01 | Demo Mode Foundation | Complete | 20 | 2026-06-24 | | 02 | Snapshot Exporter And Fixtures | Complete | 20 | 2026-06-24 | | 03 | App Data And Mutation Boundary | Complete | 21 | 2026-06-24 | | 04 | Extensions And Agent Routes | Complete | 21 | 2026-06-24 | | 05 | Pages Build And Deployment Scaffold | Complete | 16 | 2026-06-24 | | 06 | Demo QA And Privacy Verification | Complete | 20 | 2026-06-24 | | 07 | Release Polish And Documentation | Complete | 18 | 2026-06-24 | *** ## Completed Sessions * Session 01: Demo Mode Foundation - Completed 2026-06-24. Added shared public-demo mode parsing, public-demo extension visibility, demo-pages static build branching, and validation evidence for normal Worker and demo builds. * Session 02: Snapshot Exporter And Fixtures - Completed 2026-06-24. Added the local-only snapshot exporter, committed public-safe demo fixtures, privacy scans, manifest metadata, and fixture boundary documentation. * Session 03: App Data And Mutation Boundary - Completed 2026-06-24. Added frozen public-demo data loading, public identity/setup behavior, no-bridge shared mutation guards, hosted-demo disabled controls, and focused no-bridge validation coverage. * Session 04: Extensions And Agent Routes - Completed 2026-06-24. Forced hosted public-demo behavior across Hermes, Claude Code, OpenClaw, Knowledge Graph, Trend Finder, and AI Rogue routes; added static public asset handling, browser-local AI Rogue labels, no-bridge route coverage, and full validation evidence. * Session 05: Pages Build And Deployment Scaffold - Completed 2026-06-24. Added deterministic Pages build and preview scripts, a tested static dist assembly pipeline, Pages routing and header files, deployment documentation, and validation evidence for the generated-only `demo-website/dist` output. * Session 06: Demo QA And Privacy Verification - Completed 2026-06-24. Added shared Pages demo route coverage, static preview smoke tests with no `/__*` request assertions, fixture and generated-output privacy scanning, and validation evidence for build, scan, type, lint, test, and route safety gates. * Session 07: Release Polish And Documentation - Completed 2026-06-24. Added frozen-snapshot provenance, refreshed public demo metadata, polished unavailable and mobile public-demo states, added Pages budget and direct upload release helpers, and recorded deployment documentation and closeout evidence. *** ## Upcoming Sessions * None. Phase 31 is complete and archived. *** ## Objectives 1. Add a public demo build mode that emits static Pages-compatible output without weakening the normal Worker build. 2. Create a deterministic, allowlist-first snapshot exporter and committed public-safe fixtures. 3. Make AI OS host routes, agent routes, Trend Finder, Knowledge Graph, and AI Rogue render from frozen demo state without local bridge requests. 4. Produce `demo-website/dist` with static routing, headers, snapshot assets, and Cloudflare Pages setup documentation. 5. Prove the demo route matrix, privacy scans, no-bridge network behavior, and release documentation before public use. *** ## Prerequisites * Phase 30 completed. * The prior Cloudflare Pages demo planning note has been folded into this PRD and the session stubs so this phase can stand alone. * Existing Worker deployment through `wrangler.jsonc` remains the main app deployment path. * Bun 1.3.14 remains the expected package manager/runtime for build and test commands. *** ## Planning Assumptions And Resolutions ### Working Assumptions * Phase 31 is the next phase: `.spec_system/state.json` and the master PRD both ended at completed Phase 30, while the Cloudflare Pages demo plan was planned, audited on 2026-06-23, and detailed enough to reconcile into the official PRD and state without user arbitration. * SPA output is the first implementation path: the demo plan chooses a Pages `_redirects` fallback and calls out TanStack Start SPA output as the preferred static shape. Prerender remains available if route coverage requires explicit HTML files. * The snapshot exporter is local authoring only: Cloudflare builds must consume committed fixtures and never read `src/data/live-data.json`, so export and Pages build concerns stay separate. * All registered extensions stay visible: Trend Finder and AI Rogue must be reachable in public demo mode, and future registered extensions must follow the same visible-but-safe rule. * Direct upload needs an operator-supplied Pages project name: direct upload should work or have a documented constraint, but the project name is external deployment configuration and does not block phase artifact creation. ### Conflict Resolutions * Official PRD/state did not list Phase 31 while the Cloudflare Pages plan requested a phase build: choose that plan as the new phase source, update the master PRD and `.spec_system/state.json`, and record the decision because it changes phase number, objective, session count, and ordering. *** ## Rendering Model AI OS is not a plain Vite single-page app. `vite.config.ts` builds it with the `@tanstack/react-start` plugin plus: ``` cloudflare({ viteEnvironment: { name: "ssr" } }) ``` `bun run build` currently runs `seed:data` plus `vite build` and emits two trees: * `dist/client/`: hashed assets and `favicon.svg`, with no top-level `index.html`. * `dist/server/`: the Workers SSR bundle and generated `wrangler.json`. By default, routes are server-rendered per request on the Worker. The demo build cannot simply point Cloudflare Pages at `dist/client` because there is no static `index.html` to serve. Demo-pages mode must emit static HTML by one of these mechanisms: 1. SPA mode: enable TanStack Start shell output so the build writes a top-level `index.html` that boots the client and fetches `/demo/live-data.snapshot.json`. In the installed TanStack Start version, this is configured with `tanstackStart({ spa: { enabled: true } })`. If needed, `src/start.ts` can also set `defaultSsr: false` for demo mode. This matches the chosen `/* /index.html 200` Pages fallback. 2. Prerender (SSG): crawl the demo routes against the frozen snapshot and emit one static HTML file per route with `tanstackStart({ prerender: { enabled: true, ... } })`. Dynamic extension routes need an explicit route list unless link crawling proves all expected paths. In either model, the `cloudflare()` SSR plugin must be skipped in demo-pages mode. Because `vite.config.ts` currently gates `cloudflare()` on `command === "build"` only, the config must also branch on `--mode demo-pages` to drop the Worker environment and enable SPA or prerender output. *** ## Cloudflare Pages Constraints * Pages needs a build command and a build output directory. * Generic React/Vite Pages guides assume a static SPA `dist`, but AI OS is a TanStack Start SSR app; the demo build must emit static output, not the default Worker bundle. * A static Pages app needs a top-level `index.html` in the output directory. * Client-side routing needs a Pages `_redirects` file, usually with an SPA fallback such as `/* /index.html 200`. * Security and cache headers for static assets belong in a Pages `_headers` file. * Cloudflare Pages' current build image does not default to this repo's pinned Bun version. Set `BUN_VERSION=1.3.14` in the Pages project unless the build log proves `.bun-version` is being honored. * If Pages Functions or advanced `_worker.js` mode are introduced later, `_redirects` and `_headers` behavior must be revisited because those files do not apply to Function-generated responses. * If advanced `_worker.js` mode is introduced later, that Worker must explicitly pass static asset requests to `env.ASSETS.fetch(request)`. * v1 avoids Pages Functions and advanced Worker mode by staying static-only. * The existing root `wrangler.jsonc` is a Cloudflare Workers deployment contract with `main: "src/server.ts"`. Do not add Pages configuration such as `pages_build_output_dir` to it unless intentionally migrating that file into a Pages Functions source of truth. Reference docs retained from the original plan: * Cloudflare Pages build configuration: `https://developers.cloudflare.com/pages/configuration/build-configuration/` * Cloudflare Pages build image: `https://developers.cloudflare.com/pages/configuration/build-image/` * Cloudflare Pages redirects: `https://developers.cloudflare.com/pages/configuration/redirects/` * Cloudflare Pages headers: `https://developers.cloudflare.com/pages/configuration/headers/` * Cloudflare Pages Functions advanced mode: `https://developers.cloudflare.com/pages/functions/advanced-mode/` * Cloudflare Pages Wrangler configuration: `https://developers.cloudflare.com/pages/functions/wrangler-configuration/` *** ## Current State As of the 2026-06-23 audit, AI OS has most ingredients for a public demo but not the safe deployment boundary or `demo-website/` scaffold. `package.json` has no `demo:*` scripts, and no `demo-website/` directory exists. | Area | Current State | Demo Impact | | --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | UI shell | React/TanStack Start/Vite app under `src/` | Reuse the real interface and route tree. | | Build | `vite.config.ts` always adds `cloudflare()` for `command === "build"` | Branch on `mode === "demo-pages"`. | | Data boundary | `useLiveData()` fetches `/__live-data` | Replace with static snapshot in demo mode. | | Generated data | `src/data/live-data.json` is local/generated/gitignored | Private input only; never copy raw. | | Fallback data | `src/data/live-data.example.json` is committed safe fallback | Useful baseline, too thin for full demo. | | Graph data | `src/data/graphs/index.json` and `src/data/graphs/ai-os.json` are committed seed/fallback graphs | Can seed public graph snapshots. | | Trend Finder | Fixture/demo labels, provenance states, static Brief, Engine Replay, and source setup models exist | Good fit for dated frozen snapshot. | | Hermes/OpenClaw | Existing route-level demo modes disable live bridge queries when enabled manually | Global public-demo mode must force these modes. | | Knowledge Graph | Existing `demoMode` uses committed demo fixtures and disables live graph bridge reads | Global public-demo mode should force this mode. | | AI Rogue | Registered opt-in extension with browser-local/IndexedDB state and Pixi runtime | Include in full Pages demo; keep state local. | | Local bridges | Many `/__*` endpoints exist only in Vite dev middleware | Public build must never call any `/__*` endpoint. | | Deployment | Existing path targets Cloudflare Workers via root `wrangler.jsonc` | Keep separate from Pages demo deployment. | | Private checks | `runtime:check-private` verifies ignored private runtime paths, but does not scan demo output | Add demo fixture and dist content scans. | *** ## Local Endpoint Inventory These endpoints must be mocked, disabled, or avoided in public demo mode: * Host data/control: `/__live-data`, `/__time-saved-config`, `/__just-installed`, `/__operator-photo`, `/__token`, `/__refresh_data`, `/__refresh_status`, `/__run_dream`. * Trend Finder: `/__run_trend_finder`, `/__run_trend_finder_status`, `/__trend_finder_source_setup`, `/__trend_finder_scheduler_status`, `/__trend_finder_creator_lens`, `/__trend-finder-visibility-config`, `/__trend_finder_asset/*`. * Knowledge Graph: `/__graphify_list`, `/__graphify_graph`, `/__graphify_admin_status`, `/__graphify_ingest`, `/__graphify_remove`. * Hermes: `/__hermes_*`, including admin routes such as `/__hermes_chat`, `/__hermes_image_upload`, `/__hermes_missions/*`, `/__hermes_documents*`, and `/__hermes_obsidian`. * OpenClaw: `/__openclaw_*`, including `/__openclaw_admin_status` and `/__openclaw_admin_action`. Privacy boundary: generated runtime data is private by contract and may contain local paths, auth-state labels, usage metadata, project labels, and agent memory text. It must never be copied directly into a public Pages build. *** ## Target Directory Shape Use `demo-website/` as the Pages demo artifact and documentation boundary: ``` demo-website/ |-- README.md |-- snapshot-manifest.json |-- public/ | |-- _headers | |-- _redirects | `-- demo/ | |-- live-data.snapshot.json | |-- graphs/ | |-- trend-finder-assets/ | `-- snapshot-metadata.json `-- dist/ # generated-only; gitignored build output ``` The exact build output path can be adjusted during implementation. The key requirement is that Cloudflare Pages deploys one static directory and that the source of that directory is reproducible from repo-local commands. Add `demo-website/dist/` to `.gitignore` when the directory is created. *** ## Demo Build Mode Build-time flags: ``` VITE_AI_OS_PUBLIC_DEMO=1 VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all ``` In demo mode: * `useLiveData()` reads `/demo/live-data.snapshot.json` instead of `/__live-data`. * Every registered extension is enabled regardless of local `.env.local` state. * Any extension action that would normally write outside the browser renders as read-only, unavailable, or browser-local instead of being omitted. * AI Rogue is included. Its gameplay and progression persistence stays browser-local, and it must not call local bridges, remote loaders, server state, or private telemetry. * Local mutation controls are hidden or replaced with read-only unavailable states. * Setup/onboarding prompts do not auto-open. * Operator identity uses public demo copy and assets, not localStorage or `.env.local` values. * Status pills and agent pages render demo or unavailable states without trying to contact loopback-only endpoints. * Refresh/run buttons cannot start collectors, Dream jobs, scheduler jobs, source setup writes, Creator Lens writes, Knowledge Graph ingest/remove, local agent writes, chat/uploads, or document/admin actions. * `useTimeSaved()` uses snapshot/default overlays only and must not call `/__time-saved-config`. * Trend Finder source setup and scheduler status controls use the snapshot state with `autoLoad: false`. * Trend Finder asset previews use static copied asset URLs under `/demo/trend-finder-assets/` or render unavailable states, never `/__trend_finder_asset/*`. * `TrendFinderRunProvider` and the top-bar run button return a disabled demo-only control state before any `/__token` fetch can happen. Prefer the public-demo flag over overloading `isExample`. `isExample` means "bundled fallback data"; the hosted demo means "curated frozen snapshot." *** ## Snapshot Data Strategy Create a deterministic local snapshot authoring command: ``` bun run demo:snapshot ``` Inputs: * `src/data/live-data.json` when present, treated as private local input. * `src/data/live-data.example.json` as fallback. * `src/data/graphs/` seed files. * Trend Finder browser-safe fixture/generated data and static Brief outputs when they pass public-safe projection. * Public image assets under `public/assets/` and selected `src/assets/`. Outputs: * `demo-website/public/demo/live-data.snapshot.json` * `demo-website/public/demo/graphs/*.json` * `demo-website/public/demo/trend-finder-assets/*` for approved copied media * `demo-website/snapshot-manifest.json` * `demo-website/public/demo/snapshot-metadata.json` Exporter requirements: * The exporter is allowlist-first. * Copy only fields known to be browser-safe for public demo use. * Commit exporter outputs to the repo and human-review them before each update. * The Pages build consumes committed files and never reads `live-data.json`. * The manifest includes `capturedAt`, `sourceCommit`, exporter version, input sources used, redaction counts, route coverage, and scan results. Always remove or replace: * Absolute local paths such as `/home/...`, `/Users/...`, and tool config locations. * Auth state details, token/account metadata, key presence, OAuth state, and credential counts. * Agent memory text, transcripts, raw prompts, raw command output, and private note/document snippets. * Raw local project names that are not intended for public demo. * Private source logs, cache paths, debug traces, and local scheduler paths. * Any `.env`, secret, token, key, credential, or account-auth indicators. * `file://`, loopback URLs, private-LAN URLs, query-bearing local URLs, and bridge URLs beginning with `/__`. Safe replacements: * Public project labels such as `AI OS`, `Creator Radar`, and `Local Knowledge Base`. * Rounded or bounded usage totals that demonstrate layout without revealing real operator telemetry. * Trend Finder public evidence, provenance labels, source health summaries, score breakdowns, creator angles, watchlist items, and Engine Replay stages when already sanitized and source-compliance docs allow the published fields. * Demo-specific agent/session rows that are visibly fixture-backed. * Dated frozen snapshot labels such as `Frozen snapshot captured Jun 2026`. * Never use "live" unless the source was genuinely live at capture time and is safe to describe that way. *** ## Pages Build Strategy Add explicit package scripts rather than relying on the existing Worker build: ```json { "scripts": { "demo:snapshot": "bun run scripts/demo/export-pages-snapshot.ts", "demo:build:pages": "VITE_AI_OS_PUBLIC_DEMO=1 VITE_CLAUDE_OS_ENABLED_EXTENSIONS=all vite build --mode demo-pages", "demo:preview:pages": "bun run demo:build:pages && wrangler pages dev demo-website/dist" } } ``` `demo:snapshot` is a separate local-only authoring step. It refreshes committed `demo-website/public/demo/*` fixtures from redacted local data and is reviewed before commit. The Pages build deliberately does not invoke it because Cloudflare's build environment has no `src/data/live-data.json`, and the committed snapshot must stay deterministic and reviewable. Static build mechanics can use either: 1. Build the app directly into `demo-website/dist`. 2. Build to the normal Vite output, then copy only the static client output, including generated `index.html`, and demo assets into `demo-website/dist`. Both assume `demo-pages` mode emits static SPA or prerendered HTML, not the default SSR Worker bundle. Cloudflare Pages project settings: ``` Root directory: repo root Build command: bun run demo:build:pages Build output directory: demo-website/dist Production branch: main or the selected demo branch Environment variables: BUN_VERSION=1.3.14 ``` Direct upload should also work: ``` bun run demo:build:pages wrangler pages deploy demo-website/dist --project-name --branch main ``` Do not reuse `bun run worker:deploy` for this path. The existing Worker deploy and the Pages demo deploy remain independent. Do not add `pages_build_output_dir` to root `wrangler.jsonc` for v1. *** ## Static Routing And Headers `demo-website/public/_redirects`: ``` /* /index.html 200 ``` Candidate `demo-website/public/_headers` baseline: ``` /* X-Content-Type-Options: nosniff X-Frame-Options: DENY Referrer-Policy: strict-origin-when-cross-origin Permissions-Policy: camera=(), microphone=(), geolocation=() /assets/* Cache-Control: public, max-age=31536000, immutable /demo/* Cache-Control: public, max-age=300 ``` Headers may need adjustment if the deployed demo uses embedded media, external images, or analytics. Keep v1 analytics-free unless a separate privacy review approves it. *** ## Feature Matrix | Surface | Pages Demo Behavior | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | Home | Render from frozen snapshot with public operator identity and visible snapshot provenance. | | Usage panel | Show frozen plan/window values; refresh control disabled or hidden. | | Skills | Show curated skill cards and ROI controls as browser-local only; no `/__time-saved-config`. | | Memory | Show snapshot graph/constellation data; no private note paths. | | Knowledge Graph | Use public graph snapshots/demo fixtures; disable ingest/remove and live polling. | | Activity | Use demo runs and public-safe output cards only. | | Workspaces | Use public labels and frozen session summaries only. | | Hermes Agent | Force demo/read-only route; no token, chat, upload, missions, documents, file previews, or admin writes. | | Claude Code Agent | Force demo/read-only route; no local process assumptions or live-mode toggle. | | OpenClaw Agent | Force demo/read-only route; no dashboard bridge, token, or admin actions. | | Extensions index | Show every registered extension as enabled in public demo mode. | | Trend Finder Trends | Render curated frozen trend report with explicit snapshot labels. | | Trend Finder Workbench | Read from snapshot; browser-local filters/visibility toggles allowed only if clearly local to the browser. | | Hidden Gems | Read from snapshot. | | Sources | Show source states/provenance from snapshot; no source setup writes or scheduler status polling. | | Watchlist | Read-only generated demo watchlist. | | Brief | Read-only handoff view. | | Engine Replay | Show sanitized latest-run trace or fixture trace; no raw logs or asset bridge calls. | | AI Rogue | Include Play, Ledger, Loadout, and Settings with bundled assets and browser-local persistence only. | | Settings/Setup | Hide setup/credential flows or mark unavailable; no setup modal auto-open and no `/__just-installed` call. | *** ## Implementation Sessions ### Session 01: Demo Mode Foundation Make the app and build system understand public demo mode without changing the normal Worker deployment. Add `VITE_AI_OS_PUBLIC_DEMO`, preserve the separate meaning of `isExample`, force all registered extensions visible in demo mode, and make `vite.config.ts` branch on `demo-pages` so the Cloudflare Worker plugin is skipped and static TanStack output is enabled. ### Session 02: Snapshot Exporter And Fixtures Create `demo-website/`, add `demo:snapshot`, build the allowlist-first exporter, project safe live data, graph data, Trend Finder data, static Brief output, and approved media into committed `/demo/*` fixtures, and add redaction tests plus scan metadata. ### Session 03: App Data And Mutation Boundary Wire the host app to read frozen snapshot data, suppress setup/onboarding auto-open, replace private identity with public demo defaults, disable local write/refresh/admin/source/scheduler controls, and ensure status surfaces do not contact loopback-only endpoints. ### Session 04: Extensions And Agent Routes Force Hermes, Claude Code, OpenClaw, Knowledge Graph, Trend Finder, and AI Rogue routes into demo-safe behavior. Trend Finder uses snapshots or fixture fallbacks and static asset URLs. AI Rogue remains browser-local with no bridge, remote loader, server state, or private telemetry call. ### Session 05: Pages Build And Deployment Scaffold Add Pages build/preview scripts, static routing and headers, output/copy logic for `demo-website/dist`, committed fixture inclusion, and Pages setup docs including `BUN_VERSION=1.3.14`, production branch, output directory, and direct upload notes. ### Session 06: Demo QA And Privacy Verification Add Playwright route smoke coverage for the route matrix, assert no request path starts with `/__`, run build/preview/typecheck/focused tests, and scan committed fixtures plus generated output for private data. ### Session 07: Release Polish And Documentation Add visible frozen-snapshot provenance, tune snapshot content, polish empty and unavailable states, verify mobile layout, review bundle budget, optionally add a direct-upload smoke command, and update deployment docs. *** ## Acceptance Criteria The Pages demo is ready when: * `bun run demo:build:pages` creates `demo-website/dist` with a top-level `index.html`. * `demo-website/dist` contains `_redirects`, `_headers`, and `/demo/*` snapshot assets. * The app renders from static files without Vite middleware. * All generated route families and registered extension surfaces, including Trend Finder and AI Rogue, are reachable in Pages-demo mode. * Browser/network smoke tests prove no public route requests any pathname beginning with `/__`. * Scans of committed demo fixtures and `demo-website/dist` find no absolute local paths, secrets, auth files, token/key-shaped strings, private memory text, raw prompts, raw transcripts, raw command output, local bridge URLs, or credential labels. * Trend Finder pages clearly identify payloads as frozen demo snapshot, fixture/demo data, deterministic fallback, or redacted generated source snapshot as appropriate. * Cloudflare Pages can deploy the output using the configured build command and output directory. * Direct upload with `wrangler pages deploy demo-website/dist --project-name --branch main` works or has a documented constraint. *** ## Resolved Decisions 1. Deployment target: a separate Pages project sourced from `main`, not a separate demo branch. The demo is distinct from the Workers production project. Building from `main` keeps the demo UI in lockstep with the real app. Demo behavior is isolated by `VITE_AI_OS_PUBLIC_DEMO`, not by a branch. 2. Snapshot source: a committed, curated public fixture is the source of truth. The exporter seeds and refreshes it under human review. Cloudflare's build environment never has `src/data/live-data.json`, so Pages builds consume committed fixtures and do not read local generated data. 3. Extension scope: all registered extensions are included in the Pages demo. For the current repo state, that means Trend Finder and AI Rogue. Future registered extensions must also be reachable from the extension index and direct routes in public demo mode. Unsafe actions render read-only, unavailable, or browser-local. 4. Trend Finder: prefer a dated, redacted frozen snapshot; fall back to fixture/demo labels only where generated data is not safe. Hosted collection remains out of scope. 5. Build output: `demo-website/dist` is generated-only and gitignored. Do not commit built output. The recovery path is the committed snapshot fixture plus deterministic `demo:build:pages`. 6. CI: decouple the Pages demo from the Workers pipeline. Until the demo stabilizes, Pages builds via Cloudflare's Git integration on `main` or manual `wrangler pages deploy`. Once stable, optionally add a repo CI guard that runs `demo:build:pages` plus the secret/path scan, but never fold it into the Workers deploy job. ### Deferred * A repo CI guard for the Pages build and secret/path scan, revisited after the demo stabilizes. *** ## Non-Goals * No hosted collection or scraping. * No hosted scheduler. * No hosted local-agent control plane. * No secret-bearing runtime. * No account auth, OAuth, or API-key flows. * No raw local memory, transcript, prompt, command, or document publication. * No replacement for the existing local-first AI OS runtime. * No migration away from the existing Cloudflare Workers deployment path for the main app. *** ## Technical Considerations ### Architecture Phase 31 preserves the current local-first architecture while adding a public demo boundary. The demo build mode is a narrow static export path: reuse the real app shell, route tree, and extension registry; project data into committed `/demo/*` snapshot assets; and disable hosted mutations. The existing Worker build and local Vite middleware remain separate from the Pages demo. ### Technologies * Bun 1.3.14 * React 19 * TanStack Start and TanStack Router * Vite 8 * Cloudflare Pages static output * Cloudflare Workers deployment kept separate * TypeScript, Zod, React Query, Vitest, and Playwright ### Risks * Private local data leakage: mitigate with allowlist-first snapshot projection, committed fixture review, and scans for local paths, secrets, auth labels, bridge URLs, prompts, transcripts, command output, and memory text. * Worker/Pages deployment drift: mitigate by keeping `wrangler.jsonc` as the Worker contract and documenting Pages settings under `demo-website/`. * Hidden local bridge calls: mitigate with route smoke tests and a network assertion that no public demo request path starts with `/__`. * Misleading public demo behavior: mitigate with frozen-snapshot provenance, read-only states, unavailable action copy, and no hosted collection. * Bundle and asset budget drift: mitigate with build, budget, asset-size, and generated-output scans before release. * External media or analytics scope creep: v1 stays analytics-free and adjusts headers only after separate privacy review. ### Relevant Considerations * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare constraints remain baseline constraints for the Pages build. * \[P02] **Extension payloads and labels stay bounded**: Snapshot payloads must keep explicit live, fixture, fallback, degraded, blocked, and unavailable states. * \[P02] **Static extension registry requires code changes**: The public demo must enable registered extensions through the existing static registry, not dynamic loading. * \[P21] **Claude OAuth material stays script-only**: Demo fixtures and hosted browser state must not expose OAuth, token, account, or bearer material. * \[P24] **Browser-safe export and triage boundaries**: Trend Finder snapshot and Brief data must project browser-safe fields only. * \[P26] **Knowledge Graph contract alignment**: Public graph snapshots, route UI, and demo fixtures must stay aligned with the shared graph contract. * \[P30] **AI Rogue default enablement deferred**: Pages demo visibility must not imply normal default enablement outside public demo mode. * \[P30] **Release gates stay bundled**: Docs/reference checks, private scans, payload/bundle/asset gates, dependency audit, build, focused browser coverage, and extension readiness proof should be recorded together. *** ## Success Criteria Phase complete when: * [ ] All 7 sessions completed. * [ ] `bun run demo:build:pages` creates `demo-website/dist/index.html`. * [ ] `demo-website/dist` contains `_redirects`, `_headers`, and `/demo/*` snapshot assets. * [ ] The static preview renders all planned host, agent, Trend Finder, Knowledge Graph, and AI Rogue demo routes. * [ ] Browser smoke tests prove no public demo route requests a pathname beginning with `/__`. * [ ] Committed fixtures and generated output scans find no local paths, secrets, credential labels, auth material, token/key-shaped strings, raw prompts, transcripts, command output, private memory text, or local bridge URLs. * [ ] Trend Finder and AI Rogue routes clearly distinguish frozen snapshot, fixture/demo, deterministic fallback, unavailable, and browser-local behavior. * [ ] Cloudflare Pages deployment settings and direct-upload behavior are documented. *** ## Dependencies ### Depends On * Phase 30: AI Rogue Game Extension ### Enables * Public Cloudflare Pages demo maintenance and future CI guard work if the demo stabilizes. --- # 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/prd_phase_31.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.