Support flat UI groups and simplify WinCode Skill guidance

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 0.17.0 (unreleased)
 
+- Reorganize the four managed Skill documents by task. Keep the entry short, place executable UI recipe examples inside the installed Skill, and remove duplicated instructions and historical iteration notes.
+
+- Add the readonly sibling-range client recipe for flat lists whose headings and items are siblings. Read one explicit container, validate unique ordered boundaries and readable row names, and retain native identities and property gaps. Results describe only the observed logical range; missing/ambiguous boundaries and incomplete reads stop without inventing an empty or complete business group. No scrolling or item actions are performed.
+- Add optional scopePath to client readonly inspect/review and checkbox-audit. Summary and detail reads share one explicit ancestor path, resolve it separately, and retain scopeResult in step evidence. Off still skips details; invalid paths, scope failures and unsupported or unconfirmed scope results stop without whole-window fallback. Unscoped calls retain their behavior and call count.
+- Let checkbox-audit complete when only className, bounds or isOffscreen properties are unavailable, while preserving the gaps in step evidence. Required identity/state and coverage checks still apply. The client-only reader.inspect option allowAuxiliaryPropertyGaps is opt-in; ordinary reads remain strict by default and review behavior is unchanged.
 - Add opt-in client workflows through the persistent JSON Skill session: bounded readonly-ui steps, checkbox-audit over an explicit set of controls, and expand-ui for one explicit or selected Group. Preserve live observations, conditional reads, target identity, cancellation and owned-process cleanup; unknown or incomplete evidence cannot produce successful findings. No model API or background workflow runs unless explicitly invoked.
 - Add wincode_ui_set_expanded and optional scopePath for inspect/review/setExpanded. Paths resolve each observed ancestor uniquely, and failures never fall back to whole-window operations. Scoped requests require inspectionVersion 5; older Hosts are rejected, and scoped actions check capability before dispatch.
 - Carry scopePath through expand-ui discovery, selection, expansion, readback and nextRequest. Explicit parent requests inspect the child inside that parent from the first read; final child readback resolves the parent again. Duplicate names or IDs in another region cannot supply the result. Each request expands at most once; an already expanded parent needs no extra action. Keep missing, ambiguous, incomplete and unknown outcomes visible without automatic replay or recursive navigation.

CONTRIBUTING.md

@@ -37,13 +37,13 @@ Keep changes bounded to the problem. Tool registration, schema and validation be
 
 For a version change, align `package.json`, the root entries in `package-lock.json`, `src/Core/Config.ts`, the Host project version, README and Skill. Do not edit dependency metadata to change the product's Node requirement. Dependency changes need an explicit maintenance scope; update npm/NuGet locks there and validate locked restores. `.gitattributes` and `.editorconfig` define formatting for touched files; do not reformat the repository in a functional PR.
 
-Before merging a topic branch, record the problem, changes, failures and actual verification in the existing work log. Require successful Node 22/24 and CodeQL results for the exact PR head. Keep independent review and author self-review distinct, and identify unverified integrations. Changes to repository protection require an owner decision; the verified policy is recorded below. A successful CodeQL run also does not prove existing alerts are closed.
+Before merging a topic branch, record the problem, changes, failures and actual verification in the PR description. Require successful Node 22/24 and CodeQL results for the exact PR head. Keep independent review and author self-review distinct, and identify unverified integrations. Changes to repository protection require an owner decision; the verified policy is recorded below. A successful CodeQL run also does not prove existing alerts are closed.
 
 On 2026-09-08, the owner authorized applying main protection. The read-back confirmed required pull requests, strict Node 22/24 regression and three CodeQL analysis checks bound to GitHub Actions, enforcement for administrators, resolved conversations, and disabled force pushes/deletions. The single-maintainer policy requires zero GitHub approvals; this does not constitute an independent review. Re-read GitHub settings when verifying current enforcement.
 
 SDK policy follows [Microsoft global.json guidance](https://learn.microsoft.com/en-us/dotnet/core/tools/global-json); dependency locking uses [NuGet locked restore](https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies).
 
-Current implementation is described in the [architecture guide](WinCode-架构与数据流说明.md). Keep pending tests and unresolved issues in the [remaining test plan](WinCode-下一轮工程化迭代计划书.md); completed work belongs in CHANGELOG and the append-only work log. For documentation-only changes, verify local links, commands, version claims and evidence boundaries; do not claim a new runtime regression without running it. The four managed Skill files are delivery inputs, so regenerate/verify the manifest after updating them; this does not synchronize an installed client Skill or reconnect its MCP process.
+Current implementation is described in the [architecture guide](WinCode-架构与数据流说明.md). Keep unfinished tasks and unresolved issues only in [the iteration plan](docs/next-iteration.md), and current client contracts in [the workflow guide](docs/hybrid-readonly-orchestration.md). Remove completed tasks from the plan; record user-visible changes in CHANGELOG and verification in the PR. Do not add chronological work logs or duplicate roadmaps. Read historical evidence from Git or the relevant PR only when needed. For documentation-only changes, verify local links, commands, version claims and evidence boundaries; do not claim a new runtime regression without running it. The four managed Skill files are delivery inputs, so regenerate/verify the manifest after updating them; this does not synchronize an installed client Skill or reconnect its MCP process.
 
 Node 22 CI runs `npm run test:error-contracts` and uploads its bounded report. It exercises protocol errors, matching tool-error text/structured payloads, real generated-file trash failures, structured WORKSPACE_MISMATCH and same-root workspace recovery; injected UI images test serialization only. Run it locally after changes to these boundaries.
 

README.md

@@ -30,7 +30,7 @@ WinCode is a local server implementing the Model Context Protocol (MCP) for AI c
 - **Project and code analysis:** Explore declared solution and project references, search text and symbols, read selected code, and assess change impact. Built-in text analysis works by default; optional Roslyn integration provides compiler-backed C# symbol and reference analysis.
 - **Semantic UI actions:** `wincode_ui_click` and `wincode_ui_type` act on exactly one control that a single bounded search proves unique. They use UI Automation patterns and keyboard input only—never coordinate mouse simulation—and do not explicitly activate, restore or raise the target window. Control events and navigation may still bring the application forward. Disabled controls, ambiguous or incomplete matches, read-only values and unconfirmed keyboard focus are refused rather than guessed.
 
-A recorded test with a 222-node window reduced response text from approximately **62 KB to 1.6 KB** by querying a specific control instead of returning the full tree. See the [test record](docs/codex_worklog.md).
+Use a query and an observed parent scope to retrieve the relevant controls, and request compact output when full geometry is unnecessary. Check completeness and ambiguity before drawing conclusions.
 
 ### Example: Investigate a disabled Save button
 
@@ -185,7 +185,7 @@ npm run benchmark:agent -- 1  # Run one iteration of the optional scripted bench
 - [Contributing](CONTRIBUTING.md): builds, test suites and delivery requirements.
 - [Architecture and data flow](WinCode-架构与数据流说明.md): components, interfaces, resource limits and lifecycle management.
 - [Skill and MCP setup](WinCode-Skill制作与MCP配置指南.md): installation and client configuration.
-- [Work log](docs/codex_worklog.md) and [remaining test plan](WinCode-下一轮工程化迭代计划书.md): historical verification, known issues and pending validation.
+- [Iteration plan](docs/next-iteration.md): unfinished improvements, known limitations and acceptance criteria.
 
 ---
 
@@ -202,7 +202,7 @@ WinCode 是面向 AI 编程智能体的本地模型上下文协议（Model Conte
 - **实际使用中更快、更准确：**在日常 Windows/.NET 开发中，使用 WinCode 检查 UI 和定位源码，比基于截图的 Computer Use 工作流更快、更准确。通过直接获取结构化的控件属性和源码位置，可以减少对图像识别的依赖和反复交互；配合定向查询与精简响应，还能减少模型需要处理的数据量。
 - **项目与代码分析：**查看解决方案和项目中声明的引用关系，搜索文本与符号，按需读取代码，并评估变更影响。默认提供内置文本分析，可选的 Roslyn 集成支持基于编译器语义的 C# 符号与引用分析。
 
-在包含 222 个节点的窗口测试中，仅查询指定控件即可将返回文本量从约 **62 KB 减少至 1.6 KB**。详见 [测试记录](docs/codex_worklog.md)。
+通过 query 和实际观察到的父范围只读取相关控件，不需要完整几何信息时使用 compact 输出。得出结论前仍需核对完整性与歧义。
 
 ### 使用示例：排查“保存”按钮被禁用的问题
 
@@ -357,7 +357,7 @@ npm run benchmark:agent -- 1  # 执行一轮可选的脚本化基准测试
 - [贡献指南](CONTRIBUTING.md)：构建、测试套件和交付要求。
 - [架构与数据流](WinCode-架构与数据流说明.md)：组件、接口、资源限制和生命周期管理。
 - [Skill 与 MCP 配置指南](WinCode-Skill制作与MCP配置指南.md)：安装与客户端配置。
-- [工作记录](docs/codex_worklog.md) 与 [后续测试计划](WinCode-下一轮工程化迭代计划书.md)：历史验证结果、已知问题和待验证事项。
+- [迭代计划](docs/next-iteration.md)：未完成的改进、已知限制与验收条件。
 
 ---
 

WinCode-Skill制作与MCP配置指南.md

@@ -8,7 +8,7 @@
 - **磁盘交付物**包含 Gateway、原生 UIA/Code Host 及可选 Tray 的完整发布目录、构建身份和交付清单。
 - **MCP 连接实例**是客户端已经启动的进程；更新源码、构建或复制 Skill 都不会自动更新这个进程。
 
-架构与数据流见 [架构说明](WinCode-架构与数据流说明.md)。待办见 [当前计划](WinCode-下一轮工程化迭代计划书.md)，不要按历史计划重复安装和升级。
+架构与数据流见 [架构说明](WinCode-架构与数据流说明.md)。未完成任务只维护在 [迭代计划](docs/next-iteration.md)，不要按历史计划重复安装和升级。
 
 ## 2. 构建与交付核对