From eaa3cb7b3c96dee3b1cfddd34211afbbc60c6a56 Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Mon, 25 May 2026 19:19:30 -0700 Subject: [PATCH 1/5] CI: auto-commit chatbot product map on docs-only drift When validate regenerates chatbot-product-map.md from .qmd changes on same-repo PRs, commit and push the file instead of failing. Snapshot drift and fork PRs still require a local refresh. --- .github/workflows/validate-docs-site.yaml | 34 ++++++++++++++++++++++- README.md | 15 ++++++++++ site/llm/README.md | 1 + 3 files changed, 49 insertions(+), 1 deletion(-) diff --git a/.github/workflows/validate-docs-site.yaml b/.github/workflows/validate-docs-site.yaml index f9a7fc80f..9396c2e74 100644 --- a/.github/workflows/validate-docs-site.yaml +++ b/.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 diff --git a/README.md b/README.md index 775542ed9..e0848e0ef 100644 --- a/README.md +++ b/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: diff --git a/site/llm/README.md b/site/llm/README.md index 91bd82bd9..f75d9ebef 100644 --- a/site/llm/README.md +++ b/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). From 40d31c8955b9d2a489f48d3bb9531591f090b989 Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Mon, 25 May 2026 19:38:51 -0700 Subject: [PATCH 2/5] test: trigger product map drift via FAQ heading --- site/faq/faq-workflows.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/faq/faq-workflows.qmd b/site/faq/faq-workflows.qmd index a11bf82fb..a61db2379 100644 --- a/site/faq/faq-workflows.qmd +++ b/site/faq/faq-workflows.qmd @@ -45,7 +45,7 @@ Yes, {{< var vm.product >}} supports disconnected workflows natively at the data - Visualizing the disconnected workflow in terms of model testing and documentation will depend on requirements at the use-case level. ::: {.callout} -## You can also leverage the {{< var validmind.developer >}} once you are ready to document a specific model for review and validation. +## You can also leverage the {{< var validmind.developer >}} once you are ready to document a specific record (model) for review and validation. You do not need to use the {{< var validmind.platform >}} while you are in the exploration or R&D phase of model development. ::: From 3747ed2b3f69c897f6d165589542d3e482feaf11 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 26 May 2026 02:55:48 +0000 Subject: [PATCH 3/5] chore: refresh chatbot product map --- site/llm/chatbot-product-map.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/llm/chatbot-product-map.md b/site/llm/chatbot-product-map.md index d1361fcfa..c2abf3e49 100644 --- a/site/llm/chatbot-product-map.md +++ b/site/llm/chatbot-product-map.md @@ -452,7 +452,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html` @@ -474,7 +474,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html` @@ -561,7 +561,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html` From b63dd897844eb722b0525e9ee59ba0ced54618af Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Mon, 25 May 2026 20:00:55 -0700 Subject: [PATCH 4/5] test: revert FAQ heading after product map auto-commit test --- site/faq/faq-workflows.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/faq/faq-workflows.qmd b/site/faq/faq-workflows.qmd index a61db2379..a11bf82fb 100644 --- a/site/faq/faq-workflows.qmd +++ b/site/faq/faq-workflows.qmd @@ -45,7 +45,7 @@ Yes, {{< var vm.product >}} supports disconnected workflows natively at the data - Visualizing the disconnected workflow in terms of model testing and documentation will depend on requirements at the use-case level. ::: {.callout} -## You can also leverage the {{< var validmind.developer >}} once you are ready to document a specific record (model) for review and validation. +## You can also leverage the {{< var validmind.developer >}} once you are ready to document a specific model for review and validation. You do not need to use the {{< var validmind.platform >}} while you are in the exploration or R&D phase of model development. ::: From a2792941d907cec66f6fa5290cbc656d1c4f2f87 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 26 May 2026 03:18:31 +0000 Subject: [PATCH 5/5] chore: refresh chatbot product map --- site/llm/chatbot-product-map.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/llm/chatbot-product-map.md b/site/llm/chatbot-product-map.md index c2abf3e49..d1361fcfa 100644 --- a/site/llm/chatbot-product-map.md +++ b/site/llm/chatbot-product-map.md @@ -452,7 +452,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html` @@ -474,7 +474,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html` @@ -561,7 +561,7 @@ **Docs (related):** - `/faq/faq-workflows.html` - - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more + - Sections: Can I customize workflows within }?; What statuses are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific model for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; a. Configure workflow in }; b. Start workflow from external system; Trigger a paused workflow to continue; a. Configure workflow in }; b. Trigger workflow to continue from external system - `/guide/workflows/conditional-step-requirements.html`