docs: optimize link checker

We now use `Protocol.MCP` as default and would be deprecating
`Protocol.TOOLBOX` going forward. This PR makes the guide simpler and
more future-proof by removing passing `Protocol.TOOLBOX`.

.github/workflows/link_checker_workflow.yaml

@@ -15,6 +15,9 @@ name: Link Checker
 
 on:
   pull_request:
+permissions:
+  contents: read
+  pull-requests: write
 
 
 jobs:
@@ -23,8 +26,33 @@ jobs:
     steps:
       - name: Checkout Repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+      - name: Identify Changed Files
+        id: changed-files
+        shell: bash
+        run: |
+          git fetch origin main
+          CHANGED_FILES=$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD)
+
+          if [ -z "$CHANGED_FILES" ]; then
+            echo "No markdown files changed. Skipping checks."
+            echo "HAS_CHANGES=false" >> $GITHUB_ENV
+          else
+            echo "--- Changed Files to Scan ---"
+            echo "$CHANGED_FILES"
+            echo "-----------------------------"
+            
+            # Flatten newlines to spaces for the args list
+            FILES_FLAT=$(echo "$CHANGED_FILES" | tr '\n' ' ')
+            
+            echo "CHECK_FILES=$FILES_FLAT" >> $GITHUB_ENV
+            echo "HAS_CHANGES=true" >> $GITHUB_ENV
+          fi
+
 
       - name: Restore lychee cache
+        if: env.HAS_CHANGES == 'true'
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
         with:
           path: .lycheecache
@@ -33,6 +61,7 @@ jobs:
 
       - name: Link Checker
         id: lychee-check       
+        if: env.HAS_CHANGES == 'true'
         uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2
         continue-on-error: true 
         with:
@@ -42,8 +71,7 @@ jobs:
             --cache
             --max-cache-age 1d
             --exclude '^neo4j\+.*' --exclude '^bolt://.*'
-            README.md
-            docs/
+            ${{ env.CHECK_FILES }}
           output: lychee-report.md
           format: markdown
           fail: true           
@@ -51,18 +79,44 @@ jobs:
           debug: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Find comment
+        if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: "## Link Resolution Note"
+
+      - name: Prepare Report 
+        if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'
+        run: |
+          # Create a new file 'full-report.md'
+          echo "## Link Resolution Note" > full-report.md
+          echo "Local links and directory changes work differently on GitHub than on the docsite." >> full-report.md
+          echo "You must ensure fixes pass the **GitHub check** and also work with **\`hugo server\`**." >> full-report.md
+          echo "See [Link Checking and Fixing with Lychee](https://github.com/googleapis/genai-toolbox/blob/main/DEVELOPER.md#link-checking-and-fixing-with-lychee) for more details." >> full-report.md
+          echo "---" >> full-report.md
+          echo "### Broken Links Found" >> full-report.md
+          
+          # Clean the report (remove redirects) AND append it to the file
+          sed -E '/(Redirect|Redirects per input)/d' lychee-report.md >> full-report.md
+
+      - name: Create PR Comment
+        if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body-path: full-report.md
+          edit-mode: replace
 
       - name: Display Failure Report
         # Run this ONLY if the link checker failed
         if: steps.lychee-check.outcome == 'failure'
         run: |
-          echo "## Link Resolution Note" >> $GITHUB_STEP_SUMMARY
-          echo "Local links and directory changes work differently on GitHub than on the docsite." >> $GITHUB_STEP_SUMMARY
-          echo "You must ensure fixes pass the **GitHub check** and also work with **\`hugo server\`**." >> $GITHUB_STEP_SUMMARY
-          echo "See [Link Checking and Fixing with Lychee](https://github.com/googleapis/genai-toolbox/blob/main/DEVELOPER.md#link-checking-and-fixing-with-lychee) for more details." >> $GITHUB_STEP_SUMMARY
-          echo "---" >> $GITHUB_STEP_SUMMARY
-
-          echo "### Broken Links Found" >> $GITHUB_STEP_SUMMARY
-          cat ./lychee-report.md >> $GITHUB_STEP_SUMMARY
-
+          # We can now simply output the prepared file to the job summary
+          cat full-report.md >> $GITHUB_STEP_SUMMARY
+          
+          # Fail the job
           exit 1

docs/en/getting-started/quickstart/go/quickstart_test.go

@@ -20,6 +20,8 @@ import (
 	"testing"
 )
 
+var goldenKeywords = []string{"Hilton Basel", "Hyatt Regency", "book"}
+
 func TestQuickstartSample(t *testing.T) {
 	framework := os.Getenv("ORCH_NAME")
 	if framework == "" {
@@ -59,16 +61,10 @@ func TestQuickstartSample(t *testing.T) {
 		t.Fatal("Script ran successfully but produced no output.")
 	}
 
-	goldenFile, err := os.ReadFile("../golden.txt")
-	if err != nil {
-		t.Fatalf("Could not read golden.txt to check for keywords: %v", err)
-	}
-
-	keywords := strings.Split(string(goldenFile), "\n")
 	var missingKeywords []string
 	outputLower := strings.ToLower(actualOutput)
 
-	for _, keyword := range keywords {
+	for _, keyword := range goldenKeywords {
 		kw := strings.TrimSpace(keyword)
 		if kw != "" && !strings.Contains(outputLower, strings.ToLower(kw)) {
 			missingKeywords = append(missingKeywords, kw)

docs/en/getting-started/quickstart/golden.txt

@@ -1,3 +0,0 @@
-Hilton Basel
-Hyatt Regency
-book

docs/en/getting-started/quickstart/js/quickstart.test.js

@@ -25,7 +25,7 @@ const quickstartPath = path.join(orchDir, "quickstart.js");
 
 const { main: runAgent } = await import(quickstartPath);
 
-const GOLDEN_FILE_PATH = path.resolve(__dirname, "../golden.txt");
+const GOLDEN_KEYWORDS = ["Hilton Basel", "Hyatt Regency", "book"];
 
 describe(`${ORCH_NAME} Quickstart Agent`, () => {
   let capturedOutput = [];
@@ -52,11 +52,8 @@ describe(`${ORCH_NAME} Quickstart Agent`, () => {
       "Assertion Failed: Script ran successfully but produced no output."
     );
 
-    const goldenFile = fs.readFileSync(GOLDEN_FILE_PATH, "utf8");
-    const keywords = goldenFile.split("\n").filter((kw) => kw.trim() !== "");
     const missingKeywords = [];
-
-    for (const keyword of keywords) {
+    for (const keyword of GOLDEN_KEYWORDS) {
       if (!actualOutput.toLowerCase().includes(keyword.toLowerCase())) {
         missingKeywords.push(keyword);
       }

docs/en/getting-started/quickstart/python/quickstart_test.py

@@ -24,18 +24,7 @@ module_path = f"python.{ORCH_NAME}.quickstart"
 quickstart = importlib.import_module(module_path)
 
 
-@pytest.fixture(scope="module")
-def golden_keywords():
-    """Loads expected keywords from the golden.txt file."""
-    golden_file_path = Path("../golden.txt")
-    if not golden_file_path.exists():
-        pytest.fail(f"Golden file not found: {golden_file_path}")
-    try:
-        with open(golden_file_path, 'r') as f:
-            return [line.strip() for line in f.readlines() if line.strip()]
-    except Exception as e:
-        pytest.fail(f"Could not read golden.txt: {e}")
-
+GOLDEN_KEYWORDS = ["Hilton Basel", "Hyatt Regency", "book"]
 
 # --- Execution Tests ---
 class TestExecution:
@@ -62,8 +51,8 @@ class TestExecution:
         """Test that the script runs and produces no stderr."""
         assert script_output.err == "", f"Script produced stderr: {script_output.err}"
 
-    def test_keywords_in_output(self, script_output, golden_keywords):
+    def test_keywords_in_output(self, script_output):
         """Test that expected keywords are present in the script's output."""
         output = script_output.out
-        missing_keywords = [kw for kw in golden_keywords if kw not in output]
+        missing_keywords = [kw for kw in GOLDEN_KEYWORDS if kw.lower() not in output.lower()]
         assert not missing_keywords, f"Missing keywords in output: {missing_keywords}"

docs/en/how-to/deploy_toolbox.md

@@ -207,7 +207,6 @@ You can connect to Toolbox Cloud Run instances directly through the SDK.
 {{< tab header="Python" lang="python" >}}
 import asyncio
 from toolbox_core import ToolboxClient, auth_methods
-from toolbox_core.protocol import Protocol
 
 # Replace with the Cloud Run service URL generated in the previous step
 URL = "https://cloud-run-url.app"
@@ -218,7 +217,6 @@ async def main():
   async with ToolboxClient(
       URL,
       client_headers={"Authorization": auth_token_provider},
-      protocol=Protocol.TOOLBOX,
   ) as toolbox:
     toolset = await toolbox.load_toolset()
     # ...