diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a64658c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# librenotes
+
+[![CI](https://git.librete.ch/public/librenotes/actions/workflows/ci.yml/badge.svg)](https://git.librete.ch/public/librenotes/actions)
+
+Cloud-native, multi-tenant notes application. A fork of
+[Notesium](https://github.com/alonswartz/notesium) extended with
+authentication, per-user data isolation, sync, and PWA support so it can
+run as a hosted service at [librenot.es](https://librenot.es).
+
+## Features
+
+- Markdown notes with bi-directional links (Zettelkasten / evergreen notes)
+- Embedded web app — no Electron, no Node runtime, single static binary
+- Multi-tenant backend with magic-link authentication (in development)
+- Offline-capable PWA with background sync (planned, Phase 4)
+
+## Build
+
+Requires Go 1.20 or later.
+
+```sh
+go build ./cmd/librenotes
+```
+
+This produces a `librenotes` binary in the current directory. The web
+frontend and shell completion are embedded into the binary at compile
+time, so no extra files are needed at runtime.
+
+A Makefile with `build`, `test`, `run`, and `clean` targets is provided
+for convenience:
+
+```sh
+make build
+make test
+```
+
+## Run
+
+```sh
+./librenotes web --notes-dir ~/notes
+```
+
+See `./librenotes help` for the full command list.
+
+## Development setup
+
+A Nix flake provides a reproducible development environment with Go,
+build tools, and the project CLIs:
+
+```sh
+nix develop
+```
+
+The repository layout follows the standard Go project structure:
+
+```
+cmd/librenotes/      Binary entry point
+internal/notesium/   Core notes package (forked from Notesium)
+internal/notesium/web/   Embedded frontend assets
+```
+
+The Go module path is `git.librete.ch/public/librenotes`.
+
+## Fork attribution
+
+librenotes is a fork of [Notesium](https://github.com/alonswartz/notesium)
+by Alon Swartz, used and redistributed under the MIT License. See
+[NOTICE](./NOTICE) for the upstream commit hash at fork time and
+instructions for tracking upstream changes.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Copyright is shared between the original
+Notesium author and the librenotes contributors.