improve custom node doc

README.md

@@ -122,13 +122,34 @@ EOF
 cd web
 npm install
 npm run build
-node build-native.js  # Creates Bun executable
+
+# Optional: Build with custom Node.js for smaller binary (46% size reduction)
+# export VIBETUNNEL_USE_CUSTOM_NODE=YES
+# node build-custom-node.js  # Build optimized Node.js (one-time, ~20 min)
+# npm run build              # Will use custom Node.js automatically
 
 # Build the macOS app
 cd ../mac
 ./scripts/build.sh --configuration Release
 ```
 
+### Custom Node.js Builds
+
+VibeTunnel supports building with a custom Node.js for a 46% smaller executable (61MB vs 107MB):
+
+```bash
+# Build custom Node.js (one-time, ~20 minutes)
+node build-custom-node.js
+
+# Use environment variable for all builds
+export VIBETUNNEL_USE_CUSTOM_NODE=YES
+
+# Or use in Xcode Build Settings
+# Add User-Defined Setting: VIBETUNNEL_USE_CUSTOM_NODE = YES
+```
+
+See [Custom Node Build Flags](docs/custom-node-build-flags.md) for detailed optimization information.
+
 ## Development
 
 For development setup and contribution guidelines, see [CONTRIBUTING.md](docs/CONTRIBUTING.md).

docs/custom-node-build-flags.md

@@ -121,17 +121,37 @@ Each `--without-*` flag contributes to size reduction:
 
 ## Usage Instructions
 
-1. **Build custom Node.js**:
-   ```bash
-   node build-custom-node.js --version=24.2.0
-   ```
+### Building Custom Node.js
 
-2. **Use with vibetunnel**:
-   ```bash
-   node build-native.js --custom-node="/path/to/custom/node"
-   ```
+```bash
+node build-custom-node.js               # Builds Node.js 24.2.0 (default)
+node build-custom-node.js --version=24.2.0  # Specific version
+node build-custom-node.js --latest      # Latest version
+```
 
-3. **Result**: A 61MB portable executable (vs 107MB with standard Node.js)
+### Using Custom Node.js
+
+#### Option 1: Command Line
+```bash
+node build-native.js --custom-node      # Auto-detect from .node-builds/
+node build-native.js --custom-node="/path/to/custom/node"  # Specific path
+```
+
+#### Option 2: Environment Variable (Recommended for Xcode)
+```bash
+export VIBETUNNEL_USE_CUSTOM_NODE=YES   # Use custom Node.js
+export VIBETUNNEL_USE_CUSTOM_NODE=NO    # Use system Node.js
+node build-native.js                    # Respects environment variable
+```
+
+### Xcode Integration
+
+For macOS development, set `VIBETUNNEL_USE_CUSTOM_NODE` in Build Settings:
+- **YES**: Always use custom Node.js (61MB executable)
+- **NO**: Always use system Node.js (107MB executable)
+- **(not set)**: Auto-detect based on build configuration
+
+See [Xcode Custom Node Setup](xcode-custom-node-setup.md) for detailed instructions.
 
 ## Future Optimization Opportunities