diff --git a/README.md b/README.md
new file mode 100644
index 0000000..00b310b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# Persian RTL Fixer — Vazirmatn
+
+A dependency-free Chrome extension (Manifest V3) that fixes Persian text direction on dynamic websites, especially streaming AI chats, without rewriting the page’s text.
+
+## What it changes
+
+- A Persian-leading text block gets `dir="rtl"` and right alignment.
+- English-leading mixed content gets `dir="auto"` so both scripts remain readable.
+- Arabic-only, Hebrew, and English-only text are left untouched.
+- Latin digits such as `1234567890` are never converted or rewritten.
+- Unstyled Persian text receives the bundled Vazirmatn font.
+- Any font selected by the website is preserved, including inherited, generic, inline, and web fonts.
+- Text inputs use automatic direction and receive Vazirmatn only after Persian text is present.
+
+The content script batches DOM mutations, so token-by-token AI responses are corrected without rescanning the whole page for every character.
+
+## Safety model
+
+The extension never wraps, replaces, or restructures text nodes. It changes only reversible `dir` attributes and inline font styles on existing elements. Code blocks, SVG, MathML, and unsupported form controls are skipped. Disabling the extension restores every owned change without reloading the page.
+
+The detector requires Persian-specific characters before acting. This intentionally favors precision over guessing: ambiguous text made entirely from letters shared with Arabic is not modified.
+
+## Install as an unpacked extension
+
+1. Open `chrome://extensions`.
+2. Enable **Developer mode**.
+3. Select **Load unpacked** and choose this directory.
+4. Pin **Persian RTL Fixer** from the extensions menu.
+
+To use the local `demo.html`, open the extension’s details and enable **Allow access to file URLs** first.
+
+## Popup settings
+
+| Setting | Default | Behavior |
+|---|---:|---|
+| Enable on this site | On | Pauses correction for the current hostname |
+| Conservative RTL correction | On | Corrects clearly Persian blocks while preserving uncertain layouts |
+| Vazirmatn for unstyled text | On | Applies Vazirmatn only when the site declares no font |
+| Smart input direction | On | Uses automatic direction in text fields |
+| Master switch | On | Enables or disables the extension everywhere |
+
+Settings are stored locally through `chrome.storage.local`. The extension does not send page text anywhere.
+
+## Development
+
+```powershell
+npm install
+npm test
+npm run check:encoding
+```
+
+The automated suites cover real Persian fixtures, Arabic isolation, mixed direction, Latin-digit integrity, inherited and stylesheet fonts, streaming mutations, reversible teardown, protected content, input behavior, popup states, and UTF-8 integrity.
+
+## Project layout
+
+```text
+manifest.json          Manifest V3 configuration
+src/content.js         Persian detector, DOM correction, and lifecycle
+popup/                 Accessible toolbar popup
+fonts/                 Bundled Vazirmatn WOFF2 files
+icons/                 Extension icons
+demo.html              Manual and streaming test page
+test/                  jsdom and integrity tests
+```
+
+Open shadow roots and related frames are supported where Chrome exposes them. Closed shadow roots are inaccessible to browser extensions.
+
+Vazirmatn is distributed under the SIL Open Font License.