diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 52cd68db..4af9664d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -54,6 +54,10 @@ jobs:
             target: x86_64-unknown-linux-gnu
             binary: deepseek
             artifact_name: deepseek-linux-x64
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            binary: deepseek
+            artifact_name: deepseek-linux-arm64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: deepseek
@@ -71,6 +75,10 @@ jobs:
             target: x86_64-unknown-linux-gnu
             binary: deepseek-tui
             artifact_name: deepseek-tui-linux-x64
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            binary: deepseek-tui
+            artifact_name: deepseek-tui-linux-arm64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: deepseek-tui
@@ -154,6 +162,7 @@ jobs:
             | Platform | Dispatcher | TUI runtime |
             |---|---|---|
             | Linux x64 | `deepseek-linux-x64` | `deepseek-tui-linux-x64` |
+            | Linux ARM64 | `deepseek-linux-arm64` | `deepseek-tui-linux-arm64` |
             | macOS x64 | `deepseek-macos-x64` | `deepseek-tui-macos-x64` |
             | macOS ARM | `deepseek-macos-arm64` | `deepseek-tui-macos-arm64` |
             | Windows x64 | `deepseek-windows-x64.exe` | `deepseek-tui-windows-x64.exe` |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8fd27a3a..afc797e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Linux ARM64 prebuilt binaries** — the release workflow now publishes
+  `deepseek-linux-arm64` and `deepseek-tui-linux-arm64` (built natively on
+  GitHub's `ubuntu-24.04-arm` runner). The npm wrapper picks them up
+  automatically on `arm64` Linux hosts, so HarmonyOS thin-and-light,
+  openEuler/Kylin, Asahi Linux, Raspberry Pi, AWS Graviton, etc. now work
+  with a plain `npm i -g deepseek-tui`.
+
+### Changed
+- **npm `postinstall` failure messages** — when no prebuilt is available for
+  the host's `os.platform() / os.arch()` combo, the wrapper now prints the
+  full `cargo install` fallback recipe and a link to
+  [`docs/INSTALL.md`](docs/INSTALL.md) instead of just the bare error.
+- **`DEEPSEEK_TUI_OPTIONAL_INSTALL=1`** — new env knob that downgrades a
+  postinstall failure to a warning + `exit 0`, so CI matrices that include
+  unsupported platforms don't fail the whole `npm install`.
+
+### Docs
+- New [`docs/INSTALL.md`](docs/INSTALL.md) — every supported platform,
+  prebuilt vs. `cargo install` vs. manual download, cross-compiling x64 → ARM64
+  Linux with `cross` or `gcc-aarch64-linux-gnu`, and a troubleshooting section
+  covering the common `Unsupported architecture`, `MISSING_COMPANION_BINARY`,
+  and self-update mismatch errors.
+- README and `README.zh-CN.md` now have an explicit **Linux ARM64** quickstart
+  pointing ARM64 users at `cargo install deepseek-tui-cli deepseek-tui --locked`
+  for v0.8.7 and at `npm i -g deepseek-tui` for v0.8.8+.
+
 ## [0.8.7] - 2026-05-03
 
 ### Fixed
diff --git a/README.md b/README.md
index 5a9c151d..b2d579a8 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,29 @@ npm install -g deepseek-tui
 deepseek
 ```
 
+Prebuilt binaries are published for **Linux x64**, **Linux ARM64** (v0.8.8+),
+**macOS x64**, **macOS ARM64**, and **Windows x64**. For everything else —
+musl, riscv64, FreeBSD, etc. — see [Build from source](#install-from-source)
+below or the full [docs/INSTALL.md](docs/INSTALL.md) walkthrough.
+
+### Linux ARM64 (Raspberry Pi, Asahi, Graviton, HarmonyOS PC)
+
+`npm i -g deepseek-tui` works on glibc-based ARM64 Linux from **v0.8.8**
+onward. If you're stuck on v0.8.7 or earlier (where you'll see
+`Unsupported architecture: arm64`), upgrade or use `cargo install`:
+
+```bash
+# requires Rust 1.85+ (https://rustup.rs)
+cargo install deepseek-tui-cli --locked   # provides `deepseek`
+cargo install deepseek-tui     --locked   # provides `deepseek-tui`
+```
+
+You can also download `deepseek-linux-arm64` and `deepseek-tui-linux-arm64`
+directly from the [Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases)
+and drop both side by side into a directory on your `PATH`. Cross-compiling
+from x64 to ARM64 is documented in
+[docs/INSTALL.md](docs/INSTALL.md#cross-compiling-from-x64-to-arm64-linux).
+
 ### China / mirror-friendly install
 
 If GitHub or npm downloads are slow from mainland China, install the Rust
@@ -83,12 +106,12 @@ replace-with = "tuna"
 registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
 ```
 
-Then install the canonical `deepseek` dispatcher and (optionally) the
-companion TUI binary:
+Then install the canonical `deepseek` dispatcher and the companion TUI binary
+(both are required — the dispatcher delegates to the TUI runtime):
 
 ```bash
 cargo install deepseek-tui-cli --locked   # provides `deepseek`
-cargo install deepseek-tui     --locked   # provides `deepseek-tui` (optional)
+cargo install deepseek-tui     --locked   # provides `deepseek-tui`
 deepseek --version
 ```
 
@@ -129,15 +152,28 @@ deepseek --provider fireworks --model deepseek-v4-pro
 SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash
 ```
 
-<details>
+<details id="install-from-source">
 <summary>Install from source</summary>
 
+Works on any Tier-1 Rust target — including Linux musl/riscv64, FreeBSD, and
+ARM64 distros that pre-date our prebuilt binaries.
+
 ```bash
+# Linux build deps (Debian/Ubuntu/openEuler/Kylin):
+#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+#   # RHEL family: sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+
 git clone https://github.com/Hmbown/DeepSeek-TUI.git
 cd DeepSeek-TUI
-cargo install --path crates/tui --locked   # requires Rust 1.85+
+
+cargo install --path crates/cli --locked   # requires Rust 1.85+; provides `deepseek`
+cargo install --path crates/tui --locked   # provides `deepseek-tui`
 ```
 
+Both binaries are required — the `deepseek` dispatcher delegates to
+`deepseek-tui` at runtime. Cross-compilation, mirror, and platform-specific
+notes live in [docs/INSTALL.md](docs/INSTALL.md).
+
 </details>
 
 ---
@@ -153,14 +189,24 @@ assistant message bodies, which made it impossible to copy text out of
 system notes, thinking blocks, or tool output. v0.8.7 drops that gate so
 the rendered transcript block is selectable end-to-end again.
 
-> **Known issue in v0.8.7:** `deepseek update` fails with `no asset found
-> for platform …` because the platform-string mapping in the self-updater
-> uses `aarch64`/`x86_64` instead of the release artifact's `arm64`/`x64`
-> ([#503](https://github.com/Hmbown/DeepSeek-TUI/issues/503)). Until this
-> is fixed in v0.8.8, update via:
+> **Known issues in v0.8.7 (fixed in v0.8.8):**
+> - `deepseek update` fails with `no asset found for platform …` because the
+>   platform-string mapping in the self-updater uses `aarch64`/`x86_64`
+>   instead of the release artifact's `arm64`/`x64`
+>   ([#503](https://github.com/Hmbown/DeepSeek-TUI/issues/503)).
+> - `npm i -g deepseek-tui` exits with `Unsupported architecture: arm64 on
+>   platform linux` on ARM64 Linux because v0.8.7 didn't publish a
+>   `deepseek-linux-arm64` asset.
+>
+> Until v0.8.8 ships, install via:
 > ```bash
-> npm i -g deepseek-tui          # or
-> cargo install deepseek-tui-cli --locked
+> # x64 Linux / macOS / Windows
+> npm i -g deepseek-tui
+>
+> # ARM64 Linux (HarmonyOS, openEuler, Asahi, Raspberry Pi, Graviton, …) —
+> # build from source with Cargo (Rust 1.85+):
+> cargo install deepseek-tui-cli --locked   # provides `deepseek`
+> cargo install deepseek-tui     --locked   # provides `deepseek-tui`
 > ```
 
 Full changelog: [CHANGELOG.md](CHANGELOG.md).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 07380d19..289da12e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -46,6 +46,11 @@ npm install -g deepseek-tui
 deepseek
 ```
 
+预构建二进制覆盖 **Linux x64**、**Linux ARM64**（v0.8.8 起）、**macOS x64**、
+**macOS ARM64**、**Windows x64**。其他平台（musl、riscv64、FreeBSD 等）请见
+下方[「从源码安装」](#从源码安装)，或参考完整的
+[docs/INSTALL.md](docs/INSTALL.md)。
+
 首次启动时会提示输入 [DeepSeek API key](https://platform.deepseek.com/api_keys)。也可以提前配置：
 
 ```bash
@@ -57,6 +62,23 @@ export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
 deepseek
 ```
 
+### Linux ARM64（HarmonyOS 轻薄本、openEuler、Kylin、树莓派、Graviton 等）
+
+从 **v0.8.8** 起，`npm i -g deepseek-tui` 直接支持 glibc 系的 ARM64 Linux。
+如果你停留在 v0.8.7 或更早版本，会看到 `Unsupported architecture: arm64`
+错误。升级到最新版即可，或直接用 `cargo install`：
+
+```bash
+# 需要 Rust 1.85+（https://rustup.rs）
+cargo install deepseek-tui-cli --locked   # 提供 `deepseek`
+cargo install deepseek-tui     --locked   # 提供 `deepseek-tui`
+```
+
+也可以从 [Releases 页面](https://github.com/Hmbown/DeepSeek-TUI/releases) 下载
+`deepseek-linux-arm64` 与 `deepseek-tui-linux-arm64`，放到同一个 `PATH` 目录里。
+从 x64 主机交叉编译到 ARM64 的步骤见
+[docs/INSTALL.md](docs/INSTALL.md#cross-compiling-from-x64-to-arm64-linux)。
+
 ### 中国大陆 / 镜像友好安装
 
 如果在中国大陆访问 GitHub 或 npm 下载较慢，可以通过 Cargo 注册表镜像安装 Rust crate：
@@ -88,13 +110,26 @@ deepseek doctor --json
 
 ### 从源码安装
 
+适用于任何 Tier-1 Rust 目标，包括 musl、riscv64、FreeBSD，以及早于
+v0.8.8、还没有官方预编译包的 ARM64 发行版。
+
 ```bash
+# Linux 构建依赖（Debian/Ubuntu/openEuler/Kylin）：
+#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+#   # RHEL 系：sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+
 git clone https://github.com/Hmbown/DeepSeek-TUI.git
 cd DeepSeek-TUI
-cargo install --path crates/tui --locked   # 需要 Rust 1.85+
+
+cargo install --path crates/cli --locked   # 需要 Rust 1.85+；提供 `deepseek`
+cargo install --path crates/tui --locked   # 提供 `deepseek-tui`
+
 deepseek --version
 ```
 
+两个二进制都需要安装：`deepseek` 是入口调度器，运行时会调用 `deepseek-tui`。
+跨平台编译、镜像、平台特定故障排查见 [docs/INSTALL.md](docs/INSTALL.md)。
+
 ---
 
 ## 其他模型提供方
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 00000000..5976825d
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,259 @@
+# Installing DeepSeek TUI
+
+This page covers every supported install path and the most common
+"it didn't install" failures, including **Linux ARM64** and other less
+common platforms.
+
+If you just want the short version, see the
+[main README](../README.md#quickstart) or
+[简体中文 README](../README.zh-CN.md#快速开始).
+
+---
+
+## 1. Supported platforms
+
+`deepseek-tui` ships prebuilt binaries for these
+platform/architecture combinations from v0.8.8 onward:
+
+| Platform     | Architecture | npm install | `cargo install` | GitHub release asset                                  |
+| ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- |
+| Linux        | x64 (x86_64) |     ✅      |       ✅        | `deepseek-linux-x64`, `deepseek-tui-linux-x64`        |
+| Linux        | arm64        |     ✅      |       ✅        | `deepseek-linux-arm64`, `deepseek-tui-linux-arm64`    |
+| macOS        | x64          |     ✅      |       ✅        | `deepseek-macos-x64`, `deepseek-tui-macos-x64`        |
+| macOS        | arm64 (M-series) | ✅      |       ✅        | `deepseek-macos-arm64`, `deepseek-tui-macos-arm64`    |
+| Windows      | x64          |     ✅      |       ✅        | `deepseek-windows-x64.exe`, `deepseek-tui-windows-x64.exe` |
+| Other Linux (musl, riscv64, …) | — |   ❌¹    |       ✅²       | build from source                                     |
+| FreeBSD / OpenBSD              | — |   ❌      |       ✅²       | build from source                                     |
+
+¹ The npm package will exit with a clear error and point you here.
+² Provided your toolchain can compile a recent Rust workspace; see
+  [Build from source](#5-build-from-source) below.
+
+> **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not**
+> publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi
+> Linux, Raspberry Pi, AWS Graviton, etc. saw `Unsupported architecture: arm64`
+> from `npm i -g deepseek-tui`. v0.8.8 publishes both `deepseek-linux-arm64`
+> and `deepseek-tui-linux-arm64`, so a plain `npm i -g deepseek-tui` works
+> on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to
+> [Build from source](#5-build-from-source) — `cargo install` works fine.
+
+---
+
+## 2. Install via npm (recommended)
+
+```bash
+npm install -g deepseek-tui
+deepseek
+```
+
+`postinstall` downloads the right pair of binaries from the matching GitHub
+release, verifies a SHA-256 manifest, and exposes both `deepseek` and
+`deepseek-tui` on your `PATH`.
+
+Useful environment variables:
+
+| Variable                            | Purpose                                                                                |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| `DEEPSEEK_TUI_VERSION`              | Pin which release the wrapper downloads (defaults to `deepseekBinaryVersion`)          |
+| `DEEPSEEK_TUI_GITHUB_REPO`          | Point the downloader at a fork (`owner/repo`)                                          |
+| `DEEPSEEK_TUI_RELEASE_BASE_URL`     | Override the download root (e.g. an internal mirror or release-asset proxy)            |
+| `DEEPSEEK_TUI_FORCE_DOWNLOAD=1`     | Re-download even if a cached binary marker matches                                     |
+| `DEEPSEEK_TUI_DISABLE_INSTALL=1`    | Skip the `postinstall` download entirely (CI smoke, vendored binaries)                 |
+| `DEEPSEEK_TUI_OPTIONAL_INSTALL=1`   | Don't fail `npm install` on download/extract errors — useful in CI matrices            |
+
+---
+
+## 3. Install via Cargo (any Tier-1 Rust target)
+
+If GitHub releases are slow, blocked, or you're on an unsupported architecture,
+install from crates.io directly. Both crates are required — the dispatcher
+delegates to the TUI runtime at runtime.
+
+```bash
+# Requires Rust 1.85+ (https://rustup.rs)
+cargo install deepseek-tui-cli --locked   # provides `deepseek`
+cargo install deepseek-tui     --locked   # provides `deepseek-tui`
+deepseek --version
+```
+
+### China / mirror-friendly Cargo registry
+
+```toml
+# ~/.cargo/config.toml
+[source.crates-io]
+replace-with = "tuna"
+
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
+```
+
+`rsproxy`, Tencent COS, and Aliyun OSS mirrors work the same way; pick whichever
+is fastest from your network.
+
+---
+
+## 4. Manual download from GitHub Releases
+
+Grab the matching pair of binaries for your platform from the
+[Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases) and drop them
+side by side into a directory on your `PATH` (e.g. `~/.local/bin`):
+
+```bash
+# Linux ARM64 example
+mkdir -p ~/.local/bin
+curl -L -o ~/.local/bin/deepseek      \
+    https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-linux-arm64
+curl -L -o ~/.local/bin/deepseek-tui  \
+    https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-tui-linux-arm64
+chmod +x ~/.local/bin/deepseek ~/.local/bin/deepseek-tui
+deepseek --version
+```
+
+Verify integrity against the per-release SHA-256 manifest:
+
+```bash
+curl -L -o /tmp/deepseek-artifacts-sha256.txt \
+    https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt
+( cd ~/.local/bin && sha256sum -c /tmp/deepseek-artifacts-sha256.txt --ignore-missing )
+```
+
+(Use `shasum -a 256 -c` instead of `sha256sum` on macOS.)
+
+---
+
+## 5. Build from source
+
+This is the catch-all for any platform we don't ship — including musl, riscv64,
+LoongArch, FreeBSD, and pre-2024 ARM64 distros.
+
+### Prerequisites
+
+- **Rust** 1.85 or later — install with [rustup](https://rustup.rs).
+- **Linux build-time deps** (Debian/Ubuntu/openEuler/Kylin):
+  ```bash
+  sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+  # openEuler / RHEL family:
+  # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+  ```
+- A working `cmake` is **not** required.
+
+### Build and install
+
+```bash
+git clone https://github.com/Hmbown/DeepSeek-TUI.git
+cd DeepSeek-TUI
+
+cargo install --path crates/cli --locked   # provides `deepseek`
+cargo install --path crates/tui --locked   # provides `deepseek-tui`
+
+deepseek --version
+```
+
+Both binaries land in `~/.cargo/bin/` by default; make sure that directory is
+on your `PATH`.
+
+### Cross-compiling from x64 to ARM64 Linux
+
+If you want to build an ARM64 Linux binary on an x64 Linux host (e.g. for a
+HarmonyOS / openEuler ARM64 thin-and-light), use
+[`cross`](https://github.com/cross-rs/cross), which wraps the official Rust
+cross-targets in a Docker container:
+
+```bash
+# Once
+rustup target add aarch64-unknown-linux-gnu
+cargo install cross --locked
+
+# Per build
+cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli
+cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui
+```
+
+The resulting binaries land in
+`target/aarch64-unknown-linux-gnu/release/deepseek` and
+`target/aarch64-unknown-linux-gnu/release/deepseek-tui`. Copy the matched pair
+to the ARM64 host (e.g. via `scp`) and `chmod +x` them.
+
+If you don't have Docker available, install the cross-linker directly and let
+Cargo do the work:
+
+```bash
+sudo apt-get install -y gcc-aarch64-linux-gnu
+rustup target add aarch64-unknown-linux-gnu
+
+cat >> ~/.cargo/config.toml <<'EOF'
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"
+EOF
+
+cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli
+cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui
+```
+
+The same recipe works for `aarch64-unknown-linux-musl` if your distro is
+musl-based.
+
+---
+
+## 6. Troubleshooting
+
+### `Unsupported architecture: arm64 on platform linux`
+
+You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64
+binaries. Either upgrade (`npm i -g deepseek-tui@latest`) or use
+`cargo install` per [Section 3](#3-install-via-cargo-any-tier-1-rust-target).
+
+### `MISSING_COMPANION_BINARY` at runtime
+
+The dispatcher (`deepseek`) requires the TUI runtime (`deepseek-tui`) to be on
+the same `PATH`. If you installed only one crate via `cargo install`, install
+both:
+
+```bash
+cargo install deepseek-tui-cli --locked
+cargo install deepseek-tui     --locked
+```
+
+### `deepseek update` reports `no asset found for platform deepseek-linux-aarch64`
+
+This is [#503](https://github.com/Hmbown/DeepSeek-TUI/issues/503) in v0.8.7 —
+the self-updater used Rust's `aarch64`/`x86_64` arch names instead of the
+release artifact's `arm64`/`x64`. Workaround until v0.8.8:
+
+```bash
+npm i -g deepseek-tui@latest
+# or
+cargo install deepseek-tui-cli --locked
+```
+
+### npm download is slow or times out from mainland China
+
+Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to a mirrored release-asset directory
+(rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the
+Cargo mirror setup in [Section 3](#3-install-via-cargo-any-tier-1-rust-target).
+
+### Debian/Ubuntu: `error: linker 'cc' not found` while building
+
+Install the C toolchain:
+
+```bash
+sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+```
+
+### Wrapper installs but `deepseek` isn't found
+
+`npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on
+your shell's `PATH`. With nvm: `nvm use --lts && hash -r`.
+
+---
+
+## 7. Verifying your install
+
+```bash
+deepseek --version
+deepseek doctor       # checks API key, provider, runtime, and PATH integrity
+deepseek doctor --json
+```
+
+`doctor` exits non-zero if it finds a problem and prints structured remediation
+hints. Paste the JSON output into a GitHub issue if you need help.
diff --git a/npm/deepseek-tui/README.md b/npm/deepseek-tui/README.md
index d6ff56f3..07e2d891 100644
--- a/npm/deepseek-tui/README.md
+++ b/npm/deepseek-tui/README.md
@@ -52,11 +52,18 @@ is `https://integrate.api.nvidia.com/v1`. With `--provider nvidia-nim`,
 
 ## Supported platforms
 
+Prebuilt binaries for the GitHub release are downloaded automatically:
+
 - Linux x64
+- Linux arm64 (v0.8.8+)
 - macOS x64 / arm64
 - Windows x64
 
-Other platform/architecture combinations are not supported and will fail during install.
+Other platform/architecture combinations (musl, riscv64, FreeBSD, …) aren't
+shipped as prebuilts. The `postinstall` will exit with a clear error pointing
+you at `cargo install deepseek-tui-cli deepseek-tui --locked` and the full
+[docs/INSTALL.md](https://github.com/Hmbown/DeepSeek-TUI/blob/main/docs/INSTALL.md)
+build-from-source guide.
 
 ## Configuration
 
@@ -65,6 +72,7 @@ Other platform/architecture combinations are not supported and will fail during
 - Set `DEEPSEEK_TUI_GITHUB_REPO` or `DEEPSEEK_GITHUB_REPO` to override the source repo (defaults to `Hmbown/DeepSeek-TUI`).
 - Set `DEEPSEEK_TUI_FORCE_DOWNLOAD=1` to force download even when the cached binary is already present.
 - Set `DEEPSEEK_TUI_DISABLE_INSTALL=1` to skip install-time download.
+- Set `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` to make the `postinstall` step warn and exit `0` on download/extract errors instead of failing `npm install` (useful in CI matrices).
 
 ## Release integrity
 
diff --git a/npm/deepseek-tui/scripts/artifacts.js b/npm/deepseek-tui/scripts/artifacts.js
index 8dbc7148..22447bdb 100644
--- a/npm/deepseek-tui/scripts/artifacts.js
+++ b/npm/deepseek-tui/scripts/artifacts.js
@@ -6,7 +6,7 @@ const CHECKSUM_MANIFEST = "deepseek-artifacts-sha256.txt";
 const ASSET_MATRIX = {
   linux: {
     x64: ["deepseek-linux-x64", "deepseek-tui-linux-x64"],
-    // arm64: ["deepseek-linux-arm64", "deepseek-tui-linux-arm64"], // Uncomment when binaries are available
+    arm64: ["deepseek-linux-arm64", "deepseek-tui-linux-arm64"],
   },
   darwin: {
     x64: ["deepseek-macos-x64", "deepseek-tui-macos-x64"],
@@ -23,12 +23,19 @@ function detectBinaryNames() {
   const defaults = ASSET_MATRIX[platform];
   if (!defaults) {
     const supported = Object.keys(ASSET_MATRIX).map(p => `'${p}'`).join(', ');
-    throw new Error(`Unsupported platform: ${platform}. Supported platforms: ${supported}`);
+    throw new Error(
+      `Unsupported platform: ${platform}. Supported platforms: ${supported}.\n\n` +
+      unsupportedBuildHint(),
+    );
   }
   const pair = defaults[arch];
   if (!pair) {
     const supported = Object.keys(defaults).map(a => `'${a}'`).join(', ');
-    throw new Error(`Unsupported architecture: ${arch} on platform ${platform}. Supported architectures: ${supported}`);
+    throw new Error(
+      `Unsupported architecture: ${arch} on platform ${platform}. ` +
+      `Supported architectures: ${supported}.\n\n` +
+      unsupportedBuildHint(),
+    );
   }
   return {
     platform,
@@ -38,6 +45,27 @@ function detectBinaryNames() {
   };
 }
 
+function unsupportedBuildHint() {
+  return [
+    "No prebuilt binary is available for this platform/architecture combo.",
+    "You can still run DeepSeek TUI by building from source with Cargo:",
+    "",
+    "  # Requires Rust 1.85+ (https://rustup.rs)",
+    "  cargo install deepseek-tui-cli --locked   # provides `deepseek`",
+    "  cargo install deepseek-tui     --locked   # provides `deepseek-tui`",
+    "",
+    "Or build from a checkout:",
+    "",
+    "  git clone https://github.com/Hmbown/DeepSeek-TUI.git",
+    "  cd DeepSeek-TUI",
+    "  cargo install --path crates/cli --locked",
+    "  cargo install --path crates/tui --locked",
+    "",
+    "See https://github.com/Hmbown/DeepSeek-TUI/blob/main/docs/INSTALL.md",
+    "for cross-compilation, mirror, and Linux ARM64 specifics.",
+  ].join("\n");
+}
+
 function executableName(base, platform) {
   return platform === "win32" ? `${base}.exe` : base;
 }
diff --git a/npm/deepseek-tui/scripts/install.js b/npm/deepseek-tui/scripts/install.js
index e1d8ba5a..b1310094 100644
--- a/npm/deepseek-tui/scripts/install.js
+++ b/npm/deepseek-tui/scripts/install.js
@@ -210,6 +210,12 @@ module.exports = {
 if (require.main === module) {
   run().catch((error) => {
     console.error("deepseek-tui install failed:", error.message);
+    if (process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL === "1") {
+      console.error(
+        "DEEPSEEK_TUI_OPTIONAL_INSTALL=1 set; continuing without a usable binary.",
+      );
+      process.exit(0);
+    }
     process.exit(1);
   });
 }