@@ -6,7 +6,9 @@
 [![Stars](https://img.shields.io/github/stars/surge-downloader/surge?style=flat-square)](https://github.com/surge-downloader/surge/stargazers)
 [![Last Commit](https://img.shields.io/github/last-commit/surge-downloader/surge?style=flat-square)](https://github.com/surge-downloader/surge/commits/main)
 
-Surge is a blazing fast, open-source terminal (TUI) download manager built in Go. Designed for power users who prefer a keyboard-driven workflow and want full control over their downloads.
+Surge is a blazing fast, open-source download manager built in Go. While it features a beautiful **Terminal User Interface (TUI)**, it is architected to run equally well as a background **Headless Server** or a **CLI tool** for automation.
+
+Designed for power users who prefer a keyboard-driven workflow and want full control over their downloads.
 
 ![demo](assets/demo.gif)
 
@@ -28,6 +30,7 @@ brew install surge-downloader/tap/surge
 
 ```bash
 go install github.com/surge-downloader/surge@latest
+
 ```
 
 ### Build from Source
@@ -36,42 +39,123 @@ go install github.com/surge-downloader/surge@latest
 git clone https://github.com/surge-downloader/surge.git
 cd surge
 go build -o surge .
+
 ```
 
-## Features
+---
+<details><summary>
+  <h2> Operational Modes </h2>
+</summary>
+Surge operates in three distinct modes depending on your workflow needs:
+
+### 1. TUI Mode (Interactive)
+
+The default mode. Launches a full-screen, interactive dashboard to manage downloads, view real-time graphs, and manage the queue.
+
+* **Best for:** Daily usage, visual monitoring.
+
+### 2. Headless Mode (Server/Daemon)
+
+Runs Surge in the background without a user interface. It listens on a specific port for incoming download requests from the CLI or Browser Extension.
+
+* **Best for:** Raspberry Pis, VPS, always-on servers, or background tasks.
+
+### 3. CLI Mode (Client & Automation)
+
+Allows you to send commands to a running instance (TUI or Headless) or perform quick, standalone downloads similar to `wget` or `curl`.
 
-- **High-speed Downloads** with multi-connection support
-- **Beautiful TUI** built with Bubble Tea & Lipgloss
-- **Pause/Resume** downloads seamlessly
-- **Real-time Progress** with speed graphs and ETA
-- **Auto-retry** on connection failures
-- **Batch Downloads**
-- **Browser Extension** integration
-- **Clipboard Integration**
+* **Best for:** Scripts, batch processing, single-file downloads.
+</details>
+
+---
 
 ## Usage
 
+### Interactive TUI
+
+Start the visual dashboard.
+
 ```bash
-# Start TUI mode
 surge
 
-# Headless download (CLI only, no TUI)
-surge get <URL>
+```
 
-# Headless download with custom output directory
-surge get <URL> -o ~/Downloads
+### Headless Server
+
+Start the daemon in the background.
+
+```bash
+# Start server (default port)
+surge --headless
+
+# Start with specific settings
+surge --headless --port 8090 -o ~/Downloads/Surge
+
+```
 
-# Send download via CLI to already running TUI instance
-surge get <URL> --port <PORT>
+> **Note:** Set port to `0` to have Surge automatically assign a free port.
 
-# Batch download from a file (one URL per line)
+### CLI & Remote Control
+
+Send downloads to a running Surge instance (TUI or Headless) or download directly.
+
+```bash
+# 1. Send to a running instance (Remote)
+# Does not block your terminal; hands off the task to the server.
+surge get <URL> --port 8090
+
+# 2. Standalone Download (Direct)
+# Blocks the terminal until finished (like wget). No server required.
+surge get <URL>
+
+# 3. Override Output Directory
+surge get <URL> -o /tmp/downloads
+
+# 4. Batch Download
+# Reads a file with one URL per line
 surge get --batch urls.txt
+
 ```
 
+---
+
+## Features
+
+* **High-speed Downloads** with multi-connection support
+* **Beautiful TUI** built with Bubble Tea & Lipgloss
+* **Pause/Resume** downloads seamlessly
+* **Real-time Progress** with speed graphs and ETA
+* **Auto-retry** on connection failures
+* **Batch Downloads**
+* **Browser Extension** integration
+* **Clipboard Integration**
+
+---
+
+<details>
+  <summary><h2> How it Works? </h2></summary>
+
+A standard browser usually opens a single HTTP connection to the server. However, servers typically limit the bandwidth allocated to a single connection to ensure fairness for all users.
+
+Download managers (like Surge) open multiple requests simultaneously (e.g., 32 in Surge). They use this method to split the file into many small parts and download those parts individually.
+
+Not all connections are created equal; there are fast connections and slow connections due to factors like load balancers and CDNs. Download managers employ various methods to optimize these connections.
+
+The top 3 optimizations we did in Surge are:
+
+1. **Split the Largest Chunk:** Split the largest chunk whenever possible so that workers do not remain idle.
+   
+2. **Work Stealing:** Near the end, when fast workers are finished and slow workers are still processing, make the fast, idle workers "steal work" from the slow workers.
+   
+3. **Restart Slow Workers:** Calculate the mean speed of all workers. If a worker is performing at less than **0.3x** of the mean, restart it in the hopes that it will secure a better pathway to the server, which will be faster.
+</details>
+
+---
+
 ## Benchmarks
 
 | Tool | Time | Speed | vs Surge |
-|------|------|-------|----------|
+| --- | --- | --- | --- |
 | **Surge** | 28.93s | **35.40 MB/s** | — |
 | aria2c | 40.04s | 25.57 MB/s | 1.38× slower |
 | curl | 57.57s | 17.79 MB/s | 1.99× slower |
@@ -82,15 +166,16 @@ surge get --batch urls.txt
 
 *Results averaged over 5 runs*
 
-| | |
-|---|---|
+|  |  |
+| --- | --- |
 | **File** | 1GB.bin ([link](https://sin-speed.hetzner.com/1GB.bin)) |
 | **OS** | Windows 11 Pro |
 | **CPU** | AMD Ryzen 5 5600X |
 | **RAM** | 16 GB DDR4 |
 | **Network** | 360 Mbps / 45 MB/s |
 
 Run your own: `python benchmark.py -n 5`
+
 </details>
 
 ## Browser Extension
@@ -123,4 +208,4 @@ Contributions are welcome! Feel free to fork, make changes, and submit a pull re
 
 If you find Surge useful, please consider giving it a ⭐ it helps others discover the project!
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.
@@ -159,8 +159,6 @@ def benchmark_surge(project_dir: Path, url: str, output_dir: Path) -> BenchmarkR
     success, output = run_command([
         str(surge_bin), "get", url,
         "--output", str(output_dir),  # Download directory
-        # "--headless",               # Removed as it's default/unrecognized
-        # "-c", "16",                 # Removed as concurrent defaults are dynamic or strictly internal
     ], timeout=600)
     elapsed = time.perf_counter() - start
 
 
@@ -181,7 +181,7 @@ func TestHandleDownload_MethodNotAllowed(t *testing.T) {
 	req := httptest.NewRequest(http.MethodGet, "/download", nil)
 	rec := httptest.NewRecorder()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	if rec.Code != http.StatusMethodNotAllowed {
 		t.Errorf("Expected 405, got %d", rec.Code)
@@ -192,7 +192,7 @@ func TestHandleDownload_InvalidJSON(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/download", bytes.NewBufferString("not json"))
 	rec := httptest.NewRecorder()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	if rec.Code != http.StatusBadRequest {
 		t.Errorf("Expected 400, got %d", rec.Code)
@@ -207,7 +207,7 @@ func TestHandleDownload_MissingURL(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/download", bytes.NewBufferString(body))
 	rec := httptest.NewRecorder()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	if rec.Code != http.StatusBadRequest {
 		t.Errorf("Expected 400, got %d", rec.Code)
@@ -222,7 +222,7 @@ func TestHandleDownload_EmptyURL(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/download", bytes.NewBufferString(body))
 	rec := httptest.NewRecorder()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	if rec.Code != http.StatusBadRequest {
 		t.Errorf("Expected 400, got %d", rec.Code)
@@ -245,7 +245,7 @@ func TestHandleDownload_PathTraversal(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			req := httptest.NewRequest(http.MethodPost, "/download", bytes.NewBufferString(tt.body))
 			rec := httptest.NewRecorder()
-			handleDownload(rec, req)
+			handleDownload(rec, req, "")
 
 			if rec.Code != http.StatusBadRequest {
 				t.Errorf("Expected 400, got %d", rec.Code)
@@ -511,7 +511,7 @@ func TestStartHTTPServer_HealthEndpoint(t *testing.T) {
 	port := ln.Addr().(*net.TCPAddr).Port
 
 	// Start server in background
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 
 	// Give server time to start
 	time.Sleep(50 * time.Millisecond)
@@ -547,7 +547,7 @@ func TestStartHTTPServer_NoCORSHeaders(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	resp, err := http.Get(fmt.Sprintf("http://127.0.0.1:%d/health", port))
@@ -568,7 +568,7 @@ func TestStartHTTPServer_OptionsRequest(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	req, _ := http.NewRequest(http.MethodOptions, fmt.Sprintf("http://127.0.0.1:%d/download", port), nil)
@@ -590,7 +590,7 @@ func TestStartHTTPServer_DownloadEndpoint_MethodNotAllowed(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	// GET should not be allowed
@@ -612,7 +612,7 @@ func TestStartHTTPServer_DownloadEndpoint_BadRequest(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	// POST with invalid JSON
@@ -638,7 +638,7 @@ func TestStartHTTPServer_DownloadEndpoint_MissingURL(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	// POST with missing URL
@@ -664,7 +664,7 @@ func TestStartHTTPServer_NotFoundEndpoint(t *testing.T) {
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 
-	go startHTTPServer(ln, port)
+	go startHTTPServer(ln, port, "")
 	time.Sleep(50 * time.Millisecond)
 
 	resp, err := http.Get(fmt.Sprintf("http://127.0.0.1:%d/nonexistent", port))
@@ -702,14 +702,14 @@ func TestHandleDownload_ValidRequest_NoServerProgram(t *testing.T) {
 		}
 	}()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 }
 
 func TestHandleDownload_EmptyBody(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/download", bytes.NewBufferString(""))
 	rec := httptest.NewRecorder()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	// Empty body causes EOF error on decode
 	if rec.Code != http.StatusBadRequest {
@@ -725,7 +725,7 @@ func TestHandleDownload_LargeURL(t *testing.T) {
 	rec := httptest.NewRecorder()
 
 	// This should handle large URLs gracefully (validation issues)
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 
 	// Should fail on URL validation or JSON parsing
 	t.Logf("Response: %d", rec.Code)
@@ -742,7 +742,7 @@ func TestHandleDownload_SpecialCharactersInPath(t *testing.T) {
 		}
 	}()
 
-	handleDownload(rec, req)
+	handleDownload(rec, req, "")
 }
 
 // =============================================================================
 
@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/surge-downloader/surge/internal/config"
 	"github.com/surge-downloader/surge/internal/download"
 	"github.com/surge-downloader/surge/internal/messages"
 	"github.com/surge-downloader/surge/internal/utils"
@@ -98,7 +99,15 @@ func runHeadless(ctx context.Context, url, outPath string, verbose bool) error {
 		}
 	}
 
-	return <-errCh
+	err := <-errCh
+	if err == nil {
+		elapsed := time.Since(startTime)
+		speed := float64(totalSize) / elapsed.Seconds() / (1024 * 1024)
+		fmt.Fprintf(os.Stderr, "Complete: %s in %s (%.2f MB/s)\n",
+			utils.ConvertBytesToHumanReadable(totalSize),
+			elapsed.Round(time.Millisecond), speed)
+	}
+	return err
 }
 
 // sendToServer sends a download request to a running surge server
@@ -133,7 +142,6 @@ var getCmd = &cobra.Command{
 	Short: "Download a file in headless mode or send to running server",
 	Long: `Download a file from a URL without the TUI interface.
 
-Use --headless for CLI-only downloads (useful for scripting).
 Use --port to send the download to a running Surge instance.
 Use --batch to download multiple URLs from a file (one URL per line).`,
 	Args: cobra.MaximumNArgs(1),
@@ -181,9 +189,22 @@ Use --batch to download multiple URLs from a file (one URL per line).`,
 		}
 
 		if outPath == "" && port == 0 {
-			// Only default to "." for headless mode.
-			// For server mode (port > 0), send empty path so TUI uses its default.
-			outPath = "."
+			// Try to load default download directory from settings
+			settings, err := config.LoadSettings()
+			if err == nil && settings.General.DefaultDownloadDir != "" {
+				outPath = settings.General.DefaultDownloadDir
+				// Create directory if it doesn't exist
+				if err := os.MkdirAll(outPath, 0755); err != nil {
+					// If creation fails, fallback to current directory
+					outPath = "."
+				}
+			} else {
+				// Fallback to current directory
+				outPath = "."
+			}
+		} else if outPath == "" && port > 0 {
+			// For server mode, send empty path so server/TUI uses its default
+			outPath = ""
 		}
 
 		// Process each URL