docs(website): add worked guides and keep Pages publishing manual (#925)

* fix(pages): reserve publishing for the REA website

* docs(website): add worked guides and agent prompt examples

* ci(website): check relevant PRs and publish only on demand

* docs(website): clarify IDA coverage and analysis session lifetime

.github/workflows/pages.yml

@@ -1,30 +1,14 @@
-name: Documentation site
+name: Documentation build
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - "docs/**"
-      - "package.json"
-      - "package-lock.json"
-      - ".nvmrc"
-      - ".github/workflows/pages.yml"
-  pull_request:
-    branches: [main]
-    paths:
-      - "docs/**"
-      - "package.json"
-      - "package-lock.json"
-      - ".nvmrc"
-      - ".github/workflows/pages.yml"
   workflow_dispatch:
 
 permissions:
   contents: read
 
 concurrency:
-  group: pages-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  group: documentation-build-${{ github.ref }}
+  cancel-in-progress: true
 
 env:
   HUSKY: "0"
@@ -33,6 +17,7 @@ jobs:
   build:
     name: Build documentation
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -41,23 +26,3 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run docs:build
-      - uses: actions/upload-pages-artifact@v4
-        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
-        with:
-          path: docs/.vitepress/dist
-
-  deploy:
-    name: Publish documentation
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/configure-pages@v5
-      - uses: actions/deploy-pages@v4
-        id: deployment

.github/workflows/website-check.yml

@@ -0,0 +1,28 @@
+name: Website checks
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "website/**"
+      - "scripts/verify-website.py"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Website checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+      - name: Check website links and publishing configuration
+        run: python3 scripts/verify-website.py

.github/workflows/website-pages.yml

@@ -21,6 +21,8 @@ jobs:
     steps:
       - name: Check out the repository
         uses: actions/checkout@v4
+      - name: Check website links and publishing configuration
+        run: python3 scripts/verify-website.py
       - name: Configure Pages
         uses: actions/configure-pages@v5
       - name: Upload the website