diff --git a/DEVELOPMENT-SETUP.md b/DEVELOPMENT-SETUP.md
new file mode 100644
index 0000000..7338d09
--- /dev/null
+++ b/DEVELOPMENT-SETUP.md
@@ -0,0 +1,204 @@
+# Development Environment Setup
+
+This guide walks through installing everything needed to run Sloth Manager locally for development and testing, on both Windows 11 and Debian Linux.
+
+---
+
+## Windows 11
+
+### 1. Install Node.js
+
+Download and run the LTS installer from **https://nodejs.org** (choose "LTS").
+
+Verify the installation:
+
+```powershell
+node --version
+npm --version
+```
+
+Both commands should return a version number.
+
+### 2. Install Git
+
+Download and run the installer from **https://git-scm.com/download/win**.
+
+Accept the defaults. When asked about the default editor, choose whichever you prefer.
+
+Verify:
+
+```powershell
+git --version
+```
+
+### 3. Clone the repository
+
+Open PowerShell or Windows Terminal:
+
+```powershell
+git clone https://your-gitea.com/youruser/sloth-manager.git
+cd sloth-manager
+```
+
+### 4. Configure the backend
+
+```powershell
+cd backend
+copy .env.example .env
+notepad .env
+```
+
+Fill in your provider credentials. At minimum set a `JWT_SECRET`:
+
+```
+JWT_SECRET=any-long-random-string-for-dev
+```
+
+### 5. Install dependencies and start the backend
+
+```powershell
+npm install
+npm run dev
+```
+
+The backend will start on `http://localhost:3001`. Leave this terminal open.
+
+### 6. Configure and start the frontend
+
+Open a second terminal window:
+
+```powershell
+cd frontend
+copy .env.example .env
+npm install
+npm start
+```
+
+The browser will open automatically at `http://localhost:3000`.
+
+### 7. First login
+
+Log in with `admin` / `admin` and change the password immediately in **👤 My Profile**.
+
+---
+
+## Debian (12 Bookworm / 11 Bullseye)
+
+### 1. Install Node.js
+
+The version in Debian's default repositories is outdated. Install the current LTS via NodeSource:
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+Verify:
+
+```bash
+node --version
+npm --version
+```
+
+### 2. Install Git
+
+```bash
+sudo apt update
+sudo apt install -y git
+```
+
+Verify:
+
+```bash
+git --version
+```
+
+### 3. Clone the repository
+
+```bash
+git clone https://your-gitea.com/youruser/sloth-manager.git
+cd sloth-manager
+```
+
+### 4. Configure the backend
+
+```bash
+cd backend
+cp .env.example .env
+nano .env
+```
+
+Fill in your provider credentials. At minimum set a `JWT_SECRET`:
+
+```
+JWT_SECRET=any-long-random-string-for-dev
+```
+
+### 5. Install dependencies and start the backend
+
+```bash
+npm install
+npm run dev
+```
+
+The backend will start on `http://localhost:3001`. Leave this terminal open.
+
+### 6. Configure and start the frontend
+
+Open a second terminal:
+
+```bash
+cd frontend
+cp .env.example .env
+npm install
+npm start
+```
+
+Open `http://localhost:3000` in your browser.
+
+### 7. First login
+
+Log in with `admin` / `admin` and change the password immediately in **👤 My Profile**.
+
+---
+
+## Verify everything is working
+
+Once both services are running, confirm the following in the browser:
+
+- The login page loads at `http://localhost:3000`
+- After logging in, the Overview page shows the dashboard
+- Selecting a provider and pressing **⟳ Sync** fetches records without errors
+- **⚙️ Settings → Provider Status → Run Check** shows green for configured providers
+
+---
+
+## Stopping the development servers
+
+Press `Ctrl+C` in each terminal to stop the backend and frontend.
+
+---
+
+## Useful development tips
+
+**Backend auto-restarts** — nodemon watches for file changes and restarts the backend automatically. You do not need to restart it manually after editing backend files.
+
+**Frontend hot-reloads** — the React dev server reloads the browser automatically when frontend files change.
+
+**Nodemon and new files** — if you add a brand new file to the backend (not just edit an existing one), nodemon may not pick it up. Stop it with `Ctrl+C` and run `npm run dev` again.
+
+**Viewing backend logs** — all errors and audit events are printed to the terminal running the backend.
+
+**Data files** — in development, data files (`users.json`, `dns-cache.json`, etc.) are created in the `backend/` folder. These are gitignored and will not be committed.
+
+---
+
+## Summary of commands
+
+| Task | Windows | Debian |
+|------|---------|--------|
+| Copy env file | `copy .env.example .env` | `cp .env.example .env` |
+| Install deps | `npm install` | `npm install` |
+| Start backend | `npm run dev` | `npm run dev` |
+| Start frontend | `npm start` | `npm start` |
+| Open app | `http://localhost:3000` | `http://localhost:3000` |