> 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-session06-demo-qa-and-privacy-verification/spec.md). # Session Specification **Session ID**: `phase31-session06-demo-qa-and-privacy-verification` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24 *** ## 1. Session Overview This session proves that the static Cloudflare Pages demo can be exercised safely before release polish begins. Sessions 01 through 05 established public-demo mode, committed browser-safe fixtures, read-only data and mutation boundaries, extension route safety, and the generated `demo-website/dist` static artifact. The next gap is evidence: route smoke coverage, no local bridge requests, static preview behavior, and scans of both committed fixtures and generated output. The work should add automation around the existing demo path instead of changing product scope. The public demo remains static-only, read-only for hosted behavior, and separate from the Cloudflare Worker deployment path. Unsafe local endpoints beginning with `/__` must not be requested by any planned public route, while static `/demo/*` asset requests remain valid. The session creates focused test and scan commands that can be rerun during release closeout. If a route cannot render safely, the implementation should record the concrete route and failure evidence in session notes without adding new public features. *** ## 2. Objectives 1. Add a shared public-demo route matrix that covers the Phase 31 planned Pages routes. 2. Add Playwright smoke coverage that loads the route matrix from static preview and asserts no request pathname starts with `/__`. 3. Add a privacy scan command that checks committed `demo-website/public/demo/*` fixtures and generated `demo-website/dist`. 4. Verify build, preview, typecheck, focused tests, smoke tests, and static routing/header output for Session 06 completion evidence. *** ## 3. Prerequisites ### Required Sessions * [x] `phase31-session01-demo-mode-foundation` - Provides public-demo mode, demo-pages build branching, and forced extension visibility. * [x] `phase31-session02-snapshot-exporter-and-fixtures` - Provides committed public fixtures, snapshot metadata, and reusable privacy scan helpers. * [x] `phase31-session03-app-data-and-mutation-boundary` - Provides frozen app data loading and hosted mutation guards. * [x] `phase31-session04-extensions-and-agent-routes` - Provides public-demo-safe agent, Knowledge Graph, Trend Finder, and AI Rogue route behavior. * [x] `phase31-session05-pages-build-and-deployment-scaffold` - Provides `demo:build:pages`, `demo:preview:pages`, static routing/header files, and `demo-website/dist` assembly. ### Required Tools Or Knowledge * Bun 1.3.14. * Vite 8, TanStack Start static demo-pages output, and Playwright. * Wrangler 4.92.0 for `wrangler pages dev demo-website/dist`. * Existing `scripts/lib/pages-demo-snapshot.ts` privacy scan helpers. ### Environment Requirements * Repository root working directory. * `demo-website/public/demo/*` committed fixtures present. * `demo-website/dist` generated by `bun run demo:build:pages` before generated-output scans. * A local static preview process can be started for route smoke checks. *** ## 4. Scope ### In Scope (MVP) * AI OS operator can run a Pages route smoke suite - Load the planned static demo route matrix from preview and verify each route renders a real product surface. * AI OS operator can prove no local bridge calls - Fail smoke tests when any request pathname starts with `/__`, while allowing `/demo/*` fixture and asset requests. * AI OS operator can scan public fixtures - Check committed `demo-website/public/demo/*` fixture files for local paths, secrets, auth labels, token/key-shaped strings, raw private text, bridge URLs, and private URLs. * AI OS operator can scan generated Pages output - Check `demo-website/dist` after `demo:build:pages` for the same privacy hazards and required static files. * AI OS operator can verify static Pages behavior - Confirm `_redirects`, `_headers`, `index.html`, and `/demo/*` assets exist in `demo-website/dist`. * Implementation records concrete failures - Session notes name any route or scan target that cannot render or pass safely. ### Out Of Scope (Deferred) * Visible frozen-snapshot provenance and unavailable-state copy polish - Reason: Session 07 owns release polish after this safety evidence exists. * Mobile layout review and responsive fixes - Reason: Session 07 owns mobile route review. * Bundle budget review - Reason: Session 07 owns release budget review after the route matrix is safe. * CI guard for Pages build plus scan - Reason: The Phase 31 PRD defers CI until the demo stabilizes. * Direct upload to a live Pages project - Reason: Deployment requires an operator-supplied Pages project name and is not needed for local QA automation. * New public features or hosted actions - Reason: This session verifies the existing static demo path only. *** ## 5. Technical Approach ### Architecture Create a shared public-demo route matrix in `scripts/lib/pages-demo-routes.ts` and use it from snapshot metadata and the Playwright smoke suite. The matrix should preserve the current host and extension coverage from `scripts/lib/pages-demo-snapshot.ts` while adding the explicit Phase 31 Session 06 route set, including agent routes, Trend Finder views, Knowledge Graph, and AI Rogue routes. Add a reusable scan library in `scripts/lib/pages-demo-privacy-scan.ts` that builds on `collectPublicDemoPrivacyIssues` and `verifySnapshotFilePrivacy` from `scripts/lib/pages-demo-snapshot.ts`. The scanner should support committed fixture targets and generated output targets, traverse files in deterministic order, reject unexpected roots, bound file reads, and report explicit JSON/text findings. A thin CLI in `scripts/demo/scan-pages-demo.ts` can provide the package script entrypoint. Add a Playwright spec under `tests/e2e/pages-demo-routes.spec.ts`. The suite should be compatible with a static preview base URL, track every network request, fail on `/__*`, allow `/demo/*`, and assert each route has a stable route-specific heading or product surface so a blank shell cannot pass. ### Design Patterns * Shared constants: One route matrix avoids drift between snapshot metadata and smoke tests. * Tested script library: Filesystem scanning and error mapping live in `scripts/lib/` with Vitest coverage. * Static preview verification: Browser tests exercise `demo-website/dist` through Pages-style preview rather than Vite middleware. * Privacy-first fail closed behavior: Scan and smoke commands return non-zero exits with concrete file, route, or request-path evidence. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------- | -------------------------------------------------------------------- | ---------- | | `scripts/lib/pages-demo-routes.ts` | Shared public-demo route matrix and route metadata. | \~90 | | `scripts/lib/pages-demo-privacy-scan.ts` | Reusable fixture and generated-output privacy scan helpers. | \~220 | | `scripts/demo/scan-pages-demo.ts` | Bun CLI for Pages demo privacy scans with JSON and text output. | \~120 | | `scripts/lib/__tests__/pages-demo-routes.test.ts` | Unit coverage for route matrix completeness and path validity. | \~80 | | `scripts/lib/__tests__/pages-demo-privacy-scan.test.ts` | Unit coverage for fixture/dist scans, failures, and missing targets. | \~180 | | `tests/e2e/pages-demo-routes.spec.ts` | Playwright route smoke suite with no `/__*` request assertion. | \~220 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | | `scripts/lib/pages-demo-snapshot.ts` | Replace local route coverage constant with shared route matrix import. | \~20 | | `package.json` | Add a rerunnable Pages demo privacy scan script. | \~2 | | `.spec_system/specs/phase31-session06-demo-qa-and-privacy-verification/implementation-notes.md` | Record verification commands, route failures, and scan evidence during implementation. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Shared route matrix includes the Session 06 public route set and existing manifest-covered host routes. * [ ] `tests/e2e/pages-demo-routes.spec.ts` loads each planned route from static preview. * [ ] No route in the smoke suite requests a pathname beginning with `/__`. * [ ] Static `/demo/*` fixture and asset requests are allowed by the network assertion. * [ ] Privacy scan checks committed `demo-website/public/demo/*` fixtures. * [ ] Privacy scan checks generated `demo-website/dist` after `bun run demo:build:pages`. * [ ] Scan output reports concrete file paths and issue labels on failure. * [ ] `demo-website/dist` contains `index.html`, `_redirects`, `_headers`, and `/demo/*` assets. ### Testing Requirements * [ ] Unit tests cover route matrix validity and snapshot route coverage integration. * [ ] Unit tests cover privacy scan pass, privacy scan fail, missing target, JSON file scan, and text file scan paths. * [ ] Focused Playwright smoke suite passes against static preview. * [ ] Focused Vitest suites for public demo scan and route behavior pass. * [ ] `bun run typecheck` passes. ### Non-Functional Requirements * [ ] File traversal is deterministic, bounded, and confined to approved demo roots. * [ ] Scan commands fail closed when generated output is missing. * [ ] Browser smoke failures identify the route and forbidden request path. * [ ] No new hosted collection, auth, analytics, Pages Functions, local bridge, or Worker deployment behavior is introduced. ### 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 * Static preview can be run locally with `bun run demo:preview:pages`: Session 05 added the script and documented Wrangler Pages dev usage, so Session 06 can use it for smoke tests without changing the Worker dev server path. * A dedicated scan command is needed: `verifySnapshotFilePrivacy` already validates committed JSON fixtures, but the Session 06 stub also requires scanning generated `demo-website/dist`, static HTML, `_headers`, `_redirects`, and copied assets. * Route smoke coverage should be centralized: the current `PAGES_DEMO_ROUTE_COVERAGE` constant in `scripts/lib/pages-demo-snapshot.ts` is narrower than the Session 06 route matrix and should not remain a second source of truth. ### Conflict Resolutions * The Session 06 stub lists agent, Trend Finder, Knowledge Graph, and AI Rogue smoke routes, while the existing snapshot metadata constant also includes host routes such as `/workspaces`, `/setup`, `/share`, `/settings`, `/extensions`, and `/extensions/trend-finder/hidden-gems`. Use a unified matrix that includes both sets because the phase acceptance criteria require all planned host, agent, Trend Finder, Knowledge Graph, and AI Rogue routes to be reachable. * The Session 06 stub names `bun run demo:preview:pages` as the preview path, while the existing Playwright config normally starts Vite through `scripts/playwright-webserver.sh`. Keep the normal config intact and run the new smoke suite against an explicit static preview base URL when verifying Pages behavior. ### Key Considerations * Do not run `demo:snapshot` from the Pages build, preview, scan, or smoke commands. * Do not add a CI guard in this session. * Do not add public UI polish, mobile fixes, or release docs that belong to Session 07. * Do not add Pages Functions, analytics, hosted collection, hosted scheduler, hosted local-agent control plane, or new hosted writes. ### Potential Challenges * Wrangler Pages preview is long-running: run smoke tests against its base URL with `PLAYWRIGHT_REUSE_EXISTING_SERVER=true` or an equivalent implementation note, then stop the process after verification. * Some routes may lazy-load assets or app chunks after the initial page load: the network recorder should observe route navigation long enough to catch late `/__*` requests without making the suite flaky. * Generated `demo-website/dist` includes minified assets: the scanner should handle UTF-8 text and skip or report binary assets deterministically rather than reading unbounded data. ### Relevant Considerations * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Playwright, and Cloudflare constraints define the command and test approach. * \[P02] **Extension payloads and labels stay bounded**: Scan output must protect explicit demo, fixture, fallback, degraded, and unavailable state labels without exposing private payloads. * \[P21] **Claude OAuth material stays script-only**: Fixture and dist scans must catch token, bearer, account, OAuth, and credential-shaped content. * \[P24] **Browser-safe export and triage boundaries**: Trend Finder public demo output must keep raw prompts, raw transcripts, local triage notes, and private paths out of browser-visible files. * \[P30] **AI Rogue default enablement deferred**: Smoke coverage can verify AI Rogue demo routes, but must not imply normal default enablement outside public demo mode. * \[P30] **Release gates stay bundled**: This session creates build, scan, and route evidence for Session 07 release closeout. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A route smoke test could pass a blank app shell while a lazy route fails later. * A generated-output scan could miss private text in HTML or bundled text assets. * A network assertion could accidentally allow local bridge requests or fail valid `/demo/*` assets. *** ## 9. Testing Strategy ### Unit Tests * Test `scripts/lib/pages-demo-routes.ts` for unique absolute paths, required route IDs, and no `/__` route entries. * Test `scripts/lib/pages-demo-privacy-scan.ts` with temporary fixture and dist trees for pass cases, private-path failures, bridge URL failures, token-shaped string failures, missing output, and deterministic issue ordering. * Test `scripts/lib/pages-demo-snapshot.ts` still writes the shared route matrix into snapshot metadata. ### Integration Tests * Run `bun run test -- scripts/lib/__tests__/pages-demo-routes.test.ts scripts/lib/__tests__/pages-demo-privacy-scan.test.ts scripts/lib/__tests__/pages-demo-snapshot.test.ts src/routes/__tests__/public-demo-routes.test.ts`. * Run `bun run demo:build:pages` before generated-output scanning. * Run the new package scan command against committed fixtures and `demo-website/dist`. ### Runtime Verification * Start `bun run demo:preview:pages` or an equivalent static `wrangler pages dev demo-website/dist` preview. * Run `bunx playwright test tests/e2e/pages-demo-routes.spec.ts` with the preview base URL and existing server reuse enabled. * Confirm `_redirects`, `_headers`, `index.html`, and `/demo/*` assets are served from the static output. ### Edge Cases * Route matrix contains a duplicate or non-absolute path. * A public route requests `/__token`, `/__live-data`, or another local bridge after delayed rendering. * A generated dist file contains a local path, private URL, credential label, prompt marker, transcript marker, command output marker, or token-shaped string. * `demo-website/dist` is missing because the build was not run. * Binary or large files exist in the generated output. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase31-session01-demo-mode-foundation`, `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` * Depended by: `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-session06-demo-qa-and-privacy-verification/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.