diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c115543
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# matheval
+
+A math expression evaluator with an interactive REPL, written in Go.
+
+## Features
+
+- Arithmetic operators: `+`, `-`, `*`, `/`
+- Parentheses for grouping
+- Floating point numbers (including `.5` syntax)
+- Correct operator precedence (`*` and `/` bind tighter than `+` and `-`)
+- Left-to-right associativity
+- Clear error messages with position reporting
+
+## Build
+
+```sh
+go build -o matheval ./cmd/matheval
+```
+
+## Usage
+
+Run the REPL:
+
+```sh
+./matheval
+```
+
+Then type expressions:
+
+```
+>> 2 + 3 * 4
+14
+>> (2 + 3) * 4
+20
+>> 7 / 2
+3.5
+>> 1 / 0
+error: division by zero
+```
+
+Press `Ctrl+D` (EOF) to exit.
+
+You can also pipe input:
+
+```sh
+echo "2 + 3" | ./matheval
+```
+
+## Architecture
+
+```
+Input string → Lexer → Parser → AST → Evaluator → Result
+```
+
+| Package     | Responsibility                        |
+|-------------|---------------------------------------|
+| `token`     | Token types and data structures       |
+| `lexer`     | Tokenizes input string                |
+| `ast`       | AST node types (`NumberLit`, `BinaryExpr`) |
+| `parser`    | Recursive-descent parser              |
+| `evaluator` | Walks AST and computes result         |
+| `repl`      | Read-eval-print loop                  |
+
+## Grammar
+
+```
+expr   → term (('+' | '-') term)*
+term   → factor (('*' | '/') factor)*
+factor → NUMBER | '(' expr ')'
+```
+
+## Tests
+
+```sh
+go test ./...
+```
+
+This runs unit tests for each package plus integration tests covering the full pipeline.