diff --git a/README.md b/README.md
index 19ab83a..74251d3 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,93 @@
-# steward
-Steward is a long-running, AI-assisted personal operations platform designed to reduce cognitive load by acting as a persistent, trustworthy steward of both digital infrastructure and delegated personal objectives
+# Steward
+
+Steward is a long-running, AI-assisted personal operations platform designed to reduce cognitive load by acting as a persistent, trustworthy steward of both digital infrastructure and delegated personal objectives.
+
+## Features
+
+- **Telegram Bot**: Group/channel support with thread-based conversations
+- **Message Threads**: Organized conversations with automatic summarization
+- **Knowledge Base**: Stores and retrieves conversation summaries
+- **LLM Integration**: OpenAI-compatible API support
+- **Tool Calling**: Optional MCP/OpenAPI tool server integration
+- **Flexible Configuration**: YAML + environment variables (Kubernetes-ready)
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- Docker & Docker Compose
+- Telegram Bot Token (from [@BotFather](https://t.me/botfather))
+- OpenAI API Key
+
+### Local Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/djw4/steward.git
+cd steward
+```
+
+2. Copy `.env.example` to `.env` and fill in your values:
+```bash
+cp .env.example .env
+# Edit .env with your tokens and IDs
+```
+
+3. Create the data directory:
+```bash
+mkdir -p data
+```
+
+4. Start with Docker Compose:
+```bash
+docker compose -f docker-compose.dev.yml up --build
+```
+
+### Configuration
+
+See [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration options.
+
+### Running Tests
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=steward
+```
+
+### Pre-commit Hooks
+
+Set up pre-commit hooks to run linting and tests automatically:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This will run:
+- `ruff check` for code style
+- `pytest` for tests
+
+On every commit. You can skip with `git commit --no-verify` if needed.
+
+## Development
+
+- Read [AGENTS.md](AGENTS.md) for AI agent guidelines
+- Read [CONFIGURATION.md](CONFIGURATION.md) for config management
+- Check [.github/workflows/ci.yml](.github/workflows/ci.yml) for CI/CD pipeline
+
+## Deployment
+
+For Kubernetes deployment, see examples in [CONFIGURATION.md](CONFIGURATION.md#kubernetes).
+
+Production image: `ghcr.io/djw4/steward:latest`
+
+## License
+
+See LICENSE file for details.