diff --git a/Development-Guide.-.md b/Development-Guide.-.md
new file mode 100644
index 0000000..8c1c671
--- /dev/null
+++ b/Development-Guide.-.md
@@ -0,0 +1,85 @@
+# Development Guide
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/media-rip` |
+| **Page** | `Development-Guide` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Testing
+
+### Backend (pytest)
+
+```bash
+cd backend
+pip install -r requirements.txt
+pytest tests/ -v -m "not integration"
+```
+
+14 test files covering: API routes, database, download service, SSE broker, sessions, config, models, themes, health, purge, output templates.
+
+### Frontend (Vitest)
+
+```bash
+cd frontend
+npm install
+npx vitest run
+```
+
+5 test files covering: Pinia stores, SSE composable, type definitions.
+
+### Linting
+
+```bash
+cd backend && ruff check .
+cd frontend && npx vue-tsc --noEmit
+```
+
+## CI/CD
+
+### CI (`.github/workflows/ci.yml`)
+
+Runs on every push/PR to main:
+1. Backend: ruff lint + pytest
+2. Frontend: vue-tsc + vitest
+3. Docker: smoke build (no push)
+
+### Publish (`.github/workflows/publish.yml`)
+
+Triggers on `v*.*.*` tags:
+- Multi-arch build (amd64 + arm64)
+- Push to `ghcr.io/xpltdco/media-rip`
+- Creates GitHub Release
+
+## Code Patterns
+
+### Adding an API Endpoint
+
+1. Create/edit router in `backend/app/routers/`
+2. Add Pydantic models in `backend/app/models/`
+3. Register router in `backend/app/main.py`
+4. Add `Depends(get_session_id)` for session-scoped endpoints
+5. Add frontend API call in `frontend/src/api/client.ts`
+
+### Adding a Theme
+
+1. Create CSS file in `frontend/src/themes/`
+2. Define all CSS custom properties (copy existing theme as template)
+3. Import in `frontend/src/main.ts`
+4. Add to theme picker component
+
+### Adding a Background Service
+
+1. Create service in `backend/app/services/`
+2. Initialize in `main.py` lifespan context
+3. Attach to `app.state` for access in route handlers
+4. Clean up in lifespan shutdown
+
+## Conventions
+
+- **Python**: async/await throughout, Pydantic for validation, ruff for linting
+- **TypeScript**: Vue 3 Composition API, Pinia stores, strict mode
+- **Files**: snake_case (Python), PascalCase (Vue components), camelCase (TS utilities)
+- **Testing**: pytest markers for integration tests (`@pytest.mark.integration`)
\ No newline at end of file