diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37344aa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# Outlook Web Inbox Count
+
+A lightweight browser extension that adds the total number of items next to
+the **Inbox** label in Outlook Web, so you can see at a glance how many emails
+are sitting in your inbox without having to open the folder.
+
+By default Outlook Web only shows the unread count; this extension adds the
+total item count alongside it.
+
+## Install
+
+- **Chrome / Edge / Brave**: [Chrome Web Store listing](https://chromewebstore.google.com/detail/mjdfjopdcoiojbjnfkpjhcnpefjknkdn)
+- **Firefox**: load as a temporary add-on via `about:debugging` (the extension
+  is Manifest v3 and includes a `browser_specific_settings.gecko` entry).
+
+The extension runs on:
+
+- `https://outlook.office.com/*`
+- `https://outlook.office365.com/*`
+- `https://outlook.cloud.microsoft/*` (the current domain as of 2026)
+
+## How it works
+
+A content script (`content.js`) watches the Outlook Web DOM and the page
+title for the inbox item count, then injects a small span next to the Inbox
+label showing the number. It uses:
+
+- A `MutationObserver` (scoped to `title` and `data-folder-name` attribute
+  changes) to react to navigation and refresh events.
+- Multiple fallback selectors and regex patterns to cope with different
+  Outlook Web versions and locales.
+- A 1-second throttle and a 15-second periodic safety check to keep CPU
+  usage low.
+
+If the count cannot be determined, the extension shows `(-)` in grey rather
+than nothing, so it is clear the extension is running.
+
+## Development
+
+The extension is three files plus icons - no build step is needed.
+
+1. Clone the repo.
+2. In Chrome, go to `chrome://extensions`, enable **Developer mode**, and
+   click **Load unpacked**. Select the project directory.
+3. Open Outlook Web and check the DevTools console for log lines starting
+   with `Outlook Inbox Count Extension`.
+
+When a new Outlook Web version breaks detection, the most likely places to
+look are `findInboxElement()` and `findTotalItems()` in `content.js` - the
+selector and regex lists there are the extension's knowledge of how Outlook
+Web renders the inbox label and count.
+
+## Releasing
+
+The release process is automated via `publish.sh`, which builds the zip from
+`manifest.json`, uploads it to the Chrome Web Store, and submits it for
+review. The routine workflow is:
+
+1. Bump `version` in `manifest.json` and add a changelog entry in the header
+   of `content.js`.
+2. Run `./publish.sh`.
+
+See [PUBLISHING.md](PUBLISHING.md) for the full reference, including the
+one-time OAuth setup and troubleshooting.
+
+## Project layout
+
+```
+manifest.json     Chrome extension manifest (v3)
+content.js        Content script - all the logic lives here
+icon16/64/128.png Extension icons
+publish.sh        Build + upload + publish automation
+PUBLISHING.md     Chrome Web Store release process reference
+.env              Credentials for publish.sh (gitignored)
+```
+
+## Author
+
+Giorgio Gilestro - https://lab.gilest.ro