From 89edb6d246cef6dff8fef3ca07d42ad168161f85 Mon Sep 17 00:00:00 2001
From: Chen Zhenbo <fakebob2004@gmail.com>
Date: Thu, 23 Jul 2026 19:18:36 +0800
Subject: [PATCH 1/2] document macOS setup and development

---
 README.md                     |  12 +++-
 README.zh-CN.md               |  11 ++-
 docs/MAC_DEVELOPMENT.md       | 115 ++++++++++++++++++++++++++++++++
 docs/MAC_DEVELOPMENT.zh-CN.md | 108 ++++++++++++++++++++++++++++++
 docs/MAC_HANDOFF.md           |  15 ++++-
 docs/MAC_SETUP.md             | 122 ++++++++++++++++++++++++++++++++++
 docs/MAC_SETUP.zh-CN.md       | 116 ++++++++++++++++++++++++++++++++
 7 files changed, 492 insertions(+), 7 deletions(-)
 create mode 100644 docs/MAC_DEVELOPMENT.md
 create mode 100644 docs/MAC_DEVELOPMENT.zh-CN.md
 create mode 100644 docs/MAC_SETUP.md
 create mode 100644 docs/MAC_SETUP.zh-CN.md

diff --git a/README.md b/README.md
index 8859fe3..2ba6adb 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,9 @@ make
 python3 tools/analyze_capture.py touches.jsonl
 ```
 
+See the [complete macOS operation guide](docs/MAC_SETUP.md) and
+[macOS development notes](docs/MAC_DEVELOPMENT.md).
+
 ### 2. Prepare Windows
 
 Build and install the KMDF/VHF driver and receiver first. The current bring-up and restart procedure
@@ -104,8 +107,13 @@ nc -vz WINDOWS_IP 39871
 
 Stop with `Ctrl-C`. On disconnect or a 200 ms active-contact timeout, Windows releases all contacts.
 
-The agent does not intercept local macOS input. If desired, configure macOS to ignore the built-in
-trackpad while an external mouse is present under Accessibility → Pointer Control.
+The agent does not intercept local macOS input. To dedicate the built-in trackpad to Windows while
+an external mouse controls the Mac, enable:
+
+```text
+System Settings → Accessibility → Pointer Control → Mouse & Trackpad
+→ Ignore built-in trackpad when mouse or wireless trackpad is present
+```
 
 ## Repository layout
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 1543a37..792ae2d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -75,6 +75,9 @@ make
 python3 tools/analyze_capture.py touches.jsonl
 ```
 
+完整说明见 [macOS 安装与操作指南](docs/MAC_SETUP.zh-CN.md) 和
+[macOS 端开发记录](docs/MAC_DEVELOPMENT.zh-CN.md)。
+
 ### 2. 准备 Windows
 
 先构建并安装 KMDF/VHF 驱动和 Receiver。当前启动与重启流程见：
@@ -100,8 +103,12 @@ nc -vz WINDOWS_IP 39871
 
 使用 `Ctrl-C` 停止。连接断开或活跃触点超过 200ms 没有更新时，Windows 会释放全部触点。
 
-Agent 不拦截 macOS 本机输入。如果希望外接鼠标存在时禁用内建触控板，请使用 macOS 的
-“辅助功能 → 指针控制”系统设置。
+Agent 不拦截 macOS 本机输入。如果希望外接鼠标控制 Mac、内建触控板专门控制 Windows，请开启：
+
+```text
+系统设置 → 辅助功能 → 指针控制 → 鼠标与触控板
+→ 有鼠标或无线触控板时忽略内建触控板
+```
 
 ## 仓库结构
 
diff --git a/docs/MAC_DEVELOPMENT.md b/docs/MAC_DEVELOPMENT.md
new file mode 100644
index 0000000..d82144e
--- /dev/null
+++ b/docs/MAC_DEVELOPMENT.md
@@ -0,0 +1,115 @@
+# macOS development notes
+
+[简体中文](MAC_DEVELOPMENT.zh-CN.md)
+
+The macOS implementation is intentionally small. Windows owns gesture recognition and the native
+Precision Touchpad contract; the Mac has three responsibilities: capture raw contacts faithfully,
+encode complete MTP1 frames, and deliver current state with safe reconnect behavior.
+
+## 1. The original feasibility risk
+
+The project depended on whether macOS could expose stable raw contacts rather than only high-level
+scroll and gesture events. Public `NSTouch` can report normalized positions in an application event
+path, but it was not assumed to provide the required global, background, and geometry behavior.
+
+The feasibility probe therefore dynamically loads Apple's private:
+
+```text
+/System/Library/PrivateFrameworks/MultitouchSupport.framework
+```
+
+Required symbols are resolved with `dlopen`/`dlsym`, so the binary does not directly link against an
+undocumented SDK interface. All inferred structures and function types are isolated in
+`mac/Probe/MultitouchSupportABI.h`, including a compile-time size assertion for `MTTouch`.
+
+## 2. What the probe established
+
+Real capture testing established:
+
+- one built-in device is discoverable on the tested Apple Silicon MacBook;
+- five simultaneous contacts are available;
+- contact IDs remain stable through a touch lifecycle;
+- active hardware cadence has an 8 ms median interval, approximately 125 Hz;
+- position, velocity, size, ellipse axes, angle, and density fields contain usable values;
+- no invalid frames or duplicate IDs were observed in the recorded test sessions.
+
+The probe writes JSON Lines to stdout and diagnostics to stderr. A private-framework hardware banner
+initially polluted stdout; startup output is now redirected so capture files remain valid JSONL.
+
+## 3. Why the Mac sends contacts, not gestures
+
+Recognizing scroll, pinch, and multi-finger gestures on macOS would turn the project into remote
+mouse emulation and lose native Windows settings. MTP1 therefore carries the complete current
+contact set:
+
+```text
+identifier + state + flags + x/y + geometry + monotonic timestamp
+```
+
+Windows maps those contacts to HID slots and lets its Precision Touchpad stack recognize gestures.
+This is why native two-finger scrolling and pinch zoom work without Mac-side gesture code.
+
+## 4. Real-time and reconnect design
+
+The private callback must not block on TCP. `mac-touch-agent` encodes on the callback path, places
+bounded messages into a 256-frame queue, and performs socket writes on a sender thread with
+`TCP_NODELAY`.
+
+Every connection starts:
+
+```text
+HELLO(sequence=N)
+RESET(sequence=N+1)
+FRAME(sequence=N+2)
+```
+
+An early prototype reused sequence numbers for control messages. The strict Windows receiver
+correctly rejected that stream after restart. Sequence allocation was fixed to advance for every
+message. If the bounded queue overflows, the agent reconnects and starts a new `HELLO`/`RESET` epoch
+instead of continuing with an invalid gap.
+
+## 5. Coordinate orientation
+
+The wire protocol preserves raw normalized Mac coordinates. Real end-to-end testing showed that the
+Mac Y axis and Windows Precision Touchpad surface grow in opposite directions. The correction belongs
+in the Windows mapping layer:
+
+```text
+hid_y = 1 - mac_y
+```
+
+Keeping this out of the wire format preserves raw sensor meaning and allows other receivers to make
+their own coordinate choices.
+
+## 6. Local macOS input policy
+
+A CGEventTap-based suppression experiment was considered, but rejected:
+
+- it requires Accessibility/Input Monitoring privileges;
+- it cannot reliably distinguish the built-in trackpad from an external mouse;
+- global interception creates unnecessary safety and usability risk.
+
+The final design does not suppress macOS input. Users who dedicate the built-in trackpad to Windows
+use macOS's own “Ignore built-in trackpad when mouse or wireless trackpad is present” setting.
+
+## 7. Why there is relatively little Mac code
+
+The implementation is small because responsibility is deliberately narrow:
+
+- no gesture recognizer;
+- no virtual device or kernel extension on macOS;
+- no UI, pairing, installer, or background daemon yet;
+- no direct USB device-mode path;
+- shared protocol codec instead of a second serialization implementation.
+
+The difficult work was validating the private sensor path and defining failure-safe boundaries, not
+writing a large application. Keeping this side small reduces breakage when macOS private ABI changes.
+
+## Remaining macOS work
+
+- test additional Apple Silicon generations and macOS releases;
+- package a signed menu-bar/background agent;
+- add discovery, pairing, authentication, and encrypted transport;
+- handle sleep/wake and interface changes;
+- investigate a reduced-function public-API backend;
+- add calibrated device metadata only after cross-model measurement.
diff --git a/docs/MAC_DEVELOPMENT.zh-CN.md b/docs/MAC_DEVELOPMENT.zh-CN.md
new file mode 100644
index 0000000..cf68de8
--- /dev/null
+++ b/docs/MAC_DEVELOPMENT.zh-CN.md
@@ -0,0 +1,108 @@
+# macOS 端开发记录
+
+[English](MAC_DEVELOPMENT.md)
+
+macOS 端代码有意保持精简。手势识别和原生精确式触控板协议由 Windows 负责；Mac 只有三个
+职责：忠实采集原始触点、编码完整 MTP1 帧、在重连和异常情况下安全地传递当前状态。
+
+## 1. 最初真正的技术风险
+
+项目能否成立，取决于 macOS 能不能提供稳定的原始触点，而不只是滚动和手势事件。公开的
+`NSTouch` 可以在应用事件路径中提供标准化坐标，但不能预先假定它满足全局、后台和完整几何
+数据需求。
+
+因此第一步探针动态加载 Apple 私有框架：
+
+```text
+/System/Library/PrivateFrameworks/MultitouchSupport.framework
+```
+
+程序通过 `dlopen`/`dlsym` 解析所需符号，不直接链接未公开的 SDK 接口。所有推断出的结构和
+函数类型集中隔离在 `mac/Probe/MultitouchSupportABI.h`，并对 `MTTouch` 大小进行编译期断言。
+
+## 2. 探针验证了什么
+
+真实采集验证结果：
+
+- 在测试的 Apple Silicon MacBook 上可以找到一个内建触控设备；
+- 支持五指同时接触；
+- Contact ID 在一次触点生命周期内保持稳定；
+- 活动状态下中位帧间隔为 8ms，约 125Hz；
+- 坐标、速度、面积、椭圆轴、角度和密度字段都有有效数据；
+- 已记录测试中没有非法帧和重复 ID。
+
+探针把 JSON Lines 写到 stdout，把诊断写到 stderr。私有框架最初会向 stdout 输出一行硬件
+信息，污染采集文件；后来把启动阶段输出重定向，保证 JSONL 可以直接分析。
+
+## 3. 为什么 Mac 不识别手势
+
+如果在 macOS 识别滚动、缩放和多指手势，项目就会退化成远程鼠标模拟，并失去 Windows 原生
+设置。MTP1 因此发送完整的当前触点集合：
+
+```text
+identifier + state + flags + x/y + geometry + monotonic timestamp
+```
+
+Windows 将触点映射到 HID slot，并交给精确式触控板栈识别手势。因此双指滚动和双指缩放能
+原生工作，而不需要 Mac 端手势代码。
+
+## 4. 实时性与重连
+
+私有框架回调不能阻塞在 TCP 上。`mac-touch-agent` 在回调路径编码数据，写入 256 帧有界队列，
+由独立发送线程配合 `TCP_NODELAY` 执行 Socket 写入。
+
+每次连接严格从以下序列开始：
+
+```text
+HELLO(sequence=N)
+RESET(sequence=N+1)
+FRAME(sequence=N+2)
+```
+
+早期原型曾让控制消息复用 sequence，严格的 Windows Receiver 在重启后正确拒绝了该数据流。
+修复后，每条消息都会递增 sequence。队列溢出时不会带着非法缺口继续发送，而是重新连接并
+建立新的 `HELLO`/`RESET` 会话。
+
+## 5. 坐标方向
+
+网络协议保留 Mac 原始标准化坐标。真实端到端测试发现，Mac Y 轴与 Windows 精确式触控板表面
+方向相反，因此在 Windows 映射层修正：
+
+```text
+hid_y = 1 - mac_y
+```
+
+不在网络协议中反转坐标，可以保留原始传感器含义，也允许未来其他 Receiver 自行选择方向。
+
+## 6. macOS 本机输入策略
+
+开发过程中考虑过使用 CGEventTap 拦截本机输入，但最终放弃：
+
+- 需要“辅助功能”和“输入监控”权限；
+- 无法可靠区分内建触控板与外接鼠标；
+- 全局拦截会增加不必要的安全和可用性风险。
+
+最终 Agent 不拦截 macOS 输入。需要把内建触控板专用于 Windows 的用户，使用 macOS 自带的
+“有鼠标或无线触控板时忽略内建触控板”设置。
+
+## 7. 为什么 Mac 端代码看起来不多
+
+这是有意的职责收敛：
+
+- 不实现手势识别器；
+- 不在 macOS 创建虚拟设备或内核扩展；
+- 暂时没有 UI、配对、安装器和后台守护进程；
+- 不尝试普通 USB-C Device Mode；
+- 复用共享协议编码器，不创建第二套序列化实现。
+
+困难部分是验证私有传感器路径和建立异常安全边界，而不是写一个庞大的应用。Mac 端越小，
+未来 macOS 私有 ABI 发生变化时需要维护的范围越小。
+
+## 后续 macOS 工作
+
+- 测试更多 Apple Silicon 代际和 macOS 版本；
+- 封装签名的菜单栏/后台 Agent；
+- 增加发现、配对、认证和加密；
+- 处理睡眠唤醒和网络接口变化；
+- 研究功能受限的公开 API 后端；
+- 在跨机型测量后增加校准过的设备元数据。
diff --git a/docs/MAC_HANDOFF.md b/docs/MAC_HANDOFF.md
index 4949205..be6ae7f 100644
--- a/docs/MAC_HANDOFF.md
+++ b/docs/MAC_HANDOFF.md
@@ -157,9 +157,18 @@ Then run:
 ```
 
 The agent does not intercept or suppress local macOS events. If the Mac should
-ignore its built-in trackpad while an external mouse is present, use the macOS
-system setting for that behavior rather than granting the agent global event
-interception privileges.
+ignore its built-in trackpad while an external mouse is present, use:
+
+```text
+System Settings
+-> Accessibility
+-> Pointer Control
+-> Mouse & Trackpad
+-> Ignore built-in trackpad when mouse or wireless trackpad is present
+```
+
+See `docs/MAC_SETUP.md` for operation and `docs/MAC_DEVELOPMENT.md` for the
+capture, protocol, reconnect, coordinate, and local-input design history.
 
 The receiver should begin with:
 
diff --git a/docs/MAC_SETUP.md b/docs/MAC_SETUP.md
new file mode 100644
index 0000000..77508be
--- /dev/null
+++ b/docs/MAC_SETUP.md
@@ -0,0 +1,122 @@
+# macOS setup and operation
+
+[简体中文](MAC_SETUP.zh-CN.md)
+
+The macOS side is a foreground command-line agent. It reads raw contacts from the built-in trackpad
+and sends complete MTP1 frames to the Windows receiver. It does not install a system service, inject
+events, or suppress local macOS input.
+
+## 1. Optional: make macOS ignore the built-in trackpad
+
+When an external mouse is connected, macOS can ignore the built-in trackpad without any event
+interception by this project:
+
+```text
+System Settings
+→ Accessibility
+→ Pointer Control
+→ Mouse & Trackpad
+→ Ignore built-in trackpad when mouse or wireless trackpad is present
+```
+
+Enable this setting if the Mac should remain controlled by an external mouse while its built-in
+trackpad is dedicated to Windows. The option only takes effect while macOS detects a mouse or
+wireless trackpad.
+
+## 2. Build
+
+Install Xcode Command Line Tools, then:
+
+```sh
+cd /path/to/touchpad
+make clean
+make
+```
+
+Produced tools:
+
+- `build/mac-capture-probe`: local raw-contact diagnostics;
+- `build/mac-touch-agent`: MTP1 TCP sender.
+
+## 3. Verify raw capture
+
+```sh
+./build/mac-capture-probe --duration 10 > touches.jsonl
+python3 tools/analyze_capture.py touches.jsonl
+```
+
+Move one, two, and five fingers during the capture. A healthy tested machine reports:
+
+```text
+max_contacts: 5
+estimated_hz: approximately 125
+duplicate_id_frames: []
+invalid_json_lines: []
+```
+
+The live `overall_rate` includes idle time with no fingers and can be lower than the active hardware
+rate.
+
+## 4. Prepare and connect to Windows
+
+Start the Windows receiver first. Use its current private IPv4 address:
+
+```sh
+nc -vz WINDOWS_IP 39871
+./build/mac-touch-agent WINDOWS_IP 39871
+```
+
+Example:
+
+```sh
+./build/mac-touch-agent 192.168.31.115 39871
+```
+
+Expected startup:
+
+```text
+connected to WINDOWS_IP:39871
+streaming 1 built-in trackpad(s) to WINDOWS_IP:39871
+```
+
+Stop with `Ctrl-C`. The agent reconnects automatically while it remains running.
+
+## 5. Acceptance test
+
+1. Move one finger and confirm the Windows pointer follows in both axes.
+2. Lift the finger and confirm movement stops immediately.
+3. Verify native two-finger scrolling.
+4. Verify native pinch zoom.
+5. Stop the agent with fingers down and confirm Windows releases contacts within 200 ms.
+6. Restart the receiver and agent and confirm a fresh `HELLO`/`RESET` session succeeds.
+
+## Troubleshooting
+
+### `captured=0`
+
+No raw callbacks occurred during the run. Touch and move the built-in trackpad while the agent is
+active. Re-run `mac-capture-probe` to separate capture problems from networking.
+
+### Agent never prints `connected`
+
+- Start the Windows receiver first.
+- Confirm the Windows network profile is Private.
+- Run `nc -vz WINDOWS_IP 39871`.
+- Check the Private/LocalSubnet firewall rule on Windows.
+
+### Mac still reacts to the built-in trackpad
+
+The agent intentionally does not suppress local events. Connect an external mouse and enable the
+macOS setting in step 1. If macOS does not detect an external pointing device, that setting does not
+disable the built-in trackpad.
+
+### Capture stops after a macOS update
+
+The project relies on private `MultitouchSupport.framework` symbols and an inferred touch structure.
+Run the probe first and report the macOS version, Mac model, startup diagnostics, and capture file
+analysis. Do not silently change the ABI layout.
+
+## Security
+
+MTP1 currently uses unauthenticated, unencrypted TCP. Use it only on a trusted private LAN and do
+not expose port 39871 to the internet.
diff --git a/docs/MAC_SETUP.zh-CN.md b/docs/MAC_SETUP.zh-CN.md
new file mode 100644
index 0000000..6783a7e
--- /dev/null
+++ b/docs/MAC_SETUP.zh-CN.md
@@ -0,0 +1,116 @@
+# macOS 安装与操作指南
+
+[English](MAC_SETUP.md)
+
+macOS 端目前是前台命令行 Agent：读取 MacBook 内建触控板的原始触点，并向 Windows
+Receiver 发送完整的 MTP1 帧。它不会安装系统服务、注入事件，也不会拦截 macOS 本机输入。
+
+## 1. 可选：让 macOS 忽略内建触控板
+
+当外接鼠标存在时，直接使用 macOS 自带设置，不需要本项目拦截输入：
+
+```text
+系统设置
+→ 辅助功能
+→ 指针控制
+→ 鼠标与触控板
+→ 有鼠标或无线触控板时忽略内建触控板
+```
+
+如果希望外接鼠标继续控制 Mac，而 MacBook 内建触控板专门控制 Windows，请开启该选项。
+只有在 macOS 实际检测到鼠标或无线触控板时，这个选项才会生效。
+
+## 2. 构建
+
+先安装 Xcode Command Line Tools，然后执行：
+
+```sh
+cd /path/to/touchpad
+make clean
+make
+```
+
+生成两个工具：
+
+- `build/mac-capture-probe`：本地原始触点诊断工具；
+- `build/mac-touch-agent`：MTP1 TCP 发送端。
+
+## 3. 验证原始触点
+
+```sh
+./build/mac-capture-probe --duration 10 > touches.jsonl
+python3 tools/analyze_capture.py touches.jsonl
+```
+
+采集期间依次使用单指、双指和五指移动。已验证机器的健康结果为：
+
+```text
+max_contacts: 5
+estimated_hz: 约 125
+duplicate_id_frames: []
+invalid_json_lines: []
+```
+
+实时摘要中的 `overall_rate` 包含手指离开触控板的空闲时间，因此可能低于真实活动采样率。
+
+## 4. 准备并连接 Windows
+
+先启动 Windows Receiver，然后使用它当前的局域网 IPv4：
+
+```sh
+nc -vz WINDOWS_IP 39871
+./build/mac-touch-agent WINDOWS_IP 39871
+```
+
+例如：
+
+```sh
+./build/mac-touch-agent 192.168.31.115 39871
+```
+
+正常启动输出：
+
+```text
+connected to WINDOWS_IP:39871
+streaming 1 built-in trackpad(s) to WINDOWS_IP:39871
+```
+
+使用 `Ctrl-C` 停止。只要 Agent 仍在运行，断线后会自动尝试重连。
+
+## 5. 验收
+
+1. 单指移动，确认 Windows 指针的水平和垂直方向都正确。
+2. 抬起手指，确认 Windows 指针立即停止。
+3. 验证原生双指滚动。
+4. 验证原生双指缩放。
+5. 手指按住时停止 Agent，确认 Windows 在 200ms 内释放全部触点。
+6. 重启 Windows Receiver 和 Mac Agent，确认新的 `HELLO`/`RESET` 会话正常建立。
+
+## 常见问题
+
+### `captured=0`
+
+运行期间没有收到原始触点回调。请在 Agent 运行时实际触摸并移动内建触控板。重新运行
+`mac-capture-probe`，可以区分触点采集问题和网络问题。
+
+### Agent 一直没有输出 `connected`
+
+- 先启动 Windows Receiver。
+- 确认 Windows 网络类型为“专用”。
+- 执行 `nc -vz WINDOWS_IP 39871`。
+- 检查 Windows 的 Private/LocalSubnet 防火墙规则。
+
+### Mac 仍然响应内建触控板
+
+Agent 有意不拦截本机事件。请连接外接鼠标，并开启第 1 节中的 macOS 系统设置。如果 macOS
+没有检测到外接指针设备，该设置不会禁用内建触控板。
+
+### macOS 更新后无法采集
+
+项目依赖私有 `MultitouchSupport.framework` 符号和推断出的触点结构。请先运行探针，并报告
+macOS 版本、Mac 型号、启动诊断和采集分析结果。不要在没有验证的情况下静默修改 ABI 布局。
+
+## 安全说明
+
+MTP1 当前使用未认证、未加密的 TCP。请仅在可信的私有局域网中使用，不要把 39871 端口暴露
+到公网。

From 4950e0df97f2daf32922c559db7e615063d73887 Mon Sep 17 00:00:00 2001
From: Chen Zhenbo <fakebob2004@gmail.com>
Date: Thu, 23 Jul 2026 19:34:16 +0800
Subject: [PATCH 2/2] refine README story and development note

---
 README.md       | 47 +++++++++++++++++++++++++++++++++++++++++++----
 README.zh-CN.md | 41 ++++++++++++++++++++++++++++++++++++++---
 2 files changed, 81 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 2ba6adb..e170206 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,34 @@
 [![macOS](https://img.shields.io/badge/macOS-Apple%20Silicon-black.svg)](#requirements)
 [![Windows](https://img.shields.io/badge/Windows-11%20x64-0078D4.svg)](#requirements)
 
-Turn a MacBook's built-in trackpad into a native Windows Precision Touchpad over a trusted wired
-LAN. macOS captures raw contacts; Windows exposes them through KMDF and Virtual HID Framework (VHF),
-so scrolling, pinch zoom, and system gestures are handled by the Windows touchpad stack rather than
-mouse-event emulation.
+## Why?
+
+Many programmers already work with both hands:
+
+- the right hand uses a mouse for precise pointing, selection, drawing, or CAD;
+- the left hand scrolls documents, papers, browsers, and code, and performs pinch zoom.
+
+Great standalone Windows touchpads are uncommon, but many desks already have a MacBook sitting next
+to the Windows PC. Instead of buying another touchpad, this project turns the MacBook's built-in
+trackpad into a native Windows Precision Touchpad.
+
+```text
+┌─────────────────────────────┐
+│          Windows PC         │
+└─────────────────────────────┘
+
+         ⌨ Keyboard
+
+MacBook trackpad          Mouse
+   left hand            right hand
+ scroll / zoom       precise operation
+```
+
+> **Don't buy another touchpad. Reuse the best one you already have.**
+
+macOS captures raw contacts over a trusted wired LAN; Windows exposes them through KMDF and Virtual
+HID Framework (VHF), so scrolling, pinch zoom, and system gestures are handled by the native Windows
+touchpad stack rather than mouse-event emulation.
 
 > **Experimental:** the end-to-end prototype moves the Windows pointer and supports native
 > two-finger scrolling and pinch zoom. It currently requires a test-signed Windows driver and a
@@ -160,6 +184,21 @@ ctest --test-dir out\windows -C Release --output-on-failure
 Contributions should keep networking out of kernel mode, preserve complete-frame semantics, and add
 tests for protocol or contact-lifecycle changes. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Development process
+
+This prototype was developed end to end through **vibe coding with GPT-5.6 Sol (Light)**, from the
+macOS feasibility probe and MTP1 protocol to the Windows VHF driver and documentation. It used
+approximately 50% of one weekly model allowance.
+
+The work was completed in two main development sessions of roughly three hours each. When the
+Windows driver showed the Device Manager yellow warning icon, a web high-reasoning mode briefly
+joined the investigation to isolate the `VhfCreate` startup failure and its missing `vhf` lower
+filter.
+
+Physical-device actions, installation, risk decisions, and end-to-end acceptance tests were
+performed by the project owner. AI-generated code was compiled and tested on the actual Mac and
+Windows machines before being merged.
+
 ## Roadmap
 
 - Validate three- and four-finger gestures with multiple MacBook generations
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 792ae2d..16fb86e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -6,9 +6,33 @@
 [![macOS](https://img.shields.io/badge/macOS-Apple%20Silicon-black.svg)](#环境要求)
 [![Windows](https://img.shields.io/badge/Windows-11%20x64-0078D4.svg)](#环境要求)
 
-通过可信的有线局域网，把 MacBook 内建触控板变成 Windows 原生精确式触控板。macOS
-负责采集原始触点，Windows 通过 KMDF 和 Virtual HID Framework（VHF）将其呈现为触控板，
-滚动、双指缩放和系统手势均由 Windows 触控板栈处理，而不是模拟鼠标事件。
+## 为什么做这个项目？
+
+很多程序员已经习惯双手分工：
+
+- 右手使用鼠标，负责精确指向、选择、绘图或 CAD；
+- 左手负责滚动论文、文档、浏览器和代码，并进行双指缩放。
+
+Windows 上优秀的独立触控板并不多，但很多人的 Windows 主机旁边其实已经放着一台 MacBook。
+与其再买一块触控板，不如直接把 MacBook 的内建触控板变成 Windows 原生精确式触控板。
+
+```text
+┌─────────────────────────────┐
+│          Windows PC         │
+└─────────────────────────────┘
+
+           ⌨ 键盘
+
+MacBook 触控板             鼠标
+    左手                  右手
+  滚动 / 缩放            精确操作
+```
+
+> **不用再买 Windows 触控板，把你已有的 MacBook 利用起来。**
+
+macOS 通过可信的有线局域网发送原始触点；Windows 使用 KMDF 和 Virtual HID Framework
+（VHF）将其呈现为原生触控板。滚动、双指缩放和系统手势由 Windows 触控板栈处理，而不是
+模拟鼠标事件。
 
 > **实验性项目：** 当前端到端原型已经能使用真实 Mac 输入移动 Windows 指针，并支持原生
 > 双指滚动和双指缩放。现阶段仍需要 Windows 测试签名驱动和 macOS 私有框架，不适合无人值守
@@ -153,6 +177,17 @@ ctest --test-dir out\windows -C Release --output-on-failure
 贡献代码时应保持网络逻辑位于用户态、保持完整帧语义，并为协议或触点生命周期变化增加测试。
 详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
+## 开发方式
+
+本原型从 macOS 可行性探针、MTP1 协议、Windows VHF 驱动到文档，**全程采用 GPT-5.6 Sol
+（Light）进行 vibe coding**，大约使用了一个周额度的 50%。
+
+主要开发分为两个时段，每次约三小时。Windows 驱动曾在设备管理器中出现黄色感叹号；排查
+`VhfCreate` 启动失败和缺失的 `vhf` lower filter 时，短暂让网页端高思考模式介入协助定位。
+
+真实设备操作、安装、风险决策和端到端验收由项目作者完成。AI 生成的代码在合并前均在实际
+Mac 和 Windows 机器上完成编译与测试。
+
 ## 路线图
 
 - 在更多 MacBook 机型上验证三指和四指手势