feat: update setup instructions and dependencies for uv integration

README.md

@@ -14,16 +14,16 @@ interactive story engine where the AI is load-bearing for the experience.
 ## Quickstart
 
 ```bash
-python -m venv .venv
-source .venv/bin/activate         # Windows: .venv\Scripts\activate
-pip install -r requirements.txt
+uv sync                           # create .venv and install everything from the lockfile
 
 # Optional: add your API key for live inference
 cp .env.example .env              # then fill in OPENAI_API_KEY
 
-python app.py
+uv run app.py
 ```
 
+> Don't have [uv](https://docs.astral.sh/uv/)? `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
 The app runs on a **deterministic local stub** with no API key — great for testing
 and demos that need to be fully reproducible.  Add an `OPENAI_API_KEY` to switch to
 live inference.  Any OpenAI-compatible endpoint works (Together AI, Groq, Ollama,
@@ -32,7 +32,7 @@ NVIDIA NIM) — set `OPENAI_BASE_URL` in `.env`.
 ### Run tests
 
 ```bash
-python -m pytest tests/ -v
+uv run pytest tests/ -v
 ```
 
 ---
@@ -217,9 +217,9 @@ modal_app.py                Optional: serverless scheduled run (Modal)
 ```bash
 # 1. Build the thinnest slice
 # 2. Record the decision
-python -c "from scripts.new_journal_entry import main; main()" "What changed today"
+uv run python -c "from scripts.new_journal_entry import main; main()" "What changed today"
 # 3. Regenerate the living blog
-python scripts/snapshot_progress.py
+uv run scripts/snapshot_progress.py
 # 4. Confirm nothing broke
-python -m pytest tests/ -q
+uv run pytest tests/ -q
 ```

docs/architecture/next-steps/phase-3-persistence-recovery.md

@@ -145,7 +145,7 @@ embed = ["sentence-transformers>=2.7.0", "numpy>=1.26.0"]
 ```
 
 Not required — falls back to Jaccard if not installed.
-Install with: `pip install "multi-agent-land[embed]"`
+Install with: `uv sync --extra embed`
 
 ---
 

docs/runbooks/local-dev.md

@@ -3,23 +3,21 @@
 ## Start
 
 ```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python app.py
+uv sync          # create .venv and install from the lockfile
+uv run app.py
 ```
 
 ## Journal
 
 ```bash
-python scripts/new_journal_entry.py "Scaffolded walking skeleton"
-python scripts/snapshot_progress.py
+uv run scripts/new_journal_entry.py "Scaffolded walking skeleton"
+uv run scripts/snapshot_progress.py
 ```
 
 ## Checks
 
 ```bash
-python -m compileall app.py src scripts
+uv run python -m compileall app.py src scripts
 ```
 
 Add formal tests once the first persistent ledger and provider adapters land.

modal_app.py

@@ -17,10 +17,11 @@ DEFAULT_SCENARIO = "thousand-token-wood"
 TICKS_PER_EPISODE = 60
 
 # Mount the whole repo (code + config/) so the registry resolves config via the
-# same __file__ logic it uses locally.  Deps come from requirements.txt.
+# same __file__ logic it uses locally.  Deps come from pyproject.toml (single
+# source of truth, pinned locally by uv.lock).
 image = (
     modal.Image.debian_slim()
-    .pip_install_from_requirements("requirements.txt")
+    .pip_install_from_pyproject("pyproject.toml")
     .add_local_dir(
         ".",
         remote_path="/root",

requirements-dev.txt

@@ -1,4 +0,0 @@
--r requirements.txt
-pytest>=8.2.0
-ruff>=0.5.0
-

requirements.txt

@@ -1,5 +0,0 @@
-gradio>=4.44.0
-pydantic>=2.8.0
-python-dotenv>=1.0.1
-openai>=1.40.0
-pyyaml>=6.0

src/models/openai_compat.py

@@ -35,7 +35,7 @@ class OpenAICompatProvider(ModelProvider):
             except ImportError as exc:
                 raise ImportError(
                     "openai package is required for OpenAICompatProvider. "
-                    "Run: pip install openai"
+                    "Run: uv add openai"
                 ) from exc
             kwargs: dict = {}
             if self.base_url: