diff --git a/README.md b/README.md
new file mode 100644
index 0000000..63091a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# capnpc-py
+
+Cap'n Proto Python type stub generator — a `capnp compile` plugin.
+
+Generates `.pyi` type stub files for Cap'n Proto schemas, providing IDE autocompletion and static type checking support via Pyright/Pylance.
+
+## Requirements
+
+- **Python** >= 3.10
+- **pycapnp** >= 2.0.0 (Python package, installed automatically)
+- **Cap'n Proto** >= 1.0 (system package, must be installed separately)
+
+### Installing Cap'n Proto
+
+| Platform | Command |
+|----------|---------|
+| Arch Linux | `sudo pacman -S capnproto` |
+| Ubuntu/Debian | `sudo apt install capnproto` |
+| macOS | `brew install capnp` |
+| Windows | Download from [capnproto.org](https://capnproto.org) |
+
+## Installation
+
+```bash
+pip install capnpc-py
+```
+
+## Usage
+
+```bash
+capnp compile -opy myschema.capnp
+```
+
+This generates `myschema_capnp.pyi` — a Python type stub file that type checkers can use. Runtime import (`import myschema_capnp`) is handled automatically by pycapnp's import hook.
+
+### Generated output
+
+For a schema like:
+```capnp
+struct Person {
+  name @0 :Text;
+  age  @1 :Int32;
+}
+
+enum Gender { male @0; female @1; }
+```
+
+`myschema_capnp.pyi`:
+```python
+"""Auto-generated type stub for myschema.capnp"""
+from __future__ import annotations
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from typing import IO, Literal
+
+Gender = Literal["male", "female"]
+
+class Person:
+    name: str
+    age: int
+
+    @staticmethod
+    def new_message(**kwargs) -> PersonBuilder: ...
+    @staticmethod
+    @contextmanager
+    def from_bytes(data: bytes, ...) -> Iterator[PersonReader]: ...
+    @staticmethod
+    def from_bytes_packed(data: bytes, ...) -> PersonReader: ...
+    def to_dict(self) -> dict: ...
+
+class PersonReader(Person):
+    def as_builder(self) -> PersonBuilder: ...
+
+class PersonBuilder(Person):
+    @staticmethod
+    def from_dict(dictionary: dict) -> PersonBuilder: ...
+    def copy(self) -> PersonBuilder: ...
+    def to_bytes(self) -> bytes: ...
+    def to_bytes_packed(self) -> bytes: ...
+    def to_segments(self) -> list[bytes]: ...
+    def as_reader(self) -> PersonReader: ...
+    @staticmethod
+    def write(file: IO[bytes]): ...
+    @staticmethod
+    def write_packed(file: IO[bytes]): ...
+```
+
+## Development
+
+Uses [PDM](https://pdm-project.org/) for project management.
+
+```bash
+git clone https://github.com/capnproto/pycapnp  # or your fork
+cd capnp-py
+pdm install      # installs dependencies + dev tools
+pdm run pytest   # run tests
+```
+
+## Supported Features
+
+| Feature | Status |
+|---------|--------|
+| Structs (Reader/Builder classes) | ✅ |
+| Enums (Literal aliases) | ✅ |
+| Nested types | ✅ |
+| Lists (Sequence[T]) | ✅ |
+| Unions (which/init) | ✅ |
+| Self-referencing structs | ✅ |
+| Interfaces (RPC) | ⏳ Phase 3 |
+| Constants | ⏳ Phase 2 |
+| Generics | ⏳ Phase 2 |
+
+## License
+
+MIT