@alpsckr/unitycli 0.4.0 → 0.4.2

package/docs/architecture.md

@@ -0,0 +1,103 @@
+# Architecture And Public Boundaries
+
+## Product Boundary
+
+UnityCLI is a Windows-first CLI, not an MCP server. Public top-level commands are frozen to:
+
+```text
+tools
+command
+init
+extensions
+target
+instances
+doctor
+```
+
+Unity capability domains such as scene, asset, camera, prefab, build, test, package, profiler, physics, and graphics are Tools in one live catalog. They are not top-level commands.
+
+External control planes remain external: Unity Hub, Editor installation or launch, auth, Cloud, License, and proxy configuration are handled by their system or vendor interfaces.
+
+## Layers
+
+```text
+AI
+  -> unitycli process
+CLI (TypeScript)
+  -> catalog, descriptor, schema, routing, safety, package/Skill installers
+Unity Bridge (C# package)
+  -> listener, registry, completion, Unity main-thread handlers
+Unity Editor or development Player
+```
+
+Every public process writes one JSON envelope and exits. Tool calls are direct and terminal; no public background-job protocol exists.
+
+## Tool Catalog
+
+`tools run <tool> --input <json>` and `command <name> <business-args>` share the same live descriptor, schema, dispatcher, safety metadata, completion contract, and result envelope.
+
+A normal AI flow is:
+
+```text
+tools group/search
+tools describe <tool>
+tools run <tool> --input <json>
+```
+
+Descriptions expose the input and execution boundary required for one correct call. Internal output schemas and completion metadata validate terminal business data but are not duplicated into public discovery output.
+
+## Installation Control Plane
+
+Installation is split by ownership:
+
+- `init package` owns one explicit Unity project's `Packages/com.alpsckr.unitycli` copy.
+- `init skill` owns one exact user-selected Skill directory or one `.agents`/Claude preset target.
+- `init discover` is a bounded, read-only current-project installation plan with exact Editor running state.
+- `init help` is the static, versioned AI setup protocol.
+
+Bridge and Skill installation are independent effects. The CLI is non-interactive; the AI preserves explicit user targets, infers the unique current project/workspace, and asks only unresolved decisions. Normally closing an exact running Editor requires separate explicit approval and the install-scoped `--close-editor`; force termination is never used.
+
+The Bridge source is the npm-local canonical `unitypkg`. `contracts/package-files.json` fixes every managed path, size, SHA-256, and the complete tree hash. Installation validates the source before planning and again before effect, publishes through staging/rename, and proves the target from fresh filesystem readback.
+
+UnityCLI carries no private Roslyn assemblies. `code.exec` invokes the current Unity Editor's bounded Mono/csc compiler subprocess. `contracts/package-assembly-closure.json` fixes this boundary and defines protected precompiled assembly names and allowed providers.
+
+## Editor Sessions
+
+Registry v3 publishes canonical project identity and listener lifecycle. Health v3 combines transport identity with a read-only main-thread pulse. Public Editor status is normalized to:
+
+```text
+ready
+transitioning
+blocked
+unresponsive
+unverifiable
+offline
+conflict
+```
+
+The current Unity writer replaces unusable prior state with its current identity and connection, then publishes `transitioning` before `ready`. CLI calls wait within their existing deadline when the selected Unity process is starting or changing connections. Historical cleanup remains writer-owned: automatic cleanup and `instances prune` share one globally serialized, bounded retention function.
+
+A live mutation can continue across a reload only while the same Editor session owns the exact request. After the first mutation POST, a changed Editor session forbids redelivery. Timeout or disconnect before a trusted terminal response is outcome unknown.
+
+## Safety And Authorization
+
+Calling a public Tool or control-plane effect is authorization. `destructiveHint`, `sideEffects`, and `supportsDryRun` describe behavior; they do not add confirmation gates.
+
+Read-only Tools do not write files or Unity state and do not trigger import, compile, domain reload, or Play Mode transitions.
+
+Mechanism state and temporary files follow fixed, bounded roots:
+
+- user-level: `%LOCALAPPDATA%\UnityCli\.temp\`
+- Unity project: `Library\UnityCli\`
+
+Dev Unity validation uses `%LOCALAPPDATA%\UnityCli-Dev` and must not change the formal root or unrelated Unity processes.
+
+## Source Of Truth
+
+- `AGENTS.md`: repository engineering constraints
+- `contracts/`: generated and hand-governed machine contracts
+- `schemas/`: public and internal JSON schemas
+- `skills/unitycli/`: public AI Skill source
+- `unitypkg/`: canonical Unity Bridge package
+- `extensions/`: optional extension sources
+- `docs/`: public operational and architectural documentation

package/docs/availability-differences.md

@@ -80,7 +80,7 @@ Unity API版本门禁不从major版本猜测。Tool仍在当前实例catalog中
 
 ## Domain Reload
 
-Domain reload期间，Registry v3 lifecycle将实例归约为`transitioning`，listener generation随后交接；Health v3中该generation的首个Unity主线程pulse才允许归约为`ready`。系统不读取固定三分钟或其他deadline marker。session supervisor只在同一`editorSessionId`内续接完全相同的请求；首次mutation POST后若session改变，不向新session重投，并返回`E_EXECUTION_TIMEOUT`与outcome unknown。调用方先读取业务状态，再决定是否提交全新请求。
+Domain reload期间，Registry v3 lifecycle将实例归约为`transitioning`，listener generation随后交接；Health v3中该generation的首个Unity主线程pulse才允许归约为`ready`。CLI在原命令截止时间内等待首次记录或新ready generation，不读取固定时长marker，也不要求AI轮询。session supervisor只在同一`editorSessionId`内续接完全相同的请求；首次mutation POST后若session改变，不向新session重投，并返回`E_EXECUTION_TIMEOUT`与outcome unknown。调用方先读取业务状态，再决定是否提交全新请求。
 
 ## AI Agent 处理方式
 

package/docs/command-execution.md

@@ -61,15 +61,20 @@ object、array和任意JSON值必须是有效JSON。字段大小写和下划线
 ## Command级控制项
 
 ```powershell
+# 省略name时只返回有界路由摘要；参数在单命令help中读取
+unitycli command --project-path C:\path\MyProject --page-size 20
+unitycli command --project-path C:\path\MyProject --page-size 20 --cursor 20
+
 unitycli command --project-path C:\path\MyProject <name> ...
 unitycli command --timeout 120 <name> ...
 unitycli command <name> ... --timeout-ms 120000 --dry-run
 ```
 
 - `--project-path <path>`绑定现有canonical项目实例，不直连endpoint，也不写入active target。
+- 省略name时，`--page-size`默认20、最大100；存在`pageInfo.nextCursor`时将其原值传回`--cursor`。列表项不展开parameters，使用`command <name> --help`读取参数。
 - `--timeout <seconds>`位于name前；`--timeout-ms <milliseconds>`使用本项目执行控制语义。
 - `--dry-run`、`--runtime`、`--artifact-dir`和`--instance`仍是执行/选择控制项，不进入Tool business input。
-- `--raw`只改变同一JSON envelope的排版。
+- stdout默认是单行紧凑JSON；`--pretty`只增加缩进，不改变envelope字段。
 
 ## 等价性
 

package/docs/development.md

@@ -0,0 +1,91 @@
+# Local Development
+
+## Requirements
+
+- Windows
+- Node.js 20 or newer
+- PowerShell 7
+- Unity 2022.3 for the Dev validation project
+
+## Build And Test
+
+```powershell
+npm install
+npm run build:test
+npm test
+npm run architecture:validate
+```
+
+`build:test` regenerates extension projections, TypeScript registries, completion contracts, command contracts, protocol output, Tool schemas, and the canonical Package file manifest before compiling production and test code.
+
+Package integrity checks can be run directly:
+
+```powershell
+npm run package-closure:validate
+npm run init-contract:validate
+```
+
+The Package closure audit enforces:
+
+- exact canonical `unitypkg` file paths, sizes, per-file SHA-256, and tree hash;
+- zero package-owned Roslyn DLLs;
+- Unity-provided precompiled references;
+- the Unity Editor compiler path used by `code.exec`;
+- bounded assembly-conflict policy.
+
+## Run The Source CLI
+
+```powershell
+node dist/cli.js --help
+node dist/cli.js init help
+node dist/cli.js init discover
+```
+
+For global local development:
+
+```powershell
+npm link
+unitycli --version
+```
+
+## Dev Unity Isolation
+
+Only `Dev/UnityProject` is controlled by automated validation. Launch both Unity and the source CLI with the process-local environment variable:
+
+```powershell
+$env:UNITYCLI_DATA_DIR = Join-Path $env:LOCALAPPDATA 'UnityCli-Dev'
+```
+
+Do not set this variable globally. Before and after validation, record:
+
+- the formal `%LOCALAPPDATA%\UnityCli` file set;
+- existing Unity process IDs and project command lines;
+- Dev registry and temporary files;
+- every changed Dev fixture and its restoration state.
+
+Use the current source installation route before Unity validation:
+
+```powershell
+$project = (Resolve-Path 'Dev/UnityProject').Path
+node dist/cli.js init package --project $project
+node dist/cli.js init package --project $project --check
+```
+
+## Validation Order
+
+1. Finish source, tests, contracts, generated outputs, public Skill, and docs.
+2. Run focused build, type checks, tests, and contract audits.
+3. Run the affected isolated Dev Unity matrix.
+4. Audit the final diff and npm artifact.
+
+A failed validation step stops the current validation stage. Classify it as product, harness, environment, specification, or test-scope failure; fix the owner and rerun every affected check fresh.
+
+## Packaging
+
+Inspect the npm artifact without publishing:
+
+```powershell
+npm pack --dry-run --json
+```
+
+The artifact must contain the canonical `unitypkg`, contracts, schemas, public Skill source, docs, and README. Publishing, tagging, pushing, installing a release artifact, or changing versions requires the repository release procedure and explicit user authorization.

package/docs/error-codes.md

@@ -38,16 +38,32 @@ alps-unity-cli 使用结构化错误码，包含机器可读的 `code`、`transi
 | `E_OPTION_VALUE_INVALID` | boolean option 的 attached value 不是 `true` 或 `false` | 使用 `--option`、`--option=true` 或 `--option=false` |
 | `E_OBSOLETE_OPTION` | option 已从当前公开语义删除 | 按 `nextActions` 删除旧 option |
 
+### Init 安装错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_INIT_EDITOR_RUNNING` | 准确目标Unity项目正在运行，未授权安装器关闭 | 只询问一次；用户同意后对同一项目使用`init package --close-editor` |
+| `E_EDITOR_STATE_UNVERIFIABLE` | 安装前无法严格判断准确项目的Editor进程 | 确认目标项目未在Unity中打开，再重新执行安装 |
+| `E_EDITOR_CLOSE_FAILED` | 无法向准确目标Editor发送正常关闭请求 | 用户正常关闭该项目后重新安装；不得强制终止 |
+| `E_EDITOR_CLOSE_BLOCKED` | 正常关闭后Editor仍存在，通常有未保存或modal提示 | 由用户处理Unity提示并正常关闭，再重新安装 |
+| `PACKAGE_DIRECTORY_LOCKED` | Windows持续占用现有Bridge目录，原子替换无法提交 | 关闭使用该Package的Unity、IDE或扫描进程，再重新安装；不要手工部分删除 |
+| `E_INIT_SKILL_TARGET_REQUIRED` | 既未给出明确Skill目录，也未给出预设agent/scope | 使用`--target <SkillDirectory>`，或选择一个预设目标 |
+| `E_INIT_SKILL_TARGET_CONFLICT` | 明确`--target`与预设agent/scope参数混用 | 保留明确目录或预设形式之一 |
+| `E_INIT_SKILL_TARGET_INVALID` | 明确目标不是安全的本地`unitycli`目录，或位于安装事务目录 | 传独立的固定本地完整目录，例如`.pi/skills/unitycli` |
+| `E_SKILL_TARGET_OVERLAPS_SOURCE` | 安装目标与npm内置Skill准源互相包含 | 选择独立安装目录 |
+| `E_SKILL_TARGET_OWNERSHIP_UNPROVEN` | 非空目标没有UnityCLI `SKILL.md`，不能证明归安装器所有 | 选择准确UnityCLI目录或先清空明确的新目标 |
+| `E_SKILL_TARGET_UNREADABLE` | 目标因权限或文件占用无法只读验证 | 恢复读取权限后重试；不得把不可读当成损坏并覆盖 |
+
 ### Project Identity / Instance 错误
 
 | 错误码 | 含义 | 恢复 |
 |--------|------|------|
 | `E_INSTANCE_REQUIRED` | 没有显式 selector，CWD 也不在 Unity 项目中 | 传完整 `--instance <id|projectPath|alias>` 或从项目目录调用 |
-| `E_INSTANCE_NOT_FOUND` | selector 无法解析到 canonical project identity | 运行 `instances list` 或核对项目路径/alias |
-| `E_INSTANCE_NOT_RUNNING` | 项目 identity 已确定，但没有可验证的运行中 Editor | 打开该项目并等待 Bridge 注册 |
+| `E_INSTANCE_NOT_FOUND` | selector 在当前截止时间内没有对应项目记录 | 核对项目路径/alias；完整instance ID在目标Unity启动时会等待首次记录 |
+| `E_INSTANCE_NOT_RUNNING` | 项目 identity 已确定，且没有可验证的运行中 Editor | 打开该项目；CLI会在本次调用内等待首次ready记录 |
 | `E_INSTANCE_CONFLICT` | 至少两个已验证live process claim声明同一项目 | 关闭重复Editor，只保留目标session |
 | `E_INSTANCE_UNVERIFIABLE` | PID/start、project claim、Registry读取或权限证据不完整 | 重新观察identity；不得把未知mutation自动重投 |
-| `E_INSTANCE_IDENTITY_MISMATCH` | Registry、Health或请求中的canonical identity不一致 | 停止调用并检查项目移动、Registry claim或Bridge安装 |
+| `E_INSTANCE_IDENTITY_MISMATCH` | 当前Unity无法在截止时间内重建并证明一致的项目身份 | 更新匹配的CLI/Package，打开该项目并重新观察；不要手工修改内部记录 |
 | `E_UNITY_UNRESPONSIVE` | transport identity存在，但近期Unity主线程pulse或Bridge响应不可证明 | 读取`editor.state`与`editor.dialogs`后处理transition/modal |
 | `E_INSTANCE_PROJECT_MISMATCH` | 显式项目约束与 selector 指向不同 identity | 统一 `--project` 和 `--instance` |
 | `E_INSTANCE_PATH_UNAVAILABLE` | 无法取得可证明的物理 canonical path | 修复不可访问路径、broken link 或 reparse 配置 |
@@ -168,8 +184,8 @@ alps-unity-cli 使用结构化错误码，包含机器可读的 `code`、`transi
 | 错误码 | 含义 |
 |--------|------|
 | `E_UNITY_BLOCKED` | effect 前已证明 Unity/UI blocker；原错误的 `details.blockers` 含结构化弹窗摘要 |
-| `E_UNITY_BUSY` | 两种可区分语义：任务池准入deadline到达时message明确`no business request was sent`，effect未开始且可稍后提交新root；已进入池后mutation lease竞争则业务请求已经发送，等待当前mutation terminal后再决策 |
-| `E_UNITY_TRANSITION_TIMEOUT` | 可恢复 lifecycle transition 未在当前阶段的 absolute deadline 内稳定 |
+| `E_UNITY_BUSY` | 任务池、修改owner或实例清理owner正在工作；按message与`nextActions`区分是否尚未发送业务请求，`instances prune`可按`retryAfterMs`稍后重试 |
+| `E_UNITY_TRANSITION_TIMEOUT` | 首次ready记录或可恢复状态变化未在原命令截止时间内稳定；确认Unity仍在推进后才使用更大的timeout重试 |
 | `E_EXECUTION_TIMEOUT` | 已放行调用未在execution deadline内返回终态、连接提前断开，或首次mutation POST后Editor session改变；outcome unknown，CLI不向新session自动重投 |
 | `E_REQUEST_ID_REUSED` | 同一 root request ID 被不同 exact request bytes 使用 |
 | `E_TOOL_COMPLETION_PROOF_INVALID` | Tool 返回值不满足其 completion contract 或 proof 校验 |

package/docs/extensions.md

@@ -10,23 +10,23 @@
 
 ### Bridge 包安装
 
-通过 `init` 命令安装 Unity Editor Bridge 包：
+Bridge 与 AI Skill 是两个独立安装对象。先用安装协议发现并选择项目，再单独安装或检查 Bridge：
 
 ```powershell
-# 默认安装 Bridge；若项目已有 .pi/.claude/.agents，则自动安装 Skill
-unitycli init --project C:\path\MyProject
-
-# 仅安装 Bridge 包
-unitycli init --project C:\path\MyProject --pkg-only
-
-# 检查安装状态
-unitycli init --check --project C:\path\MyProject
+unitycli init help
+unitycli init discover
+unitycli init package --project C:\path\UnityProject
+# 仅在用户批准正常关闭这个准确项目后使用
+unitycli init package --project C:\path\UnityProject --close-editor
+unitycli init package --project C:\path\UnityProject --check
 ```
 
-安装内容：
-- `Packages/com.alpsckr.unitycli/` — Bridge 包（copy 模式）
-- `Packages/unitycli.install.json` — 安装元数据（项目 hash、版本、支持范围）
-- `.pi/skills/unitycli/`、`.claude/skills/unitycli/` 或 `.agents/skills/unitycli/` — 仅当对应 Agent 目录已存在，或显式传入 `--agent` 时安装完整 runtime bundle（`SKILL.md`、`references/**`、`scripts/**`）
+Bridge 安装内容：
+- `Packages/com.alpsckr.unitycli/` — canonical Bridge 包（copy 模式）
+- `Packages/unitycli.install.json` — 安装元数据（项目 hash、source hash、managed-file hash、版本与支持范围）
+- `Packages/com.alpsckr.unitycli/unitycli.files.json` — 受管文件路径清单
+
+Skill 使用`init skill --target <SkillDirectory>`安装到用户明确目录，或使用`.agents`/Claude workspace/user预设；它不属于Unity项目Package安装，Bridge失败也不阻止这个独立效果。
 
 ### 项目能力发现
 

package/docs/target-and-instance.md

@@ -13,12 +13,12 @@ CLI 只接受本机可证明的 Unity 项目目录。目录大小写、尾分隔
 ```powershell
 unitycli instances list
 unitycli instances list --all
-unitycli instances prune
+unitycli instances prune --instance <id|projectPath|alias>
 ```
 
 `instances list` 默认排除 `status="offline"` 的记录；存在隐藏项时返回 `hiddenOfflineCount`。只有需要审计历史/offline identity 时使用 `--all`，此时返回完整合法集合并省略 `hiddenOfflineCount`。每项公开字段固定为 `instanceId`、可选 `alias`、`canonicalProjectPath`、`displayProjectPath`、`projectName`、`status` 和可选 `unityVersion`；`--all` 不会恢复内部 session、快照、进程 claim 或诊断字段。
 
-实例目录按文件独立验证。旧格式、损坏、不可读或identity不匹配的记录不参与列表和路由，也不阻断其他合法Registry v3实例；存在时`instances list`和`instances prune`增加`invalidRecordCount`。CLI不会兼容解析、转换、移动或删除这些记录，`doctor`以warn报告合法和无效数量。显式选择无效记录对应的instanceId仍严格失败；应更新或重启该项目使用的匹配Unity Package，而不是绕过校验。
+实例目录按文件独立验证。旧格式、损坏、不可读或identity不匹配的记录不参与列表和路由，也不阻断其他合法Registry v3实例；`instances list`存在这类文件时返回`invalidRecordCount`。当前项目的Unity在启动或重载完成后会使用当前进程和连接重建自己的记录；CLI在能够证明目标Unity正在运行时等待该结果。不要兼容解析、转换、移动或手工删除内部记录。
 
 实例状态：
 
@@ -32,7 +32,7 @@ unitycli instances prune
 | `offline` | 该项目没有已证明存活的Editor session |
 | `conflict` | 至少两个已验证live process claim同属该project identity |
 
-`instances prune` 不直接删除进程、无效记录或伪造状态；PID/start-time 无效 claim 和过期 offline record 只由 Unity Bridge registry writer 清理。`invalidRecordCount`只报告本次被隔离的文件数量。
+`instances prune --instance <id|projectPath|alias>`只授权选定的当前Unity执行有界历史清理，CLI本身不删除记录。Unity保留当前、存活、无法确认、链接或被占用的记录；关闭记录最多保留最近100个，损坏记录最多保留最近20个，30天前的记录优先清理。每次最多检查2000个、删除20个。结果中的`removed`、`remaining`、`deferred`、`scanned`和`truncated`描述本次真实结果；`deferred>0`时可在当前清理完成后再次调用。
 
 不要读取 registry 文件、listener ID、端口或 URL，也不要直接调用 Bridge HTTP。transport binding 是 session supervisor 的内部职责。
 
@@ -44,6 +44,8 @@ Tool discovery、describe、`tools run`与`command`使用同一严格选择规
 2. 未传 selector 时，从 CWD 向上寻找最近的 Unity project root，并解析其 canonical identity。
 3. 无法得到唯一项目身份时返回结构化 instance error。
 
+目标项目已有唯一Unity进程但尚未发布记录、正在编译/导入/重载或正在更换连接时，CLI会在原命令截止时间内等待；Unity没有运行时不会进行无意义的完整等待。完整instance ID无法反推出项目路径，因此显式ID会直接等待其固定记录直到截止时间。
+
 不存在按PID、短hash、单个存活Editor或任意健康实例自动选取的路径。只有至少两个已验证live process claim才返回`E_INSTANCE_CONFLICT`；权限失败、超时或PID/start/project identity无法证明时返回`E_INSTANCE_UNVERIFIABLE`。选定项目已证明无运行进程时返回`E_INSTANCE_NOT_RUNNING`。
 
 ```powershell
@@ -70,7 +72,7 @@ alias 绑定完整 `instanceId`、canonical project path 和 canonicalization ve
 
 - 每个Editor或Development Player session独立维护默认5/3高低水位，不跨进程共享计数；
 - 对一次transport尝试绑定listener generation；
-- 在compile、import、domain reload或listener restart后重新验证generation，但不刷新execution deadline；
+- 首次记录尚未出现或在compile、import、domain reload、listener restart期间，等待当前ready generation，但不刷新execution deadline；
 - 同一次mutation调用只在`editorSessionId`未改变时，使用完全相同的root request ID与request bytes续接durable canonical terminal；
 - 首次mutation POST后若`editorSessionId`改变，禁止向新session再次POST，返回`E_EXECUTION_TIMEOUT`与outcome unknown；
 - 准入deadline到达返回effect-before `E_UNITY_BUSY`并证明业务请求未发送；

package/docs/tool-discovery.md

@@ -17,7 +17,7 @@ unitycli tools group --instance <id|projectPath|alias>
 
 ```text
 tools group
-    -> tools group list <group>
+    -> tools group list <group> [--page-size <n>] [--cursor <n>]
     -> tools describe <tool>
     -> tools run <tool> --input '<json>'
 ```
@@ -35,24 +35,26 @@ unitycli tools group --instance my-project
 
 ### `tools group list`
 
-列出一个真实分组中的全部 Tool 摘要：
+按名称稳定排序并返回一个真实分组中的 Tool 摘要页。默认 `pageSize=20`，最大 100：
 
 ```powershell
-unitycli tools group list camera
-unitycli tools group list probuilder --instance my-project
+unitycli tools group list camera --page-size 20
+unitycli tools group list probuilder --page-size 20 --cursor 20 --instance my-project
 ```
 
-分组名称必须来自当前实例的`tools group`输出，不要假设项目能力都位于`custom`分组。`tools group list`返回`nameSemantics.exact=true`与`groupPrefix=false`：每个`tools[].name`已经是完整精确调用名，group只用于筛选，绝不能拼到name前。
+分组名称必须来自当前实例的`tools group`输出，不要假设项目能力都位于`custom`分组。每个`tools[].name`已经是完整精确调用名，group只用于筛选，绝不能拼到name前；`available`仅在不可用时以`false`出现。存在`pageInfo.nextCursor`时，将其原值传回`--cursor`继续读取。
 
 ### `tools search`
 
-按名称、summary、description 和 group 搜索当前实例完整目录：
+按名称、summary、description 和 group 搜索当前实例完整目录，并只返回名称、summary、group组成的有界页。默认 `pageSize=20`，最大 100：
 
 ```powershell
-unitycli tools search 'screenshot|camera'
-unitycli tools search 'project-summary|scene' --instance my-project
+unitycli tools search 'screenshot|camera' --page-size 20
+unitycli tools search 'project-summary|scene' --page-size 20 --cursor 20 --instance my-project
 ```
 
+结果按精确 Tool name 排序；存在`pageInfo.nextCursor`时，将其原值传回同一关键词查询的`--cursor`。
+
 ### `tools describe`
 
 执行前读取单个 Tool 的完整 descriptor：
@@ -74,7 +76,7 @@ unitycli tools describe camera.screenshot
 | `requiresPackages` | 非空 Unity Package 依赖 |
 | `examples` | `description`、结构化业务 `input` 与按需 `execution` |
 
-`group`、`summary` 和 `source` 已在发现层使用，不在单 Tool describe 重复；`outputSchema`、`permissions`、fingerprint、completion 和 handler 只保留在内部 metadata。
+`group`和`summary`已在发现层使用，不在单 Tool describe重复；`source`、`outputSchema`、`permissions`、fingerprint、completion 和 handler 只保留在内部 metadata。
 
 ## 完整目录语义
 
@@ -86,7 +88,7 @@ unitycli tools describe camera.screenshot
 
 1. 用 `instances list` 确认 canonical project identity，或切换到目标 Unity 项目 CWD。
 2. 用 `tools group` 读取当前实例目录。
-3. 用 `tools group list`、`tools search '<k1|k2|...>'` 缩小范围。
+3. 用 `tools group list`、`tools search '<k1|k2|...>'` 缩小范围，并消费完所需的`pageInfo.nextCursor`页面。
 4. 用 `tools describe` 获取 schema、状态约束、副作用和示例。
 5. 用 `tools run` 调用同一名称。
 6. 安装 Package、安装 Extension、domain reload 或切换 PlayMode 后重新 discovery。

package/docs/tool-execution.md

@@ -58,7 +58,7 @@ unitycli tools run camera.screenshot --input '{}'
 
 ## Bridge 执行约束
 
-Bridge-backed Tool由Unity Editor主线程执行。准入放行后，session supervisor只创建一次execution absolute deadline，并在该deadline内处理compile、import、domain reload和listener generation交接；token重取、status、rebind和terminal recovery不得刷新预算。读取可在新generation重新执行完整读取；mutation只有在`editorSessionId`未改变时才可用完全相同的request bytes续接durable terminal。
+Bridge-backed Tool由Unity Editor主线程执行。业务请求发送前，session supervisor会在准入deadline内等待首次ready记录、compile、import、domain reload和listener generation交接；只有能证明目标Unity正在运行时才等待，证明未运行时立即返回。准入放行后只创建一次execution absolute deadline，token重取、status、rebind和terminal recovery不得刷新预算。读取可在新generation重新执行完整读取；mutation只有在`editorSessionId`未改变时才可用完全相同的request bytes续接durable terminal。
 
 首次mutation POST后若Editor session改变，CLI禁止向新session再次POST，并返回`E_EXECUTION_TIMEOUT`、`outcome:unknown`。其他超时或终态前断连同样表示没有可信终态；调用方应先用业务读取或`editor.state`收集证据，再决定是否提交全新请求。`editor.state`使用frozen本地descriptor绕过被阻断的Live catalog，再读取Registry/Health v3、内存主线程pulse、Bridge和Windows modal证据；两个dialog recovery Tool保持同一例外，其他Tool不建立静态fallback。
 
@@ -96,7 +96,8 @@ unitycli tools run asset.delete --input '{"path":"Assets/Temp.mat"}'
 
 通用规则：
 
-- 列表/层级工具优先传 `pageSize`、`cursor`、`parent`、`query`、`componentType` 或 `className`。继续读取时将输出里的 `pageInfo.nextCursor` 原值传回 `cursor`；两者保持相同 JSON 类型。`hasMore`、`truncated` 或 `childrenTruncated` 表示还有更深或更多内容。
+- discovery 的 `tools group list`、`tools search` 和省略name的`command`列表默认每页20项、最大100项；继续读取时将`pageInfo.nextCursor`原值传回CLI `--cursor`。
+- 业务列表/层级工具优先传 JSON `pageSize`、`cursor`、`parent`、`query`、`componentType` 或 `className`。继续读取时将输出里的 `pageInfo.nextCursor` 原值传回 `cursor`；两者保持相同 JSON 类型。`hasMore`、`truncated` 或 `childrenTruncated` 表示还有更深或更多内容。
 - 深度序列化工具（`object.get-data`、`asset.get-data`、`component.get`）优先传 `paths` 或 `viewQuery`，并保持 `maxDepth` 较低。数组、列表和字典受 `maxArrayItems` 限制；输出里的 `totalCount`、`returnedCount`、`truncated`、`nextPath` 用于判断是否需要继续按路径读取。CLR 的 `NaN`、正无穷和负无穷无法作为 JSON number，会在 AnyJson 值节点中分别表示为字符串 `"NaN"`、`"Infinity"`、`"-Infinity"`。
 - 文本源码工具（如 `shader.read`）使用 `offset` 和 `maxBytes` 分段读取。输出 `truncated=true` 时，下一次把 `nextOffset` 作为新的 `offset`。
 - 截图和相机工具默认返回 artifact 路径。只有确实需要内联图片时才传 `inlineBase64:true`；图片超过 Bridge 内联上限时会省略 `imageBase64` 并返回 warning，继续使用 artifact 路径。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpsckr/unitycli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Windows-first CLI for UnityCLI automation.",
   "type": "module",
   "bin": {
@@ -20,8 +20,9 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "generate:extensions": "node scripts/gen-extension-projections.mjs",
     "generate:registries": "node scripts/gen-ts-registries.mjs && node scripts/gen-tool-completion-registry.mjs",
-    "build": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.json",
-    "build:test": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/copy-test-resources.cjs && tsc -p tsconfig.json",
+    "generate:package-files": "node scripts/gen-package-files.mjs",
+    "build": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && npm run generate:package-files && npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && tsc -p tsconfig.json",
+    "build:test": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && npm run generate:package-files && npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && tsc -p tsconfig.test.json && node scripts/copy-test-resources.cjs && tsc -p tsconfig.json",
     "test": "node --test \"dist/tests/**/*.test.js\"",
     "pretest": "npm run build:test",
     "prepack": "npm run build",
@@ -29,7 +30,12 @@
     "architecture:audit": "node scripts/audit-final-architecture.mjs",
     "static-catalog:audit": "node scripts/audit-static-capability-catalog.mjs",
     "static-catalog:capture": "node scripts/capture-static-capability-catalog.mjs",
-    "architecture:validate": "node scripts/audit-final-architecture.mjs --strict && node scripts/audit-tool-completion-contract.mjs --strict && node scripts/audit-static-capability-catalog.mjs",
+    "architecture:validate": "npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && node scripts/audit-final-architecture.mjs --strict && node scripts/audit-tool-completion-contract.mjs --strict && node scripts/audit-static-capability-catalog.mjs",
+    "init-contract:validate": "node scripts/audit-init-contract.mjs",
+    "instances-contract:validate": "node scripts/audit-instances-contract.mjs",
+    "instances-live:validate": "node scripts/validation/validate-instance-concurrent-readers.mjs && node scripts/validation/validate-instance-dual-writer.mjs && node scripts/validation/validate-instance-multi-cli.mjs && node scripts/validation/validate-instance-multi-prune.mjs",
+    "package-files:validate": "node scripts/audit-package-files.mjs",
+    "package-closure:validate": "node scripts/audit-package-assembly-closure.mjs && npm run package-files:validate",
     "completion:audit": "node scripts/audit-tool-completion-contract.mjs --strict",
     "matrix:live": "node scripts/run-final-live-matrix.mjs",
     "test:matrix-runner": "node --test scripts/run-final-live-matrix.test.mjs",