diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bf3dce0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,169 @@
+# OpenScript
+
+A lightweight, modern user script manager built for Chrome Manifest V3 using the native `chrome.userScripts` API.
+
+---
+
+## ⚡ Prerequisites
+
+To run user scripts in Chrome MV3:
+1. Open `chrome://extensions` in your browser.
+2. Click **Details** on the **OpenScript** extension card.
+3. Enable the **"Allow User Scripts"** toggle.
+
+---
+
+## 📖 Writing Scripts Tutorial
+
+OpenScript uses standard Tampermonkey-compatible metadata headers with built-in secret injection.
+
+### 1. The Metadata Block
+
+Every user script begins with a `// ==UserScript==` block that tells OpenScript when and where to run:
+
+```javascript
+// ==UserScript==
+// @name         GitHub Notification Cleaner
+// @version      1.0.0
+// @description  Hides read notifications automatically
+// @author       YourName
+// @match        https://github.com/*
+// @run-at       document_idle
+// @grant        none
+// ==/UserScript==
+
+(function() {
+  'use strict';
+  console.log('OpenScript running on GitHub!');
+})();
+```
+
+#### Supported Header Directives
+
+| Directive | Description | Example |
+| :--- | :--- | :--- |
+| `@name` | Script title shown in OpenScript popup list | `@name My Custom Tool` |
+| `@version` | Version badge displayed in popup list | `@version 1.2.0` |
+| `@description` | Summary shown under the script title | `@description Auto-clicks accept buttons` |
+| `@author` | Author metadata | `@author Alice` |
+| `@match` / `@include` | URL patterns where script runs (supports multiple) | `@match https://*.example.com/*` |
+| `@run-at` | Injection timing: `document_idle` (default), `document_start`, `document_end` | `@run-at document_start` |
+| `@grant` | Compatibility header (e.g. `none`) | `@grant none` |
+
+> **Note on `@match` normalization:** OpenScript automatically normalizes bare URLs (e.g., `github.com/*` becomes `*://github.com/*` and `https://github.com` becomes `https://github.com/*`).
+
+---
+
+### 2. Execution Timing (`@run-at`)
+
+Control when your script executes relative to page lifecycle:
+
+* **`document_idle` (Default):** Runs after the page DOM is fully built and subresources have finished loading. Best for DOM manipulation and button clicks.
+* **`document_start`:** Runs before any DOM elements are constructed or external page scripts execute. Best for early theme injection, ad/tracker blockers, or prototype overrides.
+* **`document_end`:** Runs right as the DOM content is parsed (`DOMContentLoaded`), before images and stylesheets finish loading.
+
+*(Both hyphenated `document-idle` and underscore `document_idle` formats are supported).*
+
+---
+
+### 3. Using Synced Secrets & Environment Variables
+
+OpenScript allows you to store sensitive API tokens or passwords in the **Secrets** tab. Secrets are synced across your devices via `chrome.storage.sync` and injected into every active user script.
+
+#### Accessing Secrets in Code
+
+You can read secrets using any of these 3 equivalent syntaxes:
+
+```javascript
+// 1. Direct OpenScript namespace
+const token = OpenScript.env.GH_PAT;
+
+// 2. Shorthand env global
+const token = env.GH_PAT;
+
+// 3. Standard Tampermonkey GM_getValue polyfill
+const token = GM_getValue('GH_PAT', 'default_value');
+```
+
+#### Complete Example: GitHub API Fetcher with Secrets
+
+```javascript
+// ==UserScript==
+// @name         GitHub Repo Stats
+// @version      1.0.0
+// @description  Fetches repository star count with personal token
+// @match        https://github.com/*
+// @run-at       document_idle
+// ==/UserScript==
+
+(async function() {
+  'use strict';
+
+  // Retrieve secret saved in OpenScript "Secrets" tab
+  const token = env.GH_PAT;
+  if (!token) {
+    console.warn('[OpenScript] Please configure GH_PAT in OpenScript Secrets tab.');
+    return;
+  }
+
+  const [, owner, repo] = location.pathname.split('/');
+  if (!owner || !repo) return;
+
+  const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  const data = await res.json();
+  console.log(`[OpenScript] ${data.full_name} has ${data.stargazers_count} stars!`);
+})();
+```
+
+---
+
+### 4. Boilerplate Template
+
+When you click **+ New** in the extension popup, OpenScript gives you this clean starter template:
+
+```javascript
+// ==UserScript==
+// @name         New Userscript
+// @version      1.0.0
+// @description  try to take over the world!
+// @author       You
+// @match        *://*/*
+// @grant        none
+// ==/UserScript==
+
+(function() {
+    'use strict';
+
+    // Access secrets via OpenScript.env or env:
+    // console.log(OpenScript.env);
+})();
+```
+
+---
+
+## 🛠️ Development & Building
+
+```bash
+# Install dependencies
+npm install
+
+# Run Vite dev server
+npm run dev
+
+# Run unit tests
+npm test
+
+# Generate icons from master v2 logo
+npm run build:icons
+
+# Build and package Chrome Web Store zip
+npm run zip
+```
+
+---
+
+## 🔒 Privacy
+
+OpenScript does not track users, log data, or contact external servers. All user scripts are stored locally on your machine. See our [Privacy Policy](PRIVACY.md).