> 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-session07-release-polish-and-documentation/spec.md). # Session Specification **Session ID**: `phase31-session07-release-polish-and-documentation` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24 *** ## 1. Session Overview This session finishes Phase 31 by making the static Cloudflare Pages demo clear, credible, responsive, and documented. Sessions 01 through 06 created the public demo mode, snapshot exporter, read-only route behavior, static Pages build, privacy scans, and route smoke tests. The remaining gap is release quality: visible frozen-snapshot provenance, polished unavailable states, mobile route review, Pages-specific bundle evidence, direct-upload guidance, and public demo closeout notes. The work keeps the existing Cloudflare Workers deployment path intact. The Pages demo remains static-only, reads committed `/demo/*` fixtures, and must not add hosted collection, local bridge access, secret-bearing runtime behavior, analytics, Pages Functions, or remote code loading. Session 06 proved the 24-route static smoke matrix can render without `/__*` requests. This session uses that matrix as the release review target and updates the demo metadata, UI copy, tests, and documentation so a public visitor can understand that the site is a frozen demo snapshot rather than a live local operator runtime. *** ## 2. Objectives 1. Add visible public-demo provenance based on committed snapshot metadata. 2. Refresh and tune demo snapshot content and labels so major surfaces are populated without implying hosted live collection. 3. Polish unavailable and browser-local states for public-demo-only controls on host, agent, Trend Finder, Knowledge Graph, and AI Rogue surfaces. 4. Record Pages release evidence across mobile smoke, privacy scan, bundle budget, direct-upload guidance, deployment docs, and closeout notes. *** ## 3. Prerequisites ### Required Sessions * [x] `phase31-session01-demo-mode-foundation` - Provides public demo mode and demo-pages build branching. * [x] `phase31-session02-snapshot-exporter-and-fixtures` - Provides committed browser-safe snapshot fixtures and metadata. * [x] `phase31-session03-app-data-and-mutation-boundary` - Provides frozen data loading and shared mutation guards. * [x] `phase31-session04-extensions-and-agent-routes` - Provides demo-safe extension, agent, Knowledge Graph, and AI Rogue routes. * [x] `phase31-session05-pages-build-and-deployment-scaffold` - Provides Pages build, preview, static headers, redirects, and setup docs. * [x] `phase31-session06-demo-qa-and-privacy-verification` - Provides route matrix smoke coverage, no-bridge assertions, build checks, and privacy scans. ### Required Tools Or Knowledge * Bun 1.3.14, Vite 8, TanStack Start, React 19, Tailwind CSS 4, Vitest, Playwright, Wrangler Pages dev, and shell gzip. * Existing Pages demo route matrix in `scripts/lib/pages-demo-routes.ts`. * Existing public snapshot metadata and manifest under `demo-website/`. ### Environment Requirements * Repository root with dependencies installed. * `wrangler pages dev` available through the package-pinned Wrangler binary. * No Cloudflare Pages project name is required for implementation; direct upload can be documented or parameterized until an operator supplies a project name. *** ## 4. Scope ### In Scope (MVP) * Public visitors can see frozen-snapshot provenance in the app shell or route headers - Implement a small metadata-backed provenance surface with honest capture, source commit, route coverage, and scan state labels. * Public visitors can explore populated host and extension routes without live collection claims - Refresh/tune committed fixture content and metadata while preserving the allowlist-first projection and privacy scan. * Public visitors can tell disabled controls are unavailable by design - Polish shared public-demo copy for local refresh, setup, scheduler, source setup, agent admin, Knowledge Graph ingest, Trend Finder run, and AI Rogue browser-local states. * Maintainers can review public-demo mobile behavior - Add mobile route smoke coverage and responsive fixes for the Session 06 route matrix. * Maintainers can review Pages-specific release gates - Add or adapt budget, direct-upload, scan, preview, and closeout evidence around `demo-website/dist`. * Operators can deploy the demo separately from the Worker path - Update deployment docs and demo README with Git deployment, direct upload, static boundaries, and the external Pages project-name constraint. ### Out Of Scope (Deferred) * Hosted source collection, scraping, schedulers, local-agent control planes, chat/upload/admin writes, OAuth/account-auth/API-key flows, and secret-bearing runtime - Reason: Phase 31 v1 is static-only and public-safe. * Pages Functions, `_worker.js`, or moving the main app away from the Worker deployment path - Reason: the phase explicitly keeps Pages separate from the normal Worker build. * Analytics, tracking, or third-party public-demo telemetry - Reason: these need separate privacy review. * CI enforcement for Pages build plus scan - Reason: the Phase 31 PRD defers CI until the demo stabilizes; this session may document the follow-up but does not need to add workflow gates. *** ## 5. Technical Approach ### Architecture Use the existing public-demo boundary rather than creating a forked demo app. Add a small browser-safe metadata reader for `/demo/snapshot-metadata.json` and render it through a reusable provenance component mounted in the app shell. Keep metadata fetch failure non-fatal: the primary snapshot data still comes from `useLiveData()`, while provenance shows loading, unavailable, or stale states with product-facing copy only. Refresh the committed snapshot metadata and live-data fixture through the existing exporter/projection path where possible. Keep the privacy scan as the contract for committed fixtures and generated output. Align metadata route coverage with `PAGES_DEMO_ROUTE_PATHS`, because Session 06 expanded the smoke matrix to 24 routes while the committed metadata still lists the older route set. For release gates, make the existing bundle checker usable against `demo-website/dist/assets` instead of duplicating budget logic. Add a Pages budget package script and record it with build, scan, static preview, mobile route smoke, direct upload guidance, and ASCII/LF validation in the session notes. ### Design Patterns * Shared public-demo helpers: Centralize provenance and unavailable copy in `src/lib/public-demo.ts` plus a metadata helper instead of scattering string decisions across routes. * Reusable component: Keep visual provenance in a small component under `src/components/` so the top bar and route surfaces can share copy and accessibility behavior. * Existing route matrix: Reuse `scripts/lib/pages-demo-routes.ts` for desktop, mobile, snapshot metadata, and release evidence so route coverage stays deterministic. * Parameterized external deploy command: Keep the Pages project name outside git, and make any direct-upload helper require explicit operator input. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------- | | `src/lib/public-demo-metadata.ts` | Browser-safe snapshot metadata contract, fetch helper, and fallback view model | \~140 | | `src/components/public-demo-provenance.tsx` | Reusable frozen-snapshot provenance UI | \~160 | | `src/components/__tests__/public-demo-provenance.test.tsx` | Unit tests for metadata states, labels, and accessible provenance output | \~180 | | `tests/e2e/pages-demo-mobile.spec.ts` | Mobile Pages route smoke coverage with no-bridge and overflow assertions | \~180 | | `scripts/lib/pages-demo-deploy.ts` | Direct-upload command model and project-name validation | \~120 | | `scripts/demo/deploy-pages-demo.ts` | CLI wrapper for direct upload or dry-run command output | \~100 | | `scripts/lib/__tests__/pages-demo-deploy.test.ts` | Unit tests for direct-upload command validation and redaction-safe output | \~120 | | `.spec_system/specs/phase31-session07-release-polish-and-documentation/implementation-notes.md` | Implementation evidence and release gate ledger | \~200 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | | `src/lib/public-demo.ts` | Refine public-demo unavailable copy and shared provenance constants | \~50 | | `src/routes/__root.tsx` | Mount provenance in the top bar without crowding mobile or Trend Finder route state | \~80 | | `src/styles.css` | Add only necessary responsive/provenance utility styling if Tailwind classes are insufficient | \~40 | | `scripts/lib/pages-demo-snapshot.ts` | Keep metadata route coverage and demo labels aligned with the current route matrix | \~80 | | `demo-website/public/demo/live-data.snapshot.json` | Tune public-safe demo content and labels | \~200 | | `demo-website/public/demo/snapshot-metadata.json` | Refresh capture metadata, route coverage, redaction counts, and scan state | \~120 | | `demo-website/snapshot-manifest.json` | Refresh manifest with current metadata, files, and field policy | \~160 | | `scripts/check-bundle-budget.sh` | Allow a configurable asset directory for Pages budget checks | \~30 | | `package.json` | Add Pages budget and direct-upload helper scripts | \~10 | | `scripts/lib/pages-demo-routes.ts` | Add provenance/mobile surface expectations where needed | \~40 | | `tests/e2e/pages-demo-routes.spec.ts` | Assert provenance on static desktop route smoke without weakening no-bridge checks | \~60 | | `demo-website/README.md` | Verify and clarify Pages demo deployment, direct upload, and boundary docs | \~80 | | `docs/deployment.md` | Add Cloudflare Pages public demo section separate from Worker deployment | \~160 | | `docs/CHANGELOG.md` | Record Phase 31 Session 07 release polish and documentation changes | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Public-demo pages show visible frozen-snapshot provenance without claiming live hosted collection. * [ ] Snapshot metadata route coverage matches the current `PAGES_DEMO_ROUTE_PATHS` route matrix. * [ ] Unavailable local actions explain that hosted demo actions are read-only, unavailable, or browser-local by design. * [ ] Key route families remain usable at mobile viewport sizes from static preview. * [ ] Pages bundle budget is measured against `demo-website/dist/assets`. * [ ] Direct upload is either parameterized through an operator-supplied project name or documented as an external deployment constraint. * [ ] Deployment docs explain Pages Git deployment and direct upload separately from the existing Worker deployment path. ### Testing Requirements * [ ] Unit tests cover metadata loading, unavailable metadata states, and provenance rendering. * [ ] Unit tests cover direct-upload command validation and output. * [ ] Focused route smoke validates provenance and no `/__*` requests. * [ ] Mobile route smoke validates product surfaces, no `/__*` requests, and no horizontal document overflow. * [ ] Required commands run: `bun run typecheck`, `bun run typecheck:scripts`, `bun run lint`, focused Vitest, `bun run demo:build:pages`, `bun run demo:scan:pages`, and the Pages budget script. ### Non-Functional Requirements * [ ] No public-demo fixture, generated output, docs, or UI copy exposes local paths, secrets, credential labels, auth material, raw prompts, transcripts, command output, private memory text, or local bridge URLs. * [ ] Existing Worker build/deploy docs and commands remain separate and intact. * [ ] Public-demo UI remains product-facing; diagnostics stay in tests, scripts, docs, or session notes. * [ ] No new dependency, analytics, Pages Functions, remote code, database, or server storage surface 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 * [ ] Release gates are recorded together in `implementation-notes.md` *** ## 8. Implementation Notes ### Working Assumptions * Direct upload needs an operator-supplied Pages project name: The Phase 31 PRD and `demo-website/README.md` both say the project name is external deployment configuration and is not committed. Planning can proceed because the success criteria allow either a working direct-upload command or a documented project-name constraint. * The Session 06 route matrix is the mobile review target: Session 06 validated 24 static routes through `tests/e2e/pages-demo-routes.spec.ts`, and the Session 07 stub says mobile targets are selected from that smoke matrix. Planning can proceed without inventing a separate route list. * Pages budget should reuse the existing budget checker with a configurable dist path: `scripts/check-bundle-budget.sh` currently points at `dist/client/assets`, while Pages output lands under `demo-website/dist/assets`. Reusing the existing checker avoids duplicating budget thresholds. ### Conflict Resolutions * Snapshot metadata route coverage is older than current route smoke coverage: `demo-website/public/demo/snapshot-metadata.json` lists the pre-Session 06 route set, while `scripts/lib/pages-demo-routes.ts` now includes Knowledge Graph, Claude Code, AI Rogue, Workbench, and other 24-route smoke entries. Choose the route matrix as authoritative because Session 06 validation passed against it and the exporter already imports `PAGES_DEMO_ROUTE_PATHS`. ### Key Considerations * Keep public-demo provenance short enough for the 56px top bar and move details behind compact labels or responsive wrapping rather than crowding mobile. * Treat metadata fetch failure as non-fatal and visible, not as an application error. * Run privacy scans after any snapshot or fixture change, even if the change is only copy or route metadata. * Keep route product surfaces free of development diagnostics; scripts and tests can hold detailed gate output. ### Potential Challenges * Top bar crowding on mobile: Use progressive disclosure and hide secondary chips below larger breakpoints while preserving an accessible provenance label. * Snapshot content freshness versus safety: Prefer exporter-backed projection updates and preserve redaction counts; if hand edits are unavoidable, rerun fixture and dist scans before recording closeout. * Direct upload without a project name: Provide a parameterized helper and docs; record that live upload execution requires operator configuration. * Pages budget drift: Measure the generated Pages assets after `bun run demo:build:pages`, not the Worker `dist/client` output. ### Relevant Considerations * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker/Pages constraints shape all build and test commands. * \[P02] **Extension payloads and labels stay bounded**: Public demo labels must distinguish frozen, fixture, fallback, degraded, unavailable, and browser-local states. * \[P21] **Claude OAuth material stays script-only**: Demo fixtures, metadata, docs, UI, and generated output must not expose token, account, bearer, or credential-shaped material. * \[P24] **Browser-safe export and triage boundaries**: Trend Finder snapshot, Brief, and workbench data must remain browser-safe projections only. * \[P26] **Knowledge Graph contract alignment**: Public graph fixtures and route UI must stay parsed through the shared Knowledge Graph contracts. * \[P30] **Release gates stay bundled**: Record docs/reference checks, privacy scans, payload/bundle gates, build, focused browser coverage, and source/extension readiness proof together. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Metadata fetch and render paths must include loading, empty, error, and offline states without breaking the main app shell. * Direct-upload helper must validate project-name input and keep command output redaction-safe. * Static route smoke and mobile checks must retain no-bridge assertions and avoid hiding product-surface failures behind broad selectors. *** ## 9. Testing Strategy ### Unit Tests * Test `src/lib/public-demo-metadata.ts` parsing, missing metadata fallback, scan state mapping, route coverage labels, and non-fatal fetch errors. * Test `src/components/public-demo-provenance.tsx` for accessible labels, mobile-safe compact rendering, unavailable metadata copy, and product-facing text. * Test `scripts/lib/pages-demo-deploy.ts` for missing project name, invalid project name, explicit branch, and generated Wrangler command arguments. ### Integration Tests * Extend `tests/e2e/pages-demo-routes.spec.ts` to require provenance on static desktop routes while preserving no `/__*` request assertions. * Add `tests/e2e/pages-demo-mobile.spec.ts` to run selected or full route matrix checks at mobile viewport sizes with no document horizontal overflow. * Keep existing snapshot, build, scan, and route matrix tests passing. ### Runtime Verification * Run `bun run demo:build:pages`. * Run the Pages budget script against `demo-website/dist/assets`. * Run `bun run demo:scan:pages`. * Serve `demo-website/dist` with `wrangler pages dev` and run desktop plus mobile Playwright smoke against the static preview. ### Edge Cases * Missing or malformed `snapshot-metadata.json`. * Snapshot metadata with route coverage behind the route matrix. * Offline browser state during metadata fetch. * Long source commit or captured timestamp labels in narrow top bar widths. * Missing Pages project name for direct upload. * Pages output absent when budget script runs. *** ## 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`, `phase31-session06-demo-qa-and-privacy-verification` * Depended by: Phase 31 `updateprd`, then Phase Transition `audit` *** ## 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-session07-release-polish-and-documentation/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.