fix: repair Cloudflare Pages deploy + make CI mirror the real build

.github/workflows/rfc_deploy.yml

@@ -2,33 +2,29 @@ on:
   push:
     branches:
       - main
+  pull_request:
+    types: [opened, synchronize, reopened]
 
-name: Deploy RFC Docs
+name: Verify Cloudflare Pages build
+
+# NOTE: This workflow no longer deploys anything.
+#
+# https://rfc.tari.com is served by a Cloudflare Pages project ("rfcs", in the
+# "Tari and Yat" Cloudflare account) connected directly to this repo. Cloudflare
+# builds and publishes on every push to `main` — GitHub Actions is NOT in the
+# publish path. (The old job here pushed a build to the gh-pages branch for
+# GitHub Pages, which was retired in 2024 and served nothing.)
+#
+# What this job does now: run the EXACT same build Cloudflare runs
+# (scripts/build.sh), so if a change would break the real deploy, CI goes red
+# immediately instead of the site silently freezing. See DEPLOYMENT.md.
 
 jobs:
-  deploy:
+  verify-build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v2.3.1
-
-      - name: Install 🦀
-        run: |
-          curl -L https://github.com/badboy/mdbook-mermaid/releases/download/v0.17.0/mdbook-mermaid-v0.17.0-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.5.2/mdbook-v0.5.2-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-          export PATH=$PATH:$(pwd)
-          mdbook --version
-          mdbook-mermaid --version
-
-      - name: Build 🛠
-        run: |
-          export PATH=$PATH:$(pwd)
-          mdbook test
-          mdbook build
+        uses: actions/checkout@v4
 
-      - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@4.1.3
-        with:
-          branch: gh-pages
-          folder: book
-          commit-message: "[skip ci] deploy gh-pages"
+      - name: Build the book the same way Cloudflare Pages does 🛠
+        run: bash scripts/build.sh

.github/workflows/rfc_test.yml

@@ -7,23 +7,22 @@ on:
 
 name: Test RFC Docs
 
+# Builds the book via the canonical scripts/build.sh (the same recipe Cloudflare
+# Pages uses to publish rfc.tari.com), then additionally runs `mdbook test` to
+# compile the rust code samples in the docs. Reusing the script keeps the mdBook
+# version single-sourced — see DEPLOYMENT.md.
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v2.3.1
+        uses: actions/checkout@v4
 
-      - name: Install 🦀
-        run: |
-          curl -L https://github.com/badboy/mdbook-mermaid/releases/download/v0.17.0/mdbook-mermaid-v0.17.0-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.5.2/mdbook-v0.5.2-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-          export PATH=$PATH:$(pwd)
-          mdbook --version
-          mdbook-mermaid --version
+      - name: Build the book (same recipe as Cloudflare Pages) 🛠
+        run: bash scripts/build.sh
 
-      - name: Test 🧪
+      - name: Test rust code samples 🧪
         run: |
-          export PATH=$PATH:$(pwd)
+          export PATH="$PWD/.build-tools:$PATH"
           mdbook test
-          mdbook build

.gitignore

@@ -21,3 +21,6 @@ book/
 
 # Ignore local history in Visual Studio Code
 .lh
+
+# mdBook binaries fetched by scripts/build.sh
+.build-tools/

DEPLOYMENT.md

@@ -0,0 +1,64 @@
+# How rfc.tari.com is built and deployed
+
+## TL;DR
+
+Push to `main` → **Cloudflare Pages** builds the book with mdBook → publishes to
+**https://rfc.tari.com**. That's the whole pipeline. GitHub Actions is **not** in
+the publish path.
+
+## The live path
+
+1. You push / merge to `main` on `github.com/tari-project/rfcs`.
+2. The **Cloudflare Pages GitHub App** (`cloudflare-workers-and-pages`, installed
+   on the `tari-project` org) notifies the Cloudflare Pages project **`rfcs`**,
+   which lives in the **"Tari and Yat"** Cloudflare account
+   (`a5eaa078d76d43e7b6e386a3d0ff272d`).
+3. Cloudflare clones the repo and runs the project's build command,
+   **`bash scripts/build.sh`**, which installs the pinned mdBook + mdbook-mermaid
+   and runs `mdbook build` (output: `./book`).
+4. Cloudflare uploads `./book` to its CDN and serves it on the project's
+   `*.pages.dev` domain and the custom domain **rfc.tari.com** (a proxied
+   Cloudflare DNS record on the `tari.com` zone, configured in the Pages project —
+   not in Terraform).
+5. The build reports back to GitHub as the **"Cloudflare Pages"** check on the
+   commit.
+
+## The build recipe lives in one place
+
+[`scripts/build.sh`](scripts/build.sh) is the single source of truth for how the
+book is built, and it pins the mdBook / mdbook-mermaid versions. Both of these
+call it:
+
+- **Cloudflare Pages** — build command is `bash scripts/build.sh` (this is what
+  actually publishes the site).
+- **GitHub Actions** — `.github/workflows/rfc_deploy.yml` and `rfc_test.yml` run
+  the same script on every push and PR, so a change that would break the real
+  Cloudflare build turns CI red *before* it reaches `main`.
+
+To change the mdBook version, edit `scripts/build.sh` only. Do **not** add a
+second build recipe.
+
+## Things that are NOT the deploy
+
+- **`.github/workflows/rfc_deploy.yml`** no longer deploys. It used to push a
+  build to the `gh-pages` branch for GitHub Pages; GitHub Pages for this repo was
+  retired in 2024 and serves nothing. The workflow now just verifies the build.
+- A green GitHub Actions run alone does not mean the site published. The
+  authoritative signal is the **Cloudflare Pages check** on the commit, or the
+  **Deployments** tab of the `rfcs` project in the Cloudflare dashboard.
+
+## History / why this doc exists
+
+Between 2026-06-17 and 2026-07-29 the site silently froze: PR #175 removed the old
+`build.js` from the repo, but the Cloudflare Pages build command still called
+`node build.js`, so every Cloudflare build failed with
+`Cannot find module '.../build.js'`. GitHub Actions stayed green the whole time
+because it built a different way, so nothing surfaced the failure. The fix was to
+give Cloudflare and CI one shared build script (this setup) so they can never
+drift apart again.
+
+## Who can administer the Cloudflare project
+
+The Pages project is in the **"Tari and Yat"** Cloudflare account. Membership is
+via Google SSO. If you need access, ask a Super Administrator on that account to
+invite you (the Cloudflare DNS is maintained primarily by nck@tari.com).

scripts/build.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+#
+# Canonical build for the Tari RFC book.
+#
+# This is the SINGLE source of truth for how the site is built. It is invoked
+# by BOTH:
+#   * Cloudflare Pages  (project "rfcs", account "Tari and Yat") — build command
+#     is `bash scripts/build.sh`; this is what publishes https://rfc.tari.com
+#   * GitHub Actions    (.github/workflows/rfc_deploy.yml) — runs it on every
+#     push/PR so a change that would break the Cloudflare build fails CI first.
+#
+# Keeping both on this one script is deliberate: the site outage of
+# 2026-06/07 happened because the Cloudflare build command and the repo drifted
+# apart (the repo dropped build.js while Cloudflare still called it, and CI built
+# a different way so nothing went red). Do not reintroduce a second build recipe.
+#
+# See DEPLOYMENT.md for the full picture.
+
+set -euo pipefail
+
+MDBOOK_VERSION="0.5.2"
+MDBOOK_MERMAID_VERSION="0.17.0"
+
+TOOLS_DIR="$(pwd)/.build-tools"
+mkdir -p "$TOOLS_DIR"
+
+echo "==> Installing mdBook ${MDBOOK_VERSION} and mdbook-mermaid ${MDBOOK_MERMAID_VERSION}"
+curl -fsSL "https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C "$TOOLS_DIR"
+curl -fsSL "https://github.com/badboy/mdbook-mermaid/releases/download/v${MDBOOK_MERMAID_VERSION}/mdbook-mermaid-v${MDBOOK_MERMAID_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C "$TOOLS_DIR"
+
+export PATH="$TOOLS_DIR:$PATH"
+
+mdbook --version
+mdbook-mermaid --version
+
+echo "==> Building book (output: ./book)"
+mdbook build
+
+echo "==> Done."