[stannesi] make cloudflare pages build explicit

.github/workflows/viewer-demo-pages.yml

@@ -50,9 +50,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build hosted viewer demo
-        run: pnpm viewer:demo:build
-        env:
-          PRD_VIEWER_BASE_PATH: /prd/
+        run: pnpm viewer:demo:build:github-pages
 
       - name: Add GitHub Pages SPA fallback
         run: cp apps/prd-viewer-web/dist/index.html apps/prd-viewer-web/dist/404.html

BUILD_STATUS.md

@@ -8,6 +8,7 @@
 - Documented Cloudflare Pages as the intended production host for `prd.eonhive.com` and kept GitHub Pages as temporary staging/fallback under `/prd/`.
 - Added `docs/governance/PRD_HOSTING_RUNBOOK.md` for the public hosting path, custom-domain launch checklist, and route expectations.
 - Added Cloudflare Pages SPA fallback configuration through `apps/prd-viewer-web/public/_redirects` and GitHub Pages `404.html` fallback generation in the viewer demo workflow.
+- Added explicit production/staging build scripts (`viewer:demo:build:cloudflare` and `viewer:demo:build:github-pages`) plus root `wrangler.toml` so Cloudflare Pages has a repo-native output directory and does not depend on ambiguous dashboard-only settings.
 - This slice did not change manifest shape, schemas, validator behavior, CLI commands, npm exports, Studio, Cloud, PRDc, AI, account/library, payment, crypto, rights, or broad conversion behavior.
 
 ## 2026-06-05

NEXT_STEPS.md

@@ -50,5 +50,5 @@
 41. [x] Implemented a public Home/viewer demo UX slice inside `apps/prd-viewer-web` that demonstrates the real `prd init/import -> validate -> inspect -> pack -> open` flow now that text and visual import lanes exist.
 42. [x] Chose and implemented a public hosted demo/deployment path for the reference viewer using a single `apps/prd-viewer-web` app with separate `/` Home and `/viewer/` workspace routes, generated hosted sample archives, light/dark theme support, and a GitHub Pages workflow.
 43. [x] Merged PR `#46`, renamed user-facing “Landing” language to Home, added `/docs/` as the public docs index inside the hosted app, and documented Cloudflare Pages as the intended production host for `prd.eonhive.com` with GitHub Pages retained as staging/fallback.
-44. [ ] Run public launch QA for the Cloudflare production path: verify `https://prd.eonhive.com/`, `/viewer/`, `/docs/`, hosted sample archives, route refresh behavior, theme persistence, mobile layout, and manual `.prd` upload. Keep GitHub Pages as fallback until this passes.
+44. [ ] Run public launch QA for the Cloudflare production path: configure Cloudflare Pages to use repo root, build command `pnpm viewer:demo:build:cloudflare`, and output directory `apps/prd-viewer-web/dist`; then verify `https://prd.eonhive.com/`, `/viewer/`, `/docs/`, hosted sample archives, route refresh behavior, theme persistence, mobile layout, and manual `.prd` upload. Keep GitHub Pages as fallback until this passes.
 45. [ ] After Cloudflare launch QA passes, choose the next focused product polish slice: likely Home/Web Viewer UI cleanup toward a more Adobe-style document product page, while still avoiding accounts, pricing, AI assistant, Studio, Cloud, PRDc, payments, crypto, rights, and broad conversion scope.

README.md

@@ -313,6 +313,8 @@ Hosted viewer demo workflow:
 ```bash
 pnpm viewer:demo:assets
 pnpm viewer:demo:build
+pnpm viewer:demo:build:cloudflare
+pnpm viewer:demo:build:github-pages
 pnpm viewer:demo:dev
 ```
 
@@ -322,6 +324,8 @@ The hosted app has three public routes in one deployable Vite build: `/` is Home
 
 The public `/docs/` route is a user-friendly navigation layer over canonical repo docs. It does not replace `docs/`, and it intentionally does not link the tracked `codex/` operational planning files.
 
+Cloudflare Pages should build from the repository root with `pnpm viewer:demo:build:cloudflare` and output `apps/prd-viewer-web/dist`. Do not set the Cloudflare project root to `apps/prd-viewer-web`; the production build needs root access to build the CLI and pack hosted sample archives before the Vite build.
+
 
 ## Contributor MVP gate (no npm credentials required)
 
@@ -468,6 +472,10 @@ For Codex-driven work, use the repo-local run actions instead of manually piecin
   Builds the workspace, packs the example archives, and starts the web viewer.
 * `pnpm viewer:demo:build`
   Packs canonical examples, prepares hosted sample assets, and builds the deployable PRD Web Viewer demo.
+* `pnpm viewer:demo:build:cloudflare`
+  Builds the hosted viewer demo for the root-domain Cloudflare Pages production path.
+* `pnpm viewer:demo:build:github-pages`
+  Builds the hosted viewer demo for the GitHub Pages `/prd/` staging/fallback path.
 * `pnpm viewer:demo:dev`
   Prepares hosted sample assets and starts the PRD Web Viewer demo locally.
 

codex/SESSION_HANDOFF.md

@@ -2,116 +2,83 @@
 
 ## Current status
 
-- PR `#46` (`[stannesi] separate hosted landing and viewer routes`) was merged into `main`.
-- Local `main` was synced, then branch `thehive/prd-public-site-docs-hosting` was created.
-- Current branch implements the public site/docs/hosting polish lane.
-- The hosted app still lives in one deployable Vite app: `apps/prd-viewer-web`.
-- Public app routes are now `/` = Home, `/viewer/` = PRD Web Viewer, and `/docs/` = public docs index.
-- Cloudflare Pages at `prd.eonhive.com` is documented as the intended production host.
-- GitHub Pages remains staging/fallback under `/prd/` until Cloudflare launch QA passes.
+- PR `#47` (`[stannesi] add public docs and hosting path`) is merged into `main`.
+- Local `main` was fast-forwarded to `origin/main`.
+- Current branch is `thehive/cloudflare-pages-build-config`.
+- This branch addresses Cloudflare Pages build ambiguity after the hosted public site/docs lane.
+- The user pasted only the Cloudflare dependency-install portion of the failing build log, so the exact failing line was not available.
 
 ## Completed work
 
-- Renamed user-facing hosted-app navigation from “Landing” to “Home” while keeping route `/`.
-- Added `/docs/` to the app route helper and browser app shell.
-- Added an in-app public docs index for Home, Getting Started, CLI, Format, Profiles, Examples, Viewer, Conformance, and Release/Operator Notes.
-- Kept public docs as a navigation layer over canonical repo docs rather than copying or replacing `docs/`.
-- Ensured public docs do not link tracked `codex/` planning or handoff files.
-- Added Cloudflare/GitHub Pages hosting notes to the public docs surface.
-- Added Cloudflare Pages `_redirects` SPA fallback for `/viewer/` and `/docs/` refreshes.
-- Added GitHub Pages `404.html` fallback generation in the Pages workflow.
-- Added `docs/governance/PRD_HOSTING_RUNBOOK.md`.
-- Updated README, docs index, product docs, roadmap, build status, and backlog state.
-- Marked `NEXT_STEPS.md` item `43` complete and added next launch-QA/polish items.
+- Added root script `viewer:demo:build:cloudflare` for production Cloudflare Pages builds with root-domain base path `/`.
+- Added root script `viewer:demo:build:github-pages` for GitHub Pages staging/fallback builds with base path `/prd/`.
+- Updated `.github/workflows/viewer-demo-pages.yml` to use `pnpm viewer:demo:build:github-pages`.
+- Added root `wrangler.toml` declaring Cloudflare Pages output directory `apps/prd-viewer-web/dist`.
+- Updated the hosting runbook with exact Cloudflare dashboard settings:
+  - project root: repository root
+  - build command: `pnpm viewer:demo:build:cloudflare`
+  - output directory: `apps/prd-viewer-web/dist`
+- Updated README, docs index, build status, and backlog state.
 
 ## In-progress work
 
-- No code work is currently in progress.
-- Branch is ready for commit/push/PR after final review.
+- Implementation and validation are complete locally.
+- Branch is ready for commit/push/PR.
 
 ## Changed files
 
+- `.github/workflows/viewer-demo-pages.yml`
 - `BUILD_STATUS.md`
 - `NEXT_STEPS.md`
 - `README.md`
-- `.github/workflows/viewer-demo-pages.yml`
-- `apps/prd-viewer-web/public/_redirects`
-- `apps/prd-viewer-web/src/App.tsx`
-- `apps/prd-viewer-web/src/styles.css`
-- `apps/prd-viewer-web/src/viewerDemoContent.ts`
-- `apps/prd-viewer-web/src/viewerDemoContent.test.ts`
-- `apps/prd-viewer-web/src/viewerRoutes.ts`
-- `apps/prd-viewer-web/src/viewerRoutes.test.ts`
+- `codex/SESSION_HANDOFF.md`
 - `docs/README.md`
-- `docs/foundation/04_PRD/PRD_ROADMAP.md`
 - `docs/governance/PRD_HOSTING_RUNBOOK.md`
-- `docs/product/PRD_AUTHORING_WORKFLOW.md`
-- `docs/product/PRD_IMPORT_EXPORT_MATRIX.md`
-- `docs/product/PRD_PRODUCT_BOUNDARIES.md`
-- `codex/SESSION_HANDOFF.md`
+- `package.json`
+- `wrangler.toml`
 
 ## Commands run
 
 - `git status --short --branch`
-- GitHub connector: inspected and merged PR `#46`
 - `git fetch origin main`
 - `git switch main`
 - `git pull --ff-only origin main`
-- `git switch -c thehive/prd-public-site-docs-hosting`
-- `PATH="/opt/homebrew/bin:$PATH" node_modules/.bin/tsc -b apps/prd-viewer-web/tsconfig.json --pretty false`
-- `PATH="/opt/homebrew/bin:$PATH" pnpm exec vitest run apps/prd-viewer-web/src/viewerRoutes.test.ts apps/prd-viewer-web/src/viewerDemoContent.test.ts apps/prd-viewer-web/src/viewerArchiveFiles.test.ts apps/prd-viewer-web/src/viewerDocumentOutline.test.ts apps/prd-viewer-web/src/viewerRenderMode.test.ts apps/prd-viewer-web/src/viewerRenderMode.integration.test.ts`
+- `git switch -c thehive/cloudflare-pages-build-config`
+- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build:cloudflare`
 - `PATH="/opt/homebrew/bin:$PATH" pnpm docs:check -- --include-root-docs`
 - `git diff --check`
-- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build`
-- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:dev -- --host 127.0.0.1 --port 5173`
-- Browser verification at `http://localhost:5173/`
-- Browser verification at `http://localhost:5173/viewer/`
-- Browser verification at `http://localhost:5173/docs/`
+- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build:github-pages`
 - `PATH="/opt/homebrew/bin:$PATH" pnpm foundation:gate`
 
 ## Tests / verification
 
-- Viewer route/content/render targeted tests passed: 6 files, 24 tests.
-- `apps/prd-viewer-web` TypeScript build passed.
-- `pnpm docs:check -- --include-root-docs` passed.
+- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build:cloudflare` passed.
+- `PATH="/opt/homebrew/bin:$PATH" pnpm viewer:demo:build:github-pages` passed.
+- `PATH="/opt/homebrew/bin:$PATH" pnpm docs:check -- --include-root-docs` passed.
 - `git diff --check` passed.
-- `pnpm viewer:demo:build` passed and regenerated ignored hosted sample archives.
-- Cloudflare Pages `_redirects` is expected to be copied into `apps/prd-viewer-web/dist` during Vite build.
-- GitHub Pages workflow now creates `apps/prd-viewer-web/dist/404.html` during CI deployment.
-- Browser verification confirmed:
-  - `/` renders Home with route state `home`
-  - `/viewer/` renders the PRD Web Viewer with route state `viewer`
-  - `/docs/` renders the public docs index with route state `docs`
-  - public docs sections render in the expected order
-  - Cloudflare Pages and GitHub Pages hosting copy is visible
-  - public docs contain no `codex/` links
-  - browser console had no errors or warnings
-- `pnpm foundation:gate` passed: build, tests, docs consistency, example validation, and aggregate example smoke.
+- `PATH="/opt/homebrew/bin:$PATH" pnpm foundation:gate` passed: build, tests, docs consistency, example validation, and aggregate example smoke.
 
 ## Known issues
 
-- Cloudflare Pages production deployment is not configured or launch-QA verified yet.
-- GitHub Pages remains staging/fallback until `prd.eonhive.com` passes launch QA.
-- Hosted sample archives are generated ignored build assets and should not be committed.
-- Manual `.prd` file-picker/drop upload was not automated in-browser; archive filtering remains covered by tests, and hosted sample loading exercises the same in-memory open path after archive bytes are available.
+- The exact Cloudflare failing command/error line was not included in the pasted log.
+- Cloudflare Pages still needs to be configured in the dashboard to build from repository root with `pnpm viewer:demo:build:cloudflare` and output `apps/prd-viewer-web/dist`.
+- Cloudflare launch QA is still pending after build succeeds.
 
 ## Next recommended task
 
-- Commit and open PR `[stannesi] add public docs and hosting path`.
-- After merge, run `NEXT_STEPS.md` item `44`: configure/verify Cloudflare Pages for `prd.eonhive.com`, then launch-QA `/`, `/viewer/`, `/docs/`, hosted samples, route refresh, theme persistence, mobile layout, and manual `.prd` upload.
+- Commit, push, and open a PR for the Cloudflare build-config fix.
+- After merge, retry Cloudflare Pages with the documented settings.
 
 ## Important decisions
 
-- Keep one deployable app: `apps/prd-viewer-web`.
-- Use route labels `/` Home, `/viewer/` Web Viewer, and `/docs/` public docs.
-- Use Cloudflare Pages as intended production hosting for `prd.eonhive.com`.
-- Keep GitHub Pages as staging/fallback under `/prd/`.
-- Keep canonical docs in `docs/`; public `/docs/` is an index/navigation layer.
-- Keep `codex/PLANS.md` and `codex/SESSION_HANDOFF.md` tracked but hidden from public docs/site navigation.
-- Do not add a changeset; this is private app/docs/operator state.
+- Cloudflare production uses base path `/`.
+- GitHub Pages staging/fallback uses base path `/prd/`.
+- Cloudflare Pages must build from repo root, not `apps/prd-viewer-web`, because hosted sample preparation needs the CLI and examples.
+- No PRD manifest, schema, validator, CLI command, viewer runtime, npm package, Studio, Cloud authoring, PRDc, payment, crypto, rights, or broad conversion behavior changes belong in this fix.
 
 ## Do not redo
 
-- Do not redo npm publication, deprecation, registry audit, or consumer smoke for `0.1.1`.
-- Do not add Studio, Cloud authoring, PRDc product behavior, AI assistant, accounts/library, payment, crypto, rights, universal file viewer, DOCX/EPUB/PDF conversion, HTML import, or visual-editor behavior in this slice.
-- Do not add new manifest fields, schema rules, validator issue codes, viewer support states, CLI commands, package exports, or npm release behavior in this slice.
+- Do not redo npm release work.
+- Do not change PRD package format semantics.
+- Do not replace the one-app Home/docs/viewer route model.
+- Do not remove `codex/PLANS.md` or `codex/SESSION_HANDOFF.md`; keep them tracked but hidden from public docs/site navigation.

docs/README.md

@@ -166,6 +166,7 @@ Current public demo surface:
 * `../apps/prd-viewer-web/` (one deployable app with `/` Home, `/viewer/` reference Web Viewer workspace, and `/docs/` public docs index)
 * `governance/PRD_HOSTING_RUNBOOK.md` (Cloudflare production and GitHub Pages fallback/staging path)
 * `../.github/workflows/viewer-demo-pages.yml` (temporary GitHub Pages staging/fallback deployment)
+* `../wrangler.toml` (Cloudflare Pages output-directory config)
 
 The public `/docs/` route is a navigation layer over canonical repo docs. It is not a replacement for this directory, and it intentionally does not link `../codex/` operational planning files.
 

docs/governance/PRD_HOSTING_RUNBOOK.md

@@ -36,11 +36,17 @@ Current build surfaces:
 ```bash
 pnpm viewer:demo:assets
 pnpm viewer:demo:build
+pnpm viewer:demo:build:cloudflare
+pnpm viewer:demo:build:github-pages
 pnpm viewer:demo:dev
 ```
 
 `viewer:demo:assets` packs canonical examples and copies selected generated `.prd` archives into the ignored `apps/prd-viewer-web/public/examples/` directory.
 
+`viewer:demo:build:cloudflare` is the production Cloudflare Pages build. It uses root-domain base path `/`.
+
+`viewer:demo:build:github-pages` is the staging/fallback GitHub Pages build. It uses base path `/prd/`.
+
 Hosted sample archives are demo assets only. They do not define a PRD network-loading guarantee and do not change the reference viewer truth: eager whole-package in-memory loading.
 
 The Vite public directory includes `_redirects` so Cloudflare Pages serves the SPA entry for `/viewer/` and `/docs/` refreshes. The GitHub Pages workflow copies `index.html` to `404.html` after build for the same staging/fallback route behavior.
@@ -49,12 +55,19 @@ The Vite public directory includes `_redirects` so Cloudflare Pages serves the S
 
 1. Create or select the Cloudflare Pages project for `apps/prd-viewer-web`.
 2. Configure production domain `prd.eonhive.com`.
-3. Build with a root-domain base path, not the GitHub Pages `/prd/` base path.
-4. Ensure generated demo assets are prepared before the Vite build.
-5. Verify direct refresh for `/`, `/viewer/`, and `/docs/`.
-6. Verify hosted sample archives open through the same viewer path as manual `.prd` uploads.
-7. Verify dark/light theme persistence on production.
-8. Verify desktop and mobile layouts.
+3. Use the repository root as the Cloudflare project root.
+4. Use build command `pnpm viewer:demo:build:cloudflare`.
+5. Use build output directory `apps/prd-viewer-web/dist`.
+6. Build with a root-domain base path, not the GitHub Pages `/prd/` base path.
+7. Ensure generated demo assets are prepared before the Vite build.
+8. Verify direct refresh for `/`, `/viewer/`, and `/docs/`.
+9. Verify hosted sample archives open through the same viewer path as manual `.prd` uploads.
+10. Verify dark/light theme persistence on production.
+11. Verify desktop and mobile layouts.
+
+Do not set the Cloudflare project root to `apps/prd-viewer-web`. The production build needs the repository root so it can build the CLI, pack example archives, copy hosted demo assets, and then build the Vite app.
+
+The root `wrangler.toml` declares `pages_build_output_dir = "apps/prd-viewer-web/dist"` for Cloudflare Pages.
 
 Reference docs:
 

package.json

@@ -21,6 +21,8 @@
     "dev:web": "pnpm --filter @eonhive/prd-web-viewer dev",
     "viewer:demo:assets": "pnpm examples:pack && node ./scripts/prepare-viewer-demo-assets.mjs",
     "viewer:demo:build": "pnpm viewer:demo:assets && pnpm --filter @eonhive/prd-web-viewer build",
+    "viewer:demo:build:cloudflare": "PRD_VIEWER_BASE_PATH=/ pnpm viewer:demo:build",
+    "viewer:demo:build:github-pages": "PRD_VIEWER_BASE_PATH=/prd/ pnpm viewer:demo:build",
     "viewer:demo:dev": "pnpm viewer:demo:assets && pnpm --filter @eonhive/prd-web-viewer dev",
     "preexamples:pack": "pnpm --filter @eonhive/prd-cli build",
     "examples:pack": "node packages/prd-cli/dist/cli.js pack examples/document-basic --out examples/dist/document-basic.prd && node packages/prd-cli/dist/cli.js pack examples/document-segmented-basic --out examples/dist/document-segmented-basic.prd && node packages/prd-cli/dist/cli.js pack examples/resume-basic --out examples/dist/resume-basic.prd && node packages/prd-cli/dist/cli.js pack examples/comic-basic --out examples/dist/comic-basic.prd && node packages/prd-cli/dist/cli.js pack examples/storyboard-basic --out examples/dist/storyboard-basic.prd",

wrangler.toml

@@ -0,0 +1,10 @@
+# Company: EonHive Inc.
+# Title: PRD Cloudflare Pages Config
+# Purpose: Declare the public PRD site build output for Cloudflare Pages.
+# Author: Stan Nesi
+# Created: June 9, 2026
+# Updated: June 9, 2026
+# Notes: Vibe coded with Codex.
+
+name = "prd"
+pages_build_output_dir = "apps/prd-viewer-web/dist"