diff --git a/README.md b/README.md
index f4e7bb2..092536c 100644
--- a/README.md
+++ b/README.md
@@ -99,9 +99,14 @@ is the pure-Python client and expects an `aasm` runtime to be reachable some oth
 With [`uv`](https://docs.astral.sh/uv/):
 
 ```bash
-uv add agent-assembly
+uv add --prerelease=allow agent-assembly
 ```
 
+> **`--prerelease=allow` is required for now.** Unlike `pip`, `uv` refuses to
+> resolve pre-releases unless you opt in. Agent Assembly is currently published only
+> as a pre-release on PyPI, so `uv add agent-assembly` fails to resolve without it.
+> Drop the flag once a stable (non-pre-release) version is published.
+
 To track unreleased changes, install from the `master` branch:
 
 ```bash
diff --git a/agent_assembly/_install.py b/agent_assembly/_install.py
index 62205d8..300b658 100644
--- a/agent_assembly/_install.py
+++ b/agent_assembly/_install.py
@@ -30,7 +30,7 @@
 
 INSTALL_HINT = (
     "agent-assembly runtime binary `aasm` was not found.\n"
-    "  Install the platform wheel: pip install agent-assembly[runtime]\n"
+    "  Install the platform wheel: pip install --pre agent-assembly[runtime]\n"
     "  Or install manually:        brew install ai-agent-assembly/tap/aasm\n"
     "                              curl -fsSL https://agent-assembly.com/install.sh | sh"
 )
diff --git a/agent_assembly/core/gateway_resolver.py b/agent_assembly/core/gateway_resolver.py
index 3d6ccb5..8fc1e8d 100644
--- a/agent_assembly/core/gateway_resolver.py
+++ b/agent_assembly/core/gateway_resolver.py
@@ -182,7 +182,7 @@ def _auto_start_gateway(
     if aasm_path is None:
         raise ConfigurationError(
             f"No gateway found at {base_url} and 'aasm' is not on PATH. "
-            "Install it with: pip install 'agent-assembly[runtime]'"
+            "Install it with: pip install --pre 'agent-assembly[runtime]'"
         )
 
     subprocess.Popen(
diff --git a/agent_assembly/runtime.py b/agent_assembly/runtime.py
index 8aa4d64..39dde86 100644
--- a/agent_assembly/runtime.py
+++ b/agent_assembly/runtime.py
@@ -37,7 +37,7 @@
 
 INSTALL_HINT = (
     "agent-assembly runtime not found.\n"
-    "  Install with: pip install agent-assembly[runtime]\n"
+    "  Install with: pip install --pre agent-assembly[runtime]\n"
     "  Or manually:  brew install ai-agent-assembly/tap/aasm\n"
     "               curl -fsSL https://agent-assembly.com/install.sh | sh"
 )
diff --git a/docs_macros.py b/docs_macros.py
index 9cfe3b6..9c451c9 100644
--- a/docs_macros.py
+++ b/docs_macros.py
@@ -60,7 +60,7 @@ def define_env(env: Any) -> None:
             "pypi": "https://pypi.org/project/agent-assembly/",
         },
         "commands": {
-            "install_uv": "uv add agent-assembly",
+            "install_uv": "uv add --prerelease=allow agent-assembly",
             "install_pip": "pip install --pre agent-assembly",
             "install_pip_runtime": "pip install --pre 'agent-assembly[runtime]'",
         },