docs: Add prebuilt configs under integrations and add migration banner (#2857)

## Description

This PR :
- Splits the complete list of prebuilt configs adds the config specific
each source under the `integrations/` section.
- A shortcode has been added to link these files in the
`documentation/configuration/prebuilt-configs/_index.md`
- Adds migration banner to redirect users to new url
- Adds documentation for contributors on file structure for both samples
and prebuilt configs

## PR Checklist

> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [x] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [x] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)
- [x] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

Author: 3 people

.hugo/hugo.toml

@@ -37,7 +37,6 @@ ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quick
   github_subdir = "docs"
   offlineSearch = false
   version_menu = "Releases"
-  disableMigrationBanner = true
   releases_url = "/genai-toolbox/releases.releases"
   global_logo_url = "/genai-toolbox/"
   version = "dev"

.hugo/layouts/shortcodes/list-prebuilt-configs.html

@@ -0,0 +1,100 @@
+{{ $integrations := site.GetPage "section" "integrations" }}
+
+<div class="db-index-list">
+  {{/*Loop through all database folders alphabetically */}}
+  {{ range $integrations.Pages.ByTitle }}
+    {{ $db := . }}
+    {{/* Only render a row if this database has a 'prebuilt-configs' folder */}}
+    {{ with $db.GetPage "prebuilt-configs" }}
+      {{ $displayTitle := $db.Title }}
+      {{ $targetLink := .RelPermalink }}
+      {{ $displayDesc := .Description | default (printf "Explore prebuilt configurations for %s." $db.Title) }}
+
+      <a href="{{ $targetLink }}" class="db-index-row">
+        <div class="db-index-content">
+          <div class="db-index-header">
+            <span class="db-index-title">{{ $displayTitle }}</span>
+            <svg class="db-index-arrow" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <line x1="5" y1="12" x2="19" y2="12"></line>
+              <polyline points="12 5 19 12 12 19"></polyline>
+            </svg>
+          </div>
+          <div class="db-index-desc">{{ $displayDesc | plainify | truncate 120 }}</div>
+        </div>
+      </a>
+    {{ end }}
+  {{ end }}
+</div>
+
+<style>
+  .db-index-list {
+    display: flex;
+    flex-direction: column;
+    margin-top: 2rem;
+    margin-bottom: 3rem;
+    border-top: 1px solid rgba(0, 0, 0, 0.08);
+  }
+
+  .db-index-row {
+    padding: 1.25rem 0;
+    border-bottom: 1px solid rgba(0, 0, 0, 0.08);
+    text-decoration: none !important;
+    display: block;
+    background: transparent;
+    transition: all 0.2s ease;
+  }
+
+  .db-index-row:hover .db-index-title {
+    color: #4484f4;
+  }
+
+  .db-index-row:hover .db-index-arrow {
+    opacity: 1;
+    transform: translateX(0);
+    color: #4484f4;
+  }
+
+  .db-index-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 0.3rem;
+  }
+
+  .db-index-title {
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: #202124;
+    transition: color 0.2s ease;
+  }
+
+  .db-index-arrow {
+    opacity: 0;
+    transform: translateX(-10px);
+    color: #5f6368;
+    transition: all 0.25s cubic-bezier(0.25, 0.8, 0.25, 1);
+  }
+
+  .db-index-desc {
+    font-size: 0.95rem;
+    color: #5f6368;
+    line-height: 1.5;
+    padding-right: 2rem;
+  }
+
+  /* Dark Mode Adjustments */
+  html[data-bs-theme="dark"] .db-index-list,
+  body.dark .db-index-list { border-top-color: rgba(255, 255, 255, 0.1); }
+
+  html[data-bs-theme="dark"] .db-index-row,
+  body.dark .db-index-row { border-bottom-color: rgba(255, 255, 255, 0.1); }
+
+  html[data-bs-theme="dark"] .db-index-title,
+  body.dark .db-index-title { color: #e8eaed; }
+
+  html[data-bs-theme="dark"] .db-index-desc,
+  body.dark .db-index-desc { color: #9aa0a6; }
+
+  html[data-bs-theme="dark"] .db-index-row:hover .db-index-title,
+  html[data-bs-theme="dark"] .db-index-row:hover .db-index-arrow { color: #8ab4f8; }
+</style>

DEVELOPER.md

@@ -267,11 +267,13 @@ When updating documentation, you must adhere to the structural constraints enfor
   * If a new database inherits tools from a base integration (like Cloud SQL inheriting Postgres tools), create the `tools/` directory with an `_index.md` file.
   * Map the inherited tools dynamically by adding the `shared_tools` YAML array to the frontmatter of this `tools/_index.md` file. **This file must strictly contain only frontmatter.**
 * **Adding Samples:**
-  * Samples are distributed across the site and aggregated visually via the "Samples Hub". Place your sample based on its scope:
-    1. **Quickstarts:** Place in `docs/en/documentation/getting-started/quickstart/`.
-    2. **Database-Specific samples:** Place in `docs/en/integrations/<newdb>/samples/`. Make sure to include a `samples/_index.md` wrapper that contains **only frontmatter**.
-    3. **General/Cross- samples:** Place directly in `docs/en/samples/`.
-  * Ensure appropriate **frontmatter tags (`sample_filters`, `is_sample`)** are added so the UI Gallery filters can index them.
+  * **Physical Location:**
+    1. **Quickstarts:** `docs/en/documentation/getting-started/quickstart/`.
+    2. **Integration-Specific:** `docs/en/integrations/<db>/samples/`. Must include an `_index.md` with strictly only frontmatter.
+    3. **General:** `docs/en/samples/`.
+  * **Frontmatter Requirements (Maintenance):** To ensure samples appear correctly in the Samples Section, you must provide the following tags:
+    * `is_sample: true` - Required for indexing.
+    * `sample_filters:` - A YAML array used for UI filtering (e.g., `[postgres, go, sql]`).
 * **Adding Top-Level Sections:** If you add a completely new top-level documentation directory (e.g., a new section alongside `integrations`, `documentation`), you **must** update the AI documentation layout files located at `.hugo/layouts/index.llms.txt` and `.hugo/layouts/index.llms-full.txt`. Specifically, update the "Diátaxis Narrative Framework" preamble so AI models understand the purpose of your new section.
 
 #### Adding Prebuilt Tools
@@ -498,6 +500,14 @@ When adding or updating a Tool page, your markdown file must strictly adhere to
       * **Allowed Optional Headings:** `Compatible Sources`, `Requirements`, `Parameters`, `Output Format`, `Reference`, `Advanced Usage`, `Troubleshooting`, `Additional Resources`
   * **Compatible Sources Shortcode:** If you include the `## Compatible Sources` heading, you must place the compatible-sources shortcode (e.g., `{{< compatible-sources >}}`) directly beneath it.
 
+#### Prebuilt Configuration Structure (`integrations/**/prebuilt-configs/*.md`)
+
+To ensure new prebuilt configurations are automatically indexed by the `{{< list-prebuilt-configs >}}` shortcode on the main Prebuilt Configs page, follow these rules:
+
+* **Location:** Always place documentation for prebuilt configurations in a nested directory named `prebuilt-configs/` inside the database folder (e.g., `docs/en/integrations/alloydb/prebuilt-configs/`).
+* **Index Wrapper:** Every `prebuilt-configs/` directory must contain an `_index.md` file. This file acts as the anchor for the directory and must contain the `title` and `description` used in the automated lists.
+* **Architecture-Based Mapping:** Map configurations to database folders based on the `kind` defined in the tool's YAML file (in `internal/prebuiltconfigs/tools/`). For example, any tool using the `postgres` kind should live in the `postgres/` integration directory.
+
 #### Frontend Assets & Layouts
 
 If you need to modify the visual appearance, navigation, or behavior of the documentation website itself, all frontend assets are isolated within the `.hugo/` directory.

GEMINI.md

@@ -161,11 +161,25 @@ When generating or editing documentation for this repository, you must strictly
 5.  **Shortcode Placement:** If you generate the `## Compatible Sources` section, you must include the `{{< compatible-sources >}}` shortcode beneath it.
 
 ##### Samples Architecture Constraints
-Sample code is aggregated visually in the UI via the Samples section, but the physical markdown files are distributed logically based on their scope. When adding samples, use the correct location and apply proper frontmatter tags (`sample_filters`, `is_sample`) are added so the UI Gallery filters can index them.for the gallery filtering:
+Sample code is aggregated visually in the UI via the Samples section, but the physical markdown files are distributed logically based on their scope.
 1.  **Quickstarts:** `docs/en/documentation/getting-started/`
 2.  **Integration-Specific Samples:** `docs/en/integrations/<source_name>/samples/`. (The `samples/_index.md` wrapper must contain **strictly only frontmatter**).
 3.  **General/Cross-Category Samples:** `docs/en/samples/`
 
+##### Samples Maintenance Rules
+
+1. **Filtering:** Always include `sample_filters` in the frontmatter. Use specific tags for:
+   * Data Source (e.g., `bigquery`, `alloydb`)
+   * Language (e.g., `python`, `js`, `go`)
+   * Tool Type (e.g., `mcp`, `sdk`)
+2. **Metadata:** Ensure `is_sample: true` is present to prevent the sample from being excluded from the Samples Gallery.
+
+##### Prebuilt Config Constraints (`integrations/**/prebuilt-configs/*.md`)
+
+1. **Naming & Path:** All prebuilt config docs must reside in `prebuilt-configs/`.
+2. **Shortcode Requirement:** The main `documentation/configuration/prebuilt-configs/_index.md` page uses the `{{< list-prebuilt-configs >}}` shortcode, which only detects directories named exactly `prebuilt-configs`.
+3. **YAML Mapping:** Always verify the `kind` of the data source in `internal/prebuiltconfigs/tools/` before choosing the integration folder.
+
 
 ##### Asset Constraints (`docs/`)