[AAASM-4332] 📝 (readme): Document --pre for pre-release install; fix [cli] extra

README.md

@@ -78,10 +78,14 @@ version (`agent-assembly==0.0.x`) if you need a stable contract.
 The package is published on PyPI as [`agent-assembly`](https://pypi.org/project/agent-assembly/):
 
 ```bash
-pip install agent-assembly            # pure-Python SDK
-pip install 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel)
+pip install --pre agent-assembly            # pure-Python SDK
+pip install --pre 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel)
 ```
 
+> **`--pre` is required for now.** Agent Assembly is currently published only as a
+> pre-release on PyPI, and `pip` skips pre-releases unless you pass `--pre`. Drop the
+> flag once a stable (non-pre-release) version is published.
+
 `agent-assembly[runtime]` pulls a platform wheel (`manylinux`, `macosx`) that bundles the
 `aasm` sidecar binary, so you don't need a separate runtime install. Plain `agent-assembly`
 is the pure-Python client and expects an `aasm` runtime to be reachable some other way.
@@ -127,7 +131,7 @@ The pure-Python SDK works without the native extension — `maturin develop` is
 A governed LangChain ReAct agent that runs offline against a mock LLM. The example imports LangChain in addition to the SDK, so install both:
 
 ```bash
-pip install agent-assembly langchain langchain-community
+pip install --pre agent-assembly langchain langchain-community
 ```
 
 ```python

agent_assembly/core/gateway_resolver.py

@@ -70,8 +70,7 @@
         return
     if mode & 0o077:
         logger.warning(
-            "Config file %s has group/other-readable permissions (mode %o); "
-            "run `chmod 600 %s` to secure it.",
+            "Config file %s has group/other-readable permissions (mode %o); " "run `chmod 600 %s` to secure it.",
             path,
             mode,
             path,
@@ -183,7 +182,7 @@
     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[cli]"
+            "Install it with: pip install 'agent-assembly[runtime]'"
         )
 
     subprocess.Popen(

docs/compatibility/frameworks.md

@@ -135,7 +135,7 @@ your agent already uses, alongside the SDK, and the matching adapter activates
 automatically:
 
 ```bash
-pip install agent-assembly langchain   # or crewai, pydantic-ai, mcp, openai-agents, smolagents, ...
+pip install --pre agent-assembly langchain   # or crewai, pydantic-ai, mcp, openai-agents, smolagents, ...
 ```
 
 The SDK deliberately does **not** declare these frameworks as `pip install

docs/development/docs-macros.md

@@ -80,7 +80,7 @@ Report bugs on the [issue tracker]({{ aa.urls.issues }}).
   pinning pattern rather than the current version.
 - **One-off framework-composed install commands** where the readability cost
   of `{{ aa.commands.install_pip }} langchain` exceeds the drift risk of
-  `pip install agent-assembly langchain`. Templating everything is not the
+  `pip install --pre agent-assembly langchain`. Templating everything is not the
   goal; the goal is to keep the **current-state, high-drift** values in sync.
 
 If in doubt, ask: *"When we cut the next release, will this line become

docs/examples/framework-support.md

@@ -68,7 +68,7 @@ A governed LangChain ReAct agent that runs **offline** against a mock LLM — no
 and no network calls. Install the SDK plus LangChain:
 
 ```bash
-pip install agent-assembly langchain langchain-community
+pip install --pre agent-assembly langchain langchain-community
 ```
 
 ```python

docs/guides/type-checking.md

@@ -34,7 +34,7 @@ care about.
 Use any PEP 561-aware checker. With mypy:
 
 ```bash
-pip install agent-assembly mypy
+pip install --pre agent-assembly mypy
 mypy your_app.py
 ```
 

docs/quick-start.md

@@ -23,6 +23,11 @@ The package is published on PyPI as
     {{ aa.commands.install_uv }}
     ```
 
+!!! note "`--pre` is required for now"
+    Agent Assembly is currently published only as a pre-release on PyPI, and `pip`
+    skips pre-releases unless you pass `--pre` (already included above). Drop the flag
+    once a stable (non-pre-release) version is published.
+
 `{{ aa.python_sdk.package_name }}` is the pure-Python client.
 `{{ aa.python_sdk.package_name }}[runtime]` additionally pulls a platform wheel
 (`manylinux`, `macosx`) that bundles the `{{ aa.python_sdk.cli_name }}`

docs/troubleshooting.md

@@ -51,7 +51,7 @@ still works.
 To enable it:
 
 ```bash
-pip install 'agent-assembly[runtime]'   # bundled platform wheel, or
+pip install --pre 'agent-assembly[runtime]'   # bundled platform wheel, or
 uv tool run maturin develop --manifest-path native/aa-ffi-python/Cargo.toml --release  # build locally (needs Rust)
 ```
 

docs_macros.py

@@ -61,8 +61,8 @@ def define_env(env: Any) -> None:
         },
         "commands": {
             "install_uv": "uv add agent-assembly",
-            "install_pip": "pip install agent-assembly",
-            "install_pip_runtime": "pip install 'agent-assembly[runtime]'",
+            "install_pip": "pip install --pre agent-assembly",
+            "install_pip_runtime": "pip install --pre 'agent-assembly[runtime]'",
         },
     }