From 628266729754f92549d8ecc1050cd89642b16969 Mon Sep 17 00:00:00 2001
From: "Alice (OpenClaw)" <alice@cowbay.org>
Date: Wed, 13 May 2026 21:48:38 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20surface=20INSTALL=20entrypoint=20/=20?=
 =?UTF-8?q?=E5=9C=A8=20README=20=E8=88=87=20HANDOFF=20=E8=A3=9C=20INSTALL?=
 =?UTF-8?q?=20=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 HANDOFF.md | 17 ++++++-----
 INSTALL.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |  7 +++--
 3 files changed, 101 insertions(+), 11 deletions(-)
 create mode 100644 INSTALL.md

diff --git a/HANDOFF.md b/HANDOFF.md
index c8c03bc..8942340 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -37,14 +37,15 @@ This is not yet a clean cross-agent installable package. It is a successful PoC
 
 Read these files first:
 
-1. `README.md`
-2. `telegram-v1-design.md`
-3. `telegram-openclaw-poc-plan.md`
-4. `reports/telegram-openclaw-poc-success.md`
-5. `reports/openclaw-patch-inventory.md`
-6. `reports/openclaw-patch-mapping-matrix.md`
-7. `reports/next-phase-implementation-plan.md`
-8. `reports/agent-consumable-minimum.md`
+1. `INSTALL.md`
+2. `README.md`
+3. `telegram-v1-design.md`
+4. `telegram-openclaw-poc-plan.md`
+5. `reports/telegram-openclaw-poc-success.md`
+6. `reports/openclaw-patch-inventory.md`
+7. `reports/openclaw-patch-mapping-matrix.md`
+8. `reports/next-phase-implementation-plan.md`
+9. `reports/agent-consumable-minimum.md`
 
 ## Fastest operational entrypoints
 
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..bf8f303
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,88 @@
+# INSTALL
+
+## Purpose
+
+This file is the shortest installation and verification guide for another engineering-focused agent.
+
+Use this when you want to apply the current Telegram/OpenClaw PoC to the `openclawtest` environment without reading the entire project history first.
+
+## Target environment
+
+Current supported target:
+
+- `openclawtest`
+- Telegram-only
+
+This is **not** yet a general package installer for arbitrary environments.
+
+## Prerequisites
+
+- access to this repo
+- access to the `openclawtest` environment on the same machine
+- permission to run the provided scripts
+
+## Install / refresh
+
+Fastest path:
+
+```bash
+bash scripts/install-openclawtest-poc.sh
+```
+
+This does two things:
+
+1. refreshes the live `openclawtest` PoC by reapplying the patch and restarting the gateway
+2. runs a verification pass over the live state and runtime markers
+
+## Manual paths
+
+### Apply patch only
+
+```bash
+bash scripts/apply-openclaw-poc-patch.sh /home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist
+```
+
+### Refresh live openclawtest runtime
+
+```bash
+bash scripts/refresh-openclawtest-poc.sh
+```
+
+### Verify current live state
+
+```bash
+bash scripts/verify-openclaw-poc.sh \
+  /home/openclawtest/.openclaw \
+  /home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist
+```
+
+### Rollback
+
+```bash
+bash scripts/rollback-openclaw-poc-patch.sh /home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist
+```
+
+## What success looks like
+
+After install/refresh:
+
+- gateway is running
+- patch markers exist in the live OpenClaw dist files
+- Telegram assistant replies can show reply-end buttons
+- clicking buttons can update state and UI
+
+## Validation checklist
+
+1. Send a Telegram assistant reply through `openclawtest`
+2. Confirm buttons appear
+3. Click `continue` or `stop`
+4. Confirm state/debug files appear or update:
+   - `~/.openclaw/reply-end-controls.json`
+   - `~/.openclaw/reply-end-debug.log`
+5. For stop-state validation, send a later message and confirm the assistant becomes more restrained
+
+## Read next if needed
+
+- `HANDOFF.md`
+- `INTEGRATION.md`
+- `reports/final-readiness-report.md`
diff --git a/README.md b/README.md
index 7f9f471..f342655 100644
--- a/README.md
+++ b/README.md
@@ -19,9 +19,10 @@ npm run test
 
 建議閱讀順序：
 
-1. `HANDOFF.md`
-2. `INTEGRATION.md`
-3. `reports/final-readiness-report.md`
+1. `INSTALL.md`
+2. `HANDOFF.md`
+3. `INTEGRATION.md`
+4. `reports/final-readiness-report.md`
 
 ### 專案目標