docs(site): install the current release from the public channel

.github/workflows/deploy.yml

@@ -1,30 +1,46 @@
 name: Deploy to Cloudflare Pages
 
+# Production deploy. Runs after a push to main (or on demand).
+#
+# The Cloudflare Pages project `terraphim-ai` is deployed exclusively through
+# this workflow. There is no separate CDN/Git integration to keep in sync, so a
+# green run here means the published site matches main.
+
 on:
   push:
     branches:
       - main
   workflow_dispatch:
 
+permissions:
+  contents: read
+  deployments: write
+
+concurrency:
+  group: cloudflare-pages-production
+  cancel-in-progress: false
+
 env:
+  ZOLA_VERSION: "0.22.1"
+  CF_PROJECT: terraphim-ai
   OP_API_TOKEN: op://TerraphimPlatform/terraphim-md-book-cloudflare/workers-api-token
   OP_ACCOUNT_ID: op://TerraphimPlatform/terraphim-md-book-cloudflare/account_id
 
 jobs:
   build-and-deploy:
     name: Build and Deploy
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      deployments: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Install Zola 0.22.1
+      - name: Install Zola ${{ env.ZOLA_VERSION }}
         run: |
-          curl -L https://github.com/getzola/zola/releases/download/v0.22.1/zola-v0.22.1-x86_64-unknown-linux-gnu.tar.gz | tar xz
+          curl --fail --location --silent --show-error \
+            "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
+            | tar xz
           sudo mv zola /usr/local/bin
+          zola --version
 
       - name: Build site
         run: zola build
@@ -45,4 +61,29 @@ jobs:
         with:
           apiToken: ${{ env.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ env.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy public --project-name=terraphim-ai --branch=main
+          command: pages deploy public --project-name=${{ env.CF_PROJECT }} --branch=main
+
+      - name: Verify the deployed site serves the committed version
+        env:
+          DEPLOY_URL: ${{ steps.deploy.outputs.deployment-url }}
+        run: |
+          expected=$(grep -oP '^release_version\s*=\s*"\K[^"]+' config.toml)
+          url="${DEPLOY_URL:-https://${CF_PROJECT}.pages.dev}"
+          echo "Expecting release_version ${expected} at ${url}"
+
+          attempt=1
+          while [ "${attempt}" -le 5 ]; do
+            body=$(curl --fail --location --silent --show-error --max-time 30 "${url}/" || true)
+            if printf '%s' "${body}" | grep -q "${expected}"; then
+              echo "Deployment served release ${expected} on attempt ${attempt}"
+              exit 0
+            fi
+            echo "Attempt ${attempt}: ${expected} not found yet, retrying"
+            attempt=$((attempt + 1))
+            sleep 15
+          done
+
+          # Surface the site content for debugging before failing.
+          curl --fail --location --silent --show-error --max-time 30 "${url}/" | head -c 2000 || true
+          echo "::error::Deployed site does not advertise release ${expected}"
+          exit 1

.github/workflows/validate.yml

@@ -0,0 +1,67 @@
+name: Validate site
+
+# The site deploys to Cloudflare Pages from main only (.github/workflows/deploy.yml).
+# This workflow is the pull-request gate: it proves the site builds, that every
+# internal link resolves, and that the download URLs the site advertises match the
+# public release channel. Without it a broken build would only surface at deploy
+# time, after the merge.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  ZOLA_VERSION: "0.22.1"
+
+jobs:
+  build:
+    name: Build and check links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install Zola ${{ env.ZOLA_VERSION }}
+        run: |
+          curl --fail --location --silent --show-error \
+            "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
+            | tar xz
+          sudo mv zola /usr/local/bin
+          zola --version
+
+      - name: Build site
+        # Zola fails the build on broken internal links.
+        run: zola build
+
+      - name: Verify the build produced pages
+        run: |
+          pages=$(find public -name '*.html' | wc -l)
+          echo "Generated ${pages} HTML pages"
+          if [ "${pages}" -lt 10 ]; then
+            echo "::error::Expected at least 10 generated pages, found ${pages}"
+            exit 1
+          fi
+          test -f public/index.html || { echo "::error::public/index.html is missing"; exit 1; }
+
+      - name: Upload site
+        uses: actions/upload-artifact@v4
+        with:
+          name: site-public
+          path: public/
+          retention-days: 7
+
+  release-links:
+    name: Check release channel links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Verify advertised downloads exist on the public channel
+        run: python3 scripts/check-release-links.py

config.toml

@@ -50,8 +50,8 @@ include_content = true
 [languages]
 
 [extra]
-version = "1.20.5"
-release_version = "1.20.5"
+version = "1.21.16"
+release_version = "1.21.16"
 
 navbar_items = [
     { code = "en", nav_items = [

content/capabilities/terraphim-agent.md

@@ -20,7 +20,7 @@ you encounter a recurring error.
 Install it with one command:
 
 ```bash
-cargo install terraphim-agent
+cargo install terraphim_agent --features repl-full
 ```
 
 ## What it does

content/docs/crates.md

@@ -144,10 +144,10 @@ Cross-language bindings for using Terraphim from Python, Node.js, and WebAssembl
 
 ```bash
 # Install the agent (interactive REPL + session search)
-cargo install terraphim-agent
+cargo install terraphim_agent --features repl-full
 
 # Install the CLI (JSON output for automation)
-cargo install terraphim-cli
+cargo install terraphim_cli
 ```
 
 Or use the universal installer: