diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0d0cfcb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# NotesVault Client
+
+A React/Vite web interface for the [notesvault](https://git.seanstarkey.dev/notesvault) project.
+
+This app provides the browser UI for signing in, creating notes, editing notes, searching, sharing, and connecting to a NotesVault API backend.
+
+## Requirements
+
+- Node.js 22 or newer
+- npm
+- Docker, for container builds and local container runs
+- A running NotesVault API backend
+
+## Local Development
+
+Install dependencies:
+
+```sh
+npm ci
+```
+
+Start the Vite development server:
+
+```sh
+npm run dev
+```
+
+The development server proxies `/api` requests to `http://localhost:8080` by default.
+
+## Build
+
+Build the production app into `dist/`:
+
+```sh
+npm run build
+```
+
+Or use Make:
+
+```sh
+make build
+```
+
+## Docker
+
+Build the Docker image:
+
+```sh
+make docker-build
+```
+
+Run the container:
+
+```sh
+make docker-run
+```
+
+By default, the app is served at:
+
+```text
+http://localhost:8081
+```
+
+The container proxies `/api` requests to `http://host.docker.internal:8080`. Override the port or API upstream when needed:
+
+```sh
+make docker-run HOST_PORT=3000 NOTES_API_UPSTREAM=http://host.docker.internal:8080
+```
+
+Stop the container:
+
+```sh
+make docker-stop
+```
+
+## Make Targets
+
+```sh
+make help
+```
+
+Available targets include:
+
+- `make install`
+- `make build`
+- `make docker-build`
+- `make docker-run`
+- `make docker-stop`
+- `make docker-restart`
+- `make docker-logs`
+- `make docker-clean`
+
+## API Configuration
+
+The app uses `/api` by default. In local development, Vite proxies that path to the backend configured in `vite.config.js`.
+
+In Docker, nginx proxies `/api` through the `NOTES_API_UPSTREAM` environment variable.