docs: add handoff and integration entrypoints / 新增 handoff 與 integration 入口文件

HANDOFF.md

@@ -0,0 +1,79 @@
+# HANDOFF
+
+## What this project is
+
+`reply-end-controls` is a Telegram-only interaction-control feature.
+
+Its purpose is to add reply-end buttons to assistant replies:
+
+- `A. 繼續`
+- `B. 就這樣吧，不需要額外處理`
+
+The buttons are meant to:
+
+- capture user intent about whether a conversation should continue
+- persist that choice
+- influence later assistant behavior
+
+## What already works
+
+In `openclawtest`, the Telegram + OpenClaw PoC has already proven:
+
+- buttons can be attached to assistant replies
+- button clicks can be received as callback queries
+- callback state can be persisted
+- button UI can update
+- acknowledgement replies can be sent
+- stop/continue can influence later behavior
+
+## What environment this currently targets
+
+- Telegram only
+- OpenClaw runtime in `openclawtest`
+
+This is not yet a clean cross-agent installable package. It is a successful PoC being pushed toward a cleaner reusable path.
+
+## Where to start reading
+
+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`
+
+## Repo structure
+
+- `src/core/` - reusable state/policy/callback logic
+- `src/telegram/` - Telegram-specific helper logic
+- `src/adapters/` - OpenClaw-facing state bridge code
+- `src/runtime/` - runtime helper layer for current PoC behavior
+- `scripts/` - apply / rollback and helper scripts
+- `tests/` - current unit tests
+- `reports/` - design notes, PoC success, pluginization reports
+
+## What is still fragile
+
+- the live OpenClaw integration still uses runtime patching
+- the feature is not yet a clean installable plugin package
+- acceptance still includes human verification steps on Telegram UI
+
+## If you are the next agent
+
+Your likely next step is not to rediscover the idea.
+
+Your likely next step is to make the current PoC easier to consume by:
+
+- reducing runtime patching
+- tightening the apply/verify/rollback path
+- making the adapter seam cleaner
+
+## Important constraint
+
+Do not mix this project with the governance project.
+
+They are separate workstreams.

INTEGRATION.md

@@ -0,0 +1,65 @@
+# INTEGRATION
+
+## Current integration model
+
+The current working integration path is:
+
+1. patch OpenClaw Telegram runtime
+2. restart the `openclawtest` gateway
+3. send a real Telegram assistant reply
+4. verify button rendering, callback handling, and state persistence
+
+## Runtime files currently involved
+
+See:
+
+- `reports/openclaw-patch-inventory.md`
+
+## Apply
+
+Current patch apply script:
+
+- `scripts/apply-openclaw-poc-patch.sh <openclaw-dist-dir>`
+
+Example target dir in `openclawtest`:
+
+```bash
+/home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist
+```
+
+## Rollback
+
+Rollback script:
+
+- `scripts/rollback-openclaw-poc-patch.sh <openclaw-dist-dir>`
+
+This expects backup files created by the apply script.
+
+## Verify
+
+At minimum, verify these behaviors in Telegram:
+
+1. assistant replies show both buttons
+2. clicking `continue` updates UI and writes state
+3. clicking `stop` updates UI and writes state
+4. later turns are influenced by stop/continue state
+
+## Current persisted files in PoC mode
+
+- `~/.openclaw/reply-end-controls.json`
+- `~/.openclaw/reply-end-debug.log`
+
+## Current adapter-related repo modules
+
+- `src/adapters/openclaw.ts`
+- `src/adapters/openclaw-state-file.ts`
+- `src/runtime/openclaw-telegram-bridge.ts`
+- `src/runtime/openclaw-telegram-poc.ts`
+
+These do not yet replace the runtime patch end-to-end, but they are the current repo-side ownership points for the logic.
+
+## Known limitation
+
+The current integration path is reproducible, but not yet clean enough to call a final plugin package.
+
+That is the next direction of work.

reports/agent-consumable-minimum.md

@@ -0,0 +1,102 @@
+# Agent-Consumable Minimum
+
+## Purpose
+
+Define the minimum bar for saying `reply-end-controls` is ready for another AI agent to use directly, rather than merely continue developing.
+
+## Current state
+
+The project is already:
+
+- understandable by another agent
+- reproducible as a Telegram/OpenClaw PoC
+- documented well enough for engineering handoff
+
+But it is not yet at the point where another agent can simply adopt it as a clean integration without understanding the current patch model.
+
+## Minimum bar for direct consumption
+
+Another AI agent should be able to:
+
+1. understand what the feature does
+2. understand what environment it targets
+3. apply it without hand-editing runtime files
+4. verify it works
+5. roll it back if needed
+
+## Required deliverables
+
+### 1. Clear integration entrypoint
+
+There must be a single obvious entrypoint explaining:
+
+- what to install
+- what to patch
+- what scripts to run
+- what runtime assumptions exist
+
+### 2. Apply path
+
+Another agent must be able to apply the current PoC without inventing its own patch process.
+
+Current direction:
+
+- `scripts/apply-openclaw-poc-patch.sh`
+
+### 3. Verify path
+
+Another agent must be able to verify:
+
+- buttons appear
+- callback is received
+- state is written
+- stop/continue affect later behavior
+
+Current direction:
+
+- acceptance instructions
+- PoC reports
+
+### 4. Rollback path
+
+Another agent must be able to revert the patch safely.
+
+Current direction:
+
+- `scripts/rollback-openclaw-poc-patch.sh`
+
+### 5. Integration contract
+
+Another agent should not need to reverse-engineer the feature from raw runtime patches.
+
+It should have direct access to:
+
+- state model
+- callback contract
+- Telegram rendering rules
+- OpenClaw adapter assumptions
+
+## Missing pieces before this bar is truly met
+
+The main gaps are:
+
+- no single `HANDOFF.md` or `INTEGRATION.md` entrypoint yet
+- the current implementation still relies on runtime patching rather than a clean installable integration unit
+- acceptance is still partly human-driven instead of fully scripted
+
+## Recommended next tasks
+
+1. add `HANDOFF.md`
+2. add `INTEGRATION.md`
+3. add a user-facing apply/verify/rollback flow description
+4. tighten the acceptance steps into a smaller repeatable checklist
+
+## Completion rule
+
+We can say the project is ready for another agent to directly use when:
+
+- the repo contains a single handoff entrypoint
+- patch application is reproducible
+- patch rollback is reproducible
+- verification steps are explicit and bounded
+- the other agent does not need to inspect OpenClaw runtime internals before getting started