From 8383c56ae69f2ba23e32e4578b8cf0a19d9c8279 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Mon, 1 Jun 2026 14:08:09 +0530
Subject: [PATCH 01/13] ci(api-docs): trigger deployment on tag pushes

Adds tags:['**'] so the API Reference Deployment workflow fires on tag
pushes, not just main. Inert until a tag is pushed; per-package routing
and root-redirect handling follow in subsequent PRs.
---
 .github/workflows/api-docs.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml
index 95f9ead4..119c48db 100644
--- a/.github/workflows/api-docs.yml
+++ b/.github/workflows/api-docs.yml
@@ -17,7 +17,8 @@ name: "API Reference Deployment"
 on:
   push:
     branches: [ 'main', 'ref-docs' ]
-  workflow_dispatch: 
+    tags: [ '**' ]
+  workflow_dispatch:
 
 jobs:
   deploy:

From 2e1c0b977fb0a10ccb0d432490eb274310987858 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Mon, 1 Jun 2026 17:26:55 +0530
Subject: [PATCH 02/13] ci(api-docs): isolate per-package builds and stabilize
 root

Routes each tag to a single package built at /<pkg>/<version>/, builds
dev from main, and rebuilds the root README only on tag pushes so the
root URL stops flapping. Drops the destructive content wipe and macOS
sed dance.
---
 .github/workflows/api-docs.yml | 62 ++++++++++++++-------
 docs-site/hugo.toml            |  1 -
 scripts/generate-api-docs.sh   | 98 +++++++++++++---------------------
 scripts/generate-root.sh       | 25 +++++++++
 4 files changed, 103 insertions(+), 83 deletions(-)
 create mode 100755 scripts/generate-root.sh

diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml
index 119c48db..be6922fd 100644
--- a/.github/workflows/api-docs.yml
+++ b/.github/workflows/api-docs.yml
@@ -20,6 +20,10 @@ on:
     tags: [ '**' ]
   workflow_dispatch:
 
+concurrency:
+  group: api-docs-deploy
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -48,32 +52,50 @@ jobs:
           cd docs-site
           npm install postcss postcss-cli autoprefixer
 
-      - name: Build API Reference
+      - name: Resolve build target
+        id: resolve
         run: |
-          chmod +x scripts/generate-api-docs.sh
-          
-          # If the Action is running in the official upstream repository, 
-          # strictly route all assets and links to the production custom domain.
+          # Route the git ref to the package(s) and version to build.
+          # Per-package tags build one package; bare legacy tags build all three.
+          REF="${GITHUB_REF}"
+          case "$REF" in
+            refs/tags/core/v*)      echo "packages=core"                >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/core/}"     >> "$GITHUB_OUTPUT" ;;
+            refs/tags/tbadk/v*)     echo "packages=tbadk"               >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbadk/}"    >> "$GITHUB_OUTPUT" ;;
+            refs/tags/tbgenkit/v*)  echo "packages=tbgenkit"            >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbgenkit/}" >> "$GITHUB_OUTPUT" ;;
+            refs/tags/v[0-9]*)      echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/}"          >> "$GITHUB_OUTPUT" ;;
+            refs/tags/github.com/*) echo "packages="                    >> "$GITHUB_OUTPUT"; echo "version="                          >> "$GITHUB_OUTPUT" ;;
+            *)                      echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=dev"                        >> "$GITHUB_OUTPUT" ;;
+          esac
+
+          # Upstream serves from the custom domain; forks fall back to their
+          # GitHub Pages URL so external contributors can preview docsite changes.
           if [[ "${{ github.repository }}" == "googleapis/mcp-toolbox-sdk-go" ]]; then
-            BASE_URL="https://go.mcp-toolbox.dev/"
-          
-          # If the Action is running in an external contributor's fork, 
-          # dynamically fallback to their personal GitHub Pages URL.
-          # This ensures external contributors can successfully build and preview 
-          # docsite changes on their own forks without encountering broken links.
-          else
-            BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
-          fi
-          
-          if [[ $GITHUB_REF == refs/tags/* ]]; then
-            VERSION=${GITHUB_REF#refs/tags/}
+            echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
           else
-            VERSION="main"
+            echo "BASE_URL=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" >> "$GITHUB_ENV"
           fi
-          
-          ./scripts/generate-api-docs.sh "$VERSION" "$BASE_URL"
+
+      - name: Build per-package docs
+        if: steps.resolve.outputs.packages != ''
+        run: |
+          chmod +x scripts/generate-api-docs.sh
+          for PKG in ${{ steps.resolve.outputs.packages }}; do
+            # Legacy bare tags predate some packages; skip any absent at this ref.
+            if [[ "${{ steps.resolve.outputs.version }}" != "dev" ]] && [ ! -d "$PKG" ]; then
+              echo "Package $PKG absent at this ref; skipping." >&2
+              continue
+            fi
+            ./scripts/generate-api-docs.sh "$PKG" "${{ steps.resolve.outputs.version }}" "$BASE_URL"
+          done
+
+      - name: Build root page
+        if: steps.resolve.outputs.packages != '' && startsWith(github.ref, 'refs/tags/')
+        run: |
+          chmod +x scripts/generate-root.sh
+          ./scripts/generate-root.sh "$BASE_URL"
 
       - name: Deploy to gh-pages
+        if: steps.resolve.outputs.packages != ''
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs-site/hugo.toml b/docs-site/hugo.toml
index 088d751b..5e62349b 100644
--- a/docs-site/hugo.toml
+++ b/docs-site/hugo.toml
@@ -1,4 +1,3 @@
-baseURL = "PLACEHOLDER_BASE_URL"
 title = "MCP Toolbox Go API"
 
 [params]
diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
index 1c435c6c..8e064a03 100755
--- a/scripts/generate-api-docs.sh
+++ b/scripts/generate-api-docs.sh
@@ -1,87 +1,61 @@
 #!/bin/bash
-set -e
+set -euo pipefail
 
-export PATH=$PATH:$(go env GOPATH)/bin
+export PATH="$PATH:$(go env GOPATH)/bin"
 
-VERSION=${1:-"main"}
-BASE_URL=${2:-"/"}
+PACKAGE="${1:?package required (core|tbadk|tbgenkit)}"
+VERSION="${2:?version required (e.g. v1.0.0 or dev)}"
+BASE_URL="${3:-/}"
+
+case "$PACKAGE" in
+  core)     TITLE="Core" ;;
+  tbadk)    TITLE="Tbadk" ;;
+  tbgenkit) TITLE="Tbgenkit" ;;
+  *)        echo "Unknown package: $PACKAGE" >&2; exit 1 ;;
+esac
 
 go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
 
-rm -rf docs-site/content/*
-mkdir -p docs-site/content/docs
+# Per-build content tree in a temp dir, kept out of the checked-in
+# docs-site/content so concurrent package builds never trample each other.
+CONTENT_DIR="$(mktemp -d)"
+trap 'rm -rf "$CONTENT_DIR"' EXIT
+mkdir -p "$CONTENT_DIR/docs"
 
-cat <<EOF > docs-site/content/_index.md
+cat > "$CONTENT_DIR/_index.md" <<EOF
 ---
-title: "MCP Toolbox Go SDK"
+title: "MCP Toolbox Go SDK — ${TITLE} (${VERSION})"
 type: docs
 ---
-
 EOF
+cat README.md >> "$CONTENT_DIR/_index.md"
 
-cat README.md >> docs-site/content/_index.md
-
-cat <<EOF > docs-site/content/docs/_index.md
+cat > "$CONTENT_DIR/docs/_index.md" <<EOF
 ---
 title: "Packages"
 type: docs
 weight: 1
 alwaysopen: true
 ---
-Select a framework to view its public variables, functions, and structs.
+Public variables, functions, and structs for the ${TITLE} package.
 EOF
 
-generate_package() {
-  local PKG_DIR=$1
-  local TITLE=$2
-  local WEIGHT=$3
-  local MANUAL_VERSIONS=$4
-  local MD_FILE="docs-site/content/docs/${PKG_DIR}.md"
-
-  printf -- "---\ntitle: \"%s\"\ntype: docs\nweight: %s\n---\n\n" "$TITLE" "$WEIGHT" > "$MD_FILE"
-
-  cat <<EOF >> "$MD_FILE"
-<div style="margin-bottom: 2rem; padding: 1rem; background-color: #f8f9fa; border-radius: 8px; border: 1px solid #e9ecef; display: inline-block;">
-  <label for="${PKG_DIR}-version" style="font-weight: bold; margin-right: 10px; color: #4a4a4a;">Package Version:</label>
-  
-  <select id="${PKG_DIR}-version" onchange="if (this.value) window.location.href=this.value;" style="padding: 5px 10px; border-radius: 4px; border: 1px solid #ccc; background-color: white; color: #333333; cursor: pointer;">
-    <option value="${BASE_URL}main/docs/${PKG_DIR}/">main (latest)</option>
-EOF
+MD_FILE="$CONTENT_DIR/docs/${PACKAGE}.md"
+cat > "$MD_FILE" <<EOF
+---
+title: "${TITLE}"
+type: docs
+weight: 10
+---
 
-  for VER in $MANUAL_VERSIONS; do
-    echo "    <option value=\"${BASE_URL}${VER}/docs/${PKG_DIR}/\">${VER}</option>" >> "$MD_FILE"
-  done
+Viewing \`${VERSION}\`.
 
-  cat <<EOF >> "$MD_FILE"
-  </select>
-</div>
 EOF
-
-  gomarkdoc ./${PKG_DIR}/... | sed '/^# /d' >> "$MD_FILE"
-}
-
-# --- EXECUTE GENERATOR (UPDATE THESE BEFORE RELEASING!) ---
-# To add a version to the dropdown, just type it inside the quotes separated by a space.
-# Example: generate_package "core" "Core" "10" "v1.0.0 v0.9.0"
-
-generate_package "core" "Core" "10" ""
-generate_package "tbadk" "Tbadk" "20" ""
-generate_package "tbgenkit" "Tbgenkit" "30" ""
+gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$MD_FILE"
 
 cd docs-site
-sed -i "s|PLACEHOLDER_BASE_URL|${BASE_URL}|g" hugo.toml
-
-HUGO_PARAMS_VERSION="${VERSION}" hugo --minify --baseURL "${BASE_URL}${VERSION}/" --destination "public/${VERSION}"
-
-cat <<EOF > public/index.html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta http-equiv="refresh" content="0; url=${BASE_URL}${VERSION}/" />
-</head>
-<body style="background-color: rgb(64, 63, 76); color: white; text-align: center; padding-top: 50px; font-family: sans-serif;">
-  <p>Redirecting to the latest API version (${VERSION})...</p>
-  <script>window.location.replace('${BASE_URL}${VERSION}/');</script>
-</body>
-</html>
-EOF
\ No newline at end of file
+HUGO_PARAMS_VERSION="${VERSION}" hugo \
+  --minify \
+  --contentDir "${CONTENT_DIR}" \
+  --baseURL "${BASE_URL}${PACKAGE}/${VERSION}/" \
+  --destination "public/${PACKAGE}/${VERSION}"
diff --git a/scripts/generate-root.sh b/scripts/generate-root.sh
new file mode 100755
index 00000000..63f43472
--- /dev/null
+++ b/scripts/generate-root.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+set -euo pipefail
+
+BASE_URL="${1:-/}"
+
+# Render the repo README (from the checked-out tag) as the root landing page.
+# Built only on tag pushes so the root URL tracks the latest release and stays
+# stable between main-branch dev builds.
+CONTENT_DIR="$(mktemp -d)"
+trap 'rm -rf "$CONTENT_DIR"' EXIT
+
+cat > "$CONTENT_DIR/_index.md" <<EOF
+---
+title: "MCP Toolbox Go SDK"
+type: docs
+---
+EOF
+cat README.md >> "$CONTENT_DIR/_index.md"
+
+cd docs-site
+hugo \
+  --minify \
+  --contentDir "${CONTENT_DIR}" \
+  --baseURL "${BASE_URL}" \
+  --destination "public"

From 574ba734d8ca0c8a0be9111b0b2a2dd46b064798 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Mon, 1 Jun 2026 17:40:20 +0530
Subject: [PATCH 03/13] ci(api-docs): restrict deploys to upstream repo, not
 forks

---
 .github/workflows/api-docs.yml | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml
index be6922fd..b6ea63c0 100644
--- a/.github/workflows/api-docs.yml
+++ b/.github/workflows/api-docs.yml
@@ -16,7 +16,7 @@
 name: "API Reference Deployment"
 on:
   push:
-    branches: [ 'main', 'ref-docs' ]
+    branches: [ 'main' ]
     tags: [ '**' ]
   workflow_dispatch:
 
@@ -26,6 +26,8 @@ concurrency:
 
 jobs:
   deploy:
+    # Never run on forks; docs deploy only from the upstream repository.
+    if: github.repository == 'googleapis/mcp-toolbox-sdk-go'
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -67,13 +69,9 @@ jobs:
             *)                      echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=dev"                        >> "$GITHUB_OUTPUT" ;;
           esac
 
-          # Upstream serves from the custom domain; forks fall back to their
-          # GitHub Pages URL so external contributors can preview docsite changes.
-          if [[ "${{ github.repository }}" == "googleapis/mcp-toolbox-sdk-go" ]]; then
-            echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
-          else
-            echo "BASE_URL=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" >> "$GITHUB_ENV"
-          fi
+          # Deploys only run upstream (see job-level guard), so always use the
+          # production domain.
+          echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
 
       - name: Build per-package docs
         if: steps.resolve.outputs.packages != ''

From 1c89f17117717a9952d6cc0358fff6e112a9cbe2 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Mon, 1 Jun 2026 17:45:06 +0530
Subject: [PATCH 04/13] ci(api-docs): drop legacy tag handling, build only
 prefixed tags

---
 .github/workflows/api-docs.yml | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml
index b6ea63c0..72015a1e 100644
--- a/.github/workflows/api-docs.yml
+++ b/.github/workflows/api-docs.yml
@@ -58,15 +58,15 @@ jobs:
         id: resolve
         run: |
           # Route the git ref to the package(s) and version to build.
-          # Per-package tags build one package; bare legacy tags build all three.
+          # A per-package tag builds that one package; pushes to main (and manual
+          # dispatch) build all three as "dev". Any other tag is skipped.
           REF="${GITHUB_REF}"
           case "$REF" in
-            refs/tags/core/v*)      echo "packages=core"                >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/core/}"     >> "$GITHUB_OUTPUT" ;;
-            refs/tags/tbadk/v*)     echo "packages=tbadk"               >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbadk/}"    >> "$GITHUB_OUTPUT" ;;
-            refs/tags/tbgenkit/v*)  echo "packages=tbgenkit"            >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbgenkit/}" >> "$GITHUB_OUTPUT" ;;
-            refs/tags/v[0-9]*)      echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/}"          >> "$GITHUB_OUTPUT" ;;
-            refs/tags/github.com/*) echo "packages="                    >> "$GITHUB_OUTPUT"; echo "version="                          >> "$GITHUB_OUTPUT" ;;
-            *)                      echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=dev"                        >> "$GITHUB_OUTPUT" ;;
+            refs/tags/core/v*)     echo "packages=core"                >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/core/}"     >> "$GITHUB_OUTPUT" ;;
+            refs/tags/tbadk/v*)    echo "packages=tbadk"               >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbadk/}"    >> "$GITHUB_OUTPUT" ;;
+            refs/tags/tbgenkit/v*) echo "packages=tbgenkit"            >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbgenkit/}" >> "$GITHUB_OUTPUT" ;;
+            refs/tags/*)           echo "packages="                    >> "$GITHUB_OUTPUT"; echo "version="                          >> "$GITHUB_OUTPUT" ;;
+            *)                     echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=dev"                        >> "$GITHUB_OUTPUT" ;;
           esac
 
           # Deploys only run upstream (see job-level guard), so always use the
@@ -78,11 +78,6 @@ jobs:
         run: |
           chmod +x scripts/generate-api-docs.sh
           for PKG in ${{ steps.resolve.outputs.packages }}; do
-            # Legacy bare tags predate some packages; skip any absent at this ref.
-            if [[ "${{ steps.resolve.outputs.version }}" != "dev" ]] && [ ! -d "$PKG" ]; then
-              echo "Package $PKG absent at this ref; skipping." >&2
-              continue
-            fi
             ./scripts/generate-api-docs.sh "$PKG" "${{ steps.resolve.outputs.version }}" "$BASE_URL"
           done
 

From 1ac28c9b5853a845bfee14d06bace348a3d67b05 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 13:07:27 +0530
Subject: [PATCH 05/13] docs(api): make each package home its API reference

---
 scripts/generate-api-docs.sh | 25 +++----------------------
 1 file changed, 3 insertions(+), 22 deletions(-)

diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
index 8e064a03..393b8114 100755
--- a/scripts/generate-api-docs.sh
+++ b/scripts/generate-api-docs.sh
@@ -18,40 +18,21 @@ go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
 
 # Per-build content tree in a temp dir, kept out of the checked-in
 # docs-site/content so concurrent package builds never trample each other.
+# The package's API reference is the home page, so /<pkg>/<version>/ lands
+# directly on the docs (the repo README lives only at the site root).
 CONTENT_DIR="$(mktemp -d)"
 trap 'rm -rf "$CONTENT_DIR"' EXIT
-mkdir -p "$CONTENT_DIR/docs"
 
 cat > "$CONTENT_DIR/_index.md" <<EOF
 ---
 title: "MCP Toolbox Go SDK — ${TITLE} (${VERSION})"
 type: docs
 ---
-EOF
-cat README.md >> "$CONTENT_DIR/_index.md"
-
-cat > "$CONTENT_DIR/docs/_index.md" <<EOF
----
-title: "Packages"
-type: docs
-weight: 1
-alwaysopen: true
----
-Public variables, functions, and structs for the ${TITLE} package.
-EOF
-
-MD_FILE="$CONTENT_DIR/docs/${PACKAGE}.md"
-cat > "$MD_FILE" <<EOF
----
-title: "${TITLE}"
-type: docs
-weight: 10
----
 
 Viewing \`${VERSION}\`.
 
 EOF
-gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$MD_FILE"
+gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$CONTENT_DIR/_index.md"
 
 cd docs-site
 HUGO_PARAMS_VERSION="${VERSION}" hugo \

From fa3ce1ac5c501801ec88b65e1e973a283f0458cc Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 15:36:47 +0530
Subject: [PATCH 06/13] docs(api): add per-package version picker to API
 reference

Add a hand-edited version selector to the API reference docs, mirroring
the genai-toolbox pattern adapted to our per-package layout.

- hugo.toml: per-package [params.versions] lists, version_menu label, and
  custom "releases"/"latest" output formats wired into outputs.home
- home.releases.releases: per-package dropdown fragment served at
  /<pkg>/releases.releases
- home.latest.html: per-package latest redirect, hoisted to /<pkg>/latest/
- navbar-version-selector.html: override that runtime-includes the fragment
  via w3.includeHTML, so frozen old version pages show newly-added versions
  without a rebuild
- head-end.html + static/js/w3.js: load the W3.JS include helper
- generate-api-docs.sh: pass HUGO_PARAMS_PACKAGE and hoist the home-scoped
  outputs to the package root where the navbar fetches them
---
 docs-site/hugo.toml                           |  50 ++-
 docs-site/layouts/_default/home.latest.html   |  11 +
 .../layouts/_default/home.releases.releases   |   7 +
 .../layouts/_partials/hooks/head-end.html     |   1 +
 .../_partials/navbar-version-selector.html    |  14 +
 docs-site/static/js/w3.js                     | 405 ++++++++++++++++++
 scripts/generate-api-docs.sh                  |  10 +-
 7 files changed, 487 insertions(+), 11 deletions(-)
 create mode 100644 docs-site/layouts/_default/home.latest.html
 create mode 100644 docs-site/layouts/_default/home.releases.releases
 create mode 100644 docs-site/layouts/_partials/hooks/head-end.html
 create mode 100644 docs-site/layouts/_partials/navbar-version-selector.html
 create mode 100644 docs-site/static/js/w3.js

diff --git a/docs-site/hugo.toml b/docs-site/hugo.toml
index 5e62349b..6a4aa82a 100644
--- a/docs-site/hugo.toml
+++ b/docs-site/hugo.toml
@@ -3,6 +3,32 @@ title = "MCP Toolbox Go API"
 [params]
   offlineSearch = true
   copyright = "2026 Google LLC"
+  version_menu = "Versions"
+  version = "dev"            # overridden per build via HUGO_PARAMS_VERSION
+
+# Hand-edited version lists, one per package. Newest first — the order is
+# mirrored into the dropdown. Add a block before tagging a release, and only
+# list versions whose /<pkg>/<version>/ docs already exist (or will after the
+# backfill run), or the dropdown link 404s.
+[params.versions]
+  [[params.versions.core]]
+    version = "dev"
+    url = "https://go.mcp-toolbox.dev/core/dev/"
+  [[params.versions.core]]
+    version = "v1.0.0"
+    url = "https://go.mcp-toolbox.dev/core/v1.0.0/"
+  [[params.versions.tbadk]]
+    version = "dev"
+    url = "https://go.mcp-toolbox.dev/tbadk/dev/"
+  [[params.versions.tbadk]]
+    version = "v0.8.0"
+    url = "https://go.mcp-toolbox.dev/tbadk/v0.8.0/"
+  [[params.versions.tbgenkit]]
+    version = "dev"
+    url = "https://go.mcp-toolbox.dev/tbgenkit/dev/"
+  [[params.versions.tbgenkit]]
+    version = "v0.7.0"
+    url = "https://go.mcp-toolbox.dev/tbgenkit/v0.7.0/"
 
 [markup.goldmark.renderer]
   unsafe = true
@@ -31,19 +57,23 @@ title = "MCP Toolbox Go API"
   pre = "<i class='fab fa-github'></i>"
 
 [outputFormats]
-  [outputFormats.LLMS]
-    mediaType = "text/plain"
-    baseName = "llms"
-    isPlainText = true
-    root = true
-  [outputFormats.LLMS-FULL]
-    mediaType = "text/plain"
-    baseName = "llms-full"
+  # Dropdown fragment, fetched at runtime by the navbar version selector so
+  # frozen old version pages show newly-added versions without a rebuild.
+  [outputFormats.releases]
+    baseName = "releases"
     isPlainText = true
-    root = true
+    mediaType = "text/releases"
+  # Per-package "latest" redirect, hoisted to /<pkg>/latest/index.html.
+  [outputFormats.latest]
+    baseName = "latest"
+    mediaType = "text/html"
+    isHTML = true
+
+[mediaTypes."text/releases"]
+  suffixes = ["releases"]
 
 [outputs]
-  home = ["HTML", "RSS", "LLMS", "LLMS-FULL", "JSON"]
+  home = ["HTML", "JSON", "releases", "latest"]   # JSON kept for offline search
 
 [module]
   [[module.imports]]
diff --git a/docs-site/layouts/_default/home.latest.html b/docs-site/layouts/_default/home.latest.html
new file mode 100644
index 00000000..8bcec6c9
--- /dev/null
+++ b/docs-site/layouts/_default/home.latest.html
@@ -0,0 +1,11 @@
+{{- $pkg := .Site.Params.package | default "" -}}
+{{- $target := printf "/%s/dev/" $pkg -}}
+{{- with index .Site.Params.versions $pkg }}
+  {{- range . }}{{ if ne .version "dev" }}{{ $target = .url }}{{ break }}{{ end }}{{ end }}
+{{- end -}}
+<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<meta http-equiv="refresh" content="0; url={{ $target }}">
+<link rel="canonical" href="{{ $target }}">
+</head><body><a href="{{ $target }}">Redirecting…</a>
+<script>location.replace('{{ $target }}');</script></body></html>
diff --git a/docs-site/layouts/_default/home.releases.releases b/docs-site/layouts/_default/home.releases.releases
new file mode 100644
index 00000000..d3464f91
--- /dev/null
+++ b/docs-site/layouts/_default/home.releases.releases
@@ -0,0 +1,7 @@
+{{- $pkg := .Site.Params.package | default "" -}}
+<a class="dropdown-item" href="/{{ $pkg }}/latest/">latest</a>
+{{- with index .Site.Params.versions $pkg }}
+  {{- range . }}
+<a class="dropdown-item" href="{{ .url }}">{{ .version }}</a>
+  {{- end }}
+{{- end -}}
diff --git a/docs-site/layouts/_partials/hooks/head-end.html b/docs-site/layouts/_partials/hooks/head-end.html
new file mode 100644
index 00000000..abcb1b96
--- /dev/null
+++ b/docs-site/layouts/_partials/hooks/head-end.html
@@ -0,0 +1 @@
+<script src='{{ "js/w3.js" | relURL }}'></script>
diff --git a/docs-site/layouts/_partials/navbar-version-selector.html b/docs-site/layouts/_partials/navbar-version-selector.html
new file mode 100644
index 00000000..5762bfdd
--- /dev/null
+++ b/docs-site/layouts/_partials/navbar-version-selector.html
@@ -0,0 +1,14 @@
+{{ if .Site.Params.versions -}}
+{{ $pkg := .Site.Params.package | default "" -}}
+<div class="dropdown">
+  <a class="nav-link dropdown-toggle" href="#" role="button"
+     data-bs-toggle="dropdown" aria-expanded="false">
+    {{ .Site.Params.version_menu | default "Versions" }}
+  </a>
+  <div class="dropdown-menu" id="version-dropdown-menu"
+       w3-include-html="/{{ $pkg }}/releases.releases"
+       w3-include-html-default='<a class="dropdown-item" href="/{{ $pkg }}/dev/">dev</a>'>
+  </div>
+  <script>w3.includeHTML();</script>
+</div>
+{{ end -}}
diff --git a/docs-site/static/js/w3.js b/docs-site/static/js/w3.js
new file mode 100644
index 00000000..a510befb
--- /dev/null
+++ b/docs-site/static/js/w3.js
@@ -0,0 +1,405 @@
+/* W3.JS 1.04 April 2019 by w3schools.com */
+"use strict";
+var w3 = {};
+w3.hide = function (sel) {
+  w3.hideElements(w3.getElements(sel));
+};
+w3.hideElements = function (elements) {
+  var i, l = elements.length;
+  for (i = 0; i < l; i++) {
+    w3.hideElement(elements[i]);
+  }
+};
+w3.hideElement = function (element) {
+  w3.styleElement(element, "display", "none");
+};
+w3.show = function (sel, a) {
+  var elements = w3.getElements(sel);
+  if (a) {w3.hideElements(elements);}
+  w3.showElements(elements);
+};
+w3.showElements = function (elements) {
+  var i, l = elements.length;
+  for (i = 0; i < l; i++) {
+    w3.showElement(elements[i]);
+  }
+};
+w3.showElement = function (element) {
+  w3.styleElement(element, "display", "block");
+};
+w3.addStyle = function (sel, prop, val) {
+  w3.styleElements(w3.getElements(sel), prop, val);
+};
+w3.styleElements = function (elements, prop, val) {
+  var i, l = elements.length;
+  for (i = 0; i < l; i++) {
+    w3.styleElement(elements[i], prop, val);
+  }
+};
+w3.styleElement = function (element, prop, val) {
+  element.style.setProperty(prop, val);
+};
+w3.toggleShow = function (sel) {
+  var i, x = w3.getElements(sel), l = x.length;
+  for (i = 0; i < l; i++) {
+    if (x[i].style.display == "none") {
+      w3.styleElement(x[i], "display", "block");
+    } else {
+      w3.styleElement(x[i], "display", "none");
+    }
+  }
+};
+w3.addClass = function (sel, name) {
+  w3.addClassElements(w3.getElements(sel), name);
+};
+w3.addClassElements = function (elements, name) {
+  var i, l = elements.length;
+  for (i = 0; i < l; i++) {
+    w3.addClassElement(elements[i], name);
+  }
+};
+w3.addClassElement = function (element, name) {
+  var i, arr1, arr2;
+  arr1 = element.className.split(" ");
+  arr2 = name.split(" ");
+  for (i = 0; i < arr2.length; i++) {
+    if (arr1.indexOf(arr2[i]) == -1) {element.className += " " + arr2[i];}
+  }
+};
+w3.removeClass = function (sel, name) {
+  w3.removeClassElements(w3.getElements(sel), name);
+};
+w3.removeClassElements = function (elements, name) {
+  var i, l = elements.length, arr1, arr2, j;
+  for (i = 0; i < l; i++) {
+    w3.removeClassElement(elements[i], name);
+  }
+};
+w3.removeClassElement = function (element, name) {
+  var i, arr1, arr2;
+  arr1 = element.className.split(" ");
+  arr2 = name.split(" ");
+  for (i = 0; i < arr2.length; i++) {
+    while (arr1.indexOf(arr2[i]) > -1) {
+      arr1.splice(arr1.indexOf(arr2[i]), 1);
+    }
+  }
+  element.className = arr1.join(" ");
+};
+w3.toggleClass = function (sel, c1, c2) {
+  w3.toggleClassElements(w3.getElements(sel), c1, c2);
+};
+w3.toggleClassElements = function (elements, c1, c2) {
+  var i, l = elements.length;
+  for (i = 0; i < l; i++) {
+    w3.toggleClassElement(elements[i], c1, c2);
+  }
+};
+w3.toggleClassElement = function (element, c1, c2) {
+  var t1, t2, t1Arr, t2Arr, j, arr, allPresent;
+  t1 = (c1 || "");
+  t2 = (c2 || "");
+  t1Arr = t1.split(" ");
+  t2Arr = t2.split(" ");
+  arr = element.className.split(" ");
+  if (t2Arr.length == 0) {
+    allPresent = true;
+    for (j = 0; j < t1Arr.length; j++) {
+      if (arr.indexOf(t1Arr[j]) == -1) {allPresent = false;}
+    }
+    if (allPresent) {
+      w3.removeClassElement(element, t1);
+    } else {
+      w3.addClassElement(element, t1);
+    }
+  } else {
+    allPresent = true;
+    for (j = 0; j < t1Arr.length; j++) {
+      if (arr.indexOf(t1Arr[j]) == -1) {allPresent = false;}
+    }
+    if (allPresent) {
+      w3.removeClassElement(element, t1);
+      w3.addClassElement(element, t2);
+    } else {
+      w3.removeClassElement(element, t2);
+      w3.addClassElement(element, t1);
+    }
+  }
+};
+w3.getElements = function (id) {
+  if (typeof id == "object") {
+    return [id];
+  } else {
+    return document.querySelectorAll(id);
+  }
+};
+w3.filterHTML = function(id, sel, filter) {
+  var a, b, c, i, ii, iii, hit;
+  a = w3.getElements(id);
+  for (i = 0; i < a.length; i++) {
+    b = a[i].querySelectorAll(sel);
+    for (ii = 0; ii < b.length; ii++) {
+      hit = 0;
+      if (b[ii].innerText.toUpperCase().indexOf(filter.toUpperCase()) > -1) {
+        hit = 1;
+      }
+      c = b[ii].getElementsByTagName("*");
+      for (iii = 0; iii < c.length; iii++) {
+        if (c[iii].innerText.toUpperCase().indexOf(filter.toUpperCase()) > -1) {
+          hit = 1;
+        }
+      }
+      if (hit == 1) {
+        b[ii].style.display = "";
+      } else {
+        b[ii].style.display = "none";
+      }
+    }
+  }
+};
+w3.sortHTML = function(id, sel, sortvalue) {
+  var a, b, i, ii, y, bytt, v1, v2, cc, j;
+  a = w3.getElements(id);
+  for (i = 0; i < a.length; i++) {
+    for (j = 0; j < 2; j++) {
+      cc = 0;
+      y = 1;
+      while (y == 1) {
+        y = 0;
+        b = a[i].querySelectorAll(sel);
+        for (ii = 0; ii < (b.length - 1); ii++) {
+          bytt = 0;
+          if (sortvalue) {
+            v1 = b[ii].querySelector(sortvalue).innerText;
+            v2 = b[ii + 1].querySelector(sortvalue).innerText;
+          } else {
+            v1 = b[ii].innerText;
+            v2 = b[ii + 1].innerText;
+          }
+          v1 = v1.toLowerCase();
+          v2 = v2.toLowerCase();
+          if ((j == 0 && (v1 > v2)) || (j == 1 && (v1 < v2))) {
+            bytt = 1;
+            break;
+          }
+        }
+        if (bytt == 1) {
+          b[ii].parentNode.insertBefore(b[ii + 1], b[ii]);
+          y = 1;
+          cc++;
+        }
+      }
+      if (cc > 0) {break;}
+    }
+  }
+};
+w3.slideshow = function (sel, ms, func) {
+  var i, ss, x = w3.getElements(sel), l = x.length;
+  ss = {};
+  ss.current = 1;
+  ss.x = x;
+  ss.ondisplaychange = func;
+  if (!isNaN(ms) || ms == 0) {
+    ss.milliseconds = ms;
+  } else {
+    ss.milliseconds = 1000;
+  }
+  ss.start = function() {
+    ss.display(ss.current)
+    if (ss.ondisplaychange) {ss.ondisplaychange();}
+    if (ss.milliseconds > 0) {
+      window.clearTimeout(ss.timeout);
+      ss.timeout = window.setTimeout(ss.next, ss.milliseconds);
+    }
+  };
+  ss.next = function() {
+    ss.current += 1;
+    if (ss.current > ss.x.length) {ss.current = 1;}
+    ss.start();
+  };
+  ss.previous = function() {
+    ss.current -= 1;
+    if (ss.current < 1) {ss.current = ss.x.length;}
+    ss.start();
+  };
+  ss.display = function (n) {
+    w3.styleElements(ss.x, "display", "none");
+    w3.styleElement(ss.x[n - 1], "display", "block");
+  }
+  ss.start();
+  return ss;
+};
+w3.includeHTML = function(cb) {
+  var z, i, elmnt, file, xhttp;
+  z = document.getElementsByTagName("*");
+  for (i = 0; i < z.length; i++) {
+    elmnt = z[i];
+    file = elmnt.getAttribute("w3-include-html");
+    if (file) {
+      xhttp = new XMLHttpRequest();
+      xhttp.onreadystatechange = function() {
+        if (this.readyState == 4) {
+          if (this.status == 200) {elmnt.innerHTML = this.responseText;}
+          if (this.status == 404) {
+            if (elmnt.getAttribute("w3-include-html-default")) {
+              elmnt.innerHTML = elmnt.getAttribute("w3-include-html-default");
+            }
+            else { elmnt.innerHTML = "Page not found."; }
+          }
+          elmnt.removeAttribute("w3-include-html");
+          w3.includeHTML(cb);
+        }
+      }
+      xhttp.open("GET", file, true);
+      xhttp.send();
+      return;
+    }
+  }
+  if (cb) cb();
+};
+w3.getHttpData = function (file, func) {
+  w3.http(file, function () {
+    if (this.readyState == 4 && this.status == 200) {
+      func(this.responseText);
+    }
+  });
+};
+w3.getHttpObject = function (file, func) {
+  w3.http(file, function () {
+    if (this.readyState == 4 && this.status == 200) {
+      func(JSON.parse(this.responseText));
+    }
+  });
+};
+w3.displayHttp = function (id, file) {
+  w3.http(file, function () {
+    if (this.readyState == 4 && this.status == 200) {
+      w3.displayObject(id, JSON.parse(this.responseText));
+    }
+  });
+};
+w3.http = function (target, readyfunc, xml, method) {
+  var httpObj;
+  if (!method) {method = "GET"; }
+  if (window.XMLHttpRequest) {
+    httpObj = new XMLHttpRequest();
+  } else if (window.ActiveXObject) {
+    httpObj = new ActiveXObject("Microsoft.XMLHTTP");
+  }
+  if (httpObj) {
+    if (readyfunc) {httpObj.onreadystatechange = readyfunc;}
+    httpObj.open(method, target, true);
+    httpObj.send(xml);
+  }
+};
+w3.getElementsByAttribute = function (x, att) {
+  var arr = [], arrCount = -1, i, l, y = x.getElementsByTagName("*"), z = att.toUpperCase();
+  l = y.length;
+  for (i = -1; i < l; i += 1) {
+    if (i == -1) {y[i] = x;}
+    if (y[i].getAttribute(z) !== null) {arrCount += 1; arr[arrCount] = y[i];}
+  }
+  return arr;
+};
+w3.dataObject = {},
+w3.displayObject = function (id, data) {
+  var htmlObj, htmlTemplate, html, arr = [], a, l, rowClone, x, j, i, ii, cc, repeat, repeatObj, repeatX = "";
+  htmlObj = document.getElementById(id);
+  htmlTemplate = init_template(id, htmlObj);
+  html = htmlTemplate.cloneNode(true);
+  arr = w3.getElementsByAttribute(html, "w3-repeat");
+  l = arr.length;
+  for (j = (l - 1); j >= 0; j -= 1) {
+    cc = arr[j].getAttribute("w3-repeat").split(" ");
+    if (cc.length == 1) {
+      repeat = cc[0];
+    } else {
+      repeatX = cc[0];
+      repeat = cc[2];
+    }
+    arr[j].removeAttribute("w3-repeat");
+    repeatObj = data[repeat];
+    if (repeatObj && typeof repeatObj == "object" && repeatObj.length != "undefined") {
+      i = 0;
+      for (x in repeatObj) {
+        i += 1;
+        rowClone = arr[j];
+        rowClone = w3_replace_curly(rowClone, "element", repeatX, repeatObj[x]);
+        a = rowClone.attributes;
+        for (ii = 0; ii < a.length; ii += 1) {
+          a[ii].value = w3_replace_curly(a[ii], "attribute", repeatX, repeatObj[x]).value;
+        }
+        (i === repeatObj.length) ? arr[j].parentNode.replaceChild(rowClone, arr[j]) : arr[j].parentNode.insertBefore(rowClone, arr[j]);
+      }
+    } else {
+      console.log("w3-repeat must be an array. " + repeat + " is not an array.");
+      continue;
+    }
+  }
+  html = w3_replace_curly(html, "element");
+  htmlObj.parentNode.replaceChild(html, htmlObj);
+  function init_template(id, obj) {
+    var template;
+    template = obj.cloneNode(true);
+    if (w3.dataObject.hasOwnProperty(id)) {return w3.dataObject[id];}
+    w3.dataObject[id] = template;
+    return template;
+  }
+  function w3_replace_curly(elmnt, typ, repeatX, x) {
+    var value, rowClone, pos1, pos2, originalHTML, lookFor, lookForARR = [], i, cc, r;
+    rowClone = elmnt.cloneNode(true);
+    pos1 = 0;
+    while (pos1 > -1) {
+      originalHTML = (typ == "attribute") ? rowClone.value : rowClone.innerHTML;
+      pos1 = originalHTML.indexOf("{{", pos1);
+      if (pos1 === -1) {break;}
+      pos2 = originalHTML.indexOf("}}", pos1 + 1);
+      lookFor = originalHTML.substring(pos1 + 2, pos2);
+      lookForARR = lookFor.split("||");
+      value = undefined;
+      for (i = 0; i < lookForARR.length; i += 1) {
+        lookForARR[i] = lookForARR[i].replace(/^\s+|\s+$/gm, ''); //trim
+        if (x) {value = x[lookForARR[i]];}
+        if (value == undefined && data) {value = data[lookForARR[i]];}
+        if (value == undefined) {
+          cc = lookForARR[i].split(".");
+          if (cc[0] == repeatX) {value = x[cc[1]]; }
+        }
+        if (value == undefined) {
+          if (lookForARR[i] == repeatX) {value = x;}
+        }
+        if (value == undefined) {
+          if (lookForARR[i].substr(0, 1) == '"') {
+            value = lookForARR[i].replace(/"/g, "");
+          } else if (lookForARR[i].substr(0,1) == "'") {
+            value = lookForARR[i].replace(/'/g, "");
+          }
+        }
+        if (value != undefined) {break;}
+      }
+      if (value != undefined) {
+        r = "{{" + lookFor + "}}";
+        if (typ == "attribute") {
+          rowClone.value = rowClone.value.replace(r, value);
+        } else {
+          w3_replace_html(rowClone, r, value);
+        }
+      }
+      pos1 = pos1 + 1;
+    }
+    return rowClone;
+  }
+  function w3_replace_html(a, r, result) {
+    var b, l, i, a, x, j;
+    if (a.hasAttributes()) {
+      b = a.attributes;
+      l = b.length;
+      for (i = 0; i < l; i += 1) {
+        if (b[i].value.indexOf(r) > -1) {b[i].value = b[i].value.replace(r, result);}
+      }
+    }
+    x = a.getElementsByTagName("*");
+    l = x.length;
+    a.innerHTML = a.innerHTML.replace(r, result);
+  }
+};
diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
index 393b8114..5a0aa944 100755
--- a/scripts/generate-api-docs.sh
+++ b/scripts/generate-api-docs.sh
@@ -35,8 +35,16 @@ EOF
 gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$CONTENT_DIR/_index.md"
 
 cd docs-site
-HUGO_PARAMS_VERSION="${VERSION}" hugo \
+HUGO_PARAMS_VERSION="${VERSION}" HUGO_PARAMS_PACKAGE="${PACKAGE}" hugo \
   --minify \
   --contentDir "${CONTENT_DIR}" \
   --baseURL "${BASE_URL}${PACKAGE}/${VERSION}/" \
   --destination "public/${PACKAGE}/${VERSION}"
+
+# Hoist the home-scoped outputs from this version's dir up to the package root,
+# where the navbar version selector fetches them. They list every version of the
+# package, so they must live once per package (not per version) and are shared
+# across all of this package's version pages. keep_files on deploy preserves them.
+mv "public/${PACKAGE}/${VERSION}/releases.releases" "public/${PACKAGE}/releases.releases"
+mkdir -p "public/${PACKAGE}/latest"
+mv "public/${PACKAGE}/${VERSION}/latest.html" "public/${PACKAGE}/latest/index.html"

From 95addc726a5e38c12117729aebf4783ee8480e16 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 16:30:45 +0530
Subject: [PATCH 07/13] docs(api): trim version picker to essentials

---
 docs-site/hugo.toml                           |   2 -
 .../_partials/navbar-version-selector.html    |   2 +-
 docs-site/static/js/w3.js                     | 389 +-----------------
 scripts/generate-api-docs.sh                  |   2 +-
 4 files changed, 11 insertions(+), 384 deletions(-)

diff --git a/docs-site/hugo.toml b/docs-site/hugo.toml
index 6a4aa82a..bb4f3b80 100644
--- a/docs-site/hugo.toml
+++ b/docs-site/hugo.toml
@@ -3,8 +3,6 @@ title = "MCP Toolbox Go API"
 [params]
   offlineSearch = true
   copyright = "2026 Google LLC"
-  version_menu = "Versions"
-  version = "dev"            # overridden per build via HUGO_PARAMS_VERSION
 
 # Hand-edited version lists, one per package. Newest first — the order is
 # mirrored into the dropdown. Add a block before tagging a release, and only
diff --git a/docs-site/layouts/_partials/navbar-version-selector.html b/docs-site/layouts/_partials/navbar-version-selector.html
index 5762bfdd..c07357e5 100644
--- a/docs-site/layouts/_partials/navbar-version-selector.html
+++ b/docs-site/layouts/_partials/navbar-version-selector.html
@@ -5,7 +5,7 @@
      data-bs-toggle="dropdown" aria-expanded="false">
     {{ .Site.Params.version_menu | default "Versions" }}
   </a>
-  <div class="dropdown-menu" id="version-dropdown-menu"
+  <div class="dropdown-menu"
        w3-include-html="/{{ $pkg }}/releases.releases"
        w3-include-html-default='<a class="dropdown-item" href="/{{ $pkg }}/dev/">dev</a>'>
   </div>
diff --git a/docs-site/static/js/w3.js b/docs-site/static/js/w3.js
index a510befb..331fe887 100644
--- a/docs-site/static/js/w3.js
+++ b/docs-site/static/js/w3.js
@@ -1,235 +1,9 @@
-/* W3.JS 1.04 April 2019 by w3schools.com */
+/* Trimmed from W3.JS 1.04 (w3schools.com): only w3.includeHTML, plus a
+   w3-include-html-default fallback rendered on a 404. Used by the navbar
+   version selector to fetch /<pkg>/releases.releases at runtime. */
 "use strict";
 var w3 = {};
-w3.hide = function (sel) {
-  w3.hideElements(w3.getElements(sel));
-};
-w3.hideElements = function (elements) {
-  var i, l = elements.length;
-  for (i = 0; i < l; i++) {
-    w3.hideElement(elements[i]);
-  }
-};
-w3.hideElement = function (element) {
-  w3.styleElement(element, "display", "none");
-};
-w3.show = function (sel, a) {
-  var elements = w3.getElements(sel);
-  if (a) {w3.hideElements(elements);}
-  w3.showElements(elements);
-};
-w3.showElements = function (elements) {
-  var i, l = elements.length;
-  for (i = 0; i < l; i++) {
-    w3.showElement(elements[i]);
-  }
-};
-w3.showElement = function (element) {
-  w3.styleElement(element, "display", "block");
-};
-w3.addStyle = function (sel, prop, val) {
-  w3.styleElements(w3.getElements(sel), prop, val);
-};
-w3.styleElements = function (elements, prop, val) {
-  var i, l = elements.length;
-  for (i = 0; i < l; i++) {
-    w3.styleElement(elements[i], prop, val);
-  }
-};
-w3.styleElement = function (element, prop, val) {
-  element.style.setProperty(prop, val);
-};
-w3.toggleShow = function (sel) {
-  var i, x = w3.getElements(sel), l = x.length;
-  for (i = 0; i < l; i++) {
-    if (x[i].style.display == "none") {
-      w3.styleElement(x[i], "display", "block");
-    } else {
-      w3.styleElement(x[i], "display", "none");
-    }
-  }
-};
-w3.addClass = function (sel, name) {
-  w3.addClassElements(w3.getElements(sel), name);
-};
-w3.addClassElements = function (elements, name) {
-  var i, l = elements.length;
-  for (i = 0; i < l; i++) {
-    w3.addClassElement(elements[i], name);
-  }
-};
-w3.addClassElement = function (element, name) {
-  var i, arr1, arr2;
-  arr1 = element.className.split(" ");
-  arr2 = name.split(" ");
-  for (i = 0; i < arr2.length; i++) {
-    if (arr1.indexOf(arr2[i]) == -1) {element.className += " " + arr2[i];}
-  }
-};
-w3.removeClass = function (sel, name) {
-  w3.removeClassElements(w3.getElements(sel), name);
-};
-w3.removeClassElements = function (elements, name) {
-  var i, l = elements.length, arr1, arr2, j;
-  for (i = 0; i < l; i++) {
-    w3.removeClassElement(elements[i], name);
-  }
-};
-w3.removeClassElement = function (element, name) {
-  var i, arr1, arr2;
-  arr1 = element.className.split(" ");
-  arr2 = name.split(" ");
-  for (i = 0; i < arr2.length; i++) {
-    while (arr1.indexOf(arr2[i]) > -1) {
-      arr1.splice(arr1.indexOf(arr2[i]), 1);
-    }
-  }
-  element.className = arr1.join(" ");
-};
-w3.toggleClass = function (sel, c1, c2) {
-  w3.toggleClassElements(w3.getElements(sel), c1, c2);
-};
-w3.toggleClassElements = function (elements, c1, c2) {
-  var i, l = elements.length;
-  for (i = 0; i < l; i++) {
-    w3.toggleClassElement(elements[i], c1, c2);
-  }
-};
-w3.toggleClassElement = function (element, c1, c2) {
-  var t1, t2, t1Arr, t2Arr, j, arr, allPresent;
-  t1 = (c1 || "");
-  t2 = (c2 || "");
-  t1Arr = t1.split(" ");
-  t2Arr = t2.split(" ");
-  arr = element.className.split(" ");
-  if (t2Arr.length == 0) {
-    allPresent = true;
-    for (j = 0; j < t1Arr.length; j++) {
-      if (arr.indexOf(t1Arr[j]) == -1) {allPresent = false;}
-    }
-    if (allPresent) {
-      w3.removeClassElement(element, t1);
-    } else {
-      w3.addClassElement(element, t1);
-    }
-  } else {
-    allPresent = true;
-    for (j = 0; j < t1Arr.length; j++) {
-      if (arr.indexOf(t1Arr[j]) == -1) {allPresent = false;}
-    }
-    if (allPresent) {
-      w3.removeClassElement(element, t1);
-      w3.addClassElement(element, t2);
-    } else {
-      w3.removeClassElement(element, t2);
-      w3.addClassElement(element, t1);
-    }
-  }
-};
-w3.getElements = function (id) {
-  if (typeof id == "object") {
-    return [id];
-  } else {
-    return document.querySelectorAll(id);
-  }
-};
-w3.filterHTML = function(id, sel, filter) {
-  var a, b, c, i, ii, iii, hit;
-  a = w3.getElements(id);
-  for (i = 0; i < a.length; i++) {
-    b = a[i].querySelectorAll(sel);
-    for (ii = 0; ii < b.length; ii++) {
-      hit = 0;
-      if (b[ii].innerText.toUpperCase().indexOf(filter.toUpperCase()) > -1) {
-        hit = 1;
-      }
-      c = b[ii].getElementsByTagName("*");
-      for (iii = 0; iii < c.length; iii++) {
-        if (c[iii].innerText.toUpperCase().indexOf(filter.toUpperCase()) > -1) {
-          hit = 1;
-        }
-      }
-      if (hit == 1) {
-        b[ii].style.display = "";
-      } else {
-        b[ii].style.display = "none";
-      }
-    }
-  }
-};
-w3.sortHTML = function(id, sel, sortvalue) {
-  var a, b, i, ii, y, bytt, v1, v2, cc, j;
-  a = w3.getElements(id);
-  for (i = 0; i < a.length; i++) {
-    for (j = 0; j < 2; j++) {
-      cc = 0;
-      y = 1;
-      while (y == 1) {
-        y = 0;
-        b = a[i].querySelectorAll(sel);
-        for (ii = 0; ii < (b.length - 1); ii++) {
-          bytt = 0;
-          if (sortvalue) {
-            v1 = b[ii].querySelector(sortvalue).innerText;
-            v2 = b[ii + 1].querySelector(sortvalue).innerText;
-          } else {
-            v1 = b[ii].innerText;
-            v2 = b[ii + 1].innerText;
-          }
-          v1 = v1.toLowerCase();
-          v2 = v2.toLowerCase();
-          if ((j == 0 && (v1 > v2)) || (j == 1 && (v1 < v2))) {
-            bytt = 1;
-            break;
-          }
-        }
-        if (bytt == 1) {
-          b[ii].parentNode.insertBefore(b[ii + 1], b[ii]);
-          y = 1;
-          cc++;
-        }
-      }
-      if (cc > 0) {break;}
-    }
-  }
-};
-w3.slideshow = function (sel, ms, func) {
-  var i, ss, x = w3.getElements(sel), l = x.length;
-  ss = {};
-  ss.current = 1;
-  ss.x = x;
-  ss.ondisplaychange = func;
-  if (!isNaN(ms) || ms == 0) {
-    ss.milliseconds = ms;
-  } else {
-    ss.milliseconds = 1000;
-  }
-  ss.start = function() {
-    ss.display(ss.current)
-    if (ss.ondisplaychange) {ss.ondisplaychange();}
-    if (ss.milliseconds > 0) {
-      window.clearTimeout(ss.timeout);
-      ss.timeout = window.setTimeout(ss.next, ss.milliseconds);
-    }
-  };
-  ss.next = function() {
-    ss.current += 1;
-    if (ss.current > ss.x.length) {ss.current = 1;}
-    ss.start();
-  };
-  ss.previous = function() {
-    ss.current -= 1;
-    if (ss.current < 1) {ss.current = ss.x.length;}
-    ss.start();
-  };
-  ss.display = function (n) {
-    w3.styleElements(ss.x, "display", "none");
-    w3.styleElement(ss.x[n - 1], "display", "block");
-  }
-  ss.start();
-  return ss;
-};
-w3.includeHTML = function(cb) {
+w3.includeHTML = function (cb) {
   var z, i, elmnt, file, xhttp;
   z = document.getElementsByTagName("*");
   for (i = 0; i < z.length; i++) {
@@ -237,19 +11,20 @@ w3.includeHTML = function(cb) {
     file = elmnt.getAttribute("w3-include-html");
     if (file) {
       xhttp = new XMLHttpRequest();
-      xhttp.onreadystatechange = function() {
+      xhttp.onreadystatechange = function () {
         if (this.readyState == 4) {
-          if (this.status == 200) {elmnt.innerHTML = this.responseText;}
+          if (this.status == 200) { elmnt.innerHTML = this.responseText; }
           if (this.status == 404) {
             if (elmnt.getAttribute("w3-include-html-default")) {
               elmnt.innerHTML = elmnt.getAttribute("w3-include-html-default");
+            } else {
+              elmnt.innerHTML = "Page not found.";
             }
-            else { elmnt.innerHTML = "Page not found."; }
           }
           elmnt.removeAttribute("w3-include-html");
           w3.includeHTML(cb);
         }
-      }
+      };
       xhttp.open("GET", file, true);
       xhttp.send();
       return;
@@ -257,149 +32,3 @@ w3.includeHTML = function(cb) {
   }
   if (cb) cb();
 };
-w3.getHttpData = function (file, func) {
-  w3.http(file, function () {
-    if (this.readyState == 4 && this.status == 200) {
-      func(this.responseText);
-    }
-  });
-};
-w3.getHttpObject = function (file, func) {
-  w3.http(file, function () {
-    if (this.readyState == 4 && this.status == 200) {
-      func(JSON.parse(this.responseText));
-    }
-  });
-};
-w3.displayHttp = function (id, file) {
-  w3.http(file, function () {
-    if (this.readyState == 4 && this.status == 200) {
-      w3.displayObject(id, JSON.parse(this.responseText));
-    }
-  });
-};
-w3.http = function (target, readyfunc, xml, method) {
-  var httpObj;
-  if (!method) {method = "GET"; }
-  if (window.XMLHttpRequest) {
-    httpObj = new XMLHttpRequest();
-  } else if (window.ActiveXObject) {
-    httpObj = new ActiveXObject("Microsoft.XMLHTTP");
-  }
-  if (httpObj) {
-    if (readyfunc) {httpObj.onreadystatechange = readyfunc;}
-    httpObj.open(method, target, true);
-    httpObj.send(xml);
-  }
-};
-w3.getElementsByAttribute = function (x, att) {
-  var arr = [], arrCount = -1, i, l, y = x.getElementsByTagName("*"), z = att.toUpperCase();
-  l = y.length;
-  for (i = -1; i < l; i += 1) {
-    if (i == -1) {y[i] = x;}
-    if (y[i].getAttribute(z) !== null) {arrCount += 1; arr[arrCount] = y[i];}
-  }
-  return arr;
-};
-w3.dataObject = {},
-w3.displayObject = function (id, data) {
-  var htmlObj, htmlTemplate, html, arr = [], a, l, rowClone, x, j, i, ii, cc, repeat, repeatObj, repeatX = "";
-  htmlObj = document.getElementById(id);
-  htmlTemplate = init_template(id, htmlObj);
-  html = htmlTemplate.cloneNode(true);
-  arr = w3.getElementsByAttribute(html, "w3-repeat");
-  l = arr.length;
-  for (j = (l - 1); j >= 0; j -= 1) {
-    cc = arr[j].getAttribute("w3-repeat").split(" ");
-    if (cc.length == 1) {
-      repeat = cc[0];
-    } else {
-      repeatX = cc[0];
-      repeat = cc[2];
-    }
-    arr[j].removeAttribute("w3-repeat");
-    repeatObj = data[repeat];
-    if (repeatObj && typeof repeatObj == "object" && repeatObj.length != "undefined") {
-      i = 0;
-      for (x in repeatObj) {
-        i += 1;
-        rowClone = arr[j];
-        rowClone = w3_replace_curly(rowClone, "element", repeatX, repeatObj[x]);
-        a = rowClone.attributes;
-        for (ii = 0; ii < a.length; ii += 1) {
-          a[ii].value = w3_replace_curly(a[ii], "attribute", repeatX, repeatObj[x]).value;
-        }
-        (i === repeatObj.length) ? arr[j].parentNode.replaceChild(rowClone, arr[j]) : arr[j].parentNode.insertBefore(rowClone, arr[j]);
-      }
-    } else {
-      console.log("w3-repeat must be an array. " + repeat + " is not an array.");
-      continue;
-    }
-  }
-  html = w3_replace_curly(html, "element");
-  htmlObj.parentNode.replaceChild(html, htmlObj);
-  function init_template(id, obj) {
-    var template;
-    template = obj.cloneNode(true);
-    if (w3.dataObject.hasOwnProperty(id)) {return w3.dataObject[id];}
-    w3.dataObject[id] = template;
-    return template;
-  }
-  function w3_replace_curly(elmnt, typ, repeatX, x) {
-    var value, rowClone, pos1, pos2, originalHTML, lookFor, lookForARR = [], i, cc, r;
-    rowClone = elmnt.cloneNode(true);
-    pos1 = 0;
-    while (pos1 > -1) {
-      originalHTML = (typ == "attribute") ? rowClone.value : rowClone.innerHTML;
-      pos1 = originalHTML.indexOf("{{", pos1);
-      if (pos1 === -1) {break;}
-      pos2 = originalHTML.indexOf("}}", pos1 + 1);
-      lookFor = originalHTML.substring(pos1 + 2, pos2);
-      lookForARR = lookFor.split("||");
-      value = undefined;
-      for (i = 0; i < lookForARR.length; i += 1) {
-        lookForARR[i] = lookForARR[i].replace(/^\s+|\s+$/gm, ''); //trim
-        if (x) {value = x[lookForARR[i]];}
-        if (value == undefined && data) {value = data[lookForARR[i]];}
-        if (value == undefined) {
-          cc = lookForARR[i].split(".");
-          if (cc[0] == repeatX) {value = x[cc[1]]; }
-        }
-        if (value == undefined) {
-          if (lookForARR[i] == repeatX) {value = x;}
-        }
-        if (value == undefined) {
-          if (lookForARR[i].substr(0, 1) == '"') {
-            value = lookForARR[i].replace(/"/g, "");
-          } else if (lookForARR[i].substr(0,1) == "'") {
-            value = lookForARR[i].replace(/'/g, "");
-          }
-        }
-        if (value != undefined) {break;}
-      }
-      if (value != undefined) {
-        r = "{{" + lookFor + "}}";
-        if (typ == "attribute") {
-          rowClone.value = rowClone.value.replace(r, value);
-        } else {
-          w3_replace_html(rowClone, r, value);
-        }
-      }
-      pos1 = pos1 + 1;
-    }
-    return rowClone;
-  }
-  function w3_replace_html(a, r, result) {
-    var b, l, i, a, x, j;
-    if (a.hasAttributes()) {
-      b = a.attributes;
-      l = b.length;
-      for (i = 0; i < l; i += 1) {
-        if (b[i].value.indexOf(r) > -1) {b[i].value = b[i].value.replace(r, result);}
-      }
-    }
-    x = a.getElementsByTagName("*");
-    l = x.length;
-    a.innerHTML = a.innerHTML.replace(r, result);
-  }
-};
diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
index 5a0aa944..22ab58a5 100755
--- a/scripts/generate-api-docs.sh
+++ b/scripts/generate-api-docs.sh
@@ -35,7 +35,7 @@ EOF
 gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$CONTENT_DIR/_index.md"
 
 cd docs-site
-HUGO_PARAMS_VERSION="${VERSION}" HUGO_PARAMS_PACKAGE="${PACKAGE}" hugo \
+HUGO_PARAMS_PACKAGE="${PACKAGE}" hugo \
   --minify \
   --contentDir "${CONTENT_DIR}" \
   --baseURL "${BASE_URL}${PACKAGE}/${VERSION}/" \

From b3e6f07d04af31068599f506fc91e52a42397b0a Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 16:45:35 +0530
Subject: [PATCH 08/13] docs(api): show current version in picker toggle, drop
 Viewing line

---
 docs-site/layouts/_partials/navbar-version-selector.html | 2 +-
 scripts/generate-api-docs.sh                             | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs-site/layouts/_partials/navbar-version-selector.html b/docs-site/layouts/_partials/navbar-version-selector.html
index c07357e5..430ba20b 100644
--- a/docs-site/layouts/_partials/navbar-version-selector.html
+++ b/docs-site/layouts/_partials/navbar-version-selector.html
@@ -3,7 +3,7 @@
 <div class="dropdown">
   <a class="nav-link dropdown-toggle" href="#" role="button"
      data-bs-toggle="dropdown" aria-expanded="false">
-    {{ .Site.Params.version_menu | default "Versions" }}
+    {{ .Site.Params.version | default "Versions" }}
   </a>
   <div class="dropdown-menu"
        w3-include-html="/{{ $pkg }}/releases.releases"
diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
index 22ab58a5..7d038129 100755
--- a/scripts/generate-api-docs.sh
+++ b/scripts/generate-api-docs.sh
@@ -29,13 +29,11 @@ title: "MCP Toolbox Go SDK — ${TITLE} (${VERSION})"
 type: docs
 ---
 
-Viewing \`${VERSION}\`.
-
 EOF
 gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$CONTENT_DIR/_index.md"
 
 cd docs-site
-HUGO_PARAMS_PACKAGE="${PACKAGE}" hugo \
+HUGO_PARAMS_VERSION="${VERSION}" HUGO_PARAMS_PACKAGE="${PACKAGE}" hugo \
   --minify \
   --contentDir "${CONTENT_DIR}" \
   --baseURL "${BASE_URL}${PACKAGE}/${VERSION}/" \

From 7b80d4d60097300d13bf1ff41ce35a893498db92 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 17:17:58 +0530
Subject: [PATCH 09/13] ci(api-docs): add on-demand backfill workflow for
 historical versions

---
 .github/workflows/api-docs-backfill.yml | 114 ++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 .github/workflows/api-docs-backfill.yml

diff --git a/.github/workflows/api-docs-backfill.yml b/.github/workflows/api-docs-backfill.yml
new file mode 100644
index 00000000..3a17ea27
--- /dev/null
+++ b/.github/workflows/api-docs-backfill.yml
@@ -0,0 +1,114 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+name: "API Reference Backfill"
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: "Package to backfill ('all' = every listed stable version)"
+        type: choice
+        options: [all, core, tbadk, tbgenkit]
+        default: all
+      version:
+        description: "Version tag suffix, e.g. v1.0.0 (required unless package is 'all')"
+        type: string
+        default: ""
+
+concurrency:
+  group: api-docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  backfill:
+    # Never run on forks; docs deploy only from the upstream repository.
+    if: github.repository == 'googleapis/mcp-toolbox-sdk-go'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version: '1.25.0'
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
+        with:
+          hugo-version: '0.152.2'
+          extended: true
+
+      - name: Install PostCSS Dependencies
+        run: |
+          cd docs-site
+          npm install postcss postcss-cli autoprefixer
+
+      - name: Resolve backfill targets
+        id: resolve
+        run: |
+          PKG="${{ inputs.package }}"
+          VER="${{ inputs.version }}"
+          if [ "$PKG" = "all" ]; then
+            # Default: every currently-listed stable version.
+            {
+              echo "targets<<EOF"
+              echo "core v1.0.0"
+              echo "tbadk v0.8.0"
+              echo "tbgenkit v0.7.0"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+          else
+            # Single-version mode: version required, and the tag must exist.
+            if [ -z "$VER" ]; then
+              echo "::error::version is required when package is not 'all'" >&2
+              exit 1
+            fi
+            if ! git rev-parse -q --verify "refs/tags/$PKG/$VER" >/dev/null; then
+              echo "::error::tag $PKG/$VER not found" >&2
+              exit 1
+            fi
+            echo "targets=$PKG $VER" >> "$GITHUB_OUTPUT"
+          fi
+
+          # Deploys only run upstream (see job-level guard), so always use the
+          # production domain.
+          echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
+
+      - name: Build historical docs
+        run: |
+          # Build each target from main's layout (so old pages carry the current
+          # version picker), overlaying only the package's source from its tag so
+          # gomarkdoc documents that version's API.
+          chmod +x scripts/generate-api-docs.sh
+          echo "${{ steps.resolve.outputs.targets }}" | while read -r PKG VER; do
+            [ -z "$PKG" ] && continue
+            git checkout "$PKG/$VER" -- "$PKG"
+            ./scripts/generate-api-docs.sh "$PKG" "$VER" "$BASE_URL"
+            git checkout HEAD -- "$PKG"
+          done
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs-site/public
+          keep_files: true
+          cname: ${{ github.repository == 'googleapis/mcp-toolbox-sdk-go' && 'go.mcp-toolbox.dev' || '' }}

From 2e19a61eef4c94aef734a10ce905107b8cc8e605 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 18:40:32 +0530
Subject: [PATCH 10/13] ci(api-docs): backfill all listed versions; fix
 per-package source restore

---
 .github/workflows/api-docs-backfill.yml | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/api-docs-backfill.yml b/.github/workflows/api-docs-backfill.yml
index 3a17ea27..9fa83909 100644
--- a/.github/workflows/api-docs-backfill.yml
+++ b/.github/workflows/api-docs-backfill.yml
@@ -67,12 +67,19 @@ jobs:
           PKG="${{ inputs.package }}"
           VER="${{ inputs.version }}"
           if [ "$PKG" = "all" ]; then
-            # Default: every currently-listed stable version.
+            # Default: every currently-listed stable version (mirror hugo.toml,
+            # excluding dev which the normal workflow rebuilds on every push).
             {
               echo "targets<<EOF"
               echo "core v1.0.0"
+              echo "core v0.7.0"
+              echo "core v0.6.2"
               echo "tbadk v0.8.0"
+              echo "tbadk v0.7.0"
+              echo "tbadk v0.6.0"
+              echo "tbgenkit v0.8.0"
               echo "tbgenkit v0.7.0"
+              echo "tbgenkit v0.6.0"
               echo "EOF"
             } >> "$GITHUB_OUTPUT"
           else
@@ -93,17 +100,24 @@ jobs:
           echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
 
       - name: Build historical docs
+        env:
+          TARGETS: ${{ steps.resolve.outputs.targets }}
         run: |
           # Build each target from main's layout (so old pages carry the current
           # version picker), overlaying only the package's source from its tag so
           # gomarkdoc documents that version's API.
           chmod +x scripts/generate-api-docs.sh
-          echo "${{ steps.resolve.outputs.targets }}" | while read -r PKG VER; do
+          while read -r PKG VER; do
             [ -z "$PKG" ] && continue
             git checkout "$PKG/$VER" -- "$PKG"
             ./scripts/generate-api-docs.sh "$PKG" "$VER" "$BASE_URL"
+            # Restore the package tree to HEAD *exactly* before the next build:
+            # checkout alone re-adds HEAD's files but leaves files the tag had and
+            # HEAD lacks, so also unstage and clean them out.
             git checkout HEAD -- "$PKG"
-          done
+            git reset -q -- "$PKG"
+            git clean -fdq -- "$PKG"
+          done <<< "$TARGETS"
 
       - name: Deploy to gh-pages
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4

From ecb63ae231d021822c3fe450b9cc5830eefee95d Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 19:19:25 +0530
Subject: [PATCH 11/13] ci(api-docs): build one version per backfill run via
 tag overlay

---
 .github/workflows/api-docs-backfill.yml | 90 +++++++++----------------
 1 file changed, 30 insertions(+), 60 deletions(-)

diff --git a/.github/workflows/api-docs-backfill.yml b/.github/workflows/api-docs-backfill.yml
index 9fa83909..cdc1fac8 100644
--- a/.github/workflows/api-docs-backfill.yml
+++ b/.github/workflows/api-docs-backfill.yml
@@ -18,14 +18,14 @@ on:
   workflow_dispatch:
     inputs:
       package:
-        description: "Package to backfill ('all' = every listed stable version)"
+        description: "Package to backfill"
         type: choice
-        options: [all, core, tbadk, tbgenkit]
-        default: all
+        options: [core, tbadk, tbgenkit]
+        required: true
       version:
-        description: "Version tag suffix, e.g. v1.0.0 (required unless package is 'all')"
+        description: "Version tag to build, e.g. v1.0.0"
         type: string
-        default: ""
+        required: true
 
 concurrency:
   group: api-docs-deploy
@@ -39,11 +39,28 @@ jobs:
     permissions:
       contents: write
     steps:
-      - name: Checkout Code
+      # Build from main so the archived page carries the current version picker;
+      # only the package's source comes from the tag (overlaid below) so
+      # gomarkdoc documents that version's API.
+      - name: Checkout main (current layout + scripts)
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
+          ref: main
           submodules: recursive
-          fetch-depth: 0
+
+      - name: Checkout tagged package source
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: refs/tags/${{ inputs.package }}/${{ inputs.version }}
+          path: tagged_src
+          sparse-checkout: ${{ inputs.package }}
+
+      - name: Overlay tagged source onto main
+        env:
+          PKG: ${{ inputs.package }}
+        run: |
+          rm -rf "$PKG"
+          mv "tagged_src/$PKG" "$PKG"
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
@@ -61,63 +78,16 @@ jobs:
           cd docs-site
           npm install postcss postcss-cli autoprefixer
 
-      - name: Resolve backfill targets
-        id: resolve
-        run: |
-          PKG="${{ inputs.package }}"
-          VER="${{ inputs.version }}"
-          if [ "$PKG" = "all" ]; then
-            # Default: every currently-listed stable version (mirror hugo.toml,
-            # excluding dev which the normal workflow rebuilds on every push).
-            {
-              echo "targets<<EOF"
-              echo "core v1.0.0"
-              echo "core v0.7.0"
-              echo "core v0.6.2"
-              echo "tbadk v0.8.0"
-              echo "tbadk v0.7.0"
-              echo "tbadk v0.6.0"
-              echo "tbgenkit v0.8.0"
-              echo "tbgenkit v0.7.0"
-              echo "tbgenkit v0.6.0"
-              echo "EOF"
-            } >> "$GITHUB_OUTPUT"
-          else
-            # Single-version mode: version required, and the tag must exist.
-            if [ -z "$VER" ]; then
-              echo "::error::version is required when package is not 'all'" >&2
-              exit 1
-            fi
-            if ! git rev-parse -q --verify "refs/tags/$PKG/$VER" >/dev/null; then
-              echo "::error::tag $PKG/$VER not found" >&2
-              exit 1
-            fi
-            echo "targets=$PKG $VER" >> "$GITHUB_OUTPUT"
-          fi
-
+      - name: Build docs
+        env:
+          PKG: ${{ inputs.package }}
+          VER: ${{ inputs.version }}
           # Deploys only run upstream (see job-level guard), so always use the
           # production domain.
-          echo "BASE_URL=https://go.mcp-toolbox.dev/" >> "$GITHUB_ENV"
-
-      - name: Build historical docs
-        env:
-          TARGETS: ${{ steps.resolve.outputs.targets }}
+          BASE_URL: https://go.mcp-toolbox.dev/
         run: |
-          # Build each target from main's layout (so old pages carry the current
-          # version picker), overlaying only the package's source from its tag so
-          # gomarkdoc documents that version's API.
           chmod +x scripts/generate-api-docs.sh
-          while read -r PKG VER; do
-            [ -z "$PKG" ] && continue
-            git checkout "$PKG/$VER" -- "$PKG"
-            ./scripts/generate-api-docs.sh "$PKG" "$VER" "$BASE_URL"
-            # Restore the package tree to HEAD *exactly* before the next build:
-            # checkout alone re-adds HEAD's files but leaves files the tag had and
-            # HEAD lacks, so also unstage and clean them out.
-            git checkout HEAD -- "$PKG"
-            git reset -q -- "$PKG"
-            git clean -fdq -- "$PKG"
-          done <<< "$TARGETS"
+          ./scripts/generate-api-docs.sh "$PKG" "$VER" "$BASE_URL"
 
       - name: Deploy to gh-pages
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4

From dbeea2ebb9b07d56de55d73fa89662abd0bf9722 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 19:35:35 +0530
Subject: [PATCH 12/13] docs: document API reference docs workflow in
 DEVELOPER.md

---
 DEVELOPER.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/DEVELOPER.md b/DEVELOPER.md
index 7aa24306..3a243fdb 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -85,6 +85,71 @@ Releases are managed by **Release Please**.
 *   Each module (`core`, `tbadk`, `tbgenkit`) is released independently.
 *   Tags will be in the format `module/vX.Y.Z` (e.g., `core/v0.6.0`).
 
+## API Reference Documentation
+
+The API reference is published to [go.mcp-toolbox.dev](https://go.mcp-toolbox.dev).
+It is generated with [`gomarkdoc`](https://github.com/princjef/gomarkdoc) and
+rendered by [Hugo](https://gohugo.io/) + [Docsy](https://www.docsy.dev/) from the
+`docs-site/` directory. Docs are built **per package, per version** and served at
+`/<package>/<version>/` (e.g. `/core/v1.0.0/`), with a `/<package>/latest/`
+redirect to the newest release.
+
+### Layout
+
+| Path | Purpose |
+| --- | --- |
+| `scripts/generate-api-docs.sh <pkg> <version> <base_url>` | Builds one package/version into `docs-site/public/<pkg>/<version>/`. |
+| `scripts/generate-root.sh <base_url>` | Renders the repo `README.md` as the site root landing page (built on tag pushes). |
+| `docs-site/hugo.toml` | Site config and the hand-edited per-package version lists that drive the version picker. |
+| `docs-site/layouts/_partials/navbar-version-selector.html` | The navbar version-picker dropdown. |
+| `docs-site/layouts/_default/home.releases.releases` | Renders each package's version list into a fragment fetched at runtime by the picker. |
+| `docs-site/layouts/_default/home.latest.html` | The per-package `latest` redirect. |
+| `docs-site/static/js/w3.js` | Trimmed `w3.includeHTML` helper used to pull the version fragment into frozen pages. |
+
+### Workflows
+
+Two GitHub Actions workflows deploy to the `gh-pages` branch. Both run only on
+the upstream repository and share the `api-docs-deploy` concurrency group so they
+never race a deploy.
+
+*   **`api-docs.yml` (API Reference Deployment)** — the automatic flow:
+    *   Push to `main` (or manual dispatch) → builds all three packages as `dev`.
+    *   Push of a per-package tag `<pkg>/vX.Y.Z` → builds that one version **and**
+        rebuilds the root README landing page.
+    *   Other tags are skipped.
+*   **`api-docs-backfill.yml` (API Reference Backfill)** — on-demand, builds **one
+    historical version per run**. It checks out `main` for the current site layout
+    and overlays only the tagged package's source, so older versions are
+    documented with today's version picker. Trigger it from the Actions tab or:
+    ```bash
+    gh workflow run api-docs-backfill.yml -f package=core -f version=v1.0.0
+    ```
+
+### Adding a version to the picker
+
+The dropdown is driven entirely by the `[[params.versions.<pkg>]]` blocks in
+`docs-site/hugo.toml` (newest first). A listed link only resolves once that
+version's docs are deployed:
+
+1.  For a **new release**, add a block for the version, then tag it — `api-docs.yml`
+    builds and deploys it automatically.
+2.  For a **historical version** (tagged before the docs existed), add the block,
+    then run the backfill workflow once for that `<pkg>/<version>`.
+
+### Building locally
+
+```bash
+# Build a single package/version (base URL must end in a slash).
+./scripts/generate-api-docs.sh core dev http://localhost:8080/
+
+# Serve the output.
+(cd docs-site/public && python3 -m http.server 8080)
+# → http://localhost:8080/core/dev/
+```
+
+CI uses Hugo `0.152.2` (extended); match that locally to avoid Docsy build
+differences.
+
 ## Further Information
 
 *   If you encounter issues, please open an [issue](https://github.com/googleapis/mcp-toolbox-sdk-go/issues).
\ No newline at end of file

From d82686ba8df6692c3d333ccf0f42d2be71294fdd Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 19:48:52 +0530
Subject: [PATCH 13/13] docs: refine API reference docs workflow section in
 DEVELOPER.md

---
 DEVELOPER.md | 65 ++++++++++++++++++++++------------------------------
 1 file changed, 27 insertions(+), 38 deletions(-)

diff --git a/DEVELOPER.md b/DEVELOPER.md
index 3a243fdb..e67fba52 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -84,6 +84,9 @@ This project uses `golangci-lint`.
 Releases are managed by **Release Please**.
 *   Each module (`core`, `tbadk`, `tbgenkit`) is released independently.
 *   Tags will be in the format `module/vX.Y.Z` (e.g., `core/v0.6.0`).
+*   Before releasing, add a `[[params.versions.<pkg>]]` block for the new version to
+    `docs-site/hugo.toml` so it appears in the API reference version picker. See
+    [Adding a version to the picker](#adding-a-version-to-the-picker).
 
 ## API Reference Documentation
 
@@ -94,47 +97,36 @@ rendered by [Hugo](https://gohugo.io/) + [Docsy](https://www.docsy.dev/) from th
 `/<package>/<version>/` (e.g. `/core/v1.0.0/`), with a `/<package>/latest/`
 redirect to the newest release.
 
-### Layout
-
-| Path | Purpose |
-| --- | --- |
-| `scripts/generate-api-docs.sh <pkg> <version> <base_url>` | Builds one package/version into `docs-site/public/<pkg>/<version>/`. |
-| `scripts/generate-root.sh <base_url>` | Renders the repo `README.md` as the site root landing page (built on tag pushes). |
-| `docs-site/hugo.toml` | Site config and the hand-edited per-package version lists that drive the version picker. |
-| `docs-site/layouts/_partials/navbar-version-selector.html` | The navbar version-picker dropdown. |
-| `docs-site/layouts/_default/home.releases.releases` | Renders each package's version list into a fragment fetched at runtime by the picker. |
-| `docs-site/layouts/_default/home.latest.html` | The per-package `latest` redirect. |
-| `docs-site/static/js/w3.js` | Trimmed `w3.includeHTML` helper used to pull the version fragment into frozen pages. |
-
 ### Workflows
 
-Two GitHub Actions workflows deploy to the `gh-pages` branch. Both run only on
-the upstream repository and share the `api-docs-deploy` concurrency group so they
-never race a deploy.
-
-*   **`api-docs.yml` (API Reference Deployment)** — the automatic flow:
-    *   Push to `main` (or manual dispatch) → builds all three packages as `dev`.
-    *   Push of a per-package tag `<pkg>/vX.Y.Z` → builds that one version **and**
-        rebuilds the root README landing page.
-    *   Other tags are skipped.
-*   **`api-docs-backfill.yml` (API Reference Backfill)** — on-demand, builds **one
-    historical version per run**. It checks out `main` for the current site layout
-    and overlays only the tagged package's source, so older versions are
-    documented with today's version picker. Trigger it from the Actions tab or:
-    ```bash
-    gh workflow run api-docs-backfill.yml -f package=core -f version=v1.0.0
-    ```
+The `api-docs.yml` workflow deploys to the `gh-pages` branch. It runs only on
+the upstream repository and uses the `api-docs-deploy` concurrency group, so it
+never races another deploy.
+
+The automatic flow is as follows:
+*   Push to `main` (or manual dispatch) → builds all three packages as `dev`.
+*   Push of a per-package tag `<pkg>/vX.Y.Z` → builds that one version **and**
+    rebuilds the root README landing page.
+*   Other tags are skipped.
 
 ### Adding a version to the picker
 
-The dropdown is driven entirely by the `[[params.versions.<pkg>]]` blocks in
-`docs-site/hugo.toml` (newest first). A listed link only resolves once that
-version's docs are deployed:
+Before each **new release**, add a `[[params.versions.<pkg>]]` block for the version
+to `docs-site/hugo.toml` (newest first). On a successful release, the tag is created
+automatically and triggers the `api-docs.yml` workflow, which builds and deploys
+that version.
+
+### Backfilling old docs
 
-1.  For a **new release**, add a block for the version, then tag it — `api-docs.yml`
-    builds and deploys it automatically.
-2.  For a **historical version** (tagged before the docs existed), add the block,
-    then run the backfill workflow once for that `<pkg>/<version>`.
+The **`api-docs-backfill.yml`** (API Reference Backfill) workflow runs on demand and
+builds **one historical version per run**. Use it to build any version whose docs
+are missing or whose deployment failed.
+
+Trigger it from the Actions tab, or with:
+
+```bash
+gh workflow run api-docs-backfill.yml -f package=core -f version=v1.0.0
+```
 
 ### Building locally
 
@@ -147,9 +139,6 @@ version's docs are deployed:
 # → http://localhost:8080/core/dev/
 ```
 
-CI uses Hugo `0.152.2` (extended); match that locally to avoid Docsy build
-differences.
-
 ## Further Information
 
 *   If you encounter issues, please open an [issue](https://github.com/googleapis/mcp-toolbox-sdk-go/issues).
\ No newline at end of file