diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 0021f66..3cd8571 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -7,8 +7,17 @@ on:
     paths:
       - 'weac/**'
       - 'docs/sphinx/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
   pull_request:
     branches: [ main, develop ]
+    paths:
+      - 'weac/**'
+      - 'docs/sphinx/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
   workflow_dispatch:
 
 permissions:
@@ -37,14 +46,17 @@ jobs:
 
     - name: Build documentation
       run: |
+        # Clean any previous build artifacts
+        make -C docs/sphinx clean
+        
         # Generate API docs
         sphinx-apidoc -o docs/sphinx/ weac --force --separate
 
         # Build HTML docs (do not fail on warnings)
-        make -C docs/sphinx clean html SPHINXOPTS="--keep-going -n"
-
-        # Build HTML docs (do not fail on warnings)
-        make -C docs/sphinx clean html SPHINXOPTS="--keep-going -n"
+        make -C docs/sphinx html SPHINXOPTS="--keep-going -n"
+        
+        # Ensure .nojekyll file exists for GitHub Pages
+        touch docs/sphinx/_build/html/.nojekyll
 
     - name: Deploy documentation
       if: github.event_name == 'push' && github.ref == 'refs/heads/main'
@@ -53,9 +65,18 @@ jobs:
         git config --local user.email "action@github.com"
         git config --local user.name "GitHub Action"
 
+        # Build verification - ensure required files exist
+        if [ ! -f docs/sphinx/_build/html/index.html ]; then
+          echo "Build output missing (docs/sphinx/_build/html/index.html not found). Aborting deploy."
+          exit 1
+        fi
+        
+        echo "Build verification passed - index.html found"
+
         # Prepare a clean worktree for the documentation branch
         git worktree remove -f docs-deploy || true
         git worktree prune
+        
         # Ensure we know about the remote branch if it exists
         git fetch origin documentation || true
         if git show-ref --verify --quiet refs/remotes/origin/documentation; then
@@ -65,14 +86,27 @@ jobs:
           # Create a new local 'documentation' branch starting from current HEAD (content will be replaced)
           git worktree add --force -b documentation docs-deploy HEAD
         fi
-        # Copy built HTML to the worktree root
-        if [ ! -f docs/sphinx/_build/html/index.html ]; then
-          echo "Build output missing (docs/sphinx/_build/html/index.html not found). Aborting deploy."
-          exit 1
+        
+        # Clean the documentation branch but preserve .gitignore if it exists
+        pushd docs-deploy
+        # Preserve .gitignore if it exists
+        if [ -f .gitignore ]; then
+          cp .gitignore /tmp/preserve-gitignore
+        fi
+        git rm -rf . || true
+        git clean -fxd
+        # Restore .gitignore if it existed
+        if [ -f /tmp/preserve-gitignore ]; then
+          cp /tmp/preserve-gitignore .gitignore
+          rm /tmp/preserve-gitignore
         fi
+        popd
+        
+        # Create proper directory structure for GitHub Pages
+        mkdir -p docs-deploy/docs
         
-        # Copy files to deployment directory
-        cp -r docs/sphinx/_build/html/* docs-deploy/
+        # Copy built HTML to the docs directory (for GitHub Pages)
+        cp -r docs/sphinx/_build/html/* docs-deploy/docs/
         
         pushd docs-deploy
         git add -A
@@ -80,7 +114,7 @@ jobs:
           echo "No changes to publish"
           exit 0
         else
-          git commit -m "Update documentation"
+          git commit -m "Update documentation" -m "🪬 Generated with Sphinx from main branch"
           git fetch origin documentation --quiet || true
           git push --force-with-lease origin HEAD:documentation
         fi