[SC-18087] Rank chatbot product map related docs by section before the six-entry cap

.github/workflows/full-docs-validation.yaml

@@ -71,17 +71,18 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y pandoc
 
+      - name: Test chatbot product map generator
+        run: python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v
+
       - 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-dropped.md \
             site/llm/chatbot-product-map-frontend-snapshot.json
 
-      - name: Test chatbot product map generator
-        run: python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v
-
       - name: Validate LLM markdown render
         run: bash llm/render.sh
         working-directory: site

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

@@ -382,6 +382,12 @@ jobs:
         sudo apt-get update
         sudo apt-get install -y pandoc
 
+    # Runs on every PR, targeted previews included, and before the map
+    # auto-commit below, so a guide edit that evicts a pinned related doc fails
+    # the PR that caused it.
+    - name: Test chatbot product map generator
+      run: python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v
+
     # Targeted guide edits can change the map without requiring a full render.
     - name: Verify chatbot product map is up to date
       run: |
@@ -390,7 +396,7 @@ jobs:
 
         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.md site/llm/chatbot-product-map-dropped.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
@@ -399,25 +405,21 @@ jobs:
         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."
+          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, site/llm/chatbot-product-map.md and site/llm/chatbot-product-map-dropped.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."
+          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 and site/llm/chatbot-product-map-dropped.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 add site/llm/chatbot-product-map.md site/llm/chatbot-product-map-dropped.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
-      if: steps.preview.outputs.targeted != 'true'
-      run: python3 -m unittest discover -s site/scripts -p 'test_generate_chatbot_product_map.py' -v
+        echo "Auto-committed refreshed site/llm/chatbot-product-map.md and chatbot-product-map-dropped.md."
 
     - name: Validate LLM markdown render
       if: steps.preview.outputs.targeted != 'true'

site/llm/README.md

@@ -36,6 +36,7 @@ Valerie needs routes in the product UI (especially **Settings**) mapped to docum
 |----------|---------|
 | `chatbot-product-map-frontend-snapshot.json` | Vendored extract from `validmind/frontend` (Settings tree, sidebar nav, `helpLink` / docs URLs) |
 | `chatbot-product-map.md` | Retrieval-oriented map: routes → primary/related docs + section headings from `.qmd` |
+| `chatbot-product-map-dropped.md` | Related docs that matched a route but did not fit in its six slots. Committed for review only, not copied into the LLM corpus |
 
 ### Why a frontend snapshot?
 
@@ -49,7 +50,9 @@ 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.
+For same-repo pull requests, the validate workflow auto-commits docs-only refreshes of `chatbot-product-map.md` and `chatbot-product-map-dropped.md`. Fork pull requests and any snapshot drift still fail and require a local regenerate + commit.
+
+Related docs are ranked by section (the route's own docs section, then sections a route keyword names, then filename-only matches), then by position in the docs sidebars, then by path. Each route keeps six. A diff in `chatbot-product-map-dropped.md` means a route gained or lost a related doc, so check it when you add or reorder guide pages.
 
 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).

site/llm/chatbot-product-map-dropped.md

@@ -0,0 +1,250 @@
+# Related docs dropped from the chatbot product map
+
+> Auto-generated by `site/scripts/generate_chatbot_product_map.py`. Not part of the LLM corpus.
+> Each route lists matching docs that did not fit in its 6 related-doc slots,
+> most relevant first. A change here means a route gained or lost a related doc.
+
+## `/analytics`
+
+- `/guide/reporting/tracking-organization-activity.html`
+- `/guide/reporting/view-record-activity.html`
+- `/guide/reporting/view-settings-activity.html`
+- `/guide/reporting/working-with-analytics.html`
+- `/guide/reporting/view-report-data.html`
+- `/guide/reporting/manage-custom-reports.html`
+- `/guide/reporting/export-analytics.html`
+- `/guide/reporting/generating-exports.html`
+- `/guide/reporting/export-inventory.html`
+- `/guide/reporting/export-documents.html`
+- `/guide/reporting/export-artifacts.html`
+- `/faq/faq-reporting.html`
+
+## `/settings/attestation-templates`
+
+- `/guide/templates/customize-document-templates.html`
+- `/guide/templates/manage-document-templates.html`
+- `/guide/templates/manage-text-block-library.html`
+- `/guide/templates/managing-documents.html`
+- `/guide/templates/manage-document-types.html`
+- `/guide/templates/manage-documents.html`
+- `/guide/templates/customize-document-checker.html`
+- `/faq/faq-attestations.html`
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+
+## `/settings/block-library`
+
+- `/guide/templates/customize-document-checker.html`
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+
+## `/settings/document-types`
+
+- `/guide/templates/customize-document-checker.html`
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+
+## `/settings/documents/general`
+
+- `/guide/templates/manage-documents.html`
+- `/guide/templates/customize-document-checker.html`
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+
+## `/settings/integrations/connections`
+
+- `/guide/integrations/configure-data-exports.html`
+- `/guide/integrations/integrations-examples.html`
+- `/guide/integrations/integrations-examples/create-jira-ticket.html`
+- `/guide/integrations/integrations-examples/create-servicenow-incident.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-bedrock.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-sagemaker.html`
+- `/guide/integrations/integrations-examples/synchronize-with-databricks.html`
+- `/guide/integrations/integrations-examples/synchronize-gitlab.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/faq/faq-integrations.html`
+
+## `/settings/integrations/data-exports`
+
+- `/guide/integrations/link-external-records.html`
+- `/guide/integrations/integrations-examples.html`
+- `/guide/integrations/integrations-examples/create-jira-ticket.html`
+- `/guide/integrations/integrations-examples/create-servicenow-incident.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-bedrock.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-sagemaker.html`
+- `/guide/integrations/integrations-examples/synchronize-with-databricks.html`
+- `/guide/integrations/integrations-examples/synchronize-gitlab.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/faq/faq-integrations.html`
+
+## `/settings/integrations/secrets`
+
+- `/guide/integrations/configure-data-exports.html`
+- `/guide/integrations/integrations-examples.html`
+- `/guide/integrations/integrations-examples/create-jira-ticket.html`
+- `/guide/integrations/integrations-examples/create-servicenow-incident.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-bedrock.html`
+- `/guide/integrations/integrations-examples/synchronize-aws-sagemaker.html`
+- `/guide/integrations/integrations-examples/synchronize-with-databricks.html`
+- `/guide/integrations/integrations-examples/synchronize-gitlab.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/faq/faq-integrations.html`
+
+## `/settings/inventory-model-custom-fields`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/primary-record-type-stages`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/primary-record-types`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/primary-record-types/fields`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/risk-tier-templates`
+
+- `/guide/templates/customize-document-templates.html`
+- `/guide/templates/manage-document-templates.html`
+- `/guide/templates/manage-text-block-library.html`
+- `/guide/templates/managing-documents.html`
+- `/guide/templates/manage-document-types.html`
+- `/guide/templates/manage-documents.html`
+- `/guide/templates/customize-document-checker.html`
+
+## `/settings/segments`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/stakeholders`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/statuses`
+
+- `/guide/inventory/register-records-in-inventory.html`
+- `/guide/inventory/import-records-into-inventory.html`
+- `/guide/inventory/customize-inventory-layout.html`
+- `/guide/inventory/edit-inventory-fields.html`
+- `/guide/inventory/customize-record-overview-page.html`
+- `/guide/inventory/manage-record-versions.html`
+- `/guide/inventory/view-record-data.html`
+- `/guide/inventory/managing-the-inventory.html`
+- `/guide/inventory/configure-record-interdependencies.html`
+- `/guide/inventory/archive-delete-records.html`
+- `/faq/faq-inventory.html`
+- `/guide/reporting/export-inventory.html`
+
+## `/settings/templates`
+
+- `/guide/templates/customize-document-checker.html`
+- `/guide/risk-tiering/manage-risk-tier-templates.html`
+
+## `/settings/workflow-states`
+
+- `/guide/workflows/set-field-formulas.html`
+- `/guide/workflows/working-with-workflows.html`
+- `/guide/workflows/manage-workflows.html`
+- `/guide/workflows/transition-workflows.html`
+- `/guide/workflows/manage-workflow-tasks.html`
+- `/guide/workflows/assign-workflow-executions.html`
+- `/guide/workflows/workflow-configuration-examples.html`
+- `/faq/faq-workflows.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/guide/risk-tiering/set-up-risk-tiering-workflows.html`
+- `/guide/monitoring/trigger-workflows-on-threshold-breach.html`
+
+## `/settings/workflows`
+
+- `/guide/workflows/set-field-formulas.html`
+- `/guide/workflows/working-with-workflows.html`
+- `/guide/workflows/manage-workflows.html`
+- `/guide/workflows/transition-workflows.html`
+- `/guide/workflows/manage-workflow-tasks.html`
+- `/guide/workflows/assign-workflow-executions.html`
+- `/guide/workflows/workflow-configuration-examples.html`
+- `/faq/faq-workflows.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/guide/risk-tiering/set-up-risk-tiering-workflows.html`
+- `/guide/monitoring/trigger-workflows-on-threshold-breach.html`
+
+## `/workflows`
+
+- `/guide/workflows/configure-workflows.html`
+- `/guide/workflows/set-field-formulas.html`
+- `/guide/workflows/working-with-workflows.html`
+- `/guide/workflows/manage-workflows.html`
+- `/guide/workflows/transition-workflows.html`
+- `/guide/workflows/manage-workflow-tasks.html`
+- `/guide/workflows/assign-workflow-executions.html`
+- `/guide/workflows/workflow-configuration-examples.html`
+- `/faq/faq-workflows.html`
+- `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html`
+- `/guide/risk-tiering/set-up-risk-tiering-workflows.html`
+- `/guide/monitoring/trigger-workflows-on-threshold-breach.html`