diff --git a/tools/ora_editor/README.md b/tools/ora_editor/README.md
index 86817b3..3bcf6a5 100644
--- a/tools/ora_editor/README.md
+++ b/tools/ora_editor/README.md
@@ -15,6 +15,85 @@ pip install -r requirements.txt
 python app.py
 ```
 
+The editor will be available at: http://localhost:5000
+
+## Features
+
+- **Open PNG/ORA files**: Enter file path relative to project root
+- **Layer management**: Toggle visibility, rename, delete, reorder layers  
+- **Polygon drawing**: Draw polygons to guide mask extraction
+- **Mask extraction**: Use ComfyUI to extract masks from images with optional polygon overlay
+- **Krita integration**: Open layers in Krita for manual editing
+- **Settings**: Configure ComfyUI server URL
+- **Client-side logging**: Console logs for debugging UI interactions
+
+## Usage Workflow
+
+1. **Open a file**: Enter path to PNG or ORA file (relative to `/home/noti/dev/ai-game-2`)
+   - Click "Open" button
+   - File auto-converts to ORA if PNG
+2. **View layers**: See all layers with visibility checkboxes in sidebar
+3. **Draw polygon** (optional for mask extraction):
+   - Click "Start Drawing" button
+   - Click on image to add points
+   - Double-click or Enter/Escape when done
+   - Points shown with colored markers
+4. **Extract mask**:
+   - Enter subject description (e.g., "the door")
+   - Optionally check "Use polygon hint" if you've drawn a polygon
+   - Click "Extract Mask"
+   - Status shown while polling ComfyUI
+5. **Review results**: See preview modal with extracted mask
+6. **Add to ORA**: Click "Use This Mask" to add as new layer
+7. **Edit in Krita** (optional): Select layer, open in Krita for manual work
+8. **Save**: Persist all changes
+
+## Debugging
+
+### Client-side Logging
+Open browser console (F12) to see detailed logs:
+- `[ORA EDITOR] Opening file:` - File open events
+- `[ORA EDITOR] Extracting mask:` - Mask extraction flow
+- `[ORA EDITOR] Polygon drawing` - Canvas interactions
+- `[ORA EDITOR] Canvas setup` - Canvas initialization
+
+### Backend Logging
+Check Flask server logs for:
+- `[MASK EXTRACT]` - Mask extraction process
+- `[POLYGON]` - Polygon storage and operations
+- `[API]` - API request/response handling
+
+## ComfyUI Setup
+
+- **Default URL**: `127.0.0.1:8188`
+- **Polygon support**: When "Use polygon hint" is checked, the polygon overlay is drawn on the base image before sending to ComfyUI
+- **Status polling**: App polls ComfyUI for mask completion, downloads result automatically
+
+## API Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/open` | POST | Open PNG/ORA file |
+| `/api/save` | POST | Save current state |
+| `/api/layers` | GET | Get layer list |
+| `/api/layer/*` | POST | Layer operations (add, rename, delete, reorder, visibility) |
+| `/api/polygon` | POST | Draw polygon overlay |
+| `/api/mask/extract` | POST | Extract mask via ComfyUI |
+| `/api/krita/open` | POST | Open layer in Krita |
+| `/api/krita/status/<layer_name>` | GET | Check Krita temp file status |
+| `/api/file/mask` | GET | Serve mask file from temp |
+
+## Testing
+
+```bash
+# Test ORA operations
+python test_ora_ops.py
+
+# Test Flask API
+python test_app.py
+```
+
+
 The editor will be available at: http://localhost:5000
 
 ## Features
diff --git a/tools/ora_editor/__init__.py b/tools/ora_editor/__init__.py
new file mode 100644
index 0000000..d210b6c
--- /dev/null
+++ b/tools/ora_editor/__init__.py
@@ -0,0 +1,2 @@
+# ORA Editor package
+from .app import app
diff --git a/tools/ora_editor/test_app.py b/tools/ora_editor/test_app.py
index eef0109..4269c5f 100644
--- a/tools/ora_editor/test_app.py
+++ b/tools/ora_editor/test_app.py
@@ -10,9 +10,9 @@ from PIL import Image
 # Setup path
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from flask import Flask
-
-from ora_editor.app import app
+# Import the ora_editor package (not the app module directly)
+import ora_editor
+app = ora_editor.app
 
 
 def test_index():