@-mention non-collaborator release contributors; widen toolhive docs paths

Two independent but related improvements to the upstream-release-docs
pipeline:

1. Reviewer routing: @-mention contributors we can't auto-assign

   The existing reviewer-extract step batched all non-bot release
   commit authors and filtered to docs-website collaborators. On
   PR #759 that filter silently dropped four of five candidates
   (`reyortiz3`, `ChrisJBurns`, `jhroz`, `tgrunnag` are all upstream
   toolhive contributors but not collaborators on docs-website).
   The filter is mandatory because `gh pr edit --add-reviewer`
   returns 422 for any non-collaborator in the list, dropping the
   valid reviewers alongside the invalid ones.

   Now split the candidates:
     - ASSIGN_LIST (collaborators): batch-assigned as reviewers
       via `--add-reviewer`. Unchanged behavior.
     - MENTION_LIST (everyone else): @-mentioned in a new
       "Release contributors" section of the PR body so they see
       the PR documenting their work even though we can't request
       their review via the API.

   Detecting Stacklok employees directly (e.g. via the `stackers`
   team) requires a PAT with read:org scope -- `GITHUB_TOKEN`
   doesn't have it, and public-org-membership checks only see
   members with public membership. Deferred; noted in a comment.

2. Expand toolhive docs_paths hints

   The `toolhive` upstream is a monorepo shipping the CLI, the
   Kubernetes operator, and the vMCP gateway, plus cross-cutting
   features that land in concepts/, integrations/, tutorials/,
   and hand-written reference pages. The previous hints listed
   only the three guides-* folders. In practice the skill's
   Phase 3 impact map expanded beyond the hints (PR #759 touched
   concepts/, integrations/, tutorials/), so this is a focus
   improvement rather than a bug fix -- more accurate hints let
   Phase 2's source reading home in on the right areas without
   re-scanning unrelated docs.

   Other projects' hints are already accurate for their scope.
   toolhive-cloud-ui intentionally keeps docs_paths: [] -- no
   associated docs in this repo yet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rdimitrov

.github/upstream-projects.yaml

@@ -36,10 +36,21 @@ projects:
   - id: toolhive
     repo: stacklok/toolhive
     version: v0.23.1
+    # toolhive is a monorepo covering the CLI, the Kubernetes
+    # operator, and the vMCP gateway. It also introduces cross-
+    # cutting features that land in concepts/, integrations/,
+    # tutorials/, and hand-written reference pages. These entries
+    # are hints, not constraints -- the skill's Phase 3 impact map
+    # decides what actually changes. Hints focus Phase 2's source
+    # reading so the skill doesn't re-scan unrelated areas.
     docs_paths:
       - docs/toolhive/guides-cli
       - docs/toolhive/guides-k8s
       - docs/toolhive/guides-vmcp
+      - docs/toolhive/concepts
+      - docs/toolhive/integrations
+      - docs/toolhive/tutorials
+      - docs/toolhive/reference/authz-policy-reference.mdx
     assets:
       - release_asset: swagger.yaml
         destination: static/api-specs/toolhive-api.yaml

.github/workflows/upstream-release-docs.yml

@@ -391,7 +391,7 @@ jobs:
         id: pre_skill
         run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
-      - name: Extract reviewers from release compare
+      - name: Extract reviewers and contributors from release compare
         id: reviewers
         env:
           REPO: ${{ steps.detect.outputs.repo }}
@@ -408,29 +408,54 @@ jobs:
             echo "compare_ok=false" >> "$GITHUB_OUTPUT"
           fi
 
-          # Filter out bot accounts, then further filter to only this
-          # repo's collaborators. GitHub rejects reviewer requests for
-          # non-collaborators with 422, which would fail the whole
-          # `gh pr edit --add-reviewer` call and drop the valid
-          # reviewers along with the invalid ones. Community
-          # contributors from the upstream repo often aren't
-          # collaborators here; silently skip them.
+          # Filter out bot accounts.
           CANDIDATES=$(echo "$COMPARE" |
             grep -Ev '(\[bot\]$|^github-actions|^stacklokbot$|^dependabot|^renovate|^copilot)' || true)
 
-          REVIEWERS=""
+          # Split candidates into two groups:
+          #   - ASSIGN_LIST: collaborators on this repo -- safe to pass
+          #     to `gh pr edit --add-reviewer`. GitHub rejects the
+          #     entire call with 422 if any name in the list isn't a
+          #     collaborator, so the filter is mandatory to avoid
+          #     dropping valid reviewers alongside invalid ones.
+          #   - MENTION_LIST: everyone else. Upstream contributors
+          #     (often Stacklok employees with private org membership
+          #     we can't detect via GITHUB_TOKEN, which lacks
+          #     read:org) still deserve a ping so they see the PR
+          #     documenting their work. @-mentioning in the PR body
+          #     handles that without needing reviewer-assignment
+          #     rights.
+          # Future: a PAT with read:org could let us also check
+          # membership in the `stackers` team and promote those to
+          # ASSIGN_LIST. Deferred -- not wiring a secret in now.
+          ASSIGN_LIST=""
+          MENTION_LIST=""
           while IFS= read -r login; do
             [ -z "$login" ] && continue
             if gh api "repos/$REVIEW_REPO/collaborators/$login" --silent 2>/dev/null; then
-              REVIEWERS="${REVIEWERS:+$REVIEWERS,}$login"
+              ASSIGN_LIST="${ASSIGN_LIST:+$ASSIGN_LIST,}$login"
+            else
+              MENTION_LIST="${MENTION_LIST:+$MENTION_LIST }@$login"
             fi
           done <<< "$CANDIDATES"
 
-          # Cap at 5 to avoid review fatigue.
-          REVIEWERS=$(echo "$REVIEWERS" | tr ',' '\n' | head -5 | paste -sd, -)
+          # Cap auto-assignments at 5 to avoid review fatigue. Mentions
+          # aren't capped -- they're cheap and the block is a single
+          # PR-body notification.
+          ASSIGN_LIST=$(echo "$ASSIGN_LIST" | tr ',' '\n' | head -5 | paste -sd, -)
 
-          echo "list=$REVIEWERS" >> "$GITHUB_OUTPUT"
-          echo "Reviewers: ${REVIEWERS:-<none>}"
+          echo "list=$ASSIGN_LIST" >> "$GITHUB_OUTPUT"
+          {
+            echo "mention_block<<MENTION_EOF"
+            if [ -n "$MENTION_LIST" ]; then
+              echo "Release contributors who aren't collaborators on this repo and so couldn't be auto-assigned as reviewers. Mentioning them so they see the PR documenting their work:"
+              echo ""
+              echo "$MENTION_LIST"
+            fi
+            echo "MENTION_EOF"
+          } >> "$GITHUB_OUTPUT"
+          echo "Auto-assigned: ${ASSIGN_LIST:-<none>}"
+          echo "Mentioned:     ${MENTION_LIST:-<none>}"
 
       - name: Read docs_paths hint
         id: hints
@@ -797,6 +822,8 @@ jobs:
           GAPS_BLOCK: ${{ steps.signals.outputs.gaps_block }}
           AUTOGEN_NOTE: ${{ steps.autogen.outputs.note }}
           COMPARE_OK: ${{ steps.reviewers.outputs.compare_ok }}
+          MENTION_BLOCK: ${{ steps.reviewers.outputs.mention_block }}
+          ASSIGN_LIST: ${{ steps.reviewers.outputs.list }}
         run: |
           START='<!-- upstream-release-docs:start -->'
           END='<!-- upstream-release-docs:end -->'
@@ -830,8 +857,22 @@ jobs:
               echo "$GAPS_BLOCK"
               echo ""
             fi
-            echo "Reviewers below are non-bot commit authors in the release range who are also collaborators on this repo."
+            echo "### Release contributors"
             echo ""
+            if [ -n "$ASSIGN_LIST" ]; then
+              # Comma list -> @-mention list for rendering.
+              ASSIGNED_MENTIONS=$(echo "$ASSIGN_LIST" | tr ',' '\n' | sed 's/^/@/' | paste -sd' ' -)
+              echo "Auto-assigned as reviewers (collaborators on this repo): $ASSIGNED_MENTIONS"
+              echo ""
+            fi
+            if [ -n "$MENTION_BLOCK" ]; then
+              echo "$MENTION_BLOCK"
+              echo ""
+            fi
+            if [ -z "$ASSIGN_LIST" ] && [ -z "$MENTION_BLOCK" ]; then
+              echo "No non-bot contributors were found in the release range."
+              echo ""
+            fi
             echo "$END"
           } > /tmp/section.md