diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2e1661
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# Image Moderation Service
+
+TypeScript/Express service that checks uploaded images for NSFW/explicit content using a local vision LLM running on an AMD NPU. When an image is flagged unsafe, it fires callbacks to replace the image and flag the user.
+
+## How It Works
+
+1. An image is uploaded to `POST /moderate`
+2. The image is sent to the local vision LLM (gemma3:4b via FLM proxy) for analysis
+3. The LLM classifies the image as safe or unsafe
+4. If unsafe and metadata was provided, two callbacks fire (fire-and-forget):
+   - **Upload service** — replaces the image with a stub
+   - **Parochia** — flags the user for moderation
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/moderate` | Moderate an image (multipart: `file`, `context`, `imagePath`, `userId`, `siteId`) |
+| `GET` | `/health` | Health check |
+
+## Configuration
+
+All configuration is via environment variables (`.env` file):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8100` | Service port |
+| `VISION_AI_URL` | `http://localhost:8000/v1/chat/completions` | Vision LLM endpoint |
+| `VISION_AI_MODEL` | `gemma3:4b` | Vision model to use |
+| `UPLOAD_SERVICE_REPLACE_URL` | — | Callback URL to replace flagged images |
+| `UPLOAD_SERVICE_SECRET` | — | Auth secret for upload service callback |
+| `PAROCHIA_CALLBACK_URL` | — | Callback URL to flag users in Parochia |
+| `PAROCHIA_CALLBACK_SECRET` | — | Auth secret for Parochia callback |
+
+## Usage
+
+```bash
+npm install        # Install dependencies
+npm run build      # Compile TypeScript → dist/
+npm start          # Run the service
+npm run dev        # Development mode with hot-reload
+
+# Windows service
+node service-install.js
+node service-uninstall.js
+```
+
+## Project Structure
+
+```
+src/
+  server.ts      — Express app, routes, callback logic
+  moderate.ts    — Image moderation logic (vision LLM calls)
+```
+
+## Dependencies
+
+- **express** — HTTP server
+- **multer** — Multipart file upload handling
+- **sharp** — Image processing
+- **dotenv** — Environment variable loading
+- **node-windows** — Windows service management
+
+## Environment
+
+- **OS:** Windows 11, AMD NPU hardware
+- **Runtime:** Node.js + TypeScript
+- **Vision LLM:** gemma3:4b served by FLM proxy on localhost:8000