docs: add multi-version documentation support

Add versioned docs with a version dropdown, per-version sidebar menus,
and a version-scoped search filter. Content is organized into versioned
folders (1.0.0.Final, 1.1.0.Final, dev) with the default version
resolved from data files.

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

Author: kabir

AGENTS.md

@@ -74,6 +74,10 @@ mvn clean install
 - Try to use existing code instead of generating new similar code
 - Use the same code convention than existing code. If the existing convention seems incorrect, make suggestion before doing any changes
 
+### Documentation Site
+
+The docs site (`docs/`) uses versioned content folders (`docs/content/1.0.0.Final/`, `docs/content/1.1.0.Final/`, `docs/content/dev/`). When updating documentation to reflect code changes, only edit pages under `docs/content/dev/` — released version folders are frozen snapshots and must not be modified. New versioned folders are created at release time (see RELEASE.md).
+
 ### PR instructions
 - Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for the commit title and message
 - Always ask if the commit is related to a GitHub issue. If that's the case, add a `This fixes #{issue_number}` at the end of the commit message

RELEASE.md

@@ -161,7 +161,32 @@ Artifacts should include:
 - `.pom` files
 - `.asc` GPG signatures for all artifacts
 
-### 9. Increment to Next SNAPSHOT
+### 9. Update Versioned Documentation
+
+Create a new documentation version for the release:
+
+```bash
+# Copy dev docs to the new version folder
+cp -r docs/content/dev docs/content/X.Y.Z.Final
+
+# Create a new version data file
+cp docs/data/versions/dev.yml docs/data/versions/X.Y.Z.Final.yml
+```
+
+Edit `docs/data/versions/X.Y.Z.Final.yml`:
+- Set `label` to `"X.Y.Z.Final"`
+- Set `path` to `"X.Y.Z.Final"`
+- Set `sortOrder` to the next number (higher than the previous release)
+- Set `defaultVersion` to `true`
+- Set `devVersion` to `false`
+- Adjust the `menu` list if the new version adds or removes pages
+
+Update the previous default version's data file (e.g., `docs/data/versions/OLD_VERSION.yml`):
+- Set `defaultVersion` to `false`
+
+Review the new version's content for accuracy — ensure all pages reflect features available in this release.
+
+### 10. Increment to Next SNAPSHOT
 
 Prepare repository for next development cycle:
 

boms/extras/src/it/extras-usage-test/src/main/java/org/a2aproject/sdk/bom/test/extras/ExtrasBomVerifier.java

@@ -13,6 +13,7 @@ public class ExtrasBomVerifier extends DynamicBomVerifier {
 
     private static final Set<String> EXTRAS_EXCLUSIONS = Set.of(
         "boms/",            // BOM test modules themselves
+        "docs/",            // Documentation site (not an SDK artifact)
         "examples/",        // Example applications
         "itk/",             // Integration Test Kit agent
         "tck/",             // TCK test suite

boms/reference/src/it/reference-usage-test/src/main/java/org/a2aproject/sdk/bom/test/reference/ReferenceBomVerifier.java

@@ -13,6 +13,7 @@ public class ReferenceBomVerifier extends DynamicBomVerifier {
 
     private static final Set<String> REFERENCE_EXCLUSIONS = Set.of(
         "boms/",               // BOM test modules themselves
+        "docs/",               // Documentation site (not an SDK artifact)
         "examples/",           // Example applications
         "itk/",                // Integration Test Kit agent
         "tck/",                // TCK test suite

boms/sdk/src/it/sdk-usage-test/src/main/java/org/a2aproject/sdk/bom/test/sdk/SdkBomVerifier.java

@@ -13,6 +13,7 @@ public class SdkBomVerifier extends DynamicBomVerifier {
 
     private static final Set<String> SDK_EXCLUSIONS = Set.of(
         "boms/",                 // BOM test modules themselves
+        "docs/",                 // Documentation site (not an SDK artifact)
         "examples/",             // Example applications
         "itk/",                  // Integration Test Kit agent
         "tck/",                  // TCK test suite

docs/content/boms.md docs/content/1.0.0.Final/boms.mddocs/content/boms.md renamed to docs/content/1.0.0.Final/boms.md

@@ -190,8 +190,8 @@ Client client = Client
 
 ## Communicating with v0.3 Agents
 
-See [Backward Compatibility]({site.url('compatibility')}#client-communicating-with-v03-agents) for using `Client_v0_3` with older protocol agents.
+See [Backward Compatibility](compatibility#client-communicating-with-v03-agents) for using `Client_v0_3` with older protocol agents.
 
 ## Examples
 
-See [Examples]({site.url('examples')}) for Hello World walkthroughs and sample applications.
+See [Examples](examples) for Hello World walkthroughs and sample applications.

docs/content/client.md docs/content/1.0.0.Final/client.mddocs/content/client.md renamed to docs/content/1.0.0.Final/client.md

@@ -142,7 +142,7 @@ mvn exec:java -Dopentelemetry=true
 
 The client expects an OpenTelemetry collector on port 5317. The easiest way is to run the Java server with `-Popentelemetry` (which starts the collector automatically), then run the client with `-Dopentelemetry=true` for end-to-end traces.
 
-For more information, see the [OpenTelemetry extras module]({site.url('/extras/opentelemetry')}).
+For more information, see the [OpenTelemetry extras module](extras/opentelemetry).
 
 ## More Examples