diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..97d2632
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,18 @@
+HTTP_PORT=3000
+BOT_NAME=Herald
+
+WEBHOOK_SIG_HEADER_SECRET=
+
+OPEN_ROUTER_API_KEY=
+OPEN_ROUTER_MODEL=deepseek/deepseek-v4-flash
+OPEN_ROUTER_TIMEOUT=120
+
+BOT_MAX_CONCURRENT=5
+
+GITEA_URL=https://gitea.example.com
+GITEA_TOKEN=
+GITEA_TIMEOUT=30
+
+# Optional
+SENTRY_DSN=
+RUST_LOG=info
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..93d73d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# Herald
+
+Herald is a Gitea bot that performs automated AI-powered code reviews on pull requests using [OpenRouter](https://openrouter.ai/).
+
+## Features
+
+- Listens for Gitea webhook events and triggers code reviews on pull request comments
+- Streams reviews back to Gitea as PR comments
+- Concurrent review processing with configurable parallelism
+- Graceful shutdown — in-progress reviews finish before the process exits
+- Error tracking via Sentry
+- Tiny memory footprint (~4MB) thanks to Rust
+
+## Installation
+
+**Requirements:** Rust toolchain ([rustup.rs](https://rustup.rs))
+
+```sh
+cargo build --release
+./target/release/herald
+```
+
+Herald reads its configuration from environment variables (a `.env` file is supported):
+
+| Variable | Description |
+|---|---|
+| `HTTP_PORT` | Port to listen on |
+| `BOT_NAME` | The bot's Gitea username (used to detect mentions) |
+| `WEBHOOK_SIG_HEADER_SECRET` | Gitea webhook secret for signature verification |
+| `OPEN_ROUTER_API_KEY` | OpenRouter API key |
+| `OPEN_ROUTER_MODEL` | Model to use (e.g. `deepseek/deepseek-v4-flash`) |
+| `OPEN_ROUTER_TIMEOUT` | OpenRouter request timeout in seconds |
+| `BOT_MAX_CONCURRENT` | Maximum number of concurrent reviews |
+| `GITEA_URL` | Base URL of your Gitea instance |
+| `GITEA_TOKEN` | Gitea API token |
+| `GITEA_TIMEOUT` | Gitea API request timeout in seconds |
+| `SENTRY_DSN` | *(optional)* Sentry DSN for error tracking |
+| `RUST_LOG` | *(optional)* Log level, defaults to `info` |
+
+## Development
+
+The easiest way to get started is with the provided [Dev Container](https://containers.dev/) (VS Code or Zed with the dev container extension).
+
+Open the project and reopen it in the container — the Rust toolchain is pre-installed.
+
+**Without Dev Container**, you just need a Rust toolchain:
+
+```sh
+rustup toolchain install stable
+cargo run
+```
+
+Copy `.env.example` to `.env` and fill in your values before running.