mayukh4 · Nov 9, 2026 · Nov 9, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -30,6 +30,13 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: step
+    attributes:
+      label: Where did it stop?
+      description: The step number and the exact line on screen, e.g. "Step 9/11 — Installing Hangover Wine... [12:40]". Did you choose Wine?
+      placeholder: "Step 9/11 — Installing Hangover Wine... (Wine: yes)"
+
   - type: textarea
     id: device
     attributes:

diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml
@@ -24,8 +24,23 @@ jobs:
             bash -n "$f"
           done
 
-      # shellcheck runs at error severity only. These scripts intentionally
+      # shellcheck runs at warning severity. These scripts intentionally
       # avoid `set -e`/`set -u` (see the header comment in termux-linux-setup.sh),
       # which trips a lot of shellcheck's style and info-level advice.
       - name: shellcheck
-        run: shellcheck --severity=error --shell=bash *.sh
+        run: shellcheck --severity=warning --shell=bash *.sh
+
+      # The flag parser runs before anything Termux-specific, so it can be
+      # exercised on a normal runner. Also checks the scripts refuse to run
+      # outside Termux instead of half-installing.
+      - name: CLI smoke test
+        run: |
+          bash termux-linux-setup.sh --help | grep -q -- "--de"
+          bash setup-homeassistant.sh --help | grep -q -- "--no-hacs"
+          ! bash termux-linux-setup.sh --de nope 2>/dev/null
+          ! bash termux-linux-setup.sh --bogus 2>/dev/null
+          ! bash setup-homeassistant.sh --bogus 2>/dev/null
+          out=$(HOME=$(mktemp -d) PREFIX=/nonexistent bash termux-linux-setup.sh -y 2>&1 < /dev/null || true)
+          echo "$out" | grep -q "must be run inside Termux"
+          out=$(HOME=$(mktemp -d) PREFIX=/nonexistent bash setup-homeassistant.sh -y 2>&1 < /dev/null || true)
+          echo "$out" | grep -q "must be run inside Termux"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,7 +19,9 @@ There is no build system and no test suite. Before opening a PR:
 
 1. `bash -n termux-linux-setup.sh && bash -n setup-homeassistant.sh` — a syntax
    error here strands someone half-way through a 30-minute install.
-2. `shellcheck --severity=error --shell=bash *.sh` — same check CI runs.
+2. `shellcheck --severity=warning --shell=bash *.sh` — same check CI runs.
+   CI also runs `--help` and a few bad flags through both scripts, so keep
+   `parse_args` free of anything Termux-specific.
 3. Run the changed script end to end on a real device, and say which device and
    Android version you tested on in the PR description.
 
@@ -38,6 +40,11 @@ There is no build system and no test suite. Before opening a PR:
 - **Desktop-specific logic branches on `$DE_CHOICE`** (1=XFCE4, 2=LXQt, 3=MATE,
   4=KDE). If you add a desktop, update every `case` that switches on it —
   packages, kill command, start command, terminal shortcut.
+- **Never `read` from stdin directly.** Use the `ask` helper. With
+  `curl ... | bash` stdin *is* the script, so a bare `read` eats the rest of it.
+  Every new choice also needs a flag, so `-y` installs stay fully unattended.
+- **Redirect `< /dev/null` on anything that might prompt** (apt, pkg) for the
+  same reason.
 - **Colors:** GREEN success, RED error, YELLOW warning, CYAN info, GRAY skipped.
 
 ## Adding or changing a package

diff --git a/README.md b/README.md
@@ -1,11 +1,25 @@
-# Repurpose Your Old Android Phone
+# Linux on Android — Repurpose Your Old Phone
 
+[![shellcheck](https://github.com/mayukh4/linux-android/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/mayukh4/linux-android/actions/workflows/shellcheck.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Platform: Android](https://img.shields.io/badge/platform-Android%207%2B-3ddc84.svg)](https://termux.dev)
 [![Termux](https://img.shields.io/badge/Termux-F--Droid-000000.svg)](https://f-droid.org/en/packages/com.termux/)
 [![Stars](https://img.shields.io/github/stars/mayukh4/linux-android?style=flat)](https://github.com/mayukh4/linux-android/stargazers)
+[![listed on unshittify.dev](https://unshittify.dev/badge.svg)](https://unshittify.dev/p/linux-android/)
 
-Turn any old Android phone into a **Linux desktop** or a **smart home server** — no PC, no root, no cloud. Just [Termux](https://termux.dev).
+Turn any old Android phone or tablet into a **Linux desktop** or a **smart home server** — no PC, no root, no cloud. Just [Termux](https://termux.dev).
+
+One script installs a **GPU-accelerated desktop** (XFCE4, LXQt, MATE or KDE Plasma) using native Termux packages and Termux-X11 — with Turnip/Zink hardware acceleration on Snapdragon, Firefox, VLC, Python, SSH, and optional Wine for Windows apps. A second script turns the phone into an always-on **Home Assistant** server with HACS.
+
+### Quick start
+
+In [Termux from F-Droid](https://f-droid.org/en/packages/com.termux/), with the [Termux-X11 app](https://github.com/termux/termux-x11/releases) installed:
+
+```bash
+pkg upgrade -y && curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh | bash
+```
+
+Then `bash ~/start-linux.sh` and open Termux-X11. Home Assistant instead? Swap in `setup-homeassistant.sh`. Full walkthrough [below](#installation).
 
 > Created to accompany a YouTube video walkthrough. Timestamps are referenced in the video description.
 
@@ -85,17 +99,42 @@ pkg upgrade -y
 
 The `termux-wake-lock` command keeps Termux alive when your screen turns off — without it, Android can kill the process mid-install. The `pkg upgrade` brings your base system up to date before the script runs, preventing a known crash involving `libpcre` and `libandroid-selinux`.
 
-### Step 3 — Download and run the script
+### Step 3 — Run the script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh | bash
+```
+
+The script will ask you to choose a desktop environment and whether you want Wine. Everything else is automatic.
+
+Prefer to read it before running it? Download first:
 
 ```bash
 curl -O https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh
-chmod +x termux-linux-setup.sh
+less termux-linux-setup.sh
 bash termux-linux-setup.sh
 ```
 
-The script will ask you to choose a desktop environment and whether you want Wine. Everything else is automatic.
+Installation takes **10–30 minutes** depending on your internet speed. Each package shows a live timer and the latest download line, so you can tell a big download from a real hang. A full log is saved to `~/termux-setup.log`. Re-running the script is safe — anything already installed is skipped.
+
+<details>
+<summary>Unattended install (no questions)</summary>
+
+Pass choices as flags, and `-y` to accept defaults for anything not given:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh | bash -s -- --de kde --no-wine -y
+```
 
-Installation takes **10–30 minutes** depending on your internet speed. A full log is saved to `~/termux-setup.log` if anything goes wrong.
+| Flag | Meaning |
+|---|---|
+| `--de xfce\|lxqt\|mate\|kde` | Desktop to install (default `xfce`) |
+| `--wine` / `--no-wine` | Windows app support (default: no) |
+| `-y`, `--yes` | Don't ask anything |
+| `-h`, `--help` | Show all options |
+
+`setup-homeassistant.sh` takes `--hacs` / `--no-hacs` and `-y` the same way.
+</details>
 
 ### Step 4 — Start your desktop
 
@@ -269,10 +308,11 @@ Home Assistant Core runs inside a lightweight Ubuntu container (via proot-distro
 ### Installation
 
 ```bash
-curl -O https://raw.githubusercontent.com/mayukh4/linux-android/main/setup-homeassistant.sh
-bash setup-homeassistant.sh
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/setup-homeassistant.sh | bash
 ```
 
+Unattended: `... | bash -s -- --hacs -y`. Run `bash setup-homeassistant.sh --help` for all options.
+
 Installation takes **15–45 minutes** depending on your phone. The longest step is compiling Home Assistant's Python dependencies (numpy, cryptography, etc.) inside the Ubuntu container.
 
 ### Starting and stopping
@@ -418,6 +458,21 @@ Ideas for what you can do with your old Android phone running this setup:
 
 ## Troubleshooting
 
+**The install looks stuck on one step**
+Big packages (KDE Plasma, Firefox, Wine) are hundreds of MB and can take 10+ minutes on a slow connection or phone. The spinner shows the elapsed time and the latest line from apt — if that line keeps changing, it is working. If nothing moves for 5 minutes the script prints a warning. Then:
+
+- Keep Termux in the foreground with the screen on, and make sure `termux-wake-lock` is active.
+- Check the live log from a second Termux session (swipe from the left edge → New session): `tail -f ~/termux-setup.log`
+- Press `Ctrl+C` and re-run the script. Already-installed packages are skipped, so you lose nothing.
+- If one mirror is slow, pick another with `termux-change-repo`.
+
+**Termux closes with "[Process completed (signal 9)]" (Android 12+)**
+Android 12 added a "phantom process killer" that kills background processes Termux starts. On **Android 14+**, turn on *Developer options → Disable child process restrictions*. On Android 12–13, run this once from a PC with [ADB](https://developer.android.com/tools/adb):
+
+```bash
+adb shell "/system/bin/device_config set_sync_disabled_for_tests persistent; /system/bin/device_config put activity_manager max_phantom_processes 2147483647"
+```
+
 **Script exits mid-install without a clear error**
 Check `~/termux-setup.log`. The script logs every package install result. The last line will tell you exactly which package triggered the failure.
 
@@ -476,6 +531,22 @@ This is expected on Android. The `/proc/net/dev` restriction on Android 10+ prev
 
 ---
 
+## FAQ
+
+**Do I need root?** No. Everything runs as a normal Android app. Root is not used by either script.
+
+**Is this a proot / chroot distro like Andronix or UserLAnd?** The desktop is not. It uses native Termux packages and the Termux-X11 display server, so there is no emulation layer between the apps and the phone — that is what makes GPU acceleration through Turnip/Zink possible. Home Assistant does run in a proot-distro Ubuntu container, because it needs a glibc Python environment.
+
+**Will it work on my phone?** Any arm64 (64-bit) Android 7+ phone or tablet with 3 GB+ RAM should work. Qualcomm Snapdragon (Adreno GPU) gets full hardware acceleration; Mali, PowerVR and others fall back to software Vulkan, so pick XFCE4 or LXQt there.
+
+**Can I use the Play Store version of Termux?** No — it has been outdated for years and cannot install current packages. Use F-Droid or the [Termux GitHub releases](https://github.com/termux/termux-app/releases).
+
+**Can I use a keyboard, mouse and external monitor?** Yes. Bluetooth or USB keyboards and mice work in Termux-X11, and on phones with DisplayPort-over-USB-C (or Samsung DeX) you can put the desktop on a monitor.
+
+**How do I uninstall?** Run `bash ~/stop-linux.sh`, then remove the packages with `pkg uninstall <name>`, or simply clear Termux's app data to start fresh. For Home Assistant: `proot-distro remove ubuntu` and delete `~/hass-config`.
+
+---
+
 ## Advanced Notes
 
 <details>
@@ -549,7 +620,9 @@ All hardcoded `/data/data/com.termux/...` paths have been replaced with `$PREFIX
 
 ## Contributing
 
-PRs and issues are welcome. If a package name has changed, a DE has a better startup command, or you've found a new conflict to handle, open an issue with your device model and Android version.
+PRs and issues are welcome. If a package name has changed, a DE has a better startup command, or you've found a new conflict to handle, open an issue with your device model and Android version. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Tested it on your device?** Even a one-line "works on Pixel 6 / Android 15 / XFCE4" report helps the next person — open an issue or comment on an existing one.
 
 ---
 

diff --git a/README.zh.md b/README.zh.md
@@ -2,6 +2,8 @@
 
 **[English](README.md)**
 
+[![listed on unshittify.dev](https://unshittify.dev/badge.svg)](https://unshittify.dev/p/linux-android/)
+
 > 本翻译可能落后于英文 README。以 [README.md](README.md) 为准。
 
 将任意旧安卓手机变成 **Linux 桌面**或**智能家居服务器** — 无需电脑、无需 Root、无需云服务，只需 [Termux](https://termux.dev)。
@@ -84,17 +86,23 @@ pkg upgrade -y
 
 `termux-wake-lock` 命令可保持 Termux 在屏幕关闭时继续运行 — 没有它，安卓可能会在安装过程中杀死进程。`pkg upgrade` 会在脚本运行前更新基础系统，避免 `libpcre` 和 `libandroid-selinux` 相关的已知崩溃问题。
 
-### 步骤 3 — 下载并运行脚本
+### 步骤 3 — 运行脚本
 
 ```bash
-curl -O https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh
-chmod +x termux-linux-setup.sh
-bash termux-linux-setup.sh
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh | bash
 ```
 
-脚本会询问你选择哪个桌面环境以及是否安装 Wine，其余全部自动完成。
+脚本会询问你选择哪个桌面环境以及是否安装 Wine，其余全部自动完成。想先阅读脚本再运行，可以用 `curl -O` 下载后执行 `bash termux-linux-setup.sh`。
+
+安装耗时 **10–30 分钟**，取决于网络速度。每个软件包都会显示计时和 apt 的最新输出行，方便区分"大文件下载中"和"真的卡住"。完整的日志保存在 `~/termux-setup.log` 中。重复运行脚本是安全的 — 已安装的包会被跳过。
+
+**无人值守安装**（不提问）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh | bash -s -- --de kde --no-wine -y
+```
 
-安装耗时 **10–30 分钟**，取决于网络速度。完整的日志保存在 `~/termux-setup.log` 中，方便排查问题。
+`--de` 可选 `xfce`（默认）、`lxqt`、`mate`、`kde`；`--wine` / `--no-wine`；`-y` 表示全部使用默认值；`--help` 查看全部选项。
 
 ### 步骤 4 — 启动桌面
 
@@ -255,10 +263,11 @@ Home Assistant Core 运行在手机上的轻量级 Ubuntu 容器中（通过 pro
 ### 安装
 
 ```bash
-curl -O https://raw.githubusercontent.com/mayukh4/linux-android/main/setup-homeassistant.sh
-bash setup-homeassistant.sh
+curl -fsSL https://raw.githubusercontent.com/mayukh4/linux-android/main/setup-homeassistant.sh | bash
 ```
 
+无人值守：`... | bash -s -- --hacs -y`。运行 `bash setup-homeassistant.sh --help` 查看全部选项。
+
 安装耗时 **15–45 分钟**，取决于手机性能。最耗时的步骤是在 Ubuntu 容器中编译 Home Assistant 的 Python 依赖（numpy、cryptography 等）。
 
 ### 启动和停止
@@ -379,6 +388,16 @@ echo 'termux-wake-lock && nohup bash ~/start-homeassistant.sh > ~/hass.log 2>&1
 
 ## 故障排除
 
+**安装似乎卡在某一步**
+KDE Plasma、Firefox、Wine 等大包有几百 MB，网络或手机较慢时可能需要 10 分钟以上。只要计时后面的 apt 输出行还在变化，就说明仍在进行。如果 5 分钟没有任何进展，脚本会打印警告。此时：保持 Termux 在前台并亮屏；在第二个 Termux 会话中运行 `tail -f ~/termux-setup.log` 查看日志；或按 `Ctrl+C` 后重新运行脚本（已安装的包会被跳过）；镜像太慢可用 `termux-change-repo` 切换镜像。
+
+**Termux 退出并显示 "[Process completed (signal 9)]"（Android 12+）**
+这是 Android 12 引入的"幻影进程终止"机制。**Android 14+**：开启 *开发者选项 → 停用子进程限制*。Android 12–13：在电脑上通过 ADB 执行一次：
+
+```bash
+adb shell "/system/bin/device_config set_sync_disabled_for_tests persistent; /system/bin/device_config put activity_manager max_phantom_processes 2147483647"
+```
+
 **脚本安装中途退出且无明确错误**
 查看 `~/termux-setup.log`。脚本会记录每个包的安装结果，最后一行会告诉你具体是哪个包导致了失败。