diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..572bf09
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,40 @@
+.PHONY: install run dev clean setup \
+        frontend-install frontend-dev frontend-build
+
+# ── Backend Setup ──────────────────────────────────────────────────────────
+
+install:                           ## Install Python dependencies via uv
+	uv sync
+
+setup: .env                         ## Full first-time backend setup
+	uv run python -m backend.main
+
+.env: .env.example
+	cp .env.example .env
+	@echo "Created .env from .env.example — edit it with your real values."
+
+# ── Backend Development ────────────────────────────────────────────────────
+
+run:                               ## Start the backend (reload enabled)
+	uv run python -m backend.main
+
+dev:                               ## Alias for run
+	uv run python -m backend.main
+
+# ── Frontend ───────────────────────────────────────────────────────────────
+
+frontend-install:                  ## Install frontend dependencies
+	cd frontend && bun install
+
+frontend-dev:                      ## Start the Vite dev server
+	cd frontend && bun run dev
+
+frontend-build:                    ## Build frontend for production
+	cd frontend && bun run build
+
+# ── Utilities ──────────────────────────────────────────────────────────────
+
+clean:                             ## Remove caches and build artifacts
+	rm -rf __pycache__ .venv build dist *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
diff --git a/README.md b/README.md
index 70850ce..6b45114 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,16 @@ An agentic AI application built with **pydantic-ai**, featuring a FastAPI backen
 
 ```
 agent_alpha/
-├── agent_a.py              # Standalone agent runner (CLI)
+├── .env.example             # Environment variable template
+├── .gitignore
+├── Makefile                 # Common dev commands
 ├── pyproject.toml           # Python deps & metadata
 ├── backend/
 │   ├── app.py               # FastAPI application factory
 │   ├── main.py              # Uvicorn entry point
 │   ├── core/
-│   │   └── agent.py         # Agent lifecycle & inference
+│   │   ├── agent.py         # Agent lifecycle & inference
+│   │   └── config.py        # pydantic-settings config
 │   └── routes/
 │       ├── chat.py          # POST /api/chat
 │       └── health.py        # GET  /api/health
@@ -36,33 +39,55 @@ agent_alpha/
 
 ## Quick Start
 
-### 1. Python environment
+### 1. Configuration
 
 ```bash
-uv sync                     # Create .venv & install deps
+cp .env.example .env   # then edit .env with your LLM endpoint & model
 ```
 
 ### 2. Backend (FastAPI)
 
 ```bash
-uv run python -m backend.main
-# → http://localhost:8000
-# → API docs at http://localhost:8000/docs
+make install            # uv sync — create .venv & install deps
+make run                # → http://localhost:8000
+                        # → API docs at http://localhost:8000/docs
 ```
 
 ### 3. Frontend (React + Vite)
 
 ```bash
-cd frontend
-npm install
-npm run dev
-# → http://localhost:5173
+make frontend-install   # bun install
+make frontend-dev       # → http://localhost:5173
 ```
 
 The Vite dev server proxies `/api/*` requests to the FastAPI backend.
 
 ---
 
+## Makefile Commands
+
+| Command                  | Description                          |
+| ------------------------ | ------------------------------------ |
+| `make install`           | Install Python deps via `uv sync`    |
+| `make run` / `make dev`  | Start the FastAPI backend (reload)   |
+| `make frontend-install`  | Install frontend deps via `bun`      |
+| `make frontend-dev`      | Start the Vite dev server            |
+| `make frontend-build`    | Build frontend for production        |
+| `make clean`             | Remove caches and build artifacts    |
+
+---
+
+## Configuration
+
+Environment variables are loaded from `.env` via **pydantic-settings** (see `backend/core/config.py`).
+
+| Variable       | Default                       | Description           |
+| -------------- | ----------------------------- | --------------------- |
+| `LLM_BASE_URL` | `http://localhost:11434/v1`   | OpenAI-compatible API |
+| `LLM_MODEL`    | `llama`                       | Model name to use     |
+
+---
+
 ## API Endpoints
 
 | Method | Path          | Description                  |
@@ -88,7 +113,7 @@ The Vite dev server proxies `/api/*` requests to the FastAPI backend.
 - **Web search** (DuckDuckGo / provider-adaptive)
 - **MCP tool integration** (Hacker News, etc.)
 - **Context management** (sliding window + LLM compaction)
-- **Memory persistence** (`./MEMORY.md`)
+- **Memory persistence**
 - **Sub-agents** (e.g., `researcher`)
 - **Task tracking** with subtask support
 - **Safety shields**: cost caps, input guards, tool approval, secret redaction, stuck-loop detection