From 994edeef1aa32984834100a5e061cb880446033b Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Fri, 11 Sep 2026 06:57:01 +0800
Subject: [PATCH 1/3] docs: audit the Computer Use documentation group (#3522)

Audit the nine Computer Use documents against current source:

- foundation-contract: the layer-3 verification description still
  named apps/desktop/e2e/accessibility-coverage.spec.ts, which #4803
  retired with the broad route inventories; the section now records
  that the coverage is carried by the ax-tree-audit rules and the
  Storybook smoke at their owning boundaries.
- The other eight documents verified clean: command names and lab
  fixture variables (evidence-classes), outcome types and the
  deterministic harness (host-events-contract), the maka_computer
  action surface and fail-closed coordinate policy (model-loop),
  provenance paths and bundled-tools pinning (provenance,
  cursor-provenance), report classes and sanitizer scripts
  (provider-evidence), and the story manifest (ui-coverage).
- All nine gain the standard frontmatter with last_verified dates.

Refs #3522

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/codex-pip-reverse-engineering.md      | 12 ++++++++++++
 docs/computer-use-cursor-provenance.md     | 12 ++++++++++++
 docs/computer-use-evidence-classes.md      | 12 ++++++++++++
 docs/computer-use-foundation-contract.md   | 19 +++++++++++++++++--
 docs/computer-use-host-events-contract.md  | 12 ++++++++++++
 docs/computer-use-model-loop-foundation.md | 12 ++++++++++++
 docs/computer-use-provenance.md            | 12 ++++++++++++
 docs/computer-use-provider-evidence.md     | 12 ++++++++++++
 docs/computer-use-ui-coverage.md           | 12 ++++++++++++
 9 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/docs/codex-pip-reverse-engineering.md b/docs/codex-pip-reverse-engineering.md
index 258d022120..01c8263f74 100644
--- a/docs/codex-pip-reverse-engineering.md
+++ b/docs/codex-pip-reverse-engineering.md
@@ -1,3 +1,15 @@
+---
+doc_id: codex-pip-reverse-engineering
+title: "Codex picture-in-picture reverse engineering"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-cursor-provenance.md b/docs/computer-use-cursor-provenance.md
index 715502d863..43e36623cd 100644
--- a/docs/computer-use-cursor-provenance.md
+++ b/docs/computer-use-cursor-provenance.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-cursor-provenance
+title: "Computer Use cursor provenance and independent replacement"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-evidence-classes.md b/docs/computer-use-evidence-classes.md
index 4822c749a8..44c6fdd7e1 100644
--- a/docs/computer-use-evidence-classes.md
+++ b/docs/computer-use-evidence-classes.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-evidence-classes
+title: "Computer Use Evidence Classes"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-foundation-contract.md b/docs/computer-use-foundation-contract.md
index 7082ca4d01..f07ced83b2 100644
--- a/docs/computer-use-foundation-contract.md
+++ b/docs/computer-use-foundation-contract.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-foundation-contract
+title: "Maka Computer Use Foundation Contract"
+language: zh-CN
+source_language: zh-CN
+implementation_status: current
+document_status: current
+translation_status: original
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -114,8 +126,11 @@ Maka 自己的 Electron renderer 也是 Computer Use 的目标。它不能依赖
 2. `scripts/ax-tree-audit.mjs` 是 Storybook 与 Electron E2E 共用的测试侧 AX 规则源，
    拒绝无名或同一语义作用域内歧义的可操作 node、多 `main`、无名 dialog，以及缺少
    checked/selected/expanded/value 的状态控件。
-3. `apps/desktop/e2e/accessibility-coverage.spec.ts` 读取真实 Electron Chromium AX tree，
-   从运行时设置导航枚举所有设置页，并覆盖模块页、全局弹窗、会话页和 7 个工作栏面板。
+3. Electron 侧的广域设置导航 AX 清单（原
+   `apps/desktop/e2e/accessibility-coverage.spec.ts`）已随 #4803 撤下：该类
+   broad route inventory 由第 2 层的 `ax-tree-audit.mjs` 规则与第 4 层的
+   Storybook smoke 在各自的 owning boundary 承担；Electron E2E 保留修订、
+   WorkHub 与草稿焦点等边界内 journey。
 4. `scripts/storybook-visual-smoke.mjs` 对 Storybook 全目录读取 AX tree，执行 `play`
    函数到最终态，并验证 modal 焦点、隐藏/惰性 surface 和关键 Computer Use story
    inventory；名字含 `narrow` 的故事必须在窄视口运行。独立 WebContentsView 由
diff --git a/docs/computer-use-host-events-contract.md b/docs/computer-use-host-events-contract.md
index 3b85945142..7bdd214b0e 100644
--- a/docs/computer-use-host-events-contract.md
+++ b/docs/computer-use-host-events-contract.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-host-events-contract
+title: "Computer Use Host Events Contract"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-model-loop-foundation.md b/docs/computer-use-model-loop-foundation.md
index 11d764b5b9..c4ca7a4101 100644
--- a/docs/computer-use-model-loop-foundation.md
+++ b/docs/computer-use-model-loop-foundation.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-model-loop-foundation
+title: "Computer Use Model-Loop Foundation"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-provenance.md b/docs/computer-use-provenance.md
index 0c5f56386b..4a52b37614 100644
--- a/docs/computer-use-provenance.md
+++ b/docs/computer-use-provenance.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-provenance
+title: "Computer Use provenance"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-provider-evidence.md b/docs/computer-use-provider-evidence.md
index e143cd44f1..2216a373f7 100644
--- a/docs/computer-use-provider-evidence.md
+++ b/docs/computer-use-provider-evidence.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-provider-evidence
+title: "Computer Use Provider Evidence"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/computer-use-ui-coverage.md b/docs/computer-use-ui-coverage.md
index b9d1c3fc54..dfbf0494b3 100644
--- a/docs/computer-use-ui-coverage.md
+++ b/docs/computer-use-ui-coverage.md
@@ -1,3 +1,15 @@
+---
+doc_id: computer-use-ui-coverage
+title: "Computer Use Semantic UI Coverage"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-11
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file

From aa4bfca02bb77494a3f461af8af76956126db491 Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Fri, 11 Sep 2026 20:36:17 +0800
Subject: [PATCH 2/3] docs: correct the Computer Use audit per review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four follow-ups from the review of the A10 audit:

- foundation-contract layer 3 now says what #4803 actually did: the
  broad route inventory was retired rather than relocated, nothing
  enumerates routes against a running Electron app, and layer 2's
  ax-tree-audit.mjs runs Storybook-only. The old text claimed
  equivalent coverage that #4803 explicitly declined to make, and the
  adjacent "Storybook 与 Electron E2E 共用" line said the same thing.
- ui-coverage: the three prose passages still describing the retired
  Electron spec (dynamic settings-navigation enumeration, named-dialog
  overlay sequencing, running-UI inventory) are corrected the same way,
  so the two documents no longer contradict each other.
- translation_status is source-only on all nine documents: none has a
  counterpart, and main's convention reserves synced for pairs.
- provenance §3 marks the binary-recovered cursor facts as removed by
  #3293 (hotspot is now the glyph tip); codex-pip notes that the
  pip-motion test it cited as exact coverage was deleted by #2478;
  provider-evidence says four evidence classes; the lease-class list
  matches computer-use.ts's four classes; the window-action lesson is
  annotated with its date.

Refs #3522

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/codex-pip-reverse-engineering.md      |  8 +++++---
 docs/computer-use-cursor-provenance.md     |  2 +-
 docs/computer-use-evidence-classes.md      |  2 +-
 docs/computer-use-foundation-contract.md   | 14 +++++++-------
 docs/computer-use-host-events-contract.md  |  2 +-
 docs/computer-use-model-loop-foundation.md |  2 +-
 docs/computer-use-provenance.md            |  4 ++--
 docs/computer-use-provider-evidence.md     |  4 ++--
 docs/computer-use-ui-coverage.md           | 21 ++++++++++++---------
 9 files changed, 32 insertions(+), 27 deletions(-)

diff --git a/docs/codex-pip-reverse-engineering.md b/docs/codex-pip-reverse-engineering.md
index 01c8263f74..0e8647dd93 100644
--- a/docs/codex-pip-reverse-engineering.md
+++ b/docs/codex-pip-reverse-engineering.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
@@ -247,5 +247,7 @@ It needs no accessibility and no unlocked screen — it drives Electron windows
 only — which makes it the one real-machine check that keeps working when the
 rest cannot run.
 
-The physics and the anchor scoring are covered exactly, without a desktop, in
-`apps/desktop/src/main/__tests__/computer-use-pip-motion.test.ts`.
+The physics and the anchor scoring were covered without a desktop in
+`apps/desktop/src/main/__tests__/computer-use-pip-motion.test.ts` (deleted by
+#2478); after #3293 replaced the transcribed constants, that exact-coverage
+claim no longer holds — see computer-use-cursor-provenance.md.
diff --git a/docs/computer-use-cursor-provenance.md b/docs/computer-use-cursor-provenance.md
index 43e36623cd..222df93a73 100644
--- a/docs/computer-use-cursor-provenance.md
+++ b/docs/computer-use-cursor-provenance.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
diff --git a/docs/computer-use-evidence-classes.md b/docs/computer-use-evidence-classes.md
index 44c6fdd7e1..c313987180 100644
--- a/docs/computer-use-evidence-classes.md
+++ b/docs/computer-use-evidence-classes.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
diff --git a/docs/computer-use-foundation-contract.md b/docs/computer-use-foundation-contract.md
index f07ced83b2..f422c7af6c 100644
--- a/docs/computer-use-foundation-contract.md
+++ b/docs/computer-use-foundation-contract.md
@@ -5,7 +5,7 @@ language: zh-CN
 source_language: zh-CN
 implementation_status: current
 document_status: current
-translation_status: original
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
@@ -88,7 +88,7 @@ owners:
 
 7. Approval and privacy
    - approval 是 app capability gate，不是 active observation 或 action freshness 证明。
-   - Maka 采用分级短 lease：metadata read、screenshot read、pointer mutation、keyboard mutation、semantic mutation 分离；目标、action class、observation 或 session generation 变化时重新授权。
+   - Maka 采用分级短 lease：`metadata_read`、`screenshot_read`、`keyboard_mutation`、`semantic_mutation` 四类（见 `packages/core/src/computer-use.ts`），分离；目标、action class、observation 或 session generation 变化时重新授权。
    - approval 至少标明 action class 与目标 app/window；敏感应用、secure/password field 和不支持的目的地 fail closed。
    - screenshot、typed text、coordinate、raw AX label/value、window title、secret 和 raw page content 默认不进入持久 session log、telemetry 或 evaluation report。
    - 上传截图前验证 model vision capability，并满足对应用户/provider consent policy。
@@ -123,13 +123,13 @@ Maka 自己的 Electron renderer 也是 Computer Use 的目标。它不能依赖
 1. TypeScript 与 Storybook 构建保证语义属性、文案契约和非默认状态 fixture 能随产品 API
    一起演进。不要重新引入基于正则的 JSX 源码扫描器；它无法可靠理解组件语义，主干已用
    真实 AX 验证取代这类检查。
-2. `scripts/ax-tree-audit.mjs` 是 Storybook 与 Electron E2E 共用的测试侧 AX 规则源，
+2. `scripts/ax-tree-audit.mjs` 是 Storybook smoke 的测试侧 AX 规则源（当前唯一消费者，不对 Electron 运行），
    拒绝无名或同一语义作用域内歧义的可操作 node、多 `main`、无名 dialog，以及缺少
    checked/selected/expanded/value 的状态控件。
 3. Electron 侧的广域设置导航 AX 清单（原
-   `apps/desktop/e2e/accessibility-coverage.spec.ts`）已随 #4803 撤下：该类
-   broad route inventory 由第 2 层的 `ax-tree-audit.mjs` 规则与第 4 层的
-   Storybook smoke 在各自的 owning boundary 承担；Electron E2E 保留修订、
+   `apps/desktop/e2e/accessibility-coverage.spec.ts`）已随 #4803 **退役而非迁
+   移**：#4803 明确不声称存在等价覆盖，且该缺口是有意接受的。目前没有任何
+   层对运行中的 Electron 应用做路由清单枚举；Electron E2E 仅保留修订、
    WorkHub 与草稿焦点等边界内 journey。
 4. `scripts/storybook-visual-smoke.mjs` 对 Storybook 全目录读取 AX tree，执行 `play`
    函数到最终态，并验证 modal 焦点、隐藏/惰性 surface 和关键 Computer Use story
@@ -266,7 +266,7 @@ JSON/YAML 不比"一元素一行 + 缩进"省：实测分别是它的 3.5 倍和
 
 任务是「把窗口挪到左边」。移动窗口只能拖标题栏，拖标题栏只能用坐标动作，而坐标动作
 要求目标像素属于目标窗口——Computer Use 驱动的是用户没在看的窗口，后台启动的窗口
-必然压在 z-order 底部，于是必然被遮挡。**这个任务没有解**：协议里没有窗口管理动词，
+必然压在 z-order 底部，于是必然被遮挡。**这个任务当时没有解**：记录时协议里没有窗口管理动词（`window_action` 的 move/resize/minimize 是 #1952 之后才加入严格动作集的），
 而「移动窗口」也不是任何控件的 AX 动作。
 
 把拒绝语句写清楚之后，模型确实读懂了「这条路不通」，于是去试别的路——而别的路也不
diff --git a/docs/computer-use-host-events-contract.md b/docs/computer-use-host-events-contract.md
index 7bdd214b0e..38815be207 100644
--- a/docs/computer-use-host-events-contract.md
+++ b/docs/computer-use-host-events-contract.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
diff --git a/docs/computer-use-model-loop-foundation.md b/docs/computer-use-model-loop-foundation.md
index c4ca7a4101..5a4a6a15b4 100644
--- a/docs/computer-use-model-loop-foundation.md
+++ b/docs/computer-use-model-loop-foundation.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
diff --git a/docs/computer-use-provenance.md b/docs/computer-use-provenance.md
index 4a52b37614..59030ad73d 100644
--- a/docs/computer-use-provenance.md
+++ b/docs/computer-use-provenance.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
@@ -137,7 +137,7 @@ artifact, retained facts, and Maka-authored divergences are recorded in
 
 | Binary-recovered or observed fact | Informed area |
 |---|---|
-| Exact cursor geometry, center hotspot, motion configuration, close-enough thresholds, path measurement, and core scoring weights | `apps/desktop/src/renderer/computer-use-overlay/engine/cursor-engine.ts` |
+| Historical (removed by #3293): cursor geometry, center hotspot, motion configuration, close-enough thresholds, path measurement, and core scoring weights | Formerly `apps/desktop/src/renderer/computer-use-overlay/engine/cursor-engine.ts`; the #3293 replacement removed every transcribed value (the hotspot is now the glyph tip, not the center) |
 | Overlay level policy — an occluded target raises the cursor rather than hiding it | same file, and `apps/desktop/src/main/computer-use/cursor-overlay-window.ts` |
 | The observation text shape | `packages/runtime/src/computer-use-tools.ts`, corroborated by the archived capture in §2 |
 | OOP WebContent targeting, retained-element unique refetch, and renderer-generation fencing | Reimplemented in the pinned `maka-cu` source; this repository records the exact source commit and binary digest in `apps/desktop/bundled-tools.json` |
diff --git a/docs/computer-use-provider-evidence.md b/docs/computer-use-provider-evidence.md
index 2216a373f7..b7ba38d739 100644
--- a/docs/computer-use-provider-evidence.md
+++ b/docs/computer-use-provider-evidence.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
@@ -50,7 +50,7 @@ provider transports, or execution backends.
 
 ## Report Contract
 
-Reports separate three evidence classes:
+Reports separate four evidence classes:
 
 - `real-runtime`: a live provider model used the production Maka runtime;
 - `fault-injection`: a live provider and Runtime exercised a named injected
diff --git a/docs/computer-use-ui-coverage.md b/docs/computer-use-ui-coverage.md
index dfbf0494b3..75ba7c7223 100644
--- a/docs/computer-use-ui-coverage.md
+++ b/docs/computer-use-ui-coverage.md
@@ -5,7 +5,7 @@ language: en
 source_language: en
 implementation_status: current
 document_status: current
-translation_status: synced
+translation_status: source-only
 last_verified: 2026-09-11
 owners:
   - maka-backend
@@ -47,7 +47,7 @@ are not measured here; they require separate accessibility testing.
 
 | Surface | Runtime states | Semantic actions and effects |
 |---|---|---|
-| Settings | Every current top-level navigation entry is enumerated from the running UI; provider list/detail/catalog/add, subagent editor, memory populated, permission diagnostics, import empty/ready, usage variants, Daily Review selector and narrow states are in Storybook | Navigation exposes `aria-current`; focused nested stories exercise dialogs, disclosures, selectors and editors |
+| Settings | Top-level navigation entries are covered through the Storybook settings-pages stories; provider list/detail/catalog/add, subagent editor, memory populated, permission diagnostics, import empty/ready, usage variants, Daily Review selector and narrow states are in Storybook (the Electron-side dynamic enumeration was retired by #4803) | Navigation exposes `aria-current`; focused nested stories exercise dialogs, disclosures, selectors and editors |
 | Extensions | Skills empty/installed/bundled/update/disabled/narrow/inspector; MCP setup/marketplace/configured/inspector/editor/failure/narrow | Page selection, inspector/editor opening and actionable-node identity |
 | Scheduled work | Empty/configured/long/narrow/task inspector; Daily Review loading/error/refreshing/report | Task selection, dialog focus, selector state and report actions |
 | Conversation shell | New task, settled conversation, streaming, permission wait, native conversation, modes, context and inline completion | Composer submit effect, unique per-task and per-turn actions, current regions and workbar selection |
@@ -58,9 +58,11 @@ are not measured here; they require separate accessibility testing.
 
 The Storybook catalog is exhaustive for its source-defined entries and the
 smoke runner carries a required Computer Use story manifest for critical
-runtime boundaries. The Electron accessibility test dynamically enumerates
-settings navigation, then covers modules, global overlays, conversations and
-all workbar entry points.
+runtime boundaries. The Electron-side broad route inventory (a spec that
+dynamically enumerated settings navigation, then modules, global overlays,
+conversations and all workbar entry points) was retired by #4803 rather than
+relocated; the surviving Electron journeys cover revision, WorkHub and
+draft-focus boundaries only.
 
 ## AX completion gates
 
@@ -77,10 +79,11 @@ Every measured final state fails on:
 - focus inside an inert or `aria-hidden` surface;
 - a visible modal dialog that does not own focus.
 
-Critical stories and Electron journeys additionally assert action-specific
-effects. Overlay journeys wait for the specifically named prior dialog to
-close before opening and auditing the next one. Transport success or a generic
-dialog match alone is not accepted.
+Critical stories additionally assert action-specific effects. (An Electron
+variant that waited for the specifically named prior dialog to close before
+auditing the next one was part of the retired route-inventory spec; the
+surviving journeys do not carry it.) Transport success or a generic dialog
+match alone is not accepted.
 
 Repeated message and answer actions use a bounded excerpt of visible text plus
 a stable human-readable timestamp. Opaque storage IDs remain machine data and

From 8de10b2a851b87a8016bf775f0f86b52f6982d79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=85=B3=E5=A4=A9=E8=B1=AA?= <ggbdpq@gmail.com>
Date: Sat, 12 Sep 2026 15:18:03 +0800
Subject: [PATCH 3/3] docs: separate PiP motion provenance from the cursor
 replacement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up on #5172. The audit paragraph attributed the PiP window's
motion constants to the #3293 cursor replacement, but `pip-motion.ts` is
byte-identical before #3456, after it, and at this head — the replacement
rebuilt the agent cursor engine and glyphs, not the PiP springs or anchor
scoring. The paragraph now says the #2478 deletion only ends the retired
test's coverage, records that the motion module is untouched, and scopes
the cursor-provenance link to the agent cursor explicitly.

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/codex-pip-reverse-engineering.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/codex-pip-reverse-engineering.md b/docs/codex-pip-reverse-engineering.md
index 0e8647dd93..ba5dc6ebf6 100644
--- a/docs/codex-pip-reverse-engineering.md
+++ b/docs/codex-pip-reverse-engineering.md
@@ -248,6 +248,14 @@ only — which makes it the one real-machine check that keeps working when the
 rest cannot run.
 
 The physics and the anchor scoring were covered without a desktop in
-`apps/desktop/src/main/__tests__/computer-use-pip-motion.test.ts` (deleted by
-#2478); after #3293 replaced the transcribed constants, that exact-coverage
-claim no longer holds — see computer-use-cursor-provenance.md.
+`apps/desktop/src/main/__tests__/computer-use-pip-motion.test.ts`; #2478
+deleted that test, which only ends the coverage it provided — nothing has
+taken its place. The module under test is untouched: `pip-motion.ts` is
+byte-identical across the #3293 cursor replacement (implemented in #3456),
+which rebuilt the agent cursor engine and its glyphs — including the PiP
+glyph — without replacing the PiP window's motion constants. The dragging
+and settling springs and the throw factors transcribed above are still
+defined there and still drive `pip-window.ts`. Cursor provenance is tracked
+in computer-use-cursor-provenance.md, and it concerns the agent cursor only;
+the PiP window's motion model is a separate surface with no provenance
+change to record.