CI: auto-commit chatbot product map on docs-only drift

.github/workflows/validate-docs-site.yaml

@@ -5,6 +5,7 @@ on:
     types: [opened, synchronize, ready_for_review]
 
 permissions:
+  contents: write
   actions: write
   issues: write
   pull-requests: write
@@ -17,6 +18,10 @@ jobs:
     steps:
     - name: Check out documentation repository
       uses: actions/checkout@v4
+      with:
+        ref: ${{ github.head_ref }}
+        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
 
     # Reclaim space + create a reserve for deterministic headroom
     - name: Free space + create reserve
@@ -186,8 +191,35 @@ jobs:
 
     - name: Verify chatbot product map is up to date
       run: |
+        set -euo pipefail
         python3 site/scripts/generate_chatbot_product_map.py
-        git diff --exit-code site/llm/chatbot-product-map.md site/llm/chatbot-product-map-frontend-snapshot.json
+
+        map_changed=false
+        snapshot_changed=false
+        git diff --quiet site/llm/chatbot-product-map.md || map_changed=true
+        git diff --quiet site/llm/chatbot-product-map-frontend-snapshot.json || snapshot_changed=true
+
+        if [ "$map_changed" = false ] && [ "$snapshot_changed" = false ]; then
+          echo "chatbot product map is up to date"
+          exit 0
+        fi
+
+        if [ "$snapshot_changed" = true ]; then
+          echo "::error::Frontend snapshot is stale. Run: make -C site refresh-chatbot-product-map (requires ../frontend checkout), then commit site/llm/chatbot-product-map-frontend-snapshot.json and site/llm/chatbot-product-map.md."
+          exit 1
+        fi
+
+        if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.repository }}" ]; then
+          echo "::error::chatbot-product-map.md is stale for this fork PR. Run: make -C site generate-chatbot-product-map, then commit site/llm/chatbot-product-map.md."
+          exit 1
+        fi
+
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+        git add site/llm/chatbot-product-map.md
+        git commit -m "chore: refresh chatbot product map"
+        git push origin "HEAD:${{ github.head_ref }}"
+        echo "Auto-committed refreshed site/llm/chatbot-product-map.md."
 
     - name: Test chatbot product map generator
       run: python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v

README.md

@@ -174,6 +174,21 @@ The script reads from:
 
 Output: Content is injected directly into `site/guide/templates/customize-document-templates.qmd` between marker comments.
 
+#### Chatbot product map and LLM corpus
+
+The in-app assistant (Valerie) uses generated files under `site/llm/`, including `chatbot-product-map.md` (platform routes mapped to docs URLs and section headings). CI regenerates that map and fails if it is out of date with your changes.
+
+If you edit `.qmd` files that affect linked docs or headings (for example FAQ or guide pages referenced from the product UI), regenerate and commit the map before opening or updating a pull request:
+
+```bash
+cd site
+make generate-chatbot-product-map
+```
+
+On same-repo pull requests, CI now auto-commits docs-only map refreshes. Fork pull requests and frontend snapshot changes still require a local regenerate and commit.
+
+If product routes or in-app help links changed, use `make refresh-chatbot-product-map` instead (requires a local `validmind/frontend` checkout). See [`site/llm/README.md`](site/llm/README.md) for the full LLM render pipeline, snapshot maintenance, and when to refresh each artifact.
+
 #### Stylesheet organization (IN PROGRESS)
 
 The site uses a modular stylesheet architecture to maintain organized and maintainable styles:

site/llm/README.md

@@ -49,6 +49,7 @@ CI does **not** check out `validmind/frontend` (private repo; cross-repo PAT sco
 | Product routes or in-app help links | `make refresh-chatbot-product-map` (requires a sibling `../frontend` checkout) |
 
 Commit both `chatbot-product-map.md` and `chatbot-product-map-frontend-snapshot.json` when the snapshot changes. CI fails if either file is out of date after regeneration.
+For same-repo pull requests, the validate workflow auto-commits docs-only refreshes of `chatbot-product-map.md`. Fork pull requests and any snapshot drift still fail and require a local regenerate + commit.
 
 Generator: `site/scripts/generate_chatbot_product_map.py`  
 Tests: `python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v` (from repo root).