From c78fd56b6c67827e93c6eab58a1e01b26116a0d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A5=87=E6=BD=AD?= <xiaocheng.xc@alibaba-inc.com>
Date: Mon, 15 Jun 2026 10:26:44 +0800
Subject: [PATCH] fix: align A2A route preview command docs

---
 src/iac_code/a2a/app.py                       |  2 +-
 src/iac_code/cli/main.py                      | 19 ++++++---
 tests/a2a/test_app.py                         | 30 ++++++++++++++
 tests/cli/test_a2a_command.py                 | 41 +++++++++++++++----
 website/docs/a2a/command-reference.md         |  8 ++--
 website/docs/a2a/examples.md                  |  2 +-
 website/docs/a2a/getting-started.md           |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 .../current/a2a/command-reference.md          |  8 ++--
 .../current/a2a/examples.md                   |  2 +-
 .../current/a2a/getting-started.md            |  2 +-
 25 files changed, 120 insertions(+), 56 deletions(-)

diff --git a/src/iac_code/a2a/app.py b/src/iac_code/a2a/app.py
index 25804a0..875e2ce 100644
--- a/src/iac_code/a2a/app.py
+++ b/src/iac_code/a2a/app.py
@@ -454,7 +454,7 @@ def run_server(
     try:
         import uvicorn
     except ImportError as exc:
-        raise RuntimeError("A2A server dependencies are missing. Install iac-code with the 'a2a' extra.") from exc
+        raise RuntimeError("A2A server dependencies are missing. Install with: pip install 'iac-code[a2a]'") from exc
 
     uvicorn.run(
         app,
diff --git a/src/iac_code/cli/main.py b/src/iac_code/cli/main.py
index 6bbd773..905f731 100644
--- a/src/iac_code/cli/main.py
+++ b/src/iac_code/cli/main.py
@@ -47,6 +47,15 @@
 )
 app.add_typer(a2a_client_app, name="a2a-client")
 
+
+def _a2a_client_missing_dependencies_message() -> str:
+    return _("A2A client dependencies are missing. Install with: pip install 'iac-code[a2a]'")
+
+
+def _a2a_server_missing_dependencies_message() -> str:
+    return _("A2A server dependencies are missing. Install with: pip install 'iac-code[a2a]'")
+
+
 # `install-git-bash` is a Windows-only helper that installs Git for Windows
 # via the npmmirror mirror. We register it conditionally so it does not
 # show up in --help on non-Windows platforms (where it could not work).
@@ -71,7 +80,7 @@ def a2a_client(
         import iac_code.a2a.client  # noqa: F401
     except ImportError:
         typer.echo(
-            _("A2A client dependencies are missing. Install with: pip install 'iac-code[a2a]'"),
+            _a2a_client_missing_dependencies_message(),
             err=True,
         )
         raise typer.Exit(1)
@@ -649,7 +658,7 @@ def a2a(
         )
     except ImportError as exc:
         typer.echo(
-            _("A2A server dependencies are missing. Install with: pip install 'iac-code[a2a]'"),
+            _a2a_server_missing_dependencies_message(),
             err=True,
         )
         raise typer.Exit(1) from exc
@@ -1504,7 +1513,7 @@ def _build_a2a_auth_config(
         from iac_code.a2a.transport import A2AAuthConfig
     except ImportError as exc:
         typer.echo(
-            _("A2A client dependencies are missing. Install with: pip install 'iac-code[a2a]'"),
+            _a2a_client_missing_dependencies_message(),
             err=True,
         )
         raise typer.Exit(1) from exc
@@ -1865,7 +1874,7 @@ def _parse_a2a_route_spec(value: str):
         from iac_code.a2a.router import A2ARoute
     except ImportError as exc:
         typer.echo(
-            _("A2A client dependencies are missing. Install with: pip install 'iac-code[a2a]'"),
+            _a2a_client_missing_dependencies_message(),
             err=True,
         )
         raise typer.Exit(1) from exc
@@ -1904,7 +1913,7 @@ def _save_a2a_route_snapshots(persistence_dir: str, routes: list[Any]) -> None:
         from iac_code.a2a.persistence import A2APersistenceStore, A2ARouteSnapshot
     except ImportError as exc:
         typer.echo(
-            _("A2A client dependencies are missing. Install with: pip install 'iac-code[a2a]'"),
+            _a2a_client_missing_dependencies_message(),
             err=True,
         )
         raise typer.Exit(1) from exc
diff --git a/tests/a2a/test_app.py b/tests/a2a/test_app.py
index 3677ecf..819eea7 100644
--- a/tests/a2a/test_app.py
+++ b/tests/a2a/test_app.py
@@ -1,4 +1,5 @@
 import asyncio
+import builtins
 import json
 from base64 import b64encode
 from pathlib import Path
@@ -25,6 +26,7 @@
     resolve_api_key,
     resolve_basic_credentials,
     resolve_token,
+    run_server,
 )
 from iac_code.a2a.persistence import A2APersistenceStore
 from iac_code.a2a.transports.dispatcher import create_runtime_components
@@ -86,6 +88,34 @@ def test_health_route() -> None:
     assert response.json() == {"status": "healthy"}
 
 
+def test_run_server_reports_aligned_missing_uvicorn_hint(monkeypatch, tmp_path) -> None:
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "uvicorn":
+            raise ImportError("No module named 'uvicorn'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+    monkeypatch.setattr("iac_code.a2a.app.create_app", lambda **kwargs: object())
+
+    with pytest.raises(
+        RuntimeError,
+        match=r"A2A server dependencies are missing\. Install with: pip install 'iac-code\[a2a\]'",
+    ):
+        run_server(
+            host="127.0.0.1",
+            port=41242,
+            token=None,
+            model="qwen3.6-plus",
+            basic_username=None,
+            basic_password=None,
+            api_key=None,
+            api_key_header="X-API-Key",
+            persistence_dir=tmp_path / "a2a",
+        )
+
+
 def test_agent_card_route() -> None:
     app = create_app(host="127.0.0.1", port=41242, token=None, model="qwen3.6-plus")
     client = TestClient(app)
diff --git a/tests/cli/test_a2a_command.py b/tests/cli/test_a2a_command.py
index d9fbbc5..8ceaa30 100644
--- a/tests/cli/test_a2a_command.py
+++ b/tests/cli/test_a2a_command.py
@@ -5,7 +5,11 @@
 
 from iac_code.a2a.persistence import A2APersistenceStore, A2ARouteSnapshot
 from iac_code.a2a.transport import A2AAuthConfig
-from iac_code.cli.main import app
+from iac_code.cli.main import (
+    _a2a_client_missing_dependencies_message,
+    _a2a_server_missing_dependencies_message,
+    app,
+)
 from iac_code.config import DEFAULT_MODEL
 
 _ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
@@ -51,13 +55,15 @@ def test_a2a_client_help_groups_client_commands() -> None:
     assert "push-config-create" in stdout
     assert "extended-card" in stdout
     assert "route-preview" in stdout
+    assert "a2a-route-preview" not in stdout
 
 
-def test_removed_top_level_a2a_client_command_is_rejected() -> None:
-    result = CliRunner().invoke(app, ["a2a-call", "--help"])
+def test_removed_top_level_a2a_client_commands_are_rejected() -> None:
+    for command in ("a2a-call", "a2a-route-preview"):
+        result = CliRunner().invoke(app, [command, "--help"])
 
-    assert result.exit_code == 2
-    assert "No such command" in result.stderr
+        assert result.exit_code == 2
+        assert "No such command" in result.stderr
 
 
 def test_a2a_command_passes_config_options_to_server(monkeypatch, tmp_path) -> None:
@@ -972,7 +978,7 @@ def test_a2a_route_preview_resolves_and_saves_routes(tmp_path) -> None:
 
 def test_a2a_command_reports_missing_extra(monkeypatch) -> None:
     def fake_run_server(**kwargs) -> None:
-        raise RuntimeError("A2A server dependencies are missing. Install iac-code with the 'a2a' extra.")
+        raise RuntimeError(_a2a_server_missing_dependencies_message())
 
     monkeypatch.setattr("iac_code.a2a.app.run_server", fake_run_server)
     monkeypatch.setattr("iac_code.a2a.app.resolve_token", lambda token: None)
@@ -983,7 +989,7 @@ def fake_run_server(**kwargs) -> None:
 
     assert result.exit_code == 1
     combined_output = (result.stdout or "") + (result.stderr or "") + (result.output or "")
-    assert "a2a" in combined_output
+    assert _a2a_server_missing_dependencies_message() in combined_output
 
 
 def test_a2a_command_reports_import_error(monkeypatch) -> None:
@@ -1002,7 +1008,26 @@ def fake_import(name, *args, **kwargs):
 
     assert result.exit_code == 1
     combined_output = (result.stdout or "") + (result.stderr or "") + (result.output or "")
-    assert "a2a" in combined_output
+    assert _a2a_server_missing_dependencies_message() in combined_output
+
+
+def test_a2a_client_command_reports_import_error(monkeypatch) -> None:
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "iac_code.a2a.client":
+            raise ImportError("missing optional a2a dependency")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    result = CliRunner().invoke(app, ["a2a-client", "discover", "--url", "http://agent.example/rpc"])
+
+    assert result.exit_code == 1
+    combined_output = (result.stdout or "") + (result.stderr or "") + (result.output or "")
+    assert _a2a_client_missing_dependencies_message() in combined_output
 
 
 def test_a2a_command_bootstraps_telemetry_around_run_server(monkeypatch) -> None:
diff --git a/website/docs/a2a/command-reference.md b/website/docs/a2a/command-reference.md
index 5079724..bbedc84 100644
--- a/website/docs/a2a/command-reference.md
+++ b/website/docs/a2a/command-reference.md
@@ -24,7 +24,7 @@ This page documents every A2A-related `iac-code` command. Use it when you need e
 | `iac-code a2a-client push-config-list` | List task push notification configs |
 | `iac-code a2a-client push-config-delete` | Delete a task push notification config |
 | `iac-code a2a-client extended-card` | Fetch the authenticated extended Agent Card |
-| `iac-code a2a-route-preview` | Preview local route selection for `a2a-client call` |
+| `iac-code a2a-client route-preview` | Preview local route selection for `a2a-client call` |
 
 All HTTP client commands accept the same authentication options:
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 The public Agent Card advertises `capabilities.extendedAgentCard=true`. The extended card adds authenticated runtime details, including task management and push configuration capability metadata.
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 Preview how `a2a-client call` resolves configured routes when `--url` is omitted.
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 Save route snapshots:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/docs/a2a/examples.md b/website/docs/a2a/examples.md
index c11e69f..e8085bb 100644
--- a/website/docs/a2a/examples.md
+++ b/website/docs/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 Preview route selection before calling a routed agent:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/docs/a2a/getting-started.md b/website/docs/a2a/getting-started.md
index 5a67f42..eabf364 100644
--- a/website/docs/a2a/getting-started.md
+++ b/website/docs/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 For multi-agent routing, preview route selection before calling:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index 848be11..7f9d39d 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ Diese Seite dokumentiert jeden A2A-bezogenen `iac-code`-Befehl. Verwenden Sie si
 | `iac-code a2a-client push-config-list` | Task-Push-Notification-Configs auflisten |
 | `iac-code a2a-client push-config-delete` | Eine Task-Push-Notification-Config loeschen |
 | `iac-code a2a-client extended-card` | Die authentifizierte erweiterte Agent Card abrufen |
-| `iac-code a2a-route-preview` | Lokale Routenauswahl fuer `a2a-client call` voranzeigen |
+| `iac-code a2a-client route-preview` | Lokale Routenauswahl fuer `a2a-client call` voranzeigen |
 
 Alle HTTP-Clientbefehle akzeptieren dieselben Authentifizierungsoptionen:
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 Die oeffentliche Agent Card bewirbt `capabilities.extendedAgentCard=true`. Die erweiterte Karte fuegt authentifizierte Laufzeitdetails hinzu, einschliesslich Task-Verwaltung und Push-Konfigurationsfaehigkeitsmetadaten.
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 Vorschau, wie `a2a-client call` konfigurierte Routen aufloest, wenn `--url` ausgelassen ist.
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 Routen-Snapshots speichern:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/examples.md
index 7844453..59c5c1c 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 Zeigen Sie vor dem Aufrufen eines gerouteten Agent die Routenauswahl in der Vorschau an:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index 249e456..f409735 100644
--- a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 Zeigen Sie bei Multi-Agent-Routing die Routenauswahl vor dem Aufruf in der Vorschau an:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index 29d7522..8cba684 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ Esta página documenta todos los comandos de `iac-code` relacionados con A2A. Ú
 | `iac-code a2a-client push-config-list` | Listar configuraciones de notificación push de tarea |
 | `iac-code a2a-client push-config-delete` | Eliminar una configuración de notificación push de tarea |
 | `iac-code a2a-client extended-card` | Obtener la Agent Card extendida autenticada |
-| `iac-code a2a-route-preview` | Previsualizar la selección local de ruta para `a2a-client call` |
+| `iac-code a2a-client route-preview` | Previsualizar la selección local de ruta para `a2a-client call` |
 
 Todos los comandos de cliente HTTP aceptan las mismas opciones de autenticación:
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 La Agent Card pública anuncia `capabilities.extendedAgentCard=true`. La tarjeta extendida agrega detalles autenticados del runtime, incluidos metadatos de capacidades de gestión de tareas y configuración push.
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 Previsualiza cómo `a2a-client call` resuelve rutas configuradas cuando `--url` se omite.
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 Guardar instantáneas de rutas:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/examples.md
index 52adc92..97842d3 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 Previsualiza la selección de ruta antes de llamar a un agente enrutado:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index 9444ca0..fe28c7a 100644
--- a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 Para enrutamiento multiagente, previsualiza la selección de ruta antes de llamar:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index 29999f7..1392c45 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ Cette page documente chaque commande `iac-code` liée à A2A. Utilisez-la lorsqu
 | `iac-code a2a-client push-config-list` | Lister les configurations de notification push de tâche |
 | `iac-code a2a-client push-config-delete` | Supprimer une configuration de notification push de tâche |
 | `iac-code a2a-client extended-card` | Récupérer l'Agent Card étendue authentifiée |
-| `iac-code a2a-route-preview` | Prévisualiser la sélection de route locale pour `a2a-client call` |
+| `iac-code a2a-client route-preview` | Prévisualiser la sélection de route locale pour `a2a-client call` |
 
 Toutes les commandes client HTTP acceptent les mêmes options d'authentification :
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 L'Agent Card publique annonce `capabilities.extendedAgentCard=true`. La carte étendue ajoute des détails runtime authentifiés, y compris les métadonnées de capacités de gestion des tâches et de configuration push.
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 Prévisualise la manière dont `a2a-client call` résout les routes configurées lorsque `--url` est omis.
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 Enregistrer les instantanés de route :
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/examples.md
index 43d78a3..6886603 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 Prévisualisez la sélection de route avant d'appeler un agent routé :
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index 49047c9..929d141 100644
--- a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 Pour le routage multi-agent, prévisualisez la sélection de route avant l'appel :
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index 500eb2f..e5b9736 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ sidebar_position: 3
 | `iac-code a2a-client push-config-list` | タスクプッシュ通知設定を一覧表示 |
 | `iac-code a2a-client push-config-delete` | タスクプッシュ通知設定を削除 |
 | `iac-code a2a-client extended-card` | 認証済みの拡張 Agent Card を取得 |
-| `iac-code a2a-route-preview` | `a2a-client call` のローカルルート選択をプレビュー |
+| `iac-code a2a-client route-preview` | `a2a-client call` のローカルルート選択をプレビュー |
 
 すべての HTTP クライアントコマンドは、同じ認証オプションを受け付けます。
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 公開 Agent Card は `capabilities.extendedAgentCard=true` を広告します。拡張カードは、タスク管理やプッシュ設定機能メタデータを含む認証済みランタイム詳細を追加します。
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 `a2a-client call` が、`--url` が省略された場合に設定済みルートをどのように解決するかをプレビューします。
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 ルートスナップショットを保存する:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/examples.md
index f6bc673..5f5aa5f 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 ルーティングされたエージェントを呼び出す前に、ルート選択をプレビューします。
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index d826f3d..0635944 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 マルチエージェントルーティングでは、呼び出し前にルート選択をプレビューします。
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index c7f2b98..3730dcb 100644
--- a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ Esta página documenta todos os comandos `iac-code` relacionados a A2A. Use-a qu
 | `iac-code a2a-client push-config-list` | Listar configurações de notificação push de tarefa |
 | `iac-code a2a-client push-config-delete` | Excluir uma configuração de notificação push de tarefa |
 | `iac-code a2a-client extended-card` | Buscar o Agent Card estendido autenticado |
-| `iac-code a2a-route-preview` | Pré-visualizar a seleção local de rota para `a2a-client call` |
+| `iac-code a2a-client route-preview` | Pré-visualizar a seleção local de rota para `a2a-client call` |
 
 Todos os comandos de cliente HTTP aceitam as mesmas opções de autenticação:
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 O Agent Card público anuncia `capabilities.extendedAgentCard=true`. O card estendido adiciona detalhes autenticados do runtime, incluindo gerenciamento de tarefas e metadados de capacidade de configuração push.
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 Pré-visualize como `a2a-client call` resolve rotas configuradas quando `--url` é omitido.
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 Salvar snapshots de rotas:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/examples.md
index 16a669a..501aab8 100644
--- a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 Pré-visualize a seleção de rota antes de chamar um agente roteado:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index c2f740c..74258ce 100644
--- a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 Para roteamento multiagente, pré-visualize a seleção de rota antes de chamar:
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/command-reference.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/command-reference.md
index 94f3dc1..a322ffe 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/command-reference.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/command-reference.md
@@ -24,7 +24,7 @@ sidebar_position: 3
 | `iac-code a2a-client push-config-list` | 列出 task push notification configs |
 | `iac-code a2a-client push-config-delete` | 删除 task push notification config |
 | `iac-code a2a-client extended-card` | 获取已认证的扩展 Agent Card |
-| `iac-code a2a-route-preview` | 为 `a2a-client call` 预览本地路由选择 |
+| `iac-code a2a-client route-preview` | 为 `a2a-client call` 预览本地路由选择 |
 
 所有 HTTP client 命令都接受相同的认证选项：
 
@@ -465,12 +465,12 @@ iac-code a2a-client --config a2a-client.yml extended-card \
 
 Public Agent Card 会公布 `capabilities.extendedAgentCard=true`。扩展 card 会添加已认证运行时细节，包括任务管理和推送配置能力元数据。
 
-## `iac-code a2a-route-preview`
+## `iac-code a2a-client route-preview`
 
 预览省略 `--url` 时 `a2a-client call` 如何解析已配置路由。
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
@@ -488,7 +488,7 @@ iac-code a2a-route-preview \
 保存 route snapshots：
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
   --route-state-dir ~/.iac-code/a2a \
   --save-routes
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/examples.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/examples.md
index 3005121..43e7238 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/examples.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/examples.md
@@ -165,7 +165,7 @@ iac-code a2a-client --config a2a-client.yml push-config-create \
 调用 routed agent 前预览路由选择：
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --prompt "Create a ROS VPC template"
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/getting-started.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/getting-started.md
index a63a8de..38ffeb7 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/getting-started.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/getting-started.md
@@ -167,7 +167,7 @@ iac-code a2a-client --config a2a-client.yml call \
 对于多 agent 路由，请在调用前预览路由选择：
 
 ```bash
-iac-code a2a-route-preview \
+iac-code a2a-client route-preview \
   --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
   --skill iac_generation \
   --route-state-dir ~/.iac-code/a2a