vibepup 1.0.2 → 1.0.4

package/.ralph/runs/iter-0001/agent_response.txt

@@ -0,0 +1,189 @@
+INFO  2026-01-26T13:18:12 +54ms service=models.dev file={} refreshing
+|  Bash     List top-level directory contents
+
+total 28
+drwxr-xr-x 1 shantanu shantanu  204 Jan 26 18:43 .
+drwxr-xr-x 1 shantanu shantanu  266 Jan 26 15:08 ..
+drwxr-xr-x 1 shantanu shantanu   16 Jan 26 13:39 bin
+drwxr-xr-x 1 shantanu shantanu   70 Jan 26 13:39 lib
+-rw-r--r-- 1 shantanu shantanu   39 Jan 24 17:28 .npmignore
+-rw-r--r-- 1 shantanu shantanu  832 Jan 26 18:10 package.json
+-rw-r--r-- 1 shantanu shantanu  132 Jan 26 13:39 prd.md
+-rw-r--r-- 1 shantanu shantanu    3 Jan 26 13:39 prd.state.json
+-rw-r--r-- 1 shantanu shantanu    0 Jan 26 18:46 progress.log
+-rw-r--r-- 1 shantanu shantanu 1541 Jan 26 18:10 PUBLISHING.md
+drwxr-xr-x 1 shantanu shantanu    8 Jan 26 18:43 .ralph
+-rw-r--r-- 1 shantanu shantanu 7218 Jan 26 15:08 README.md
+-rw-r--r-- 1 shantanu shantanu    0 Jan 26 14:33 repo-map.md
+drwxr-xr-x 1 shantanu shantanu  178 Jan 26 18:48 tui
+
+|  Bash     Recursively list repository tree
+
+.:
+bin
+lib
+package.json
+prd.md
+prd.state.json
+progress.log
+PUBLISHING.md
+README.md
+repo-map.md
+tui
+
+./bin:
+ralph.js
+
+./lib:
+agents
+prompt.md
+ralph.sh
+ralph-win.js
+
+./lib/agents:
+architect.md
+reviewer.md
+
+./tui:
+animations
+config
+data
+go.mod
+go.sum
+main.go
+motion
+persona
+process
+progress.log
+theme
+ui
+vibepup-tui
+
+./tui/animations:
+loaders.go
+memes.go
+registry.go
+
+./tui/config:
+flags.go
+
+./tui/data:
+
+./tui/motion:
+engine.go
+
+./tui/persona:
+quip.go
+
+./tui/process:
+runner.go
+
+./tui/theme:
+registry.go
+
+./tui/ui:
+layout.go
+statusbar.go
+viewport.go
+
+|  Bash     Show git status with untracked files
+
+MM npm-package/PUBLISHING.md
+ M npm-package/bin/ralph.js
+ M npm-package/lib/ralph.sh
+M  npm-package/package.json
+ M npm-package/tui/config/flags.go
+ M npm-package/tui/go.mod
+ M npm-package/tui/go.sum
+ M npm-package/tui/main.go
+ M npm-package/tui/motion/engine.go
+ M npm-package/tui/persona/quip.go
+?? npm-package/.ralph/runs/iter-0001/agent_response.txt
+?? npm-package/.ralph/runs/latest
+?? npm-package/tui/process/runner.go
+?? npm-package/tui/ui/viewport.go
+
+[Category+Skill Reminder]
+
+You are an orchestrator agent. Consider whether this work should be delegated:
+
+**DELEGATE when:**
+- UI/Frontend work → category: "visual-engineering", skills: ["frontend-ui-ux"]
+- Complex logic/architecture → category: "ultrabrain"
+- Quick/trivial tasks → category: "quick"
+- Git operations → skills: ["git-master"]
+- Browser automation → skills: ["playwright"] or ["agent-browser"]
+
+**DO IT YOURSELF when:**
+- Gathering context/exploring codebase
+- Simple edits that are part of a larger task you're coordinating
+- Tasks requiring your full context understanding
+
+Example delegation:
+```
+delegate_task(
+  category="visual-engineering",
+  load_skills=["frontend-ui-ux"],
+  description="Implement responsive navbar with animations",
+  run_in_background=true
+)
+```
+
+|  Bash     Show repo root, branch, recent commits
+
+/home/shantanu/ralph-project
+master
+b968a2c changes as per the new anim and blocking
+63735d8 docs: enhance README with TUI build instructions and local development setup
+038ab49 feat: add Windows mode selection and project documentation
+c36c7da feat: optimize TUI command execution with direct vibepup invocation
+6025683 Add Windows mode selection with interactive prompt and comprehensive docs
+78c051f feat: revamp TUI with charm.sh libraries and enhance CLI flags
+170b4ae chore: update package version to 1.0.2
+67ba775 docs: add vibepup free setup command
+57c7095 feat: add vibepup free setup and improve TUI flow
+cc7d3e5 chore: update package version to 1.0.1 and specify bin entry for vibepup
+
+|  Glob     {"pattern":"**/package.json","path":"/home/shantanu/ralph-project/npm-package"}
+|  Glob     {"pattern":"**/{tsconfig*.json,jsconfig*.json}","path":"/home/shantanu/ralph-project/npm-package"}
+|  Glob     {"pattern":"**/{README*,readme*,CHANGELOG*,LICENSE*,CONTRIBUTING*}","path":"/home/shantanu/ralph-project/npm-package"}
+|  Glob     {"pattern":"**/{src,index.* ,cli.* ,bin/*,lib/*,dist/*}","path":"/home/shantanu/ralph-project/npm-package"}
+|  Grep     {"pattern":"\"(name|version|type|main|module|types|exports|bin|files|scripts|dependencies|devDependencies)\"\\s*:","include":"package.json","path":"/home/shantanu/ralph-project/npm-package"}
+|  ast_grep_search  {"pattern":"export $$$","lang":"typescript","paths":["/home/shantanu/ralph-project/npm-package"],"context":2}
+|  delegate_task  {"subagent_type":"explore","run_in_background":true,"load_skills":[],"description":"Map codebase structure","prompt":"1. TASK: Map the repository's high-level structure and identify key subsystems (CLI, core library, build tooling, tests).\n2. EXPECTED OUTCOME: A concise structural map listing top-level dirs/files, entrypoints, and where core logic likely lives.\n3. REQUIRED TOOLS: functions.glob, functions.grep, functions.read (no bash).\n4. MUST DO: Find package entrypoints (bin/main/exports), identify src/lib/dist layout, note test framework and config files.\n5. MUST NOT DO: Do not propose implementations; do not modify files; do not run commands.\n6. CONTEXT: Repo at /home/shantanu/ralph-project/npm-package; goal is to populate repo-map.md."}
+|  delegate_task  {"subagent_type":"explore","run_in_background":true,"load_skills":[],"description":"Find patterns & conventions","prompt":"1. TASK: Discover coding conventions and patterns used across the repo (TS/JS module style, lint/format, error handling, logging, config).\n2. EXPECTED OUTCOME: A checklist of conventions + where they are defined (configs, sample files).\n3. REQUIRED TOOLS: functions.grep, functions.glob, functions.read.\n4. MUST DO: Locate ESLint/Prettier configs, tsconfig settings, test runner config, Node ESM/CJS conventions.\n5. MUST NOT DO: Do not change files; do not run builds/tests.\n6. CONTEXT: PLAN mode mapping only."}
+|  delegate_task  {"subagent_type":"explore","run_in_background":true,"load_skills":[],"description":"AST surface scan","prompt":"1. TASK: Use AST-oriented searching to identify the public API surface (exported functions/classes) and main modules.\n2. EXPECTED OUTCOME: A short list of key exported symbols and their defining files; note any CLI command registration.\n3. REQUIRED TOOLS: functions.ast_grep_search, functions.grep, functions.glob, functions.read.\n4. MUST DO: Focus on top-level exports and any CLI entry file.\n5. MUST NOT DO: No edits; no speculative design.\n6. CONTEXT: Repo /home/shantanu/ralph-project/npm-package."}
+1076 |     const info = provider.models[modelID]
+1077 |     if (!info) {
+1078 |       const availableModels = Object.keys(provider.models)
+1079 |       const matches = fuzzysort.go(modelID, availableModels, { limit: 3, threshold: -10000 })
+1080 |       const suggestions = matches.map((m) => m.target)
+1081 |       throw new ModelNotFoundError({ providerID, modelID, suggestions })
+                   ^
+ProviderModelNotFoundError: ProviderModelNotFoundError
+ data: {
+  providerID: "opencode",
+  modelID: "glm-4.7-free",
+  suggestions: [],
+},
+
+      at getModel (src/provider/provider.ts:1081:13)
+
+|  delegate_task  {"subagent_type":"librarian","run_in_background":true,"load_skills":[],"description":"External: package name intel","prompt":"1. TASK: Infer likely usage patterns for this npm package based on its name once discovered (from package.json).\n2. EXPECTED OUTCOME: A brief note: comparable OSS packages, typical file layout, and what docs to mirror.\n3. REQUIRED TOOLS: functions.websearch_web_search_exa (or functions.grep_app_searchGitHub if name known).\n4. MUST DO: Wait until you know the package name; then search for similar packages and patterns.\n5. MUST NOT DO: Do not suggest code changes; do not fetch irrelevant sources.\n6. CONTEXT: We are mapping architecture only."}
+1076 |     const info = provider.models[modelID]
+1077 |     if (!info) {
+1078 |       const availableModels = Object.keys(provider.models)
+1079 |       const matches = fuzzysort.go(modelID, availableModels, { limit: 3, threshold: -10000 })
+1080 |       const suggestions = matches.map((m) => m.target)
+1081 |       throw new ModelNotFoundError({ providerID, modelID, suggestions })
+                   ^
+ProviderModelNotFoundError: ProviderModelNotFoundError
+ data: {
+  providerID: "opencode",
+  modelID: "glm-4.7-free",
+  suggestions: [],
+},
+
+      at getModel (src/provider/provider.ts:1081:13)
+
+|  delegate_task  {"subagent_type":"librarian","run_in_background":true,"load_skills":[],"description":"External: tooling configs","prompt":"1. TASK: If the repo uses common tooling (TypeScript, eslint, prettier, vitest/jest), collect best-practice structure references.\n2. EXPECTED OUTCOME: A short set of pointers to official docs about config file roles and typical layouts.\n3. REQUIRED TOOLS: functions.websearch_web_search_exa, functions.context7_resolve-library-id, functions.context7_query-docs.\n4. MUST DO: Focus on docs about package exports/bin fields, TS project structuring for npm packages.\n5. MUST NOT DO: No implementation guidance beyond architecture mapping.\n6. CONTEXT: Used to enrich repo-map.md mapping."}

package/PUBLISHING.md

@@ -1,5 +1,43 @@
 # Vibepup npm Publishing (from any machine)
 
+cd np   ## 0) Test from build (before pushing to dev npm)
+
+Run and test the package **from the built artifacts** before publishing.
+
+**Option A – Run from repo (fast iteration)**  
+Requires Go 1.22+ for TUI.
+
+```bash
+cd npm-package
+npm run build          # build TUI binary (tui/vibepup-tui)
+npm run run:local -- --tui     # test TUI
+npm run run:local -- --watch   # test CLI engine
+npm run run:local -- 3         # test N-iteration run
+```
+
+**Option B – Install from local tarball (simulate npm install)**  
+Same as users installing from registry.
+
+```bash
+cd npm-package
+npm run pack:local     # build TUI + npm pack → vibepup-1.0.2.tgz
+npm install -g ./vibepup-1.0.2.tgz
+vibepup --tui          # or vibepup --watch, vibepup 3, etc.
+```
+
+**Option C – `npm link` (global symlink for development)**  
+Changes in the repo are reflected immediately when you run `vibepup`.
+
+```bash
+cd npm-package
+npm run build
+npm link
+cd /any/project
+vibepup --tui
+```
+
+---
+
 ## 1) Login
 ```bash
 npm adduser
@@ -19,4 +57,4 @@ npm publish --access public
 ## Notes
 - Publish must be run inside `npm-package/`.
 - If you see a `bin` warning, ensure `package.json` has: `"bin": "bin/ralph.js"`.
-- Windows users should have Git Bash or WSL installed to run the CLI.
+- Windows users: WSL2 mode is recommended for publishing to ensure consistent environment behavior. Windows-native mode is supported but may lack some Linux-parity features.

package/README.md

@@ -35,13 +35,44 @@ Most AI agents are black boxes that overwrite your files and get stuck in loops.
 ## 🚀 Get Started
 
 ### ✅ Works Everywhere
-Linux, macOS, and Windows (via Git Bash or WSL). Vibepup is portable and requires only Bash + `opencode`.
+Linux, macOS, and Windows. **Recommended:** use WSL2 on Windows for full Linux parity.
 
 ### 1. Install
 ```bash
 npm install -g vibepup
 ```
 
+### Windows (choose your mode)
+
+Vibepup supports two modes on Windows. If a TTY is detected, it will prompt you to choose; otherwise, it defaults to WSL if installed.
+
+**Recommended: WSL2 Mode**
+Best parity with Linux/macOS. Requires [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) installed.
+```bash
+vibepup --platform=wsl
+# or
+vibepup --wsl
+```
+*   **Note:** When using WSL mode, run from a WSL shell or ensure paths are WSL-formatted (e.g., `/home/...` or `/mnt/c/...`). `wsl.exe` forwards arguments without path translation. [Microsoft Path Docs](https://learn.microsoft.com/en-us/windows/wsl/filesystems#mixing-linux-and-windows-commands).
+
+**Windows-native Mode**
+Simpler setup, but with limitations.
+```bash
+vibepup --platform=windows
+# or
+vibepup --windows
+```
+
+**Windows-native Limitations:**
+- **No Bash/Curl Helpers:** Linux-specific shell scripts or `curl`-based skills may fail.
+- **Reduced Parity:** Some advanced agent behaviors optimized for Linux environments might be unavailable.
+- **No Design-Mode Injection:** Environment-based skill injection (like `DESIGN_MODE`) is not supported in native mode.
+- **Path Differences:** Uses Windows backslashes (`\`) which can occasionally confuse agents expecting POSIX paths.
+
+**Auto-selection Behavior:**
+- If WSL is detected, Vibepup defaults to WSL mode unless explicitly overridden.
+- Use `--platform=windows` or `--windows` to force native mode.
+
 ### 1b. bunx (no global install)
 ```bash
 bunx vibepup --watch
@@ -62,6 +93,11 @@ vibepup --tui
 vibepup free
 ```
 
+### 1f. Doctor (diagnose setup issues)
+```bash
+vibepup doctor
+```
+
 ### 2. Fetch!
 Go to any empty folder and tell Vibepup what to build.
 
@@ -105,6 +141,52 @@ Vibepup works out of the box. For the easiest free-tier bootstrap, run:
 vibepup free
 ```
 
+### ✅ Full Onboarding (step-by-step)
+
+#### Step 0: Diagnose (recommended)
+```bash
+vibepup doctor
+```
+This checks Node/npm/opencode and your model registry.
+
+#### Step 1: Install Node 20+
+Free auth requires Node 20+.
+- **WSL/Linux:** `nvm install 20 && nvm use 20`
+- **Windows:** https://nodejs.org/en/download
+
+#### Step 2: Fix npm permissions (WSL/Linux)
+If npm fails with `EACCES`:
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+Then retry the install.
+
+#### Step 3: Install opencode
+```bash
+npm install -g opencode-ai
+```
+
+#### Step 4: Free-tier auth
+```bash
+npm install -g opencode-antigravity-auth
+opencode auth login antigravity
+opencode models --refresh
+```
+
+If you cannot open a browser:
+```bash
+opencode auth print-token antigravity
+export OPENCODE_ANTIGRAVITY_TOKEN="<token>"
+```
+
+#### Step 5: Run Vibepup
+```bash
+vibepup --watch
+```
+
 If `opencode` is missing, Vibepup will try to install it on Linux/macOS and then guide you. You can also set up a free tier manually:
 
 ```bash
@@ -119,12 +201,26 @@ export OPENCODE_ANTIGRAVITY_TOKEN="<token>"
 ```
 
 ### TUI build (optional)
-TUI requires Go 1.22+.
+TUI requires Go 1.22+. If you skip this, `vibepup --tui` will try `go run .` and needs `go` in your PATH.
 ```bash
 cd npm-package/tui
-
-go build -o vibepup-tui
+go build -o vibepup-tui .
 ```
+Or from `npm-package`: `npm run build:tui`.
+
+### Run locally (development)
+To test the Vibepup CLI from this repo without publishing:
+
+1. **Build the TUI** (needed for `--tui`; avoids "spawn go ENOENT"):
+   ```bash
+   cd npm-package && npm run build:tui
+   ```
+2. **Run the local package:**
+   ```bash
+   cd npm-package && npx . --tui
+   ```
+   Or run the CLI engine: `npx . --watch`, `npx . 3`, etc.
+3. **Optional – use globally while developing:** `cd npm-package && npm link`, then `vibepup --tui` (or `vibepup --watch`) from any directory.
 
 Vibepup also supports manual config in `~/.config/ralph/config.json`:
 
@@ -145,5 +241,25 @@ Vibepup also supports manual config in `~/.config/ralph/config.json`:
 *   **Build Mode**: When `repo-map.md` exists, Vibepup executes tasks from `prd.md`.
 
 
+## 🎛️ TUI flags (Go)
+TUI lives in `npm-package/tui` (Go 1.22+). Helpful flags:
+
+- `--quiet` reduce motion/sass; `--dense` increase animation density.
+- `--no-emoji` force ASCII frames; `--theme <name>` swap palettes.
+- `--snark mild|spicy|unhinged` choose persona spice level.
+- `--anim <preset>` pick loader (e.g., `vhs-scan`, `matrix-rain`).
+- `--fx fire|matrix|none` sysc-Go header effect toggle (when wired).
+- `--perf-low` lower FPS; `--no-alt` avoid alt-screen; `--force-run` bypass TTY check (CI/non-interactive).
+
+Hotkeys: `q` quits (kills child process), `?` toggles help. Palette/anim/snark switching via command palette is planned.
+
+## 🛠️ Troubleshooting
+
+- **TUI fails in CI/non-TTY**: use `--force-run` to skip TTY enforcement; add `--no-alt` to avoid alt-screen.
+- **Multiple terminals keep running after quit**: press `q`; the TUI now tracks and kills the child process before exit.
+- **Emoji render poorly**: add `--no-emoji` or pick a theme with `--theme=mono-chill`.
+- **High CPU from animations**: add `--perf-low` or `--quiet` to slow ticks and reduce density.
+
+
 ## License
 MIT

package/bin/ralph.js

@@ -1,74 +1,190 @@
 #!/usr/bin/env node
 
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const readline = require('readline');
 
-const scriptPath = path.join(__dirname, '../lib/ralph.sh');
-const allArgs = process.argv.slice(2);
-const useTui = allArgs.includes('--tui');
-const args = allArgs.filter((arg) => arg !== '--tui');
+async function promptPlatform() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
 
-try {
-  fs.chmodSync(scriptPath, '755');
-} catch (err) {}
+    rl.question(
+      '\n🐾 Vibepup on Windows! Choose your mode:\n' +
+      '  1) WSL (recommended) - Full Linux parity\n' +
+      '  2) Windows-native - Simpler setup\n' +
+      'Select (1 or 2): ',
+      (answer) => {
+        rl.close();
+        const choice = answer.trim();
+        if (choice === '1') {
+          resolve('wsl');
+        } else if (choice === '2') {
+          resolve('windows');
+        } else {
+          console.log('Invalid choice. Defaulting to WSL...');
+          resolve('wsl');
+        }
+      }
+    );
+  });
+}
 
-console.log('🐾 Vibepup is waking up...');
+async function main() {
+  const scriptPath = path.join(__dirname, '../lib/runner/index.js');
+  const windowsRunnerPath = path.join(__dirname, '../lib/runner/index.js');
+  const allArgs = process.argv.slice(2);
+  const useTui = allArgs.includes('--tui');
 
-const shellOptions = { stdio: 'inherit', shell: false };
+  let selectedPlatform = null;
+  let explicitPlatformFlag = false;
+  const args = [];
+  for (const arg of allArgs) {
+    if (arg === '--tui') continue;
+    if (arg === '--wsl') {
+      selectedPlatform = 'wsl';
+      explicitPlatformFlag = true;
+      continue;
+    }
+    if (arg === '--windows') {
+      selectedPlatform = 'windows';
+      explicitPlatformFlag = true;
+      continue;
+    }
+    if (arg.startsWith('--platform=')) {
+      selectedPlatform = arg.split('=')[1];
+      explicitPlatformFlag = true;
+      continue;
+    }
+    args.push(arg);
+  }
 
-if (useTui) {
-  const tuiDir = path.join(__dirname, '../tui');
-  const binName = os.platform() === 'win32' ? 'vibepup-tui.exe' : 'vibepup-tui';
-  const binPath = path.join(tuiDir, binName);
+  try {
+    fs.chmodSync(scriptPath, '755');
+  } catch (err) {}
 
-  if (fs.existsSync(binPath)) {
-    const tui = spawn(binPath, args, shellOptions);
-    tui.on('error', (err) => {
-      console.error('❌ Failed to start Vibepup TUI.');
-      console.error(String(err));
-      process.exit(1);
-    });
-    tui.on('close', (code) => process.exit(code));
-    return;
-  }
+  console.log('🐾 Vibepup is waking up...');
 
-  if (os.platform() !== 'win32' && fs.existsSync(tuiDir)) {
-    const goCmd = spawn('go', ['run', '.', ...args], { ...shellOptions, cwd: tuiDir });
-    goCmd.on('error', (err) => {
-      console.error('❌ Failed to start Vibepup TUI.');
-      console.error(String(err));
-      process.exit(1);
-    });
-    goCmd.on('close', (code) => process.exit(code));
-    return;
-  }
+  const shellOptions = { stdio: 'inherit', shell: false };
+  const isWindows = os.platform() === 'win32';
 
-  console.error('❌ Vibepup TUI not available.');
-  console.error('   Build it with:');
-  console.error('   cd ' + tuiDir + ' && go build -o ' + binName);
-  process.exit(1);
-}
+  const hasWsl = () => {
+    if (!isWindows) return false;
+    const res = spawnSync('wsl.exe', ['-l', '-q'], { stdio: 'ignore' });
+    return res.status === 0;
+  };
 
-let command = 'bash';
-let cmdArgs = [scriptPath, ...args];
-if (os.platform() === 'win32') {
-  shellOptions.shell = true;
-}
+  const toWslPath = (winPath) => {
+    const resolved = path.resolve(winPath);
+    const drive = resolved[0].toLowerCase();
+    const rest = resolved.slice(2).replace(/\\/g, '/');
+    return `/mnt/${drive}${rest}`;
+  };
 
-const vibepup = spawn(command, cmdArgs, shellOptions);
+   if (useTui) {
+     const tuiDir = path.join(__dirname, '../tui');
+     const binName = os.platform() === 'win32' ? 'vibepup-tui.exe' : 'vibepup-tui';
+     const binPath = path.join(tuiDir, binName);
 
-vibepup.on('error', (err) => {
+      if (fs.existsSync(binPath)) {
+        const tuiArgs = ['--runner', scriptPath, ...args];
+        const tui = spawn(binPath, tuiArgs, shellOptions);
+       tui.on('error', (err) => {
+         console.error('❌ Failed to start Vibepup TUI.');
+         console.error(String(err));
+         process.exit(1);
+       });
+       tui.on('close', (code) => process.exit(code));
+       return;
+     }
+
+      if (os.platform() !== 'win32' && fs.existsSync(tuiDir)) {
+        const goArgs = ['run', '.', '--runner', scriptPath, ...args];
+        const goCmd = spawn('go', goArgs, { ...shellOptions, cwd: tuiDir });
+       goCmd.on('error', (err) => {
+         console.error('❌ Failed to start Vibepup TUI.');
+         console.error(String(err));
+         process.exit(1);
+       });
+       goCmd.on('close', (code) => process.exit(code));
+       return;
+     }
+
+     console.error('❌ Vibepup TUI not available.');
+     console.error('   Build it with:');
+     console.error('   cd ' + tuiDir + ' && go build -o ' + binName);
+     process.exit(1);
+   }
+
+   let command = process.execPath;
+   let cmdArgs = [scriptPath, ...args];
+
+   if (isWindows) {
+     const wslAvailable = hasWsl();
+
+     // Interactive prompt for Windows when no explicit platform flag provided
+     if (!explicitPlatformFlag && process.stdin.isTTY) {
+       if (wslAvailable) {
+         selectedPlatform = await promptPlatform();
+       } else {
+         console.warn('⚠️  WSL not detected. Using Windows-native mode.');
+         console.warn('   💡 Tip: install WSL2 for full Linux parity.');
+         selectedPlatform = 'windows';
+       }
+     } else if (!explicitPlatformFlag) {
+       // No TTY: auto-select WSL if available, else Windows
+       selectedPlatform = wslAvailable ? 'wsl' : 'windows';
+       if (!wslAvailable) {
+         console.warn('⚠️  WSL not detected. Using Windows-native mode.');
+         console.warn('   💡 Tip: install WSL2 for full Linux parity.');
+       }
+     }
+
+     const normalizedPlatform = (selectedPlatform || '').toLowerCase();
+
+      if (normalizedPlatform === 'wsl' || (!normalizedPlatform && wslAvailable)) {
+        if (!wslAvailable) {
+          console.error('❌ WSL not found. Install WSL2 or use --platform=windows.');
+          process.exit(1);
+        }
+        const wslScriptPath = toWslPath(scriptPath);
+        const wslCwd = toWslPath(process.cwd());
+        command = 'wsl.exe';
+        cmdArgs = ['--cd', wslCwd, '--', 'node', wslScriptPath, ...args];
+      } else {
+        console.warn('⚠️  Using Windows-native mode.');
+        console.warn('   💡 Tip: install WSL2 for full Linux parity.');
+        command = process.execPath;
+        cmdArgs = [windowsRunnerPath, ...args];
+      }
+   }
+
+  const vibepup = spawn(command, cmdArgs, shellOptions);
+
+  vibepup.on('error', (err) => {
     console.error('❌ Failed to start Vibepup.');
     if (err.code === 'ENOENT') {
-        console.error('   Error: Bash not found. Please install Git Bash or WSL.');
+      if (command === 'bash') {
+        console.error('   Error: Bash not found. Install WSL2 or use --platform=windows.');
+      } else {
+        console.error('   Error: Required runtime not found on PATH.');
+      }
     } else {
-        console.error(String(err));
+      console.error(String(err));
     }
     process.exit(1);
-});
+  });
 
-vibepup.on('close', (code) => {
+  vibepup.on('close', (code) => {
     process.exit(code);
+  });
+}
+
+main().catch((err) => {
+  console.error('❌ Error:', err.message);
+  process.exit(1);
 });

package/lib/ralph-win.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const runnerPath = path.join(__dirname, 'runner', 'index.js');
+const result = spawnSync(process.execPath, [runnerPath, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(result.status || 0);