@avalw/search-worker 1.1.0 → 2.1.1

package/README.md

@@ -1,303 +1,295 @@
 # @avalw/search-worker
 
-Free privacy-focused search API in exchange for compute power.
+> Distributed Cache Worker for AVALW Search Network
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+Contribute your computer's cache storage to the AVALW search network and earn free API access in return.
 
-## What is AVALW Worker?
+## How It Works
 
-AVALW Worker is a lightweight Node.js application that runs on your server and contributes CPU power to the AVALW distributed network. In return, you get **free access** to the AVALW Search API - a privacy-focused search engine that doesn't track users. Your API quota scales with your contribution.
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        AVALW DISTRIBUTED CACHE                          │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│    ┌─────────┐         ┌──────────────┐         ┌─────────────┐        │
+│    │  User   │────────▶│  avalw.org   │────────▶│ Coordinator │        │
+│    │ Search  │         │   Server     │         │   Server    │        │
+│    └─────────┘         └──────────────┘         └──────┬──────┘        │
+│                                                        │               │
+│                              ┌─────────────────────────┼───────┐       │
+│                              │                         │       │       │
+│                              ▼                         ▼       ▼       │
+│                        ┌──────────┐            ┌──────────┐ ┌──────┐   │
+│                        │ Worker 1 │            │ Worker 2 │ │ ...  │   │
+│                        │  Cache   │            │  Cache   │ │      │   │
+│                        └──────────┘            └──────────┘ └──────┘   │
+│                                                                         │
+│    YOUR WORKER stores search results and serves them when requested     │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
 
-**No tracking. No ads. No data collection. Just search.**
+### The Flow
 
-## How It Works
+```
+1. USER SEARCHES          2. CHECK CACHE           3. SERVE RESULT
+   "spotify"
+                          ┌─────────────┐
+   ┌──────┐              │ Coordinator  │         ┌──────────┐
+   │ User │──search──▶   │   checks     │──hit──▶ │  Worker  │──result──▶ User
+   └──────┘              │   workers    │         │  serves  │
+                         └─────────────┘          └──────────┘
+                               │
+                          miss │
+                               ▼
+                         ┌──────────┐
+                         │  Server  │──result──▶ User + Distribute to Workers
+                         │ process  │
+                         └──────────┘
+```
+
+### What Your Worker Does vs. Doesn't Do
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           AVALW WORKER SYSTEM                               │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   YOUR SERVER                      AVALW NETWORK           YOUR USERS       │
-│   ───────────                      ────────────            ──────────       │
-│                                                                             │
-│   ┌─────────────┐                 ┌─────────────┐                           │
-│   │   Worker    │ ───────────────►│  Compute    │                           │
-│   │   Process   │   Contributes   │   Pool      │                           │
-│   │             │   Core-Hours    │             │                           │
-│   │  CPU: ████░ │                 │ ┌─┐┌─┐┌─┐┌─┐│                           │
-│   │       70%   │                 │ └─┘└─┘└─┘└─┘│                           │
-│   └─────────────┘                 └──────┬──────┘                           │
-│         │                                │                                  │
-│         │ Reports:                       │ Calculates:                      │
-│         │ • CPU cores                    │ • Core-hours                     │
-│         │ • CPU speed (GHz)              │ • Your tier                      │
-│         │ • Usage %                      │ • API quota                      │
-│         │ • Online time                  │                                  │
-│         ▼                                ▼                                  │
-│   ┌─────────────┐                 ┌─────────────┐        ┌─────────────┐   │
-│   │   Your App  │◄────────────────│  Search API │◄───────│   Search    │   │
-│   │             │   Free access   │  (quota     │        │   Query     │   │
-│   │  // search  │   based on      │   based)    │        │             │   │
-│   │  fetch(..); │   contribution  │             │        │  "weather"  │   │
-│   └─────────────┘                 └─────────────┘        └─────────────┘   │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Core-Hours System
-
-Unlike simple percentage-based systems, AVALW uses **Core-Hours** - a fair metric that accounts for your actual hardware contribution.
-
-### What is a Core-Hour?
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         CORE-HOUR CALCULATION                               │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   Core-Hours = CPU Cores × (CPU Speed ÷ 3.0 GHz) × Usage% × Hours Online   │
-│                                                                             │
-│   ═══════════════════════════════════════════════════════════════════════   │
-│                                                                             │
-│   EXAMPLE: Intel i7-10700 running for 24 hours at 50%                       │
-│                                                                             │
-│   • Cores: 8                                                                │
-│   • Speed: 2.9 GHz base (normalized to 3.0 GHz baseline)                    │
-│   • Usage: 50%                                                              │
-│   • Time: 24 hours                                                          │
-│                                                                             │
-│   Calculation: 8 × (2.9 ÷ 3.0) × 0.50 × 24 = 92.8 core-hours/day           │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Tiers Based on Core-Hours
-
-| Tier | Requests/Day | Core-Hours/Day | Minimum Cores |
-|------|--------------|----------------|---------------|
-| **Starter** | 1,000 | 3 | 3 cores |
-| **Basic** | 5,000 | 12 | 4 cores |
-| **Pro** | 20,000 | 36 | 6 cores |
-| **Business** | 50,000 | 72 | 8 cores |
-| **Enterprise** | 500,000 | 240 | 16 cores |
-
-## Real CPU Examples
-
-### Desktop CPUs
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        DESKTOP CPU EXAMPLES                                 │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Intel Core i5-10400 (6 cores @ 2.9 GHz)                             │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 6 × 0.97 × 0.50 × 24 = 69.8 core-hours             │   │
-│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
-│  │                                                                     │   │
-│  │ At 30% for 24h: 6 × 0.97 × 0.30 × 24 = 41.9 core-hours             │   │
-│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Intel Core i7-10700 (8 cores @ 2.9 GHz)                             │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 8 × 0.97 × 0.50 × 24 = 93.1 core-hours             │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  │                                                                     │   │
-│  │ At 25% for 24h: 8 × 0.97 × 0.25 × 24 = 46.6 core-hours             │   │
-│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Intel Core i9-10900 (10 cores @ 2.8 GHz)                            │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 10 × 0.93 × 0.50 × 24 = 111.6 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  │                                                                     │   │
-│  │ At 80% for 24h: 10 × 0.93 × 0.80 × 24 = 178.6 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ AMD Ryzen 5 5600X (6 cores @ 3.7 GHz)                               │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 6 × 1.23 × 0.50 × 24 = 88.6 core-hours             │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ AMD Ryzen 7 5800X (8 cores @ 3.8 GHz)                               │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 8 × 1.27 × 0.50 × 24 = 121.9 core-hours            │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Server CPUs
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         SERVER CPU EXAMPLES                                 │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Intel Xeon E-2288G (8 cores @ 3.7 GHz)                              │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 30% for 24h: 8 × 1.23 × 0.30 × 24 = 70.8 core-hours             │   │
-│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
-│  │                                                                     │   │
-│  │ At 50% for 24h: 8 × 1.23 × 0.50 × 24 = 118.1 core-hours            │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ AMD EPYC 7302 (16 cores @ 3.0 GHz)                                  │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 30% for 24h: 16 × 1.00 × 0.30 × 24 = 115.2 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  │                                                                     │   │
-│  │ At 60% for 24h: 16 × 1.00 × 0.60 × 24 = 230.4 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ AMD EPYC 7742 (64 cores @ 2.25 GHz)                                 │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 20% for 24h: 64 × 0.75 × 0.20 × 24 = 230.4 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  │                                                                     │   │
-│  │ At 50% for 24h: 64 × 0.75 × 0.50 × 24 = 576.0 core-hours           │   │
-│  │ ✓ Qualifies for: ENTERPRISE tier (500,000 requests/day)            │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### VPS / Cloud Examples
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         VPS / CLOUD EXAMPLES                                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Basic VPS (2 vCPU @ 2.5 GHz) - ~$5/month                            │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 80% for 24h: 2 × 0.83 × 0.80 × 24 = 31.9 core-hours             │   │
-│  │ ✗ Not enough for Starter (needs 3 cores minimum)                   │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Standard VPS (4 vCPU @ 2.5 GHz) - ~$20/month                        │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 4 × 0.83 × 0.50 × 24 = 39.8 core-hours             │   │
-│  │ ✓ Qualifies for: PRO tier (20,000 requests/day)                    │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ Premium VPS (8 vCPU @ 3.0 GHz) - ~$80/month                         │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 50% for 24h: 8 × 1.00 × 0.50 × 24 = 96.0 core-hours             │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │ AWS EC2 c5.4xlarge (16 vCPU @ 3.4 GHz)                              │   │
-│  ├─────────────────────────────────────────────────────────────────────┤   │
-│  │ At 40% for 24h: 16 × 1.13 × 0.40 × 24 = 173.6 core-hours           │   │
-│  │ ✓ Qualifies for: BUSINESS tier (50,000 requests/day)               │   │
-│  │                                                                     │   │
-│  │ At 70% for 24h: 16 × 1.13 × 0.70 × 24 = 303.7 core-hours           │   │
-│  │ ✓ Qualifies for: ENTERPRISE tier (500,000 requests/day)            │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
+   ✅ DOES                              ❌ DOESN'T
+   ─────────────────────────────────    ─────────────────────────────────
+   • Store search RESULTS               • Have the search INDEX
+   • Serve cached results               • Process raw documents
+   • Use 50-200MB RAM                   • Use significant CPU
+   • Use 500MB-2GB disk                 • Access your files
+   • Connect via WebSocket              • Run arbitrary code
+   • Earn you API access                • Collect your data
 ```
 
 ## Quick Start
 
-### 1. Get Your Token
+```bash
+# 1. Get your token at https://worker.avalw.org
+# 2. Run the worker:
+npx @avalw/search-worker --token YOUR_TOKEN
+```
 
-Visit [worker.avalw.org](https://worker.avalw.org) and create a free account. You'll receive:
-- **Account Hash** - Your unique identifier (save this!)
-- **Worker Token** - Used to run the worker
+That's it! Your worker will connect and start contributing.
 
-### 2. Install the Worker
+## Installation
 
 ```bash
+# Global install
 npm install -g @avalw/search-worker
+
+# Or use npx (no install needed)
+npx @avalw/search-worker --token YOUR_TOKEN
 ```
 
-### 3. Run the Worker
+## What's New in v2.1.0
 
-```bash
-avalw-worker YOUR_WORKER_TOKEN
 ```
+┌────────────────────────────────────────────────────────────────┐
+│  INTELLIGENT CACHE SYSTEM                                      │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │ Size Limits │  │ Time-Based  │  │ Popularity  │            │
+│  │ 100MB - 2GB │  │  Eviction   │  │  Scoring    │            │
+│  └─────────────┘  └─────────────┘  └─────────────┘            │
+│                                                                │
+│  • Cache up to 2GB of search results                          │
+│  • Auto-remove queries unused for 7+ days                     │
+│  • Popular queries stay cached longer                         │
+│  • Background cleanup every hour                              │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Command Line Options
+
+```bash
+# Basic usage (500MB cache, 7 day retention)
+npx @avalw/search-worker --token abc123
 
-You'll see real-time stats:
+# Custom cache size (100-2048 MB)
+npx @avalw/search-worker --token abc123 --cache-size 1024
+
+# Custom retention (1-30 days)
+npx @avalw/search-worker --token abc123 --max-age 14
+
+# Full customization
+npx @avalw/search-worker \
+  --token abc123 \
+  --cache-size 1024 \
+  --max-age 14
 ```
-  ╔═══════════════════════════════════════════════════════════════════╗
-  ║              AVALW Search Worker v1.1.0                           ║
-  ╠═══════════════════════════════════════════════════════════════════╣
-  ║  Free Search API in exchange for compute                          ║
-  ╚═══════════════════════════════════════════════════════════════════╝
 
-  System Info:
-  ├─ CPU: Intel(R) Core(TM) i7-10700 @ 2.90GHz
-  ├─ Cores: 8
-  ├─ Speed Factor: 0.97x (normalized to 3.0 GHz)
-  └─ Memory: 32 GB
+### All Options
 
-  Worker Status:
-  ├─ Token: abc123def456...
-  ├─ API URL: https://worker.avalw.org
-  └─ Target Usage: 50%
+```
+┌──────────────────┬─────────────────┬───────────────────────────────────┐
+│ Option           │ Default         │ Description                       │
+├──────────────────┼─────────────────┼───────────────────────────────────┤
+│ -t, --token      │ $AVALW_TOKEN    │ Your worker authentication token  │
+│ -s, --cache-size │ 500             │ Max cache size in MB (100-2048)   │
+│ -a, --max-age    │ 7               │ Days to keep unused queries (1-30)│
+│ -h, --help       │                 │ Show help                         │
+│ -v, --version    │                 │ Show version                      │
+└──────────────────┴─────────────────┴───────────────────────────────────┘
+```
 
-  [10:30:45] ✓ Heartbeat OK
-  ├─ Core-Hours Today: 46.5 / 72 needed for BUSINESS
-  ├─ Current Tier: PRO (20,000 req/day)
-  ├─ Usage Today: 1,234 / 20,000
-  └─ Online: 12h 35m
+### Environment Variables
 
-  Press Ctrl+C to stop.
+```bash
+export AVALW_WORKER_TOKEN=your-token-here
+export AVALW_CACHE_SIZE_MB=1024
+export AVALW_MAX_AGE_DAYS=14
+npx @avalw/search-worker
 ```
 
-### 4. Use the Search API
+## Programmatic Usage
 
 ```javascript
-const response = await fetch(
-  'https://worker.avalw.org/api/search?q=your+query&token=YOUR_TOKEN'
-);
-const results = await response.json();
+const { createWorker } = require('@avalw/search-worker');
+
+const worker = createWorker({
+  workerToken: 'your-token-here',
+
+  // Cache configuration
+  cacheSizeMB: 1024,       // 1GB cache
+  maxAgeDays: 14,          // 14 day retention
+
+  // Event handlers
+  onConnected: (w) => console.log('Connected to coordinator'),
+  onDisconnected: (w) => console.log('Disconnected'),
+  onCacheHit: (key) => console.log('Served:', key),
+  onCacheStore: (key) => console.log('Cached:', key),
+  onError: (err) => console.error('Error:', err)
+});
+
+// Connect
+worker.connect();
+
+// Get stats
+const stats = worker.getStats();
+console.log(`Cache: ${stats.cache.sizeFormatted} / ${stats.cache.maxSizeFormatted}`);
+console.log(`Hit rate: ${stats.hitRate}%`);
+
+// Runtime configuration
+worker.setCacheSize(2048);  // Change to 2GB
+worker.setCacheMaxAge(30);  // Change to 30 days
+
+// Cleanup
+worker.disconnect();
 ```
 
-## Running as a Service
+## API Tiers & Rewards
 
-### Using PM2 (Recommended)
+Your contribution is measured in Core-Hours:
 
-```bash
-# Install PM2
-npm install -g pm2
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         CORE-HOURS FORMULA                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   Core-Hours = Cores × (CPU Speed ÷ 3.0 GHz) × Usage% × Hours      │
+│                                                                     │
+│   Example: 8 cores × (3.5 GHz ÷ 3.0 GHz) × 80% × 1 hour            │
+│          = 8 × 1.17 × 0.8 × 1 = 7.5 Core-Hours                     │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
-# Start worker with 50% CPU target
-pm2 start avalw-worker -- YOUR_WORKER_TOKEN
+### Tier Benefits
 
-# Or specify custom CPU percentage
-pm2 start avalw-worker -- YOUR_WORKER_TOKEN --cpu 30
+```
+┌─────────────┬────────────┬───────────┬─────────────────┐
+│ Tier        │ Core-Hours │ Min Cores │ API Requests    │
+├─────────────┼────────────┼───────────┼─────────────────┤
+│ Starter     │ 3          │ 3         │ 1,000/day       │
+│ Basic       │ 12         │ 4         │ 5,000/day       │
+│ Pro         │ 36         │ 6         │ 20,000/day      │
+│ Business    │ 72         │ 8         │ 50,000/day      │
+│ Enterprise  │ 240        │ 16        │ 500,000/day     │
+└─────────────┴────────────┴───────────┴─────────────────┘
+```
+
+## Intelligent Cache Details
+
+### How Eviction Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    EVICTION PRIORITY                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. EXPIRED TTL                                             │
+│     └── Items past their time-to-live (5 min default)      │
+│                                                             │
+│  2. MAX AGE EXCEEDED                                        │
+│     └── Items not accessed for N days (7 days default)     │
+│                                                             │
+│  3. LOWEST POPULARITY                                       │
+│     └── Score = log2(accessCount) × recency × stability    │
+│                                                             │
+│  Priority: 1 > 2 > 3 (expired items removed first)         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Popularity Scoring
+
+```
+Score = log2(accessCount + 1) × recencyFactor × stabilityFactor
+
+┌─────────────────┬─────────────────────────────────────────┐
+│ Factor          │ Description                             │
+├─────────────────┼─────────────────────────────────────────┤
+│ accessCount     │ Number of times the query was accessed  │
+│ recencyFactor   │ 1.0 → 0.0 over 7 days since last access │
+│ stabilityFactor │ Higher for consistent access patterns   │
+└─────────────────┴─────────────────────────────────────────┘
+
+Example: Query accessed 100 times, last accessed 1 day ago
+Score = log2(101) × 0.86 × 1.2 = 6.65 × 0.86 × 1.2 = 6.86
+```
+
+## Resource Usage
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                 TYPICAL RESOURCE USAGE                   │
+├──────────────────────────────────────────────────────────┤
+│                                                          │
+│  CPU:     1-5%     [▓░░░░░░░░░░░░░░░░░░░] minimal       │
+│  RAM:     50-200MB [▓▓▓▓░░░░░░░░░░░░░░░░] light         │
+│  Disk:    500MB-2GB [▓▓▓▓▓▓▓▓░░░░░░░░░░░░] configurable │
+│  Network: Low       [▓▓░░░░░░░░░░░░░░░░░░] WebSocket    │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Privacy & Security
 
-# Save for auto-restart
-pm2 save
-pm2 startup
 ```
+┌────────────────────────────────────────────────────────────────┐
+│                      PRIVACY GUARANTEES                        │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ✓ Workers cache RESULTS only, not the search index           │
+│  ✓ No IP addresses are logged                                 │
+│  ✓ Workers don't see who requested a search                   │
+│  ✓ All communication encrypted (WSS/HTTPS)                    │
+│  ✓ No access to your local files                              │
+│  ✓ Open source - audit the code yourself                      │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Running as a Service
 
-### Using systemd (Linux)
+### Linux (systemd)
 
-Create `/etc/systemd/system/avalw-worker.service`:
+```bash
+# Create service file
+sudo nano /etc/systemd/system/avalw-worker.service
+```
 
 ```ini
 [Unit]
@@ -306,8 +298,11 @@ After=network.target
 
 [Service]
 Type=simple
-User=your-user
-ExecStart=/usr/bin/avalw-worker YOUR_WORKER_TOKEN
+User=nobody
+Environment=AVALW_WORKER_TOKEN=your-token-here
+Environment=AVALW_CACHE_SIZE_MB=1024
+Environment=AVALW_MAX_AGE_DAYS=14
+ExecStart=/usr/bin/npx @avalw/search-worker
 Restart=always
 RestartSec=10
 
@@ -315,136 +310,103 @@ RestartSec=10
 WantedBy=multi-user.target
 ```
 
-Then:
 ```bash
+# Enable and start
+sudo systemctl daemon-reload
 sudo systemctl enable avalw-worker
 sudo systemctl start avalw-worker
+
+# Check status
+sudo systemctl status avalw-worker
 ```
 
-### Using Docker
+### Docker
 
 ```dockerfile
-FROM node:20-alpine
+FROM node:18-alpine
 RUN npm install -g @avalw/search-worker
-CMD ["avalw-worker", "YOUR_WORKER_TOKEN"]
+ENV AVALW_WORKER_TOKEN=your-token-here
+ENV AVALW_CACHE_SIZE_MB=1024
+ENV AVALW_MAX_AGE_DAYS=14
+CMD ["avalw-worker"]
 ```
 
 ```bash
 docker build -t avalw-worker .
-docker run -d --name avalw-worker avalw-worker
+docker run -d --name avalw avalw-worker
 ```
 
-## API Reference
-
-### Search Endpoint
+### PM2
 
-```
-GET https://worker.avalw.org/api/search
+```bash
+pm2 start avalw-worker --name "avalw" -- --token YOUR_TOKEN --cache-size 1024
+pm2 save
+pm2 startup
 ```
 
-| Parameter | Type   | Required | Description                    |
-|-----------|--------|----------|--------------------------------|
-| q         | string | Yes      | Search query                   |
-| token     | string | Yes      | Your worker token              |
-| page      | number | No       | Page number (default: 1)       |
-| limit     | number | No       | Results per page (default: 10) |
+### Windows (Task Scheduler)
 
-**Response:**
-```json
-{
-  "success": true,
-  "results": [
-    {
-      "title": "Example Result",
-      "url": "https://example.com",
-      "snippet": "This is a snippet..."
-    }
-  ],
-  "total": 100,
-  "page": 1,
-  "tier": "PRO",
-  "usage": {
-    "today": 1234,
-    "limit": 20000,
-    "core_hours": 46.5
-  }
-}
+```batch
+@echo off
+set AVALW_WORKER_TOKEN=your-token-here
+set AVALW_CACHE_SIZE_MB=1024
+npx @avalw/search-worker
 ```
 
-## FAQ
-
-### Why do I need minimum 3 cores?
-
-The AVALW network requires meaningful contributions to remain sustainable. A 3-core minimum ensures:
-- Fair distribution of compute power
-- Quality of service for all users
-- Sustainable network operation
-
-### Can I run on a 2-core VPS?
-
-Unfortunately, 2 cores don't meet the minimum requirement. Consider:
-- Upgrading to a 4-core VPS
-- Running on a different server with more cores
-- Combining with another server (coming soon: multi-worker support)
-
-### How is my tier calculated?
-
-Your tier is recalculated every hour based on your rolling 24-hour core-hours contribution. The formula:
+## Troubleshooting
 
 ```
-Core-Hours = Cores × (Speed ÷ 3.0) × Usage% × Hours
+┌─────────────────────────────────────────────────────────────────┐
+│                      COMMON ISSUES                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  "Connection refused"                                           │
+│  └── Check internet connection, firewall settings               │
+│                                                                 │
+│  "Invalid token"                                                │
+│  └── Get a new token at https://worker.avalw.org                │
+│                                                                 │
+│  "Cache full, high eviction rate"                               │
+│  └── Increase --cache-size or decrease --max-age                │
+│                                                                 │
+│  "Memory usage too high"                                        │
+│  └── Decrease --cache-size (minimum 100MB)                      │
+│                                                                 │
+│  "Worker keeps disconnecting"                                   │
+│  └── Check network stability, worker will auto-reconnect        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-### What if my server goes offline?
-
-Your core-hours accumulate only while online. If you go offline:
-- Your accumulated core-hours for the day remain
-- Your tier may drop if you don't maintain the required hours
-- API calls will fail until your worker reconnects
+## System Requirements
 
-## Security
-
-- **No data collection**: We don't log search queries
-- **No tracking**: No cookies, no fingerprinting
-- **Open protocol**: Transparent heartbeat mechanism
-- **Your server, your control**: Worker runs on your infrastructure
+```
+┌────────────────┬────────────────────────────────────┐
+│ Component      │ Requirement                        │
+├────────────────┼────────────────────────────────────┤
+│ Node.js        │ 14.0.0 or higher                   │
+│ CPU            │ 3+ cores for Starter tier          │
+│ RAM            │ 512MB+ free                        │
+│ Disk           │ 500MB - 2GB for cache              │
+│ Network        │ Stable internet, WebSocket support │
+│ OS             │ Windows, macOS, Linux              │
+└────────────────┴────────────────────────────────────┘
+```
 
 ## Support
 
-- Website: [worker.avalw.org](https://worker.avalw.org)
+- Dashboard: [worker.avalw.org](https://worker.avalw.org)
+- Documentation: [worker.avalw.org/protocol](https://worker.avalw.org/protocol)
 - Email: contact@avalw.com
+- Search Engine: [avalw.org](https://avalw.org)
 
 ## License
 
-MIT License
-
-Copyright (c) 2026 AVALW
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License - Free to use, modify, and distribute.
 
 ---
 
-Made with privacy in mind by [AVALW](https://cronos.avalw.com/about)
-
-### Our Projects
-
-- [AVALW Search](https://avalw.org) - Privacy-focused search engine
-- [Cronos Browser](https://cronos.avalw.com) - Secure, private browser
-- [AVALW Protocol](https://avalw.com) - Decentralized communication protocol
-- [Worker API](https://worker.avalw.org) - This project
+```
+Made with transparency in mind by AVALW
+https://avalw.com
+```