From 10ea615b8f994c1398d61e6870b5d4ddf6added4 Mon Sep 17 00:00:00 2001
From: Sudo-Ivan <ivan@quad4.io>
Date: Fri, 26 Dec 2025 21:30:45 -0600
Subject: [PATCH] first commit

---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3001da9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# Web News
+
+Web News is a privacy-focused, offline-first RSS reader and full-text extractor. It combines a Svelte-based reactive frontend with a high-performance Go-based backend, available as a standalone web server or a native desktop application (Wails).
+
+## Features
+
+- **Privacy-First**: No tracking, no accounts, no clouds. Your data stays in your browser.
+- **Offline-First**: Articles, feeds, and settings are stored locally in IndexedDB.
+- **Desktop & Web**: Run as a single Go binary or a native app via Wails.
+- **Full-Text Extraction**: One-click "Read Mode" that pulls clean content from any URL.
+- **Global Search**: Instant full-text search across your entire reading history.
+- **Vim-like Shortcuts**: Navigate with `j`/`k`, save with `s`, and manage feeds without a mouse.
+- **Content Filtering**: "Mute Filters" to automatically hide articles based on keywords.
+- **Smart Feed**: Personalized ranking that learns from your reading habits locally.
+- **Activity Heatmap**: Visualize your reading trends over the last 30 days.
+- **Bulk Actions**: Multi-select mode to quickly manage large volumes of articles.
+- **Customizable Reader**: Adjust font (Serif/Sans), size, and line height for a premium reading experience.
+
+## Privacy and Security
+
+Web News follows a "zero-knowledge" philosophy:
+
+1. **Data Sovereignty**: Your reading list and history never leave your device.
+2. **Anonymous Access**: 16-digit account numbers for server access.
+3. **Local Cache**: Full-text content is cached locally in IndexedDB for offline reading and instant access.
+4. **Hardened Backend**: Built-in bot blocking, rate limiting, and secure token generation.
+
+## Getting Started
+
+### Prerequisites
+- Go 1.21+
+- Node.js 18+
+- [Wails CLI](https://wails.io/docs/gettingstarted/installation) (for desktop builds)
+
+### Build & Run (Web Server)
+1. **Build the binary**:
+   ```bash
+   make build
+   ```
+2. **Run it**:
+   ```bash
+   ./bin/web-news
+   ```
+
+### Build & Run (Desktop App)
+1. **Launch Dev Mode**:
+   ```bash
+   make desktop-dev
+   ```
+2. **Build for current platform**:
+   ```bash
+   make desktop-build
+   ```
+3. **Cross-Compile**:
+   ```bash
+   make desktop-windows  # Build for Windows
+   make desktop-darwin   # Build for macOS (Universal)
+   ```
+
+## Configuration
+
+### Server Flags
+- `--auth-mode`: `none` (default), `token`, or `multi`.
+- `--allow-registration`: Allow generating new account numbers (default: true).
+- `--auth-file`: Path to the account storage (default: `accounts.json`).
+- `--port`: Port to listen on (default: `8080`).
+
+### Keyboard Shortcuts (Default)
+- `j` / `k`: Next / Previous article
+- `r`: Mark as read
+- `s`: Toggle save
+- `x`: Toggle select mode
+- `o`: Open original URL
+
+## Development
+
+- **Dev Server**: `make dev` (Starts Go backend + Vite frontend)
+- **Format & Lint**: `npm run format && npm run lint`
+- **Clean Artifacts**: `make clean`
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+---
+Created by [Quad4](https://quad4.io)