docs: update README and development instructions for clarity and structure

Author: euxx

README.md

@@ -1,74 +1,32 @@
 # GitHub Notifier Pro
 
-A browser extension that brings GitHub notifications to your browser toolbar.
+<img src="images/icon.png" width="100" alt="GitHub Notifier Pro" align="left">
 
-![Chrome](https://img.shields.io/badge/Chrome-MV3-green) ![Firefox](https://img.shields.io/badge/Firefox-supported-orange)
-
-## Screenshot
+<div>
+  <p>GitHub notifications in your browser toolbar.</p>
+  <p>Supports Chrome 99+ (MV3) and Firefox 110+.</p>
+</div>
 
-<!-- Add your screenshot here -->
-
-![Popup Screenshot](images/screenshot.png)
+![Chrome](https://img.shields.io/badge/Chrome-MV3-green) ![Firefox](https://img.shields.io/badge/Firefox-supported-orange)
 
 ## Features
 
-- **Real-time notifications** - Badge shows unread count, auto-refreshes in background
-- **Adaptive polling** - Automatically adjusts refresh interval (60s-10min) based on GitHub's X-Poll-Interval header
-- **Smart caching** - Uses HTTP 304 responses to minimize API calls and bandwidth
-- **Rate limit protection** - Tracks GitHub API limits with visual indicators and automatic retry
-- **Desktop alerts** - Optional native notifications for new items
-- **Quick actions** - Open, mark as read, or mark all as read
-- **Rich details** - Shows PR state, issue status, author avatars
-- **Secure auth** - OAuth Device Flow (no secret needed) or PAT
-
-## Permissions
-
-This extension requires:
-
-| Permission       | Purpose                          |
-| ---------------- | -------------------------------- |
-| `notifications`  | Show desktop notifications       |
-| `storage`        | Store auth token and preferences |
-| `alarms`         | Background polling               |
-| `identity`       | OAuth authentication flow        |
-| `api.github.com` | Fetch notifications              |
-| `github.com`     | OAuth authentication             |
-
-**OAuth Scopes**: `repo`, `notifications`
-
-## Installation
-
-### From Source
-
-1. Clone the repository
-2. Configure OAuth:
-   ```bash
-   cp src/config/config.example.js src/config/config.js
-   # Edit config.js with your GitHub OAuth App Client ID
-   ```
-3. Load in browser:
-   - **Chrome**: `chrome://extensions` → Enable Developer mode → Load unpacked → Select project folder
-   - **Firefox**: Run `npm run dev:firefox`, then `about:debugging` → Load Temporary Add-on → Select `dist/firefox-dev/manifest.json`
-
-### Build for Distribution
-
-```bash
-npm run build
-# Outputs: dist/github-notifier-pro-chrome.zip and dist/github-notifier-pro-firefox.zip
-```
+- 🔔 Real-time unread count badge and desktop notifications
+- 📋 Issues, PRs, Releases, and all types with rich details
+- ✅ Mark as read per notification, per repository, or all at once
+- 🔐 OAuth Device Flow or Personal Access Token authentication
+- ✨ Clean, minimal UI — feature-rich without the clutter
+- 🎨 Light / Dark / System theme with adjustable popup width
 
 ## Usage
 
-### Authentication
-
-1. **OAuth (recommended)** - Click "Sign in with GitHub", enter the code on GitHub
-2. **Personal Access Token** - Generate a token with `repo` and `notifications` scopes at [GitHub Settings](https://github.com/settings/tokens)
-
+1. **OAuth (recommended)** — Click "Sign in with GitHub", enter the code on GitHub
+2. **Personal Access Token** — Generate a token with `repo` and `notifications` scopes at [GitHub Settings](https://github.com/settings/tokens)
 
 ## Development
 
-See [development.md](development.md) for build instructions and contribution guidelines.
+See [development.md](development.md) for installation, building, and setup.
 
 ## License
 
-MIT
+Under the [MIT](LICENSE) License.

development.md

@@ -1,11 +1,21 @@
 # Development
 
-## Setup
+## Installation from Source
 
-```bash
-npm install
-npm run prepare
-```
+1. Clone the repository
+2. Install dependencies and set up git hooks:
+   ```bash
+   npm install
+   npm run prepare
+   ```
+3. Configure OAuth:
+   ```bash
+   cp src/config/config.example.js src/config/config.js
+   # Edit config.js with your GitHub OAuth App Client ID
+   ```
+4. Load in browser:
+   - **Chrome**: `chrome://extensions` → Enable Developer mode → Load unpacked → Select project folder
+   - **Firefox**: Run `npm run dev:firefox`, then `about:debugging` → Load Temporary Add-on → Select `dist/firefox-dev/manifest.json`
 
 ## Scripts