Per-user reviewer attempts + @-mention fallback + widen toolhive docs paths

.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