From bb52efdcf2721dda402ffc497f178eaa57f4bb75 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 19 Jul 2025 03:01:17 +0200
Subject: [PATCH] Clean up and improve documentation across the project

- Add Linux/headless support documentation to introduction.mdx and project-overview.md
- Fix sidebar navigation with descriptive titles instead of generic README labels
- Remove experimental Tauri references from docs.json
- Reorganize docs.json with better categorization and all relevant files
- Keep architecture-mario.md and consolidated org-migrate.md as TODO
---
 docs.json                | 32 ++++++++++++++++++++------------
 docs/project-overview.md | 11 ++++++++++-
 introduction.mdx         | 16 +++++++++++-----
 3 files changed, 41 insertions(+), 18 deletions(-)

diff --git a/docs.json b/docs.json
index 6a91012e..0dcaca11 100644
--- a/docs.json
+++ b/docs.json
@@ -60,8 +60,14 @@
       {
         "group": "Installation",
         "pages": [
-          "mac/README",
-          "ios/README",
+          {
+            "title": "macOS Installation",
+            "href": "mac/README"
+          },
+          {
+            "title": "iOS Installation", 
+            "href": "ios/README"
+          },
           "web/docs/VT_INSTALLATION",
           "docs/custom-node"
         ]
@@ -123,7 +129,10 @@
       {
         "group": "iOS Testing",
         "pages": [
-          "ios/VibeTunnelTests/README",
+          {
+            "title": "Test Suite Overview",
+            "href": "ios/VibeTunnelTests/README"
+          },
           "ios/VibeTunnelTests/TestCoverage",
           "ios/VibeTunnelTests/TestingApproach"
         ]
@@ -131,7 +140,10 @@
       {
         "group": "Web Development",
         "pages": [
-          "web/README",
+          {
+            "title": "Web Frontend Guide",
+            "href": "web/README"
+          },
           "web/docs/performance",
           "web/docs/playwright-testing",
           "web/src/test/playwright/SEQUENTIAL_OPTIMIZATIONS",
@@ -145,13 +157,6 @@
           "docs/RELEASE"
         ]
       },
-      {
-        "group": "Experimental",
-        "pages": [
-          "tauri/README",
-          "tauri/IMPROVEMENTS"
-        ]
-      },
       {
         "group": "Tools & Integration",
         "pages": [
@@ -159,7 +164,10 @@
           "CLAUDE",
           "docs/gemini",
           "GEMINI",
-          ".github/workflows/README"
+          {
+            "title": "GitHub Actions Guide",
+            "href": ".github/workflows/README"
+          }
         ]
       },
       {
diff --git a/docs/project-overview.md b/docs/project-overview.md
index 6776dfb9..083ccef3 100644
--- a/docs/project-overview.md
+++ b/docs/project-overview.md
@@ -53,6 +53,13 @@ The project provides a native macOS menu bar application that runs a local HTTP
 - Xcode 15+ for building from source
 - Code signing for proper terminal permissions
 
+**Linux & Headless Support**
+- Any Linux distribution with Node.js 20+
+- Runs as standalone server via npm package
+- No GUI required - perfect for VPS/cloud deployments
+- Install: `npm install -g vibetunnel`
+- Run: `vibetunnel-server`
+
 **iOS Requirements**  
 - iOS 17.0+
 - iPhone or iPad
@@ -66,9 +73,11 @@ The project provides a native macOS menu bar application that runs a local HTTP
 **Server Platforms**
 - Primary: Bun runtime (Node.js compatible)
 - Build requirements: Node.js 20+, npm/bun
+- Supports macOS, Linux, and headless environments
 
 **Key Platform Files**
 - macOS app bundle: `mac/VibeTunnel.xcodeproj`
 - iOS app: `ios/VibeTunnel.xcodeproj`  
 - Web server: `web/` directory with TypeScript source
-- CLI tool: Installed to `/usr/local/bin/vt`
\ No newline at end of file
+- CLI tool: Installed to `/usr/local/bin/vt` (macOS only)
+- npm package: `vibetunnel` on npm registry
\ No newline at end of file
diff --git a/introduction.mdx b/introduction.mdx
index 4488f705..10031bc7 100644
--- a/introduction.mdx
+++ b/introduction.mdx
@@ -1,21 +1,27 @@
 # Welcome to VibeTunnel Documentation
 
-VibeTunnel is a powerful macOS application that allows you to access your terminal sessions through any web browser. Whether you're on your iPad, iPhone, or any other device with a web browser, VibeTunnel makes your terminal accessible from anywhere.
+VibeTunnel is a powerful terminal sharing application that allows you to access your terminal sessions through any web browser. Whether you're on macOS, Linux, iPad, iPhone, or any other device with a web browser, VibeTunnel makes your terminal accessible from anywhere.
 
 ## Key Features
 
-- **Remote Terminal Access**: Access your macOS terminal from any web browser
-- **Native Performance**: Built with Swift/SwiftUI for optimal macOS integration
+- **Remote Terminal Access**: Access your terminal from any web browser
+- **Cross-Platform**: Native macOS app with Swift/SwiftUI, plus Linux support via npm package
 - **Secure Connection**: End-to-end encrypted terminal sessions
-- **Multi-Platform**: Works on iOS, iPadOS, and any modern web browser
+- **Multi-Device**: Works on iOS, iPadOS, and any modern web browser
 - **Real-time Sync**: Changes sync instantly across all connected devices
+- **Headless Mode**: Run on servers and cloud instances without a GUI
 
 ## Quick Start
 
+### For macOS
 1. [Download VibeTunnel](https://vibetunnel.com/download) for macOS
 2. Launch the app and create your first terminal session
 3. Access your terminal from any device at your unique VibeTunnel URL
-4. Start coding from anywhere!
+
+### For Linux & Headless Environments
+1. Install via npm: `npm install -g vibetunnel`
+2. Run the server: `vibetunnel-server`
+3. Access your terminal at `http://localhost:4020`
 
 ## Documentation Overview