diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0998955
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# Outlook Relook
+
+A Chrome extension that reskins Outlook Web App (outlook.office.com) with minimalist themes and granular control over visual clutter.
+
+## Features
+
+- **Switchable themes:** Swiss (Helvetica minimalism) and Material (clean, subtle elevation)
+- **Light & Dark modes** with system preference detection
+- **~40 granular toggles** for density, element hiding, readability, and behavior
+- **MutationObserver** suppresses dynamically injected clutter (Copilot, banners, suggested replies)
+- **Behavior patches:** auto-collapse ribbon, suppress contact hover cards, auto-advance after delete, toast management
+- **Gmail-style keyboard navigation:** j/k to move, x/Space to multi-select, # delete, e archive, Shift+i/u read/unread, v move
+- **Quick actions:** "Mark all as read" button, Ctrl+Shift+K folder jump
+- **Settings sync** across Chrome instances via chrome.storage.sync
+- **Export/Import/Reset** settings
+
+## Install (Development)
+
+1. Clone this repo
+2. Open `chrome://extensions` in Chrome
+3. Enable "Developer mode" (top-right toggle)
+4. Click "Load unpacked" and select this directory
+5. Open [outlook.office.com](https://outlook.office.com) — the extension activates automatically
+
+## Usage
+
+Click the extension icon to open the settings panel. Changes apply immediately — no page reload needed.
+
+### Keyboard Shortcuts
+
+**Message list (Gmail-style):**
+- `j` / `Down Arrow` — Next message
+- `k` / `Up Arrow` — Previous message
+- `x` / `Space` — Toggle select
+- `Shift+Down` / `Shift+Up` — Extend selection
+- `#` — Delete selected
+- `e` — Archive selected
+- `Shift+i` — Mark read
+- `Shift+u` — Mark unread
+- `v` — Move to folder
+- `Escape` — Deselect all
+- `Enter` / `o` — Open message
+
+**Global:**
+- `Ctrl+Shift+K` (or `Cmd+Shift+K` on Mac) — Quick folder jump
+
+## Development
+
+No build step. Edit files, reload the extension at `chrome://extensions`, refresh the OWA tab.
+
+- `themes/base.css` — density/spacing/hiding rules (always loaded)
+- `themes/swiss.css` / `themes/material.css` — theme-specific styles
+- `content/` — content scripts (observer, behavior, injector)
+- `popup/` — settings panel
+- `selectors-test.html` — offline selector verification
+
+### Selector Strategy
+
+OWA uses obfuscated class names. Selectors prioritize `aria-label`, `data-*`, and `role` attributes over class names. See `content/selectors.js` for the registry.
+
+When selectors break after an OWA update, check the console for `[Outlook Relook]` warnings, inspect the live DOM, and update `selectors.js`.
+
+## Adding a New Theme
+
+1. Create `themes/yourtheme.css` — define the same CSS custom properties as `swiss.css`
+2. Add an option to the theme dropdown in `popup/popup.html`
+3. That's it — the content script handles injection automatically
+
+## Adding a New Toggle
+
+1. Add the key and default to `DEFAULTS` in both `content/settings-defaults.js` and `popup/popup.js`
+2. Add the toggle HTML to the appropriate section in `popup/popup.html`
+3. If CSS-based: add a `data-or-*` attribute mapping in `content/content.js` and the CSS rule in `themes/base.css`
+4. If observer-based: add a selector entry to `content/selectors.js` and a mapping in `content/observer.js`
+5. If behavior-based: add a setup function in `content/behavior.js`