diff --git a/README.md b/README.md
index 0936b37b..f15a222d 100644
--- a/README.md
+++ b/README.md
@@ -213,7 +213,10 @@ from agent_assembly import init_assembly
 from agent_assembly.exceptions import ConfigurationError
 
 try:
-    context = init_assembly(gateway_url="", api_key="my-api-key", agent_id="my-agent-001")
+    # An invalid mode fails validation up front and raises ConfigurationError.
+    # (An empty/unset gateway_url is not an error — it triggers local
+    # auto-discovery; a gateway that can't be reached raises GatewayError.)
+    context = init_assembly(gateway_url="http://localhost:7391", mode="invalid-mode")
 except ConfigurationError as exc:
     print(f"Invalid configuration: {exc}")
 ```
diff --git a/agent_assembly/cli/main.py b/agent_assembly/cli/main.py
index 2e2ac080..ef59809f 100644
--- a/agent_assembly/cli/main.py
+++ b/agent_assembly/cli/main.py
@@ -5,6 +5,8 @@
 import argparse
 import sys
 
+from agent_assembly import __version__
+
 
 def _build_parser() -> argparse.ArgumentParser:
     """Build the top-level argument parser with the adapter subcommand."""
@@ -12,6 +14,11 @@ def _build_parser() -> argparse.ArgumentParser:
         prog="aasm",
         description="Agent Assembly SDK command-line tools.",
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
     adapter_parser = subparsers.add_parser("adapter", help="Adapter management commands")
diff --git a/test/unit/cli/test_cli_main.py b/test/unit/cli/test_cli_main.py
index bcd5df95..6624739b 100644
--- a/test/unit/cli/test_cli_main.py
+++ b/test/unit/cli/test_cli_main.py
@@ -6,9 +6,21 @@
 
 import pytest
 
+from agent_assembly import __version__
 from agent_assembly.cli.main import main
 
 
+class TestCliMainVersion:
+    """Tests for the ``aasm --version`` flag."""
+
+    def test_version_prints_version_and_exits_zero(self, capsys: pytest.CaptureFixture[str]) -> None:
+        with mock.patch("sys.argv", ["aasm", "--version"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 0
+            assert capsys.readouterr().out.strip() == f"aasm {__version__}"
+
+
 class TestCliMainExitCodeZero:
     """Tests for CLI main returning exit code 0."""