Installer doesn't fall back to CLI mode in headless/SSH environments (v3.0)

[lumberwhack]

Hello, first off wanted to say how much I appreciate everything you guys have done with PAI. It is absolutely amazing. After giving it a test run on a local VM, decided to permanently add it to the homelab by installing it on an Ubuntu Server (no desktop) via SSH.

Issue:
When running the installer in a terminal-only environment, it doesn't automatically fall back to CLI mode. The docs suggest it should, but install.sh always invokes main.ts with --mode gui — and if Electron can't launch, the process just exits rather than switching to CLI.

Steps to Reproduce (on main / a5622ad):

1. Use a terminal-only environment: Ubuntu Server 24.04.4 LTS (Noble) over SSH (fresh install), with no DISPLAY/WAYLAND_DISPLAY.
2. Run cd ~/.claude && ./PAI-Install/install.sh.
3. install.sh always invokes main.ts with --mode gui.
4. If Electron cannot launch (no desktop/display), process exits instead of switching to CLI.

Expected behavior:
According to the readme.md (top level Release/V3.0), I was expecting headless/terminal-only environments to default to CLI mode. An explicit --mode flag or env var override could be helpful. I had to search around into the PAI-Install/readme.md to find the work around. (Will be submitting a simple PR shortly to fix a broken URL for v3.0 that tries to link to install.md).

Code review (PAI+Claude and Codex):

• install.sh hardcodes GUI: Releases/v3.0/.claude/PAI-Install/install.sh:156
• main.ts fallback only covers dependency install failure, not GUI launch/runtime failure: Releases/v3.0/.claude/PAI-Install/main.ts:42, :45
• The GUI exit path just exits with no fallback: Releases/v3.0/.claude/PAI-Install/main.ts:66, :67
• Docs implied terminal fallback would work: Releases/v3.0/README.md:142, :144

Workaround:
Following the Quick Start instructions (copy release to ~/.claude, then run the installer from there), substituting step 4 with:

cd ~/.claude && bun run PAI-Install/main.ts --mode cli

The CLI wizard completed successfully this way.

Suggestions:
It'd be great if install.sh auto-detected the environment and defaulted to cli for common headless cases (no display vars on Linux, macOS SSH session), with --mode and an env var as explicit overrides. Updating the docs to match actual behavior would also help avoid the confusion I ran into.

---

I originally wrote this up as a PR, but it ended up being quite a bit of code. I'm still pretty novice at coding, so it would have been a lot of AI assistance that has been catching some heat lately in the FOSS community. Looking forward to continuing to learn about your project and hopefully give some more contributions!

[kaimagnus]

Fixed in v4.0.2 — the bootstrap script now auto-detects headless/SSH environments (checks $DISPLAY, $WAYLAND_DISPLAY, and platform) and falls back to CLI mode automatically. Thanks for reporting!