From ae06931890ade58a192dc38a7689240b66e271c5 Mon Sep 17 00:00:00 2001
From: khton <ya.eltyshev@gmail.com>
Date: Tue, 31 Mar 2026 15:24:34 +0300
Subject: [PATCH] add readme

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2eba63e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+<div align="center">
+  <h1>🦊 KettuRay</h1>
+  <p><strong>A sleek, powerful, and hybrid VPN client for Windows built with Go and Wails.</strong></p>
+
+  <p>
+    <a href="#features">Features</a> •
+    <a href="#architecture">Architecture</a> •
+    <a href="#getting-started">Getting Started</a> •
+    <a href="#development">Development</a>
+  </p>
+
+  <img src="https://img.shields.io/badge/Platform-Windows-blue.svg?style=flat-square" alt="Platform: Windows" />
+  <img src="https://img.shields.io/badge/Language-Go%20%7C%20JavaScript-00ADD8.svg?style=flat-square" alt="Language" />
+  <img src="https://img.shields.io/badge/Framework-Wails%20v2-red.svg?style=flat-square" alt="Wails" />
+</div>
+
+---
+
+## 📖 Overview
+
+**KettuRay** is a lightweight yet immensely powerful VPN client combining the best proxy cores into a single, seamless Windows experience. Built heavily around a **dark "design-code" aesthetic**, it provides a distraction-free, vertical, frameless user interface with ultra-fast UX flows.
+
+## ✨ Features
+
+- ⚡ **Hybrid Core Engine**: Leverages the power of **Xray-core** as the backend proxy engine and **sing-box** as the TUN-based frontend for reliable system-wide traffic routing.
+- 🎨 **Premium UI/UX**: Compact, frameless, and dark-themed interface built specifically for Windows. Enjoy smooth animations, beautiful typography, and immediate responsiveness.
+- 🔐 **Next-Gen Protocols**: Full support for `VLESS`, `VMess`, `Trojan`, `Shadowsocks`, `REALITY`, and `gRPC`.
+- 📋 **Seamless Import**: Smart clipboard parsing allows you to copy a config link and instantly add it to your profile.
+- 🔄 **Smart Connectivity**: Real-time ping testing, auto-connect on startup, and intelligent auto-reconnect fallback mechanism.
+- ⌨️ **Global Hotkeys**: Control KettuRay instantly from anywhere with `Win + Alt + V`.
+- 🔔 **Native Integrations**: Sleek system tray icon management and native Windows notifications popping right above your taskbar.
+- 📜 **Live Logs**: Expandable sidebar with real-time connection logging and copy capabilities.
+
+## 🏗 Architecture
+
+KettuRay utilizes a split-core design:
+1. **Frontend**: JavaScript/HTML/CSS powered by Vite, packed inside a borderless Wails v2 Webview wrapper.
+2. **Controller (Go)**: A robust `Go` backend that handles system-level calls, hotkeys, systray menus, and inter-process communication (IPC).
+3. **Network Cores**: 
+   - `Xray-core` securely negotiates complex proxy connections to your remote endpoints.
+   - `sing-box` wraps the connection in a virtual network interface (TUN) to capture all local system traffic correctly without tedious system proxy configurations.
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+To build and run KettuRay, you will need:
+- [Go 1.20+](https://golang.org/doc/install)
+- [Node.js 16+](https://nodejs.org/en/download/) (for frontend assets)
+- [Wails CLI v2](https://wails.io/docs/gettingstarted/installation)
+
+Install Wails globally via Go:
+```bash
+go install github.com/wailsapp/wails/v2/cmd/wails@latest
+```
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/khton/kettuRay.git
+   cd kettuRay_go
+   ```
+
+2. Install frontend dependencies:
+   ```bash
+   cd frontend
+   npm install
+   cd ..
+   ```
+
+## 🛠 Development
+
+Start the application in development mode with live reloading for both Go and the frontend:
+
+```bash
+wails dev
+```
+
+To build a standalone production executable:
+
+```bash
+wails build -clean -platform windows/amd64
+```
+The compiled binary (`kettuRay.exe`) will be generated inside the `build/bin` directory.
+
+---
+
+<div align="center">
+  <sub>Developed with ❤️ for secure and aesthetically pleasing internet access.</sub>
+</div>