improve custom node docs

mac/docs/BunServerSupport.md

@@ -1,96 +0,0 @@
-# Bun Server Support
-
-VibeTunnel now includes support for running with Bun, a high-performance JavaScript runtime with built-in native module support.
-
-## Architecture Considerations
-
-**Important**: Bun does not support universal binaries. The Bun executable is architecture-specific and will be built for the native architecture during compilation. Despite this limitation, VibeTunnel still creates a universal binary for the main application, with the Bun executable being selected at runtime based on the current architecture.
-
-## Features
-
-- High-performance JavaScript/TypeScript execution
-- Built-in native module support (pty.node, spawn-helper)
-- Integrated `fwd` command for terminal forwarding
-- Smaller binary size compared to Node.js
-
-## Building with Bun Support
-
-### Automatic Build (Recommended)
-
-The Bun executable is automatically built during the main build process. The build script:
-1. Detects the native architecture
-2. Builds the Bun executable for that architecture
-3. Embeds it into the universal app bundle
-
-**Note**: Each build contains only the Bun executable for the build machine's architecture. For a true universal distribution, separate builds on Intel and Apple Silicon machines would need to be combined.
-
-### Manual Build
-
-If you need to build the Bun executable manually:
-
-```bash
-cd web
-node build-native.js
-```
-
-This creates:
-- `native/vibetunnel` - The Bun executable
-- `native/pty.node` - Native PTY module
-- `native/spawn-helper` - Helper binary for spawning processes
-
-### Verification
-
-To verify Bun support is properly built:
-
-```bash
-# Check if files exist
-ls -la web/native/
-
-# Test the executable
-web/native/vibetunnel --version
-```
-
-## CLI Usage
-
-When using the Bun server, the `vt` command automatically prepends `fwd`:
-
-```bash
-# With Go server:
-vt mycommand  # → vibetunnel mycommand
-
-# With Bun server:
-vt mycommand  # → vibetunnel fwd mycommand
-```
-
-## Switching Between Servers
-
-You can switch between Go and Bun servers in Settings → Debug → Server Type.
-
-When switching, you may need to reinstall the CLI tools to update the `vt` wrapper script.
-
-## Troubleshooting
-
-### "Bun server is not available"
-
-This error means the Bun executable or native modules are missing. Solutions:
-
-1. Ensure the build script runs: Check Xcode build logs for "Build Bun Executable"
-2. Build manually: `cd web && node build-native.js`
-3. Verify files: Check `VibeTunnel.app/Contents/Resources/` for:
-   - vibetunnel (60MB executable)
-   - pty.node
-   - spawn-helper
-
-### CLI not working after switching
-
-After switching server types, reinstall the CLI tools:
-1. Settings → Advanced → Reinstall CLI Tools
-2. Enter admin password when prompted
-3. The installer will create the appropriate `vt` script/symlink
-
-## Development
-
-The Bun server code is in:
-- `mac/VibeTunnel/Core/Services/BunServer.swift` - Swift integration
-- `web/src/server/` - JavaScript server implementation
-- `web/build-native.js` - Build script for creating the Bun executable

web/build-custom-node.js

@@ -3,23 +3,12 @@
 /**
  * Build a custom Node.js binary with reduced size by excluding features we don't need.
  * 
- * This creates a Node.js build without:
+ * See custom-node.md for detailed documentation, usage, and troubleshooting.
- * - International support (ICU) - saves ~28MB
- * - npm/npx - saves ~5MB
- * - corepack
- * - dtrace/etw instrumentation
  * 
- * The resulting binary is typically 50-60MB instead of 110+MB.
+ * Quick usage:
- * 
+ *   node build-custom-node.js               # Current version
- * Usage:
+ *   node build-custom-node.js --latest      # Latest version
- * ```bash
+ *   node build-custom-node.js --version=24.1.0  # Specific version
- * node build-custom-node.js               # Build for current Node.js version
- * node build-custom-node.js --latest      # Build latest Node.js version
- * node build-custom-node.js --version=24.2.0  # Build specific version
- * ```
- * 
- * The custom Node.js will be built in:
- * .node-builds/node-vXX-minimal/out/Release/node
  */
 
 const { execSync } = require('child_process');

web/custom-node.md

@@ -0,0 +1,87 @@
+# Custom Node.js Build
+
+This document describes how to build a minimal custom Node.js binary for VibeTunnel.
+
+## Overview
+
+The custom Node.js build reduces binary size from ~110MB to ~50-60MB by excluding:
+- International support (ICU) - saves ~28MB
+- npm/npx - saves ~5MB
+- corepack
+- dtrace/etw instrumentation
+- Inspector protocol
+- Other unused features
+
+## Usage
+
+```bash
+# Build for current Node.js version
+node build-custom-node.js
+
+# Build latest Node.js version
+node build-custom-node.js --latest
+
+# Build specific version
+node build-custom-node.js --version=24.1.0
+node build-custom-node.js --version=24.2.0
+```
+
+## Output Location
+
+The custom Node.js will be built in:
+```
+.node-builds/node-vXX-minimal/out/Release/node
+```
+
+## Build Requirements
+
+- Python 3 (for Node.js build system)
+- C++ compiler (Xcode command line tools on macOS)
+- make
+- ~10-20 minutes build time
+
+## Troubleshooting
+
+### Incomplete Builds
+
+If builds are incomplete (directories exist but no executable):
+
+```bash
+# Delete the incomplete build
+rm -rf .node-builds/node-v24.1.0-minimal
+
+# Rebuild
+node build-custom-node.js --version=24.1.0
+```
+
+### Common Issues
+
+- **Interrupted builds**: Delete the directory and rebuild
+- **Missing executable**: Check `.node-builds/node-vXX-minimal/out/Release/node` exists
+- **Build failures**: Ensure Xcode command line tools are installed (macOS)
+- **Build time**: The build process takes 10-20 minutes - let it complete fully
+
+### Verification
+
+After building, verify the executable exists:
+```bash
+ls -la .node-builds/node-v24.1.0-minimal/out/Release/node
+```
+
+## Using with build-native.js
+
+The custom Node.js is automatically detected by `build-native.js`:
+
+```bash
+# Auto-detect latest custom build
+node build-native.js --custom-node
+
+# Specify custom Node path
+node build-native.js --custom-node=/path/to/custom/node
+```
+
+## Size Comparison
+
+- Standard Node.js: ~110MB
+- Custom Node.js: ~50-60MB
+- Final executable with custom Node: ~105MB (vs ~155MB with standard Node)