diff --git a/README.md b/README.md
index bcac5b9e..8cbabc3b 100644
--- a/README.md
+++ b/README.md
@@ -52,16 +52,31 @@ claude-code-proxy/
 
 ### Install
 
-Using `uv`:
+The fastest path is the bundled installer, which creates a virtualenv,
+installs runtime dependencies, prompts for your Nebius API key without
+echoing it to your shell, validates the configured model IDs against
+`GET /v1/models`, and runs an end-to-end smoke test before declaring
+success:
 
 ```bash
-uv sync
+./install.sh
 ```
 
-Using `pip`:
+#### Manual install
+
+If you'd rather wire things up yourself:
 
 ```bash
-python -m pip install -e ".[dev]"
+python -m venv .venv
+.venv/bin/python -m pip install --upgrade pip   # fresh venvs ship pip <22 which fails on pyproject editable installs
+.venv/bin/pip install -r requirements.txt
+cp .env.example .env                            # then edit .env to set OPENAI_API_KEY
+```
+
+Or with `uv`:
+
+```bash
+uv sync
 ```
 
 ### Configure
@@ -101,10 +116,32 @@ uv run claude-code-proxy-nebius
 
 ### Use with Claude Code
 
+Pick one of these patterns and add it to your shell rc (`~/.zshrc` or
+`~/.bashrc`), then open a new shell:
+
+**Option A — separate command.** Bare `claude` keeps using Anthropic; a
+named alias (here, `claudius`) routes through this proxy. The env vars
+exist only for the duration of that invocation, so there's no hidden
+shell state.
+
 ```bash
-ANTHROPIC_BASE_URL="http://localhost:8083" ANTHROPIC_API_KEY="any-value" claude
+claudius() {
+  ANTHROPIC_BASE_URL=http://localhost:8083 ANTHROPIC_API_KEY=claude-local claude "$@"
+}
 ```
 
+**Option B — global exports.** Every `claude` invocation routes through
+the proxy; convenient if you mostly use Claude Code with this proxy.
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8083
+export ANTHROPIC_API_KEY=claude-local
+```
+
+Option A keeps the provider visible in the command name. Option B is
+fewer keystrokes per invocation. The bundled `install.sh` can write
+either snippet for you at the end of install.
+
 If `IGNORE_CLIENT_API_KEY=false`, the client key must match `ANTHROPIC_API_KEY`.
 
 ## MCP Support