docs: lead the install instructions with uv, with uvx and pip as alternatives

AGENTS.md

@@ -16,14 +16,20 @@ environments; agent-env depends on it.
 
 Python 3.11 or newer. The repo convention is a `.venv` at the root, which the Makefile and CI use.
 
+```bash
+uv sync --extra dev && . .venv/bin/activate
+```
+
+Without uv:
+
 ```bash
 python3.11 -m venv .venv && . .venv/bin/activate
-pip install -e ./packages/agentenv-protocol -e '.[dev]'   # or: uv sync --extra dev
+pip install -e ./packages/agentenv-protocol -e '.[dev]'
 ```
 
-Install the in-repo protocol package together with the dev extra: agent-env depends on it and the
-workspace copy is the one to develop against (`uv sync` does this through the uv workspace in
-`pyproject.toml`). `make install` is the same in one step. No cloud credentials are needed; the
+Both install the in-repo protocol package together with the dev extra: agent-env depends on it and
+the workspace copy is the one to develop against (`uv sync` does this through the uv workspace in
+`pyproject.toml`). `make install` is the pip route in one step. No cloud credentials are needed; the
 default stores are local.
 
 ## Commands
@@ -36,7 +42,7 @@ default stores are local.
 | `make installer-test` | `tst/installer`: `plugin add` / `remove` through the real pip, uv and pipx, offline against wheels built from the checkout, and the container user journey (`python:3.12-slim`, `--network none`) with the PEP 668 refusal; needs uv, pipx and Docker |
 | `make clean-install-test` | the `clean-install` CI gate: both distributions built as the release builds them, installed into a fresh venv from public PyPI with an allowlisted environment, and `agent-env run hello` run twice by name and checked through the local store; needs Python 3.11, uv and git |
 | `pytest tst/unit/env/store_test.py -v` | one file; add `--log-cli-level=DEBUG` for debug logs |
-| `pip install build && python -m build` | wheel `agentenv_framework-<version>-py3-none-any.whl` (`src/agent_env` only) and sdist `agentenv_framework-<version>.tar.gz` (`src`, `tst`, the protocol package) |
+| `uv build` | wheel `agentenv_framework-<version>-py3-none-any.whl` (`src/agent_env` only) and sdist `agentenv_framework-<version>.tar.gz` (`src`, `tst`, the protocol package) |
 | `agent-env`, `python -m agent_env.cli` | the CLI; `agent-env config show` prints which config file is in effect and where each section came from |
 
 ## Configuration
@@ -188,7 +194,7 @@ Actions are pinned to commit SHAs.
 - Versions are cut by the maintainers' release automation. Never edit `version` in
   `pyproject.toml` or push a tag in a PR.
 - Names: the distribution is `agentenv-framework`, the import package `agent_env`, the console
-  script `agent-env`. Only the first is what `pip install` and `importlib.metadata.version()` take.
+  script `agent-env`. Only the first is what `uv add`, `pip install` and `importlib.metadata.version()` take.
 - Comments: default to none. The code says what; a docstring of one to three dense lines says why
   when that is not obvious. No comment that restates the code, no trailing assertion notes in tests.
 - Imports at module top, never inside functions.

README.md

@@ -11,12 +11,27 @@ agent-env is a Python SDK and CLI for building, deploying and running agentic en
 
 ## Install
 
-Both packages are on PyPI. You need Python 3.11 or newer and, to run environments locally, a running Docker daemon:
+Both packages are on PyPI. You need Python 3.11 or newer and, to run environments locally, a running Docker daemon. With [uv](https://docs.astral.sh/uv/), install the `agent-env` command as a tool:
+
+```bash
+uv tool install agentenv-framework
+agent-env run hello
+```
+
+`agent-env run hello` runs the built-in hello task, which needs no Docker, model or configuration. To try it without installing anything, run it with uvx:
+
+```bash
+uvx --from agentenv-framework agent-env run hello
+```
+
+Or install it with pip, into a virtualenv:
 
 ```bash
 pip install agentenv-framework
 ```
 
+To use the SDK in your own project, add it as a dependency with `uv add agentenv-framework`. The explorer, `agent-env up`, needs the `explorer` extra (`uv tool install 'agentenv-framework[explorer]'`, or the same extra with uvx or pip) and an `.agentenv/config.toml` in the current folder or above it; an empty one keeps every local default.
+
 The distribution is named `agentenv-framework`, the import package is `agent_env` and the command is `agent-env`. It depends on `agentenv-framework-protocol`, whose import package is `agentenv_protocol`, and installs it too.
 
 To work on agent-env itself, install from a clone with [uv](https://docs.astral.sh/uv/):
@@ -100,7 +115,7 @@ triage = "mycorp_demo.bundles"
 
 ### Plugin settings
 
-A plugin that needs settings of its own reads them from `[plugins.<package>]`, where `<package>` is its distribution name: the name `pip install` takes and `agent-env plugin list` prints. That table belongs to the plugin. agent-env reads nothing in it and checks none of its keys. Every other top-level table belongs to agent-env, which warns about one it does not read in `agent-env config show`, so a plugin keeps nothing of its own anywhere else.
+A plugin that needs settings of its own reads them from `[plugins.<package>]`, where `<package>` is its distribution name: the name `uv add` and `pip install` take and `agent-env plugin list` prints. That table belongs to the plugin. agent-env reads nothing in it and checks none of its keys. Every other top-level table belongs to agent-env, which warns about one it does not read in `agent-env config show`, so a plugin keeps nothing of its own anywhere else.
 
 ```toml
 [plugins.acme-agentenv-browser]

packages/agentenv-protocol/README.md

@@ -1,7 +1,8 @@
 # agentenv-framework-protocol
 
 Open data-plane protocol and server SDK for agent environments. Install it with
-`pip install agentenv-framework-protocol`; the import package is `agentenv_protocol`.
+`uv add agentenv-framework-protocol` or `pip install agentenv-framework-protocol`; the import
+package is `agentenv_protocol`.
 
 An environment author writes a class with decorated methods and serves it: