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

[nrichers]

Pull Request Description

What and why?

This PR improves how the chatbot product map gets committed, removing the need for authors to manually do the commit after regeneration.

The problem

When you change documentation (for example FAQ wording or headings), CI rebuilds the site/llm/chatbot-product-map.md file that the in-app assistant uses. This file maps product screens to docs and pulls section titles from our .qmd files.

If you updated the docs but did not regenerate and commit that map, CI failed, even when the only difference was your doc edits. Contributors had to know to run make generate-chatbot-product-map and commit the result, which was easy to miss (cf. my Slack convo with Beck).

Solution

CI still regenerates the map to check it is current. On pull requests from branches in this repo, if only chatbot-product-map.md is out of date, the workflow now commits and pushes the refreshed file for you.

You still need to fix things locally when:

• The PR comes from a fork (CI cannot push to the fork branch), or
• The frontend snapshot is stale (product routes or help links changed — run make refresh-chatbot-product-map with a local frontend checkout).

README and site/llm/README.md describe when to regenerate locally vs when to let CI handle it.

Shortcut: https://app.shortcut.com/validmind/story/16405

How to test

Tested on this PR (end-to-end):

1. Changed the FAQ callout heading in site/faq/faq-workflows.qmd (specific model → specific record (model)) without updating chatbot-product-map.md, then pushed.
2. Validate docs site run 26429112104 completed successfully. The Verify chatbot product map is up to date step auto-committed site/llm/chatbot-product-map.md (chore: refresh chatbot product map, commit 3747ed2b3).
3. Reverted the FAQ heading to specific model and pushed again.
4. Validate docs site run 26429755873 completed successfully and auto-committed the map again (a2792941d). FAQ and map text matched after the run.

Reviewer smoke test:

• Change a linked .qmd heading without refreshing chatbot-product-map.md on a same-repo PR — validate should auto-commit the map and pass (may take ~20 minutes for the full job).
• Confirm snapshot drift still fails with the refresh-chatbot-product-map message (not exercised on this PR).
• Locally: python3 site/scripts/generate_chatbot_product_map.py and python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v (both pass).

What needs special review?

Dependencies, breaking changes, and deployment notes

No breaking changes. CI-only; no deployment steps beyond the existing validate workflow.

Release notes

internal — no user-facing release notes.

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

[github-actions]

Lighthouse check results

✓ INFO: No site pages to audit in this PR.

Commit SHA: eaa3cb7

[github-actions]

PR Summary

This PR improves the documentation validation workflow by enhancing the automation related to the chatbot product map generation. The main changes include:

• Updating the GitHub Actions workflow (.github/workflows/validate-docs-site.yaml) to:

  • Checkout using a specified ref, full history (fetch-depth: 0), and token for write access.
  • Introduce enhanced error handling and robust shell options (set -euo pipefail) during the chatbot product map verification step.
  • Compare both chatbot-product-map.md and its associated frontend snapshot, with clear error messages if the frontend snapshot is stale or if the changes come from forked repositories.
  • Automatically commit and push the refreshed chatbot-product-map.md for same-repo pull requests, reducing manual intervention.

• Updating documentation in README.md and site/llm/README.md to explain the changes:

  • Providing detailed instructions on how and when to regenerate the chatbot product map and the snapshot.
  • Clarifying that auto-commit behavior only applies to same-repo PRs, while forked PRs must handle regenerations manually.

• Minor content adjustments in site/llm/chatbot-product-map.md to update textual reference from "specific model" to "specific record (model)", ensuring clarity in documentation.

These changes aim to streamline the CI process around documentation validation and ensure that the in-app chatbot assistant always has up-to-date mapping data.

Test Suggestions

• Trigger the workflow with a PR that modifies documentation to see if the chatbot product map files are auto-refreshed as expected.
• Simulate a scenario where the frontend snapshot is stale to verify that the workflow emits the appropriate error message.
• Test forked pull requests to confirm that the auto-commit step is skipped and proper instructions are output for manual refresh.
• Run the included unittest (test_generate_chatbot_product_map.py) to verify that the map generation script produces the expected outputs.

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[github-actions]

Lighthouse check results

✓ INFO: No site pages to audit in this PR.

Commit SHA: b63dd89