From 3153696a08d3063bf81fc1df0126190ec6ef2ae6 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Mon, 8 Dec 2025 20:12:53 +0100
Subject: [PATCH 01/11] Improve CI workflows for docs and publishing

---
 .github/workflows/docs-gh-pages.yml | 100 ++++++++++++++++++++++------
 .github/workflows/publish.yml       |  73 ++++++++++++++------
 2 files changed, 134 insertions(+), 39 deletions(-)

diff --git a/.github/workflows/docs-gh-pages.yml b/.github/workflows/docs-gh-pages.yml
index 435af957..220c646b 100644
--- a/.github/workflows/docs-gh-pages.yml
+++ b/.github/workflows/docs-gh-pages.yml
@@ -1,40 +1,100 @@
-name: Build and Deploy Documentation
+name: Docs — Build & Preview
 
 on:
   push:
-    branches:
-      - main
+    branches: [ main ]            # regular prod deploy
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
+  pull_request:                    # preview only when docs are touched
+    branches: [ '**' ]
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
 
 jobs:
-  build-and-deploy-docs:
+  build:
     runs-on: ubuntu-latest
+    outputs:
+      short_sha: ${{ steps.sha.outputs.short }}
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Fetch all history for .git-restore-mtime to work correctly
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.x'
+        with: { fetch-depth: 0 }
 
-      - name: Install uv via GitHub Action
-        uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@v6
 
-      - name: Install mesa-frames + docs dependencies
+      - name: Install mesa-frames + docs deps
         run: |
           uv pip install --system .
           uv pip install --group docs --system
 
-      - name: Build MkDocs site (general documentation)
-        run: mkdocs build --config-file mkdocs.yml --site-dir ./site
+      - name: Convert jupytext .py notebooks to .ipynb
+        run: |
+          set -euxo pipefail
+          # Convert any jupytext .py files to .ipynb without executing them.
+          # Enable nullglob so the pattern expands to empty when there are no matches
+          # and globstar so we recurse into subdirectories (e.g., user-guide/).
+          shopt -s nullglob globstar || true
+          files=(docs/general/**/*.py)
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No jupytext .py files found under docs/general"
+          else
+            for src in "${files[@]}"; do
+              [ -e "$src" ] || continue
+              dest="${src%.py}.ipynb"
+              echo "Converting $src -> $dest"
+              # jupytext will write the .ipynb alongside the source file
+              uv run jupytext --to notebook "$src"
+            done
+          fi
+
+      - name: Build MkDocs site
+        run: uv run mkdocs build --config-file mkdocs.yml --site-dir ./site
+
+      - name: Build Sphinx docs (API)
+        run: uv run sphinx-build -b html docs/api site/api
+
+      - name: Short SHA
+        id: sha
+        run: echo "short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site
 
-      - name: Build Sphinx docs (API documentation)
-        run: sphinx-build -b html docs/api site/api
+  deploy-main:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: site, path: site }
+      - name: Deploy to GitHub Pages (main)
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          force_orphan: true
 
-      - name: Deploy to GitHub Pages
+  deploy-preview:
+    needs: build
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: site, path: site }
+      - name: Deploy preview under subfolder
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
           publish_dir: ./site
-          force_orphan: true
\ No newline at end of file
+          destination_dir: preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}
+          keep_files: true        # keep previous previews
+          # DO NOT set force_orphan here
+      - name: Print preview URL
+        run: |
+          echo "Preview: https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}/"
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 105824de..7204a0bc 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -17,33 +17,27 @@ jobs:
       with:
         fetch-depth: 0
         token: ${{ secrets.VERSION_PUSH_TOKEN }}
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install hatch
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v3
     - name: Set release version
       run: |
         # Get the tag from the GitHub release
         TAG=${GITHUB_REF#refs/tags/}
         # Remove 'v' prefix if present
         VERSION=${TAG#v}
-        hatch version $VERSION
+        uvx hatch version $VERSION
     - name: Build package
-      run: hatch build
+      run: uvx hatch build
     - name: Run tests
-      run: hatch run test:pytest
+      run: uvx hatch run test:pytest
     - name: Publish package to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
     - name: Verify PyPI Release
       run: |
         # Verify PyPI release
         PACKAGE_NAME="mesa_frames"
-        CURRENT_VERSION=$(hatch version)
-        pip install $PACKAGE_NAME==$CURRENT_VERSION
+        CURRENT_VERSION=$(uvx hatch version)
+        uv pip install --system $PACKAGE_NAME==$CURRENT_VERSION
         python -c "import mesa_frames; print(mesa_frames.__version__)"
     - name: Update GitHub Release
       uses: softprops/action-gh-release@v1
@@ -51,9 +45,50 @@ jobs:
       with:
         files: |
           dist/*
+    - name: Generate changelog from release notes
+      id: notes
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          const tag = (context.payload.release && context.payload.release.tag_name)
+            ? context.payload.release.tag_name
+            : (process.env.GITHUB_REF || '').replace('refs/tags/', '');
+
+          const body = (context.payload.release && context.payload.release.body) ? context.payload.release.body : '';
+          if (!body || body.trim().length === 0) {
+            core.setFailed('Release body is empty. Ensure the GitHub Release is created with auto-generated notes configured by .github/release.yml or supply a body.');
+          }
+
+          fs.writeFileSync('RELEASE_BODY.md', body, 'utf8');
+          core.setOutput('tag', tag);
+    - name: Prepend notes to CHANGELOG.md
+      env:
+        TAG: ${{ steps.notes.outputs.tag }}
+      run: |
+        VERSION_NO_V=${TAG#v}
+        DATE_UTC=$(date -u +%Y-%m-%d)
+        echo "## Version ${VERSION_NO_V} — ${DATE_UTC}" > RELEASE_HEADER.md
+        echo "" >> RELEASE_HEADER.md
+        if [ -f CHANGELOG.md ]; then
+          cat RELEASE_HEADER.md RELEASE_BODY.md CHANGELOG.md > CHANGELOG.new
+        else
+          cat RELEASE_HEADER.md RELEASE_BODY.md > CHANGELOG.new
+        fi
+        mv CHANGELOG.new CHANGELOG.md
+    - name: Commit and push CHANGELOG update
+      env:
+        TAG: ${{ steps.notes.outputs.tag }}
+      run: |
+        git config user.name github-actions
+        git config user.email github-actions@github.com
+        git add CHANGELOG.md
+        # Avoid CI cycles
+        git commit -m "Changelog: add notes for ${TAG} [skip ci]" || echo "No changelog changes to commit"
+        git push origin main || true
     - name: Create or recreate version branch
       run: |
-        CURRENT_VERSION=$(hatch version)
+        CURRENT_VERSION=$(uvx hatch version)
         BRANCH_NAME="v$CURRENT_VERSION"
 
         git config user.name github-actions
@@ -72,15 +107,15 @@ jobs:
     - name: Update to Next Version
       run: |
         # Bump to next development version
-        hatch version patch
-        hatch version dev
+        uvx hatch version patch
+        uvx hatch version dev
 
         # Get the new version
-        NEW_VERSION=$(hatch version)
+        NEW_VERSION=$(uvx hatch version)
 
         # Commit and push the version bump
         git config user.name github-actions
         git config user.email github-actions@github.com
-        git add mesa_frames/__init__.py
+        git add mesa_frames/__init__.py CHANGELOG.md
         git commit -m "Bump version to $NEW_VERSION [skip ci]"
-        git push origin main
\ No newline at end of file
+        git push origin main

From 9aa7138551c20a2b760e739b61208186bc75d60a Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 09:57:20 +0100
Subject: [PATCH 02/11] Enhance CI workflows: add preview deployment for PRs
 and adjust permissions

---
 .github/workflows/docs-gh-pages.yml         | 34 +++---------
 .github/workflows/docs-preview-dispatch.yml | 60 +++++++++++++++++++++
 2 files changed, 68 insertions(+), 26 deletions(-)
 create mode 100644 .github/workflows/docs-preview-dispatch.yml

diff --git a/.github/workflows/docs-gh-pages.yml b/.github/workflows/docs-gh-pages.yml
index 220c646b..86652f25 100644
--- a/.github/workflows/docs-gh-pages.yml
+++ b/.github/workflows/docs-gh-pages.yml
@@ -1,4 +1,6 @@
 name: Docs — Build & Preview
+permissions:
+  contents: read
 
 on:
   push:
@@ -15,8 +17,9 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    outputs:
-      short_sha: ${{ steps.sha.outputs.short }}
+    permissions:
+      contents: read
+      actions: write
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -54,10 +57,6 @@ jobs:
       - name: Build Sphinx docs (API)
         run: uv run sphinx-build -b html docs/api site/api
 
-      - name: Short SHA
-        id: sha
-        run: echo "short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
-
       - name: Upload site artifact
         uses: actions/upload-artifact@v4
         with:
@@ -68,6 +67,9 @@ jobs:
     needs: build
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
     steps:
       - uses: actions/download-artifact@v4
         with: { name: site, path: site }
@@ -78,23 +80,3 @@ jobs:
           publish_branch: gh-pages
           publish_dir: ./site
           force_orphan: true
-
-  deploy-preview:
-    needs: build
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/download-artifact@v4
-        with: { name: site, path: site }
-      - name: Deploy preview under subfolder
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_branch: gh-pages
-          publish_dir: ./site
-          destination_dir: preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}
-          keep_files: true        # keep previous previews
-          # DO NOT set force_orphan here
-      - name: Print preview URL
-        run: |
-          echo "Preview: https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}/"
diff --git a/.github/workflows/docs-preview-dispatch.yml b/.github/workflows/docs-preview-dispatch.yml
new file mode 100644
index 00000000..c583eecf
--- /dev/null
+++ b/.github/workflows/docs-preview-dispatch.yml
@@ -0,0 +1,60 @@
+# Deploys preview artifacts produced by the Docs — Build & Preview workflow for PRs.
+# The build workflow runs with read-only permissions on PRs (including forks) and
+# uploads the built site as an artifact. This workflow runs in the base repo with
+# the permissions needed to publish the preview to the gh-pages branch, but it
+# never checks out or executes untrusted PR code.
+name: Docs — Preview Deploy
+
+on:
+  workflow_run:
+    workflows: ["Docs — Build & Preview"]
+    types: [completed]
+
+permissions:
+  contents: write
+  actions: read
+  pages: write
+
+jobs:
+  deploy-preview:
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      (github.event.workflow_run.pull_requests || null)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download built site artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: site
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Derive preview metadata
+        id: meta
+        run: |
+          set -euo pipefail
+          head_sha="${{ github.event.workflow_run.head_sha }}"
+          head_branch="${{ github.event.workflow_run.head_branch }}"
+          pr_number="${{ github.event.workflow_run.pull_requests[0].number }}"
+          short_sha="$(printf '%s' "$head_sha" | cut -c1-7)"
+          {
+            echo "short_sha=$short_sha"
+            echo "head_branch=$head_branch"
+            echo "pr_number=$pr_number"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Deploy preview under subfolder
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          destination_dir: preview/${{ steps.meta.outputs.head_branch }}/${{ steps.meta.outputs.short_sha }}
+          keep_files: true
+
+      - name: Print preview URL
+        run: |
+          echo "Preview for PR #${{ steps.meta.outputs.pr_number }}:"
+          echo "https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ steps.meta.outputs.head_branch }}/${{ steps.meta.outputs.short_sha }}/"

From d1d5804bfa47c7f8a8635c1e2cdb7edf59355ff4 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 09:59:20 +0100
Subject: [PATCH 03/11] Ensure main branch checkout before committing changelog
 updates

---
 .github/workflows/publish.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 7204a0bc..a2070903 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -82,6 +82,8 @@ jobs:
       run: |
         git config user.name github-actions
         git config user.email github-actions@github.com
+        # Ensure we are on the main branch before committing so the push lands on main.
+        git checkout main
         git add CHANGELOG.md
         # Avoid CI cycles
         git commit -m "Changelog: add notes for ${TAG} [skip ci]" || echo "No changelog changes to commit"

From 21f23ce79a093a217449445ec58f6ccc3594c6f2 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:06:41 +0100
Subject: [PATCH 04/11] Refactor preview metadata derivation in CI workflow for
 security

---
 .github/workflows/docs-preview-dispatch.yml | 23 ++++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/docs-preview-dispatch.yml b/.github/workflows/docs-preview-dispatch.yml
index c583eecf..3cc22b92 100644
--- a/.github/workflows/docs-preview-dispatch.yml
+++ b/.github/workflows/docs-preview-dispatch.yml
@@ -33,16 +33,17 @@ jobs:
 
       - name: Derive preview metadata
         id: meta
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
         run: |
           set -euo pipefail
-          head_sha="${{ github.event.workflow_run.head_sha }}"
-          head_branch="${{ github.event.workflow_run.head_branch }}"
-          pr_number="${{ github.event.workflow_run.pull_requests[0].number }}"
-          short_sha="$(printf '%s' "$head_sha" | cut -c1-7)"
+          short_sha="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
           {
             echo "short_sha=$short_sha"
-            echo "head_branch=$head_branch"
-            echo "pr_number=$pr_number"
+            echo "head_branch=$HEAD_BRANCH"
+            echo "pr_number=$PR_NUMBER"
           } >> "$GITHUB_OUTPUT"
 
       - name: Deploy preview under subfolder
@@ -55,6 +56,12 @@ jobs:
           keep_files: true
 
       - name: Print preview URL
+        env:
+          PREVIEW_OWNER: ${{ github.repository_owner }}
+          PREVIEW_REPO: ${{ github.repository }}
+          HEAD_BRANCH: ${{ steps.meta.outputs.head_branch }}
+          SHORT_SHA: ${{ steps.meta.outputs.short_sha }}
+          PR_NUMBER: ${{ steps.meta.outputs.pr_number }}
         run: |
-          echo "Preview for PR #${{ steps.meta.outputs.pr_number }}:"
-          echo "https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ steps.meta.outputs.head_branch }}/${{ steps.meta.outputs.short_sha }}/"
+          echo "Preview for PR #${PR_NUMBER}:"
+          echo "https://${PREVIEW_OWNER}.github.io/$(basename "$PREVIEW_REPO")/preview/${HEAD_BRANCH}/${SHORT_SHA}/"

From 5c459c9ac55309cc2c47f3014ab567cdf00390a9 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:11:58 +0100
Subject: [PATCH 05/11] try docs preview (to be reverted)

---
 docs/general/index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/general/index.md b/docs/general/index.md
index 9859d2ee..9d0cb777 100644
--- a/docs/general/index.md
+++ b/docs/general/index.md
@@ -1,5 +1,7 @@
 # Welcome to mesa-frames 🚀
 
+
+
 mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax.
 
 You can get a model which is multiple orders of magnitude faster based on the number of agents - the more agents, the faster the relative performance.

From f1ece04d8620eb58417f1d60b98d107282592516 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 11 Dec 2025 09:15:25 +0000
Subject: [PATCH 06/11] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 docs/general/index.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/general/index.md b/docs/general/index.md
index 9d0cb777..9859d2ee 100644
--- a/docs/general/index.md
+++ b/docs/general/index.md
@@ -1,7 +1,5 @@
 # Welcome to mesa-frames 🚀
 
-
-
 mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax.
 
 You can get a model which is multiple orders of magnitude faster based on the number of agents - the more agents, the faster the relative performance.

From 90f9d51e59b7c9669cddfa7593486805c7fa0288 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:19:07 +0100
Subject: [PATCH 07/11] Refactor Python setup in CI workflow to use
 actions/setup-python for improved compatibility

---
 .github/workflows/docs-gh-pages.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs-gh-pages.yml b/.github/workflows/docs-gh-pages.yml
index 86652f25..68767dd5 100644
--- a/.github/workflows/docs-gh-pages.yml
+++ b/.github/workflows/docs-gh-pages.yml
@@ -24,7 +24,14 @@ jobs:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
 
-      - uses: astral-sh/setup-uv@v6
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          allow-prereleases: true
+          cache: "pip"
+
+      - uses: astral-sh/setup-uv@v7
 
       - name: Install mesa-frames + docs deps
         run: |

From 15a5be3287bba0a27b0042ea418627650b113c52 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:23:34 +0100
Subject: [PATCH 08/11] test on docs to be deleted

---
 docs/general/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/general/index.md b/docs/general/index.md
index 9859d2ee..d4d3e8d8 100644
--- a/docs/general/index.md
+++ b/docs/general/index.md
@@ -1,6 +1,6 @@
 # Welcome to mesa-frames 🚀
 
-mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax.
+mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax. .
 
 You can get a model which is multiple orders of magnitude faster based on the number of agents - the more agents, the faster the relative performance.
 

From 0ab6b380f41b3a2534a709623b3edb0512d9c77d Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:43:07 +0100
Subject: [PATCH 09/11] added manual workflow dispatch for testing (to be
 reverted)

---
 .github/workflows/docs-preview-dispatch.yml | 32 ++++++++++++++++-----
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/docs-preview-dispatch.yml b/.github/workflows/docs-preview-dispatch.yml
index 3cc22b92..64ffdfdd 100644
--- a/.github/workflows/docs-preview-dispatch.yml
+++ b/.github/workflows/docs-preview-dispatch.yml
@@ -9,6 +9,20 @@ on:
   workflow_run:
     workflows: ["Docs — Build & Preview"]
     types: [completed]
+  workflow_dispatch:
+    inputs:
+      run_id:
+        description: "Run ID of Docs — Build & Preview (artifact source)"
+        required: true
+      pr_number:
+        description: "Pull request number"
+        required: true
+      head_branch:
+        description: "Pull request head branch"
+        required: true
+      head_sha:
+        description: "Pull request head SHA"
+        required: true
 
 permissions:
   contents: write
@@ -18,25 +32,29 @@ permissions:
 jobs:
   deploy-preview:
     if: >
-      github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion == 'success' &&
-      (github.event.workflow_run.pull_requests || null)
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.event == 'pull_request' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       (github.event.workflow_run.pull_requests || null))
+      || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    env:
+      RUN_ID: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.id || inputs.run_id }}
     steps:
       - name: Download built site artifact
         uses: actions/download-artifact@v4
         with:
           name: site
           path: site
-          run-id: ${{ github.event.workflow_run.id }}
+          run-id: ${{ env.RUN_ID }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Derive preview metadata
         id: meta
         env:
-          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
-          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
-          PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
+          HEAD_SHA: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || inputs.head_sha }}
+          HEAD_BRANCH: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || inputs.head_branch }}
+          PR_NUMBER: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.pull_requests[0].number || inputs.pr_number }}
         run: |
           set -euo pipefail
           short_sha="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"

From 7105eff6bc4d3368999348f028bca292fcec420a Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:59:32 +0100
Subject: [PATCH 10/11] Revert "added manual workflow dispatch for testing (to
 be reverted)"

This reverts commit 0ab6b380f41b3a2534a709623b3edb0512d9c77d.
---
 .github/workflows/docs-preview-dispatch.yml | 32 +++++----------------
 1 file changed, 7 insertions(+), 25 deletions(-)

diff --git a/.github/workflows/docs-preview-dispatch.yml b/.github/workflows/docs-preview-dispatch.yml
index 64ffdfdd..3cc22b92 100644
--- a/.github/workflows/docs-preview-dispatch.yml
+++ b/.github/workflows/docs-preview-dispatch.yml
@@ -9,20 +9,6 @@ on:
   workflow_run:
     workflows: ["Docs — Build & Preview"]
     types: [completed]
-  workflow_dispatch:
-    inputs:
-      run_id:
-        description: "Run ID of Docs — Build & Preview (artifact source)"
-        required: true
-      pr_number:
-        description: "Pull request number"
-        required: true
-      head_branch:
-        description: "Pull request head branch"
-        required: true
-      head_sha:
-        description: "Pull request head SHA"
-        required: true
 
 permissions:
   contents: write
@@ -32,29 +18,25 @@ permissions:
 jobs:
   deploy-preview:
     if: >
-      (github.event_name == 'workflow_run' &&
-       github.event.workflow_run.event == 'pull_request' &&
-       github.event.workflow_run.conclusion == 'success' &&
-       (github.event.workflow_run.pull_requests || null))
-      || github.event_name == 'workflow_dispatch'
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      (github.event.workflow_run.pull_requests || null)
     runs-on: ubuntu-latest
-    env:
-      RUN_ID: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.id || inputs.run_id }}
     steps:
       - name: Download built site artifact
         uses: actions/download-artifact@v4
         with:
           name: site
           path: site
-          run-id: ${{ env.RUN_ID }}
+          run-id: ${{ github.event.workflow_run.id }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Derive preview metadata
         id: meta
         env:
-          HEAD_SHA: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || inputs.head_sha }}
-          HEAD_BRANCH: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || inputs.head_branch }}
-          PR_NUMBER: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.pull_requests[0].number || inputs.pr_number }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
         run: |
           set -euo pipefail
           short_sha="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"

From be0abd2ec0af285ac18fcaffacb063ddb1c1bd18 Mon Sep 17 00:00:00 2001
From: Adam Amer <136176500+adamamer20@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:59:44 +0100
Subject: [PATCH 11/11] Revert "test on docs to be deleted"

This reverts commit 15a5be3287bba0a27b0042ea418627650b113c52.
---
 docs/general/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/general/index.md b/docs/general/index.md
index d4d3e8d8..9859d2ee 100644
--- a/docs/general/index.md
+++ b/docs/general/index.md
@@ -1,6 +1,6 @@
 # Welcome to mesa-frames 🚀
 
-mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax. .
+mesa-frames is an extension of the [mesa](https://github.com/projectmesa/mesa) framework, designed for complex simulations with thousands of agents. By storing agents in a DataFrame, mesa-frames significantly enhances the performance and scalability of mesa, while maintaining a similar syntax.
 
 You can get a model which is multiple orders of magnitude faster based on the number of agents - the more agents, the faster the relative performance.