From f0bee7db5d4aa05621b55a6b2ef187b9076d18d7 Mon Sep 17 00:00:00 2001
From: Michael Cammarata <55518507+mgrimace@users.noreply.github.com>
Date: Mon, 12 Jan 2026 13:31:03 -0500
Subject: [PATCH] Update README.md (#445)

v3 Readme, simplified, clearer warnings for common issues.
---
 README.md | 205 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 203 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8091a2f..c4f4eb2 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,210 @@
 
 ---
 
-TODO
+## Table of Contents
+- [Quick Setup](#quick-setup)
+- [Nix Setup](#nix-setup)
+- [Configuration Options](#configuration-options)
+- [Account Configuration](#account-configuration)
+- [Troubleshooting](#troubleshooting)
+- [Disclaimer](#disclaimer)
 
-[For installation see the main (v1) or v2 branch (mostly the same)](https://github.com/TheNetsky/Microsoft-Rewards-Script/tree/main?tab=readme-ov-file#setup)
+---
+## Quick Setup
+
+**Requirements:** Node.js >= 22 and Git  
+Works on Windows, Linux, macOS, and WSL.
+
+### Get the script
+```bash
+git clone https://github.com/TheNetsky/Microsoft-Rewards-Script.git
+cd Microsoft-Rewards-Script
+```
+Or, download the latest release ZIP and extract it.
+
+### Create an account.json and config.json
+Copy, rename, and edit your account and configuration files before deploying the script.
+- Copy or rename `src/accounts.example.json` to `src/accounts.json` and add your credentials
+- Copy or rename `src/config.example.json` to `src/config.json` and customize your preferences.
+
+> [!CAUTION]
+> Do not skip this step.
+> Prior versions of accounts.json and config.json are not compatible with current release.
+
+> [!WARNING]
+> You must rebuild your script after making any changes to accounts.json and config.json. 
+
+### Build and run the script (bare metal version)
+```bash
+npm run pre-build
+npm run build
+npm run start
+```
+
+### Build and run the script (docker version)
+```bash
+docker compose up -d
+```
+
+> [!CAUTION]
+> Set `headless` to `true` in the `config.json` when using docker
+> Additional docker-specific scheduling options are in the `compose.yaml`
+
+> [!NOTE]
+> When headless, monitor logs with `docker logs microsoft-rewards-script` (for example, to view 2FA codes), or enable a webhook service
+---
+
+## Nix Setup
+
+If using Nix:
+
+1. Run the pre-build step first:
+   ```bash
+   npm run pre-build
+   ```
+
+2. Then start the script:
+   ```bash
+   ./run.sh
+   ```
+
+This will launch the script headlessly using `xvfb-run`.
+
+---
+
+## Configuration Reference
+
+> [!NOTE] 
+> Edit `src/config.json` to customize behavior. Below are all currently available options
+> Rebuild the script after all changes.
+
+### Core
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `baseURL` | string | `"https://rewards.bing.com"` | Microsoft Rewards base URL |
+| `sessionPath` | string | `"sessions"` | Directory to store browser sessions |
+| `headless` | boolean | `false` | Run browser invisibly |
+| `runOnZeroPoints` | boolean | `false` | Run even when no points are available |
+| `clusters` | number | `1` | Number of concurrent account clusters |
+| `errorDiagnostics` | boolean | `false` | Enable error diagnostics |
+| `searchOnBingLocalQueries` | boolean | `false` | Use local query list |
+| `globalTimeout` | string | `"30sec"` | Timeout for all actions |
+
+> [!CAUTION]
+> Set `headless` to `true` when using docker
+
+### Workers
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `workers.doDailySet` | boolean | `true` | Complete daily set |
+| `workers.doSpecialPromotions` | boolean | `true` | Complete special promotions |
+| `workers.doMorePromotions` | boolean | `true` | Complete more promotions |
+| `workers.doPunchCards` | boolean | `true` | Complete punchcards |
+| `workers.doAppPromotions` | boolean | `true` | Complete app promotions |
+| `workers.doDesktopSearch` | boolean | `true` | Perform desktop searches |
+| `workers.doMobileSearch` | boolean | `true` | Perform mobile searches |
+| `workers.doDailyCheckIn` | boolean | `true` | Complete daily check-in |
+| `workers.doReadToEarn` | boolean | `true` | Complete Read-to-Earn |
+
+### Search Settings
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `searchSettings.scrollRandomResults` | boolean | `false` | Scroll randomly on results |
+| `searchSettings.clickRandomResults` | boolean | `false` | Click random links |
+| `searchSettings.parallelSearching` | boolean | `true` | Run searches in parallel |
+| `searchSettings.queryEngines` | string[] | `["google", "wikipedia", "reddit", "local"]` | Query engines to use |
+| `searchSettings.searchResultVisitTime` | string | `"10sec"` | Time to spend on each search result |
+| `searchSettings.searchDelay.min` | string | `"30sec"` | Minimum delay between searches |
+| `searchSettings.searchDelay.max` | string | `"1min"` | Maximum delay between searches |
+| `searchSettings.readDelay.min` | string | `"30sec"` | Minimum delay for reading |
+| `searchSettings.readDelay.max` | string | `"1min"` | Maximum delay for reading |
+
+### Logging
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `debugLogs` | boolean | `false` | Enable debug logging |
+| `consoleLogFilter.enabled` | boolean | `false` | Enable console log filtering |
+| `consoleLogFilter.mode` | string | `"whitelist"` | Filter mode (whitelist/blacklist) |
+| `consoleLogFilter.levels` | string[] | `["error", "warn"]` | Log levels to filter |
+| `consoleLogFilter.keywords` | string[] | `["starting account"]` | Keywords to filter |
+| `consoleLogFilter.regexPatterns` | string[] | `[]` | Regex patterns for filtering |
+
+### Proxy
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `proxy.queryEngine` | boolean | `true` | Proxy query engine requests |
+
+### Webhooks
+| Setting | Type | Default | Description |
+|----------|------|----------|-------------|
+| `webhook.discord.enabled` | boolean | `false` | Enable Discord webhook |
+| `webhook.discord.url` | string | `""` | Discord webhook URL |
+| `webhook.ntfy.enabled` | boolean | `false` | Enable ntfy notifications |
+| `webhook.ntfy.url` | string | `""` | ntfy server URL |
+| `webhook.ntfy.topic` | string | `""` | ntfy topic |
+| `webhook.ntfy.token` | string | `""` | ntfy authentication token |
+| `webhook.ntfy.title` | string | `"Microsoft-Rewards-Script"` | Notification title |
+| `webhook.ntfy.tags` | string[] | `["bot", "notify"]` | Notification tags |
+| `webhook.ntfy.priority` | number | `3` | Notification priority (1-5) |
+| `webhook.webhookLogFilter.enabled` | boolean | `false` | Enable webhook log filtering |
+| `webhook.webhookLogFilter.mode` | string | `"whitelist"` | Filter mode (whitelist/blacklist) |
+| `webhook.webhookLogFilter.levels` | string[] | `["error"]` | Log levels to send |
+| `webhook.webhookLogFilter.keywords` | string[] | `["starting account", "select number", "collected"]` | Keywords to filter |
+| `webhook.webhookLogFilter.regexPatterns` | string[] | `[]` | Regex patterns for filtering |
+
+
+> [!WARNING]
+> **NTFY Users** Set the `webhookLogFilter` to `enabled`, otherwise you will receive push notifications for *all* log lines
+> When enabled, only account start, 2FA codes, and account completion summaries are delivered as push notifcations.
+> Customize which notifications you receive with the `keywords` options.
+
+---
+
+## Account Configuration
+
+> [!NOTE]
+> Edit `src/accounts.json`. The file is an **array** of accounts
+> Rebuild the script after all changes.
+
+```json
+[
+  {
+    "email": "email_1",
+    "password": "password_1",
+    "proxy": {
+      "proxyAxios": true,
+      "url": "",
+      "port": 0,
+      "username": "",
+      "password": ""
+    }
+  },
+  {
+    "email": "email_2",
+    "password": "password_2",
+    "proxy": {
+      "proxyAxios": true,
+      "url": "",
+      "port": 0,
+      "username": "",
+      "password": ""
+    }
+  }
+]
+```
+
+**Notes**
+- The file is a **flat array**, not `{ "accounts": [ ... ] }`.  
+- Only `email`, `password`, and `proxy` are supported.  
+- `proxyAxios` enables Axios-level proxying for API requests.
+
+---
+## Troubleshooting
+
+> [!NOTE]
+> Most login issues can be fixed by deleting your /sessions folder, and redeploying the script 
+
+---
 
 ## Disclaimer