ci(context7): gate version-tag move + refresh on docs-only changes

Add `paths:` filter to `Update version tags` push trigger so infra-only
pushes (workflows, scripts, Docker, README, etc.) skip the tag move and
therefore skip the downstream Context7 refresh. Context7 only ingests
`docs/**` (per context7.json `folders`), so refreshing on infra commits
wasted API calls and gave no benefit. `context7.json` is also covered
because changes to its `rules`/`folders`/`excludeFolders` affect what
Context7 returns even when no .md files moved.

The version tag's only consumer is Context7, so skipping the move on
infra-only pushes is semantically correct — the tag still represents
the latest docs state. `workflow_dispatch` on context7-refresh.yml
remains available to force a refresh out of band.

🤖 Generated by [robots](https://vyos.io)

(cherry picked from commit 800acbfd4c7ddeb6e60be6ddf60d5d8ef433d735)

# Conflicts:
#	.github/workflows/context7-refresh.yml
#	.github/workflows/update-version-tags.yml

1 files changed, 104 insertions, 0 deletions

diff --git a/.github/workflows/context7-refresh.yml b/.github/workflows/context7-refresh.yml
new file mode 100644
index 00000000..8072c389
--- /dev/null
+++ b/.github/workflows/context7-refresh.yml
@@ -0,0 +1,104 @@
+name: Context7 refresh
+
+# Listens for completion of "Update version tags" via workflow_run, then
+# refreshes the Context7 variant for the branch that fed it. The upstream
+# workflow is matched by name — DO NOT rename `Update version tags` without
+# updating the `workflows:` field below.
+#
+# Context7 API addresses variants by their TYPE:
+#   - default variant (rolling)     → omit both `branch` and `tag`
+#   - tag-backed variants (1.5/1.4) → `tag: "1.5"` / `tag: "1.4"`
+#   - branch-backed non-default     → `branch: "<name>"` (none used here)
+# `branch: "1.5"` returns 404 branch_not_found; `branch: "rolling"` returns
+# 400 branch-not-found. Empirically verified 2026-05-10 against the live API.
+#
+# OPERATOR NOTE: do NOT use GitHub's "Re-run jobs" on `Update version tags`.
+# Re-runs replay the original SHA, which would move the version tag
+# BACKWARD and trigger this workflow to refresh Context7 against stale
+# content. To force a Context7 refresh, use the workflow_dispatch input
+# below — it calls Context7 directly without touching any tag.
+#
+# Docs-only gating is enforced upstream: `Update version tags` has a
+# `paths:` filter scoped to `docs/**` and `context7.json`, so infra-only
+# pushes (workflows, scripts, README, etc.) never fire that workflow and
+# this one never sees a workflow_run event for them.
+
+on:
+  workflow_run:
+    workflows: ["Update version tags"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      variant:
+        description: "Context7 variant to refresh (rolling = default; 1.5 = circinus; 1.4 = sagitta)"
+        type: choice
+        options: [rolling, "1.5", "1.4"]
+        default: rolling
+
+permissions: {}
+
+concurrency:
+  group: >-
+    context7-refresh-${{
+      (contains(fromJSON('["rolling","1.5","1.4"]'), inputs.variant) && inputs.variant)
+      || (github.event.workflow_run.head_branch == 'circinus' && '1.5')
+      || (github.event.workflow_run.head_branch == 'sagitta' && '1.4')
+      || (github.event.workflow_run.head_branch == 'rolling' && 'rolling')
+      || 'invalid'
+    }}
+  cancel-in-progress: true
+
+jobs:
+  refresh:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       contains(fromJSON('["rolling","circinus","sagitta"]'), github.event.workflow_run.head_branch))
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Refresh Context7 library
+        env:
+          CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          DISPATCH_VARIANT: ${{ inputs.variant }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
+            echo "ERROR: CONTEXT7_API_KEY is unset or empty" >&2
+            exit 1
+          fi
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            VARIANT="$DISPATCH_VARIANT"
+          else
+            case "$HEAD_BRANCH" in
+              rolling)  VARIANT=rolling ;;
+              circinus) VARIANT=1.5 ;;
+              sagitta)  VARIANT=1.4 ;;
+              *) echo "Unexpected head_branch: $HEAD_BRANCH" >&2; exit 1 ;;
+            esac
+          fi
+          # Defense-in-depth: type:choice UI constraint is bypassable when
+          # workflow_dispatch is invoked via API (`gh workflow run -f variant=…`).
+          case "$VARIANT" in
+            rolling|1.5|1.4) ;;
+            *) echo "Invalid variant: '${VARIANT}'. Expected one of: rolling, 1.5, 1.4." >&2; exit 1 ;;
+          esac
+          echo "Refreshing Context7 variant: $VARIANT"
+          # rolling = default variant (no field). 1.5/1.4 = tag-backed.
+          if [[ "$VARIANT" == "rolling" ]]; then
+            PAYLOAD="$(jq -nc --arg lib "/${{ github.repository }}" \
+              '{libraryName: $lib}')"
+          else
+            PAYLOAD="$(jq -nc --arg lib "/${{ github.repository }}" --arg tg "$VARIANT" \
+              '{libraryName: $lib, tag: $tg}')"
+          fi
+          curl -fsSL \
+            --connect-timeout 10 \
+            --max-time 60 \
+            --retry 2 --retry-delay 10 \
+            -X POST \
+            "https://context7.com/api/v1/refresh" \
+            -H "Authorization: Bearer $CONTEXT7_API_KEY" \
+            -H "Content-Type: application/json" \
+            -d "$PAYLOAD"