> 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_05_pages_build_and_deployment_scaffold.md).

# Session 05: Pages Build And Deployment Scaffold

**Session ID**: `phase31-session05-pages-build-and-deployment-scaffold` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Produce a deployable Cloudflare Pages static directory with the right routing, headers, scripts, and operator instructions.

***

## Scope

### In Scope (MVP)

* Add `demo:build:pages` package script.
* Add `demo:preview:pages` package script.
* Configure the build to write or copy static output into `demo-website/dist`.
* Ensure `demo-website/dist` contains a top-level `index.html`.
* Add `demo-website/public/_redirects` with the SPA fallback.
* Add `demo-website/public/_headers` with conservative static-site security and cache headers.
* Ensure `_redirects`, `_headers`, and `demo-website/public/demo/*` are present in final Pages output.
* Document Cloudflare Pages settings in `demo-website/README.md`.
* Document direct-upload behavior and the need for an operator-supplied Pages project name.

### Out of Scope

* Pages Functions or advanced `_worker.js` mode.
* Migrating root `wrangler.jsonc` to Pages.
* Reusing `bun run worker:deploy` for the demo path.
* Committing generated `demo-website/dist`.
* Adding CI guard before the demo stabilizes.

***

## Folded Source Details

Package scripts to add:

```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 local-only and must not be invoked by the Pages build.

Static build mechanics can use either:

1. Build the app directly into `demo-website/dist`.
2. Build to normal Vite output, then copy only the static client output, including generated `index.html`, and demo assets into `demo-website/dist`.

`demo-website/public/_redirects`:

```
/* /index.html 200
```

Candidate `demo-website/public/_headers`:

```
/*
  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 embedded media, external images, or analytics are introduced. Keep v1 analytics-free unless a separate privacy review approves it.

Cloudflare Pages project settings to document:

```
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 command to document:

```
bun run demo:build:pages
wrangler pages deploy demo-website/dist --project-name <pages-project-name> --branch main
```

Important deployment boundaries:

* Do not reuse `bun run worker:deploy`.
* Keep Worker deploy and Pages demo deploy independent.
* Do not add `pages_build_output_dir` to root `wrangler.jsonc` for v1.
* If Pages Functions or advanced `_worker.js` mode are introduced later, revisit `_redirects` and `_headers`.
* If advanced `_worker.js` mode is introduced later, pass static asset requests to `env.ASSETS.fetch(request)`.

Cloudflare reference docs:

* `https://developers.cloudflare.com/pages/configuration/build-configuration/`
* `https://developers.cloudflare.com/pages/configuration/build-image/`
* `https://developers.cloudflare.com/pages/configuration/redirects/`
* `https://developers.cloudflare.com/pages/configuration/headers/`
* `https://developers.cloudflare.com/pages/functions/advanced-mode/`
* `https://developers.cloudflare.com/pages/functions/wrangler-configuration/`

***

## Prerequisites

* [ ] Session 01 static app output works in demo-pages mode.
* [ ] Session 02 committed fixtures exist.
* [ ] `demo-website/dist/` is gitignored.
* [ ] The build output/copy strategy has been chosen and documented.

***

## Deliverables

1. Reproducible Pages build and preview commands.
2. Generated-only `demo-website/dist` output path.
3. Static `_redirects` and `_headers` files.
4. Pages setup documentation covering root directory, build command, output directory, production branch, and `BUN_VERSION=1.3.14`.
5. Direct-upload notes that accept the final Pages project name as an operator deployment detail.
6. Documentation that Worker deploy and Pages demo deploy remain independent.

***

## Success Criteria

* [ ] `bun run demo:build:pages` creates `demo-website/dist/index.html`.
* [ ] `demo-website/dist` contains `_redirects`, `_headers`, and `/demo/*` snapshot assets.
* [ ] `bun run demo:preview:pages` serves the static output without Vite middleware.
* [ ] Existing Worker deploy documentation and root `wrangler.jsonc` remain independent.
* [ ] Direct upload works when a Pages project name is supplied or has a documented external-configuration constraint.


---

# 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_05_pages_build_and_deployment_scaffold.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.