Installer: install into the project when run inside one; stop before login

.github/workflows/installer.yml

@@ -63,15 +63,18 @@ jobs:
         # lagging a publish by a few seconds.
         run: |
           get_script() {
-            if [ "$SOURCE" = "url" ]; then curl -fsSL https://kitaru.ai/install; else cat install.sh; fi
+            if [ "$SOURCE" = "url" ]; then curl -fsSL https://kitaru.ai/install; else cat "$GITHUB_WORKSPACE/install.sh"; fi
           }
+          # Run from an empty directory: the checkout is itself a Python project,
+          # which would put the installer into project mode.
+          cd "$(mktemp -d)"
           for attempt in 1 2 3 4 5; do
-            get_script | bash -s -- --no-login && exit 0
+            get_script | bash -s -- && exit 0
             echo "installer attempt $attempt failed; retrying in 30s" >&2
             sleep 30
           done
           echo "::group::verbose rerun for diagnostics"
-          get_script | bash -s -- --no-login --verbose || true
+          get_script | bash -s -- --verbose || true
           echo "::endgroup::"
           exit 1
       - name: Verify
@@ -98,13 +101,26 @@ jobs:
             | grep -q ".local/bin" || { echo "PATH not persisted"; exit 1; }
       - name: Re-run is an upgrade, not an error
         shell: bash
-        run: cat install.sh | bash -s -- --no-login --no-skills --no-mcp --quiet
+        run: cd "$(mktemp -d)" && cat "$GITHUB_WORKSPACE/install.sh" | bash -s --
+          --no-skills --no-mcp --quiet
+      - name: Inside a project, install into that project's environment
+        shell: bash
+        run: |
+          set -euxo pipefail
+          export PATH="$HOME/.local/bin:$PATH"
+          cd "$(mktemp -d)"
+          uv init --quiet -p 3.12 --name demo-agent .
+          cat "$GITHUB_WORKSPACE/install.sh" | bash -s -- --no-skills --no-mcp
+          grep -q 'kitaru\[cli,mcp,worker\]' pyproject.toml
+          uv run kitaru --version
+          uv run kitaru-mcp --help >/dev/null
       - name: A failed install must exit nonzero (quiet path)
         shell: bash
         # Regression for the status-swallowing bug in `quiet`: an impossible
         # version pin makes `uv tool install` fail, and that must surface.
         run: |-
-          if cat install.sh | bash -s -- --no-login --no-skills --no-mcp --version=99.99.99; then
+          cd "$(mktemp -d)"
+          if cat "$GITHUB_WORKSPACE/install.sh" | bash -s -- --no-skills --no-mcp --version=99.99.99; then
             echo "installer exited 0 on a failed install" >&2; exit 1
           fi
           echo "failed install correctly exited nonzero"

README.md

@@ -44,19 +44,19 @@ Kitaru turns that history into something you can test:
 
 ## ⚡ Get started
 
-**1. Install and log in.** One line installs the CLI and MCP server (via `uv`), the coding-agent skills, registers the MCP server with Claude Code and Codex, and starts the local server if Docker is running:
+**1. Install.** Open a terminal in your agent's repository and run one line. It adds Kitaru to that project's environment with `uv` (the worker that replays your agent has to live next to its dependencies), installs the coding-agent skills, and registers the MCP server with Claude Code and Codex. It ends by printing the two ways to get a server: `kitaru login --local` (Docker, free) or `kitaru login` for the managed cloud (14-day trial, no credit card required).
 
 ```bash
 curl -fsSL https://kitaru.ai/install | bash
 ```
 
-Already in Claude Code, Codex, or Cursor? Paste this instead and let it run the same installer:
+Already in Claude Code, Codex, or Cursor? Open the repository there and paste this instead:
 
 ```
-Set up Kitaru on this machine by following https://kitaru.ai/install.md. Use the one-line installer, tell me what it did, and stop before logging in if Docker is not running.
+Set up Kitaru in this repository by following https://kitaru.ai/install.md. Use the one-line installer and tell me what it did.
 ```
 
-Prefer to do it by hand, or want Kitaru inside your project's environment? The local server is FastAPI + Postgres, and `kitaru login --local` provisions it with Docker:
+Prefer to do it by hand? The local server is FastAPI + Postgres, and `kitaru login --local` provisions it with Docker:
 
 ```bash
 uv add "kitaru[cli,worker,mcp]" kitaru-pydantic-ai    # or: pip install

docs/book/agent-native/setup.md

@@ -13,7 +13,7 @@ Kitaru observes your production agents; your coding assistant is how you talk to
 Skills and MCP work together: the skills say how to work, and the server bounds what can be touched.
 
 {% hint style="success" %}
-Used the [one-line installer](../getting-started/installation.md)? It already installed the MCP server, registered it with Claude Code and Codex (user scope, pointed at `http://localhost:8000` in `standard` mode), and installed the skills. Skip to [Capability modes and tools](#capability-modes-and-tools) unless you use another assistant or a different server URL.
+Used the [one-line installer](../getting-started/installation.md)? It already installed the MCP server, registered it with Claude Code (in your repo's `.mcp.json` when run inside a repository, user scope otherwise) and Codex, pointed at `http://localhost:8000` in `standard` mode, and installed the skills. Skip to [Capability modes and tools](#capability-modes-and-tools) unless you use another assistant or a different server URL.
 {% endhint %}
 
 ## Install the MCP server

docs/book/getting-started/installation.md

@@ -5,35 +5,56 @@ icon: download
 
 # Installation
 
-One command installs everything a first session needs. It needs [Docker](https://docs.docker.com/get-started/get-docker/) for the local server (the CLI installs without it) and works on macOS, Linux, WSL, and Git Bash on Windows:
+Open a terminal **in your agent's repository** and run:
 
 ```bash
 curl -fsSL https://kitaru.ai/install | bash
 ```
 
-What it does, in order:
+That one command:
 
-1. Installs the `kitaru` CLI and the `kitaru-mcp` server into an isolated [uv](https://docs.astral.sh/uv/) environment, installing uv first if you do not have it. No system Python is required.
-2. Installs the [agent skills](../agent-native/setup.md) into `~/.agents/skills`, and into `~/.claude/skills` and `~/.codex/skills` when Claude Code or Codex is installed.
-3. Registers the MCP server with Claude Code and Codex.
-4. Runs `kitaru login --local`, which starts the server and PostgreSQL in Docker and logs you in. If Docker is not running, it prints that command for later instead.
+1. Adds `kitaru[cli,mcp,worker]` to the project's environment with `uv add`. The worker that replays your agent has to live next to your agent's dependencies, so this is the environment that matters. uv is installed first if you do not have it; no system Python and no `sudo` are needed.
+2. Installs the [agent skills](../agent-native/setup.md) into `~/.agents/skills`, plus `~/.claude/skills` and `~/.codex/skills` when Claude Code or Codex is installed.
+3. Registers the MCP server with Claude Code (in the repo's `.mcp.json`) and Codex, as `uv run --directory <repo> kitaru-mcp`.
+4. Prints the two ways to get a server, and stops:
 
-Nothing needs `sudo`, everything lands under your home directory, and running it again upgrades. Options: `--server https://your-team.kitaru.ai` logs in to a team server instead of starting a local one, `--with kitaru-pydantic-ai` adds an adapter to the same environment, `--no-login`, `--no-skills`, `--no-mcp` skip steps, and `--no-modify-path` leaves your shell rc files alone. `bash -s -- --help` after the pipe lists everything.
+```
+uv run kitaru login --local    local, in Docker. Free, open source.
+uv run kitaru login            managed cloud. 14-day trial, no credit card required.
+```
+
+(Inside a project Kitaru is not on your PATH, hence `uv run`. The isolated install uses plain `kitaru`.)
+
+Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades.
+
+{% hint style="info" %}
+**Not in a repository?** Run it anywhere and it installs an isolated `kitaru` CLI on your PATH instead (a `uv tool` environment under `~/.local/share/uv/tools/kitaru`). That is enough to log in, import traces, run evaluators, and serve MCP, but replays need Kitaru inside the agent's own project, so re-run the installer there when you have one. `--project` and `--global` force either mode.
+{% endhint %}
+
+| Option | Effect |
+| --- | --- |
+| `--version 0.24.0` | Pin a Kitaru release (`--pre` allows pre-releases) |
+| `--with kitaru-pydantic-ai` | Also install a package into the same environment (repeatable) |
+| `--server https://your-team.kitaru.ai` | Point the MCP server at a team server instead of `http://localhost:8000` |
+| `--project` / `--global` | Force the in-project or the isolated install |
+| `--no-skills`, `--no-mcp` | Skip those steps |
+| `--no-modify-path` | Leave your shell rc files alone (global mode) |
+
+`curl -fsSL https://kitaru.ai/install | bash -s -- --help` lists everything, with environment-variable equivalents.
 
-Prefer to do it by hand? The installer is three commands, which you can run yourself:
+**Prefer to do it by hand?** Inside your repository, the installer is equivalent to:
 
 ```bash
-uv tool install "kitaru[cli,mcp,worker]"     # CLI + MCP server, isolated from your projects
-npx skills add zenml-io/kitaru-skills          # the coding-agent skills
-kitaru login --local                           # local server in Docker, or: kitaru login <team-url>
+uv add "kitaru[cli,mcp,worker]" kitaru-pydantic-ai    # into this project; pick your adapter
+npx skills add zenml-io/kitaru-skills                  # the coding-agent skills
 ```
 
-then point your assistant at `kitaru-mcp` as described in [Set up your coding agent](../agent-native/setup.md).
+plus registering `uv run kitaru-mcp --server http://localhost:8000 --mode standard` with your assistant, as described in [Set up your coding agent](../agent-native/setup.md).
 
-Already inside Claude Code, Codex, or Cursor? Paste this instead and it runs the same installer for you:
+**Already inside Claude Code, Codex, or Cursor?** Open your agent's repository there, paste this, and it runs the same installer for you:
 
 ```
-Set up Kitaru on this machine by following https://kitaru.ai/install.md. Use the one-line installer, tell me what it did, and stop before logging in if Docker is not running.
+Set up Kitaru in this repository by following https://kitaru.ai/install.md. Use the one-line installer and tell me what it did.
 ```
 
 ## Verify
@@ -42,7 +63,7 @@ Set up Kitaru on this machine by following https://kitaru.ai/install.md. Use the
 kitaru doctor
 ```
 
-It checks the CLI, the server connection, authentication, and whether the skills are installed. If the installer skipped login because Docker was not running, start Docker and run `kitaru login --local`; the section below covers the local server's lifecycle.
+It checks the CLI, the server connection, authentication, and whether the skills are installed. Server connection and authentication fail until you have run `kitaru login --local` (needs [Docker](https://docs.docker.com/get-started/get-docker/)) or `kitaru login` for the managed cloud; the sections below cover both.
 
 Then read the [Quickstart](quickstart.md). It is written as prompts for your coding agent, and everything it needs is now in place.
 
@@ -81,7 +102,7 @@ Node applications can also reuse a developer's selected CLI login without export
 
 ## Other ways to install
 
-The installer is the right choice for the CLI on a laptop. The paths below are for when Kitaru has to live inside a specific environment: your agent's own code, a Node project, CI, or a machine where you only want the skills.
+The installer run inside your agent's repository already installs into that project. The paths below are for adding the SDK by hand, Node projects, CI, or a machine where you only want the skills.
 
 Kitaru is three pieces: the **SDK + CLI**, a **server** your team shares (self-hosted, one per team), and **workers** that execute replays and evaluations in your environment. The CLI, server, and workers require **Python 3.11 or newer**; TypeScript agents use Node **22.22 or newer in the Node 22 release line** and connect to the same server. The server stores everything in **PostgreSQL**, provisioned for you locally by `kitaru login --local`; a [self-hosted deployment](../deploy/README.md) brings its own. Workers are plain processes (`kitaru worker start`) that run wherever your agent's environment lives; for containerized fleets, the published `zenmldocker/kitaru-worker` image works out of the box (see [Workers in production](../deploy/workers.md)).