docs: add Android Termux guide

Closes #286

Assisted-by: OpenAI Codex

Signed-off-by: Puneet Dixit <236133619+puneetdixit200@users.noreply.github.com>

README.md

@@ -321,6 +321,8 @@ Download the APK from [picoclaw.io](https://picoclaw.io/download/) and install d
 
 **Option 2: Termux**
 
+For a full command-line setup checklist, see the [Android Termux Guide](docs/guides/android-termux.md).
+
 <details>
 <summary><b>Terminal Launcher (for resource-constrained environments)</b></summary>
 

docs/guides/README.md

@@ -3,6 +3,7 @@
 Task-oriented guides for setup, configuration, and common PicoClaw workflows.
 
 - [Docker & Quick Start Guide](docker.md): install and run PicoClaw with Docker or the launcher.
+- [Android Termux Guide](android-termux.md): run the PicoClaw terminal binary on an ARM64 Android phone.
 - [Configuration Guide](configuration.md): environment variables, workspace layout, routing, and sandbox settings.
 - [Session Guide](session-guide.md): how session scope affects memory sharing, summaries, and isolation.
 - [Routing Guide](routing-guide.md): agent dispatch, session overrides, and light-model routing.

docs/guides/android-termux.md

@@ -0,0 +1,88 @@
+# Android Termux Guide
+
+> Back to [Guides](README.md)
+
+This guide covers running the PicoClaw terminal binary on an ARM64 Android phone with Termux. Use the APK from [picoclaw.io](https://picoclaw.io/download/) if you want the Android app experience; use Termux when you want a lightweight command-line install on an older or resource-constrained device.
+
+## Requirements
+
+- ARM64 Android device. Run `uname -m` in Termux and use this guide when it prints `aarch64`.
+- Termux installed from [Termux GitHub Releases](https://github.com/termux/termux-app/releases) or F-Droid.
+- Network access for downloading the release and calling your LLM provider.
+- An API key for at least one configured model provider.
+
+## Install PicoClaw
+
+Open Termux and install the packages used by the release archive and chroot wrapper:
+
+```bash
+pkg update
+pkg install -y wget tar proot
+```
+
+Download and unpack the ARM64 Linux release:
+
+```bash
+mkdir -p ~/picoclaw
+cd ~/picoclaw
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+chmod +x ./picoclaw
+```
+
+Start first-run setup through `termux-chroot`, which gives the Linux binary a more standard filesystem layout than a raw Android userspace:
+
+```bash
+termux-chroot ./picoclaw onboard
+```
+
+## Configure
+
+Edit the generated config and add at least one model provider API key:
+
+```bash
+vim ~/.picoclaw/config.json
+```
+
+The default workspace is `~/.picoclaw/workspace`. If you want PicoClaw to read or write Android shared storage, run `termux-setup-storage` first and then point the workspace or any file paths at the mounted storage directory.
+
+See [Configuration Guide](configuration.md) and [Providers & Model Configuration](providers.md) for the available config fields and provider examples.
+
+## Run
+
+Use one-shot agent mode to confirm the installation:
+
+```bash
+termux-chroot ./picoclaw agent -m "Hello from Termux"
+```
+
+For long-running use, start the gateway:
+
+```bash
+termux-chroot ./picoclaw gateway
+```
+
+Keep the Termux session open while PicoClaw is running. Android battery optimization can stop background work, so disable battery optimization for Termux if you expect PicoClaw to keep running after the screen locks.
+
+## Update
+
+Your config and workspace live under `~/.picoclaw`, so updating the binary does not remove them:
+
+```bash
+cd ~/picoclaw
+rm -f picoclaw_Linux_arm64.tar.gz
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+chmod +x ./picoclaw
+termux-chroot ./picoclaw version
+```
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| `permission denied` | Run `chmod +x ./picoclaw` after unpacking the archive. |
+| `not found` after running `./picoclaw` | Confirm `uname -m` prints `aarch64` and that you downloaded `picoclaw_Linux_arm64.tar.gz`. |
+| Files or paths behave differently than Linux | Run PicoClaw through `termux-chroot` instead of calling the binary directly. |
+| Provider requests fail | Check the API key and network access in `~/.picoclaw/config.json`. |
+| PicoClaw stops when the phone sleeps | Disable Android battery optimization for Termux and keep a foreground Termux session active. |

docs/guides/hardware-compatibility.md

@@ -97,7 +97,7 @@ Consumer products, routers, and industrial devices that have been tested with Pi
 
 Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
 
-> See [README: Run on old Android Phones](../../README.md#-run-on-old-android-phones) for setup instructions.
+> See the [Android Termux Guide](android-termux.md) for setup instructions.
 
 ### Desktop / Server / Cloud