revert to peaceiris (gh-pages), add explicit Pages setup instructions

Made-with: Cursor

Author: NAOR YUVAL

.github/workflows/deploy.yml

@@ -1,7 +1,9 @@
 # Deploy unified MPCP docs to https://mpcp-protocol.github.io/
 # Site structure: / (landing) | /spec | /reference
 #
-# Requires: Settings → Pages → Build and deployment → Source: GitHub Actions
+# CRITICAL: Settings → Pages → Source: Deploy from a branch
+#           Branch: gh-pages  |  Folder: / (root)
+#           If you use "main", only the landing page will load (404 on /spec, /reference)
 name: Deploy Docs
 
 on:
@@ -12,18 +14,11 @@ on:
     types: [deploy-docs]
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
+  contents: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    environment: pages
     steps:
       - name: Checkout org site
         uses: actions/checkout@v4
@@ -67,17 +62,13 @@ jobs:
           cp -r _site_spec site/spec
           cp -r _site_reference site/reference
           touch site/.nojekyll
-          # Verify structure
           test -f site/spec/index.html || (echo "Missing site/spec/index.html" && exit 1)
           test -f site/reference/index.html || (echo "Missing site/reference/index.html" && exit 1)
-          echo "Site structure OK:"
+          echo "Site structure OK"
           find site -name index.html | head -20
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      - name: Deploy to GitHub Pages (gh-pages branch)
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          path: ./site
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

README.md

@@ -13,6 +13,9 @@ Unified documentation site for the Machine Payment Control Protocol (MPCP).
 
 1. Create the `mpcp-protocol.github.io` repository in the mpcp-protocol organization.
 2. Push this content to `main`.
-3. GitHub Settings → Pages → Source: **GitHub Actions**
-4. Run the "Deploy Docs" workflow (runs on push to `main`, or manually).
-4. The deploy workflow builds both sites and publishes on push to `main` or via manual trigger.
+3. **Configure Pages** (critical for /spec and /reference to work):
+   - Repo **Settings** → **Pages**
+   - **Build and deployment** → **Source**: **Deploy from a branch**
+   - **Branch**: `gh-pages` (not `main`)
+   - **Folder**: `/ (root)`
+4. Run **Actions** → **Deploy Docs** (runs on push to `main`, or trigger manually).