@mokuyoaxis/dsh-iris 0.1.2 → 0.1.4

package/.dsh/skills/iris-compose-media/SKILL.md

@@ -45,61 +45,35 @@ An attachment returned by `iris_draw_image` can be passed as `first_frame_attach
 
 ## Choose a workflow
 
-### Analyze an image, then draw
+Choose the minimum chain, then read only the matching section of [references/workflows.md](references/workflows.md):
 
-1. Inspect the source with `iris_look_at_image` or `iris_relook_attachment`. Ask specifically about the subject, composition, palette, style, visible text, and the transformation requested by the user.
-2. Convert the observations into a self-contained generation prompt. Separate facts visible in the source from requested changes; preserve explicit constraints and exact text.
-3. Call `iris_draw_image` once for each requested artifact.
-4. If the user requested verification or iteration, inspect the generated attachment with `iris_relook_attachment` against the original requirements. Regenerate only for a concrete mismatch.
+- inspect an image, then draw: `iris_look_at_image` or `iris_relook_attachment` → `iris_draw_image`;
+- generate/reuse a still, then animate: optional `iris_draw_image` → `iris_generate_video`;
+- summarize a video, then narrate: `iris_media_summarize` → `iris_speak_text`;
+- create an S2V talking video: resolve a first frame and audio → `iris_generate_video`;
+- recognize, then create: `iris_long_ocr` or `iris_transcribe_audio` → the requested creation tool.
 
-### Generate a still, then animate it
-
-1. Create the still with `iris_draw_image`, reuse an Iris-produced first-frame attachment, or obtain a host-visible absolute path for the supplied image. Do not pass an ordinary session attachment as `first_frame_attachment_id`.
-2. Write a motion prompt describing camera movement, subject motion, timing, and what must remain stable. Do not merely repeat the still-image prompt.
-3. Call `iris_generate_video` with `first_frame_attachment_id` or `first_frame_path` for i2v. Use `size` and `duration` only when appropriate for the selected t2v/i2v model.
-4. If the call returns a background task ID, use `iris_task_status` before claiming that the video exists.
-
-### Summarize a video, then narrate it
-
-1. Call `iris_media_summarize` with the user's question and `transcribe=true` unless they want a visual-only summary.
-2. Do not also call `iris_video_frames` or `iris_transcribe_audio` by default: `iris_media_summarize` already samples frames and optionally transcribes the audio track.
-3. Turn the summary into narration suited to the requested audience and length. Do not present inferred details as visible facts.
-4. Call `iris_speak_text` and return the summary, contact-sheet attachment, and saved audio path.
-
-Use `iris_video_frames` separately only when the user explicitly needs individual frames or a custom frame-level workflow. Use `iris_transcribe_audio` separately when the full transcript itself is required or when the input is an audio file rather than a video-summary task.
-
-### Create an S2V talking video
-
-1. Resolve or generate a suitable first-frame portrait.
-2. Use an existing host audio file, or call `iris_speak_text` and capture its saved absolute path.
-3. Confirm that the audio is a clear human voice in WAV or MP3 format, smaller than 15 MB, and shorter than 20 seconds. Shorten the script and synthesize it again if the generated speech exceeds the limit.
-4. Call `iris_generate_video` with an S2V model, `first_frame_attachment_id` or `first_frame_path`, `audio_path`, and `resolution` of `480P` or `720P`. Do not pass t2v/i2v-only `size` or `duration` controls.
-5. Track a background result with `iris_task_status`; do not submit a duplicate while it is running.
-
-### Turn recognized content into a new artifact
-
-Use `iris_long_ocr` for image text or `iris_transcribe_audio` for audio speech, then structure the recognized content for the requested output. Feed only the necessary, checked facts into `iris_draw_image`, `iris_speak_text`, or `iris_generate_video`. Preserve names, numbers, and quoted wording exactly when accuracy matters.
+Use `iris_video_frames` only for explicit frame extraction or a custom frame-level workflow. Do not load every workflow section when one route is sufficient.
 
 ## Control cost and iteration
 
-- Make one generation attempt per requested artifact by default.
-- A request to create an artifact authorizes that requested generation; do not ask again solely because it may incur provider cost.
-- Run at most 2 generation attempts per artifact unless the user explicitly requests a larger iterative loop.
-- Review does not automatically authorize regeneration. If the user asked only for one result, report a detected mismatch and offer the next step.
-- Do not probe models or create speculative alternatives as part of the workflow.
-- Honor an explicit `providerId::modelId` override. Otherwise use the configured capability assignment and its ordered failover list.
+- Create one new Iris generation **Task** per requested artifact by default. A Provider Attempt is an internal candidate submission inside that Task; do not count failover attempts as user-authorized new Tasks.
+- The original request authorizes its requested artifact. Review alone does not authorize regeneration.
+- Create at most 2 new generation Tasks per artifact, and only when the first Task has a known terminal outcome and the user explicitly requested iteration. Respect a lower or higher bound stated by the user.
+- Do not probe models or create speculative alternatives. Honor an explicit `providerId::modelId`; otherwise use Iris capability assignment and bounded failover.
+- Automatic failover is allowed only while the current Provider Attempt has `acceptance=not_accepted`. Accepted, acceptance-unknown, or outcome-unknown work must never trigger another Provider Attempt or Task automatically.
 
-Iris generation failover covers upload, submission, and synchronous-generation failures only. Once a remote service accepts an asynchronous task, that task is bound to its provider. If polling, waiting, or download later fails, query `iris_task_status` and report the state; never resubmit automatically, because that can duplicate work and billing.
+## Handle Task v2, cancellation, and failures
 
-## Handle tasks, cancellation, and failures
+When a generation tool returns a Task, or the user asks to retry, recover, cancel, or deliver one, read [references/task-v2-recovery.md](references/task-v2-recovery.md). Its stop rules are mandatory.
 
-- Continue immediately when a tool returns a completed attachment, text, or local path.
-- When a tool reports a background task, wait or query with `iris_task_status` only when the next step depends on its output.
-- If the user cancels, stop the chain. Do not launch downstream generation after cancellation, even if an earlier artifact later completes.
-- If an attachment cannot be found, ask the user to re-upload it or provide a host path.
-- If `ffmpeg` or `ffprobe` is unavailable, video frames and video summarization cannot run. Explain the missing optional dependency; do not claim that visual video analysis completed.
-- If vision is unavailable but the user's creation prompt is already complete, skip source analysis and proceed only when that still satisfies the request.
-- Preserve partial outputs. Report which step succeeded, which step failed, and whether any accepted task remains active.
+- Continue immediately only from a completed attachment, text, or local path.
+- Use `iris_task_status` to observe an existing background Task when a dependent next step needs the result. Never describe queued/running work as complete.
+- Observation failure resumes observation; delivery failure resumes delivery. Neither authorizes regeneration. If that recovery action is available only in the Iris workbench, say so and preserve the Task ID.
+- If the user cancels, stop the chain and do not launch downstream generation. Cancellation requested or unknown is not proof that no provider work occurred.
+- Preserve partial outputs. Report which step succeeded, which failed or became uncertain, and whether accepted work may remain active.
+- If an attachment is missing, request a re-upload or host path. If `ffmpeg`/`ffprobe` is unavailable, explain that frame extraction and video summarization cannot run.
+- If vision is unavailable but the creation prompt is complete, skip source analysis only when the requested result still remains valid.
 
 ## Report the result
 
@@ -109,6 +83,6 @@ Return a compact workflow record containing:
 2. attachment IDs and host paths needed to use the outputs;
 3. task IDs and their last known status;
 4. any omitted or failed step and its effect on the final artifact;
-5. whether further generation would require another attempt.
+5. whether further generation would create another potentially billable Task.
 
-Never describe a queued or running task as complete. Never hide that a summary omitted audio, that a review was skipped, or that the final artifact differs from the request.
+Never hide that a summary omitted audio, that a review was skipped, or that the final artifact differs from the request.

package/.dsh/skills/iris-compose-media/references/task-v2-recovery.md

@@ -0,0 +1,30 @@
+# Iris Task v2 recovery
+
+Read this reference only after a generation tool has returned a Task, or when the user asks about retrying, cancelling, recovering, or delivering an existing Task.
+
+## Keep the identities separate
+
+- A **Task** represents one user-authorized artifact request.
+- A **Provider Attempt** is an internal candidate submission inside that Task.
+- Automatic failover may create another Provider Attempt only while acceptance is explicitly `not_accepted`; it does not authorize a new Task.
+- A new Task is a new potentially billable user operation. Create it only for the original requested artifact or after explicit, informed retry/iteration approval.
+
+## Decide from facts
+
+| Observed fact | Agent action | Forbidden action |
+|---|---|---|
+| `acceptance=not_accepted` | Let Iris continue its bounded provider failover inside the same Task | Creating a replacement Task merely to imitate failover |
+| accepted or `acceptance=unknown` | Preserve the Task ID and stop new generation | Resubmitting to another provider/model |
+| queued/running | Observe the existing Task only when the next step depends on it | Claiming the artifact exists or starting a duplicate |
+| `watching_paused` / observation failure | Tell the user to resume/re-observe the same Task in the Iris workbench | Starting generation again |
+| succeeded but delivery unavailable | Tell the user to retry delivery for the same Task in the Iris workbench | Regenerating the media |
+| `needs_attention` / outcome unknown | Report the known facts and request human review | Guessing failure, success, or billing outcome |
+| cancellation requested/unknown | Stop downstream work and preserve the Task ID | Treating cancellation as proof that the provider did no work |
+| terminal failure with known non-acceptance | Report failure and the exhausted attempts | Silently starting a new Task |
+| terminal result reviewed and user explicitly requests another version | Create at most one additional Task unless the user sets a larger bound | Treating review itself as approval to regenerate |
+
+`iris_task_status` observes the existing Task. If an action is not exposed as an Iris Agent tool, direct the user to the existing Task in the Iris workbench; never simulate recovery by calling a generation tool again.
+
+## Report uncertainty
+
+Always include the Task ID, last observed state, acceptance/outcome knowledge, whether a remote operation may still be active, and the exact safe next action. Do not collapse “could not observe” into “generation failed.”

package/.dsh/skills/iris-compose-media/references/workflows.md

@@ -0,0 +1,38 @@
+# Iris composition workflow details
+
+Read only the section matching the chosen workflow. Keep paid steps bounded by the main Skill and Task v2 recovery rules.
+
+## Inspect, then draw
+
+1. Inspect the source with `iris_look_at_image` or `iris_relook_attachment`. Ask about subject, composition, palette, style, visible text, and the requested transformation.
+2. Turn observations into a self-contained prompt. Separate visible facts from requested changes and preserve exact text.
+3. Call `iris_draw_image` once for each requested artifact.
+4. Inspect the result only when verification or iteration was requested. A mismatch is evidence to report, not automatic permission to regenerate.
+
+## Generate or reuse a still, then animate
+
+1. Create a still with `iris_draw_image`, reuse an Iris-produced first-frame attachment, or obtain a host-visible path. Do not pass an ordinary session attachment as `first_frame_attachment_id`.
+2. Write a motion prompt that covers camera movement, subject motion, timing, and invariants.
+3. Call `iris_generate_video` with `first_frame_attachment_id` or `first_frame_path`. Use only controls supported by the selected t2v/i2v model.
+4. Observe a returned Task before claiming that the video exists.
+
+## Summarize a video, then narrate
+
+1. Call `iris_media_summarize` with `transcribe=true` unless the user wants visual-only analysis.
+2. Do not also call `iris_video_frames` or `iris_transcribe_audio` by default; the summary action already samples frames and can transcribe audio.
+3. Write narration for the requested audience and length without presenting inference as visible fact.
+4. Call `iris_speak_text`; return the summary, contact-sheet attachment, and saved audio path.
+
+Use `iris_video_frames` separately only for individual frames or a custom frame workflow. Use `iris_transcribe_audio` separately for a full transcript or an audio-only input.
+
+## Create an S2V talking video
+
+1. Resolve or generate a suitable first-frame portrait.
+2. Use existing host audio or call `iris_speak_text` and keep its absolute output path.
+3. Confirm that the audio is a clear human voice in WAV/MP3, smaller than 15 MB, and shorter than 20 seconds.
+4. Call `iris_generate_video` with an S2V model, first-frame input, `audio_path`, and `480P` or `720P`. Do not pass t2v/i2v-only `size` or `duration` controls.
+5. Observe the returned Task; do not submit a duplicate while it is running.
+
+## Turn recognized content into a new artifact
+
+Use `iris_long_ocr` for exact image text or `iris_transcribe_audio` for speech, then pass only necessary checked facts into the selected generation tool. Preserve names, numbers, and quoted wording when accuracy matters.

package/.dsh/skills/iris-verify-ui/SKILL.md

@@ -96,32 +96,10 @@ After each modification:
 
 Run at most 3 modify-and-recheck rounds by default. Stop as soon as the user's criteria pass. Also stop when one round gives no improvement, capture conditions cannot be aligned, or remaining differences come from the environment. Explain the stopping reason instead of looping indefinitely.
 
-## Assign a verdict
+## Assign a verdict and degrade safely
 
-Use exactly one verdict:
-
-- **Pass**: all objective requirements are satisfied and the evidence supports the conclusion.
-- **Partial pass**: the primary goal is satisfied, but localized differences or environment noise remain.
-- **Indeterminate**: a reference is missing, capture conditions differ, a required tool is unavailable, or evidence is insufficient.
-
-For a “pixel-identical” claim, require matching dimensions and matching render conditions. When the longest side exceeds 1024 pixels, `iris_pixel_diff` downsizes the comparison and cannot by itself prove original-resolution identity.
-
-## Degrade safely
-
-- `dsh-builtin-browser` unavailable: ask for a current screenshot and continue with image comparison.
-- Vision model unavailable: skip semantic inspection and model location; continue with known coordinates, crops, and pixel diff.
-- `iris_locate` unstable: narrow the target using the heatmap and known layout; do not retry blindly.
-- HTML depends on scripts or remote resources: create a static offline-renderable version, or use the project's existing screenshot workflow.
-- Reference contains dynamic data: freeze or mask dynamic regions. If that is impossible, report them separately as noise.
+Read [references/verdict-and-degradation.md](references/verdict-and-degradation.md) when assigning the final verdict or when Browser, vision, location, offline HTML, or comparable capture conditions are unavailable. Use exactly **Pass**, **Partial pass**, or **Indeterminate**, and apply the reference's evidence limits.
 
 ## Report the result
 
-Include:
-
-1. Conditions: inputs, dimensions, theme, capture method, and known noise sources.
-2. Changes: what changed and why.
-3. Evidence: before-and-after diff, worst regions, key bounding boxes, and relevant attachments.
-4. Verdict: Pass, Partial pass, or Indeterminate.
-5. Remaining work: anything requiring human judgment or a real-browser check.
-
-Do not finish with only “looks correct.” Do not report precision that the evidence cannot support.
+Use the five-field report in [references/verdict-and-degradation.md](references/verdict-and-degradation.md). Keep conditions, changes, evidence, one verdict, and remaining work distinct. Do not finish with only “looks correct” or report precision the evidence cannot support.

package/.dsh/skills/iris-verify-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Iris Verify UI"
+  short_description: "Verify UI changes with visual evidence"
+  default_prompt: "Use $iris-verify-ui to compare the supplied UI with its reference and return a bounded evidence-based verdict."

package/.dsh/skills/iris-verify-ui/references/verdict-and-degradation.md

@@ -0,0 +1,31 @@
+# Iris UI verification verdict and degradation
+
+Read this reference when preparing the final verdict or when a required verification capability is unavailable.
+
+## Verdict template
+
+Use exactly one verdict:
+
+- **Pass**: all objective requirements are satisfied and comparable evidence supports the conclusion.
+- **Partial pass**: the primary goal is satisfied, but localized differences or environmental noise remain.
+- **Indeterminate**: a reference is missing, capture conditions differ, a required tool is unavailable, or evidence is insufficient.
+
+Report:
+
+1. Conditions: inputs, dimensions, theme, capture method, and known noise.
+2. Changes: what changed and why, if edits were authorized.
+3. Evidence: before/after diff, worst regions, bounding boxes, and attachments.
+4. Verdict: one value from the list above.
+5. Remaining work: human judgment or real-browser checks still needed.
+
+For “pixel-identical,” require matching dimensions and render conditions. A normalized diff whose longest side was reduced to 1024 pixels cannot prove original-resolution identity.
+
+## Safe degradation
+
+- Browser unavailable: request a current screenshot and continue with supplied images.
+- Vision unavailable: skip semantic inspection and model location; use known coordinates, crops, and pixel diff.
+- `iris_locate` unstable: narrow the target from the heatmap and known layout; do not retry blindly or invent coordinates.
+- HTML needs scripts or remote resources: use an offline-renderable static version or the project’s existing real-browser capture workflow.
+- Dynamic reference data cannot be frozen: isolate or report it as noise; otherwise use **Indeterminate**.
+
+Never finish with only “looks correct,” and never report precision unsupported by the available evidence.

package/CHANGELOG.md

@@ -4,7 +4,60 @@
 
 ## [Unreleased]
 
-当前没有尚未发布的用户可见变更。
+## [0.1.4] - 2026-09-10
+
+### Added
+
+- 冻结 Host Adapter v0 的命名端口、能力快照、缺能力错误和 Command × Host Port 矩阵，并加入零网络纯契约测试。
+- 深化两项随包 Skill：增加显式用户/模型调用策略、DSH `/name` 示例、渐进参考资料和 10 条零费用行为契约。
+- 增加 test-only Local Host fixture：在无 DSH、无网络下运行确定性图片动作、Task 查询与提醒确认，并固定缺 Host Port 和未迁移动作的错误边界。
+- 增加 DSH Host Adapter：集中探测并映射工具、路由、附件、会话、Browser、文本/视觉模型、Skill 和客户端 Slot 九类能力，区分能力缺失与接口不兼容。
+- 增加 Provider Adapter v0 完整生命周期与零网络 conformance runner；DashScope/OpenAI Images 的发现、提交、轮询、下载和错误映射统一声明，未验证的取消能力显式标为 unsupported。
+- 增加零网络 Host Doctor 与工作台诊断卡：从安全能力快照、成功注册账本和受限浏览器握手检查 DSH 版本、插件、14 个工具、2 项 Skill、4 组路由、可选 Host 能力及 4 个 UI Slot；不调用 Browser、模型或 Provider。
+- 增加 Provider × Model × Capability 持久健康证据与四色 UI：灰色未配置、蓝色待验证、绿色 7 天内成功、暗红色明确认证/权限失败；真实任务与显式实测共用证据，记录脱敏来源和时间且不做后台探测。
+- 增加独立作品库 v0：新产物自动入库，升级时接回已有 `outputs/`，支持分页浏览、重新索引和独立删除；清任务历史后工作台与泡泡仍能访问作品。
+
+### Changed
+
+- 将公开路线图切换到 0.1.4：聚焦 Host/Provider 适配边界、Host Doctor、现有两项 Skill 的 Agent 易用性深化与最小作品库；不在本版扩充 Provider、完整 Artifact Manifest 或 standalone 范围。
+- 将动作、工作台 API、提示词优化、视觉后端和注册生命周期改为消费 Host Port；非空原始 DSH `ctx` 不能再作为 Command 输入。HTML Browser 渲染同时补齐 `AbortSignal` 取消与清理边界。
+- 将图片、视频、转写、TTS、模型发现、能力实测、任务恢复和重新交付的供应商生命周期调用收口到 Provider Adapter；canonical `unknown` 与 `canceled` 分别保持未知事实和远端确认取消，禁止退化为普通失败。
+- 健康状态按当前 failover 候选保守汇总：任一近期成功即绿色，有待验证路径即蓝色，只有全部候选明确认证失败才为暗红；429、网络、5xx、内容安全、取消和未知受理不覆盖近期成功。汇总时间只取决定当前颜色的候选证据；模型或能力移除会裁掉旧绿灯，空成功说明不再误写为失败文案。
+- 收紧手机端泡泡面板的真实视口宽高与四边约束，补充 `pointercancel` 位置持久化，并加入实际执行工作台、进度条和泡泡组件树的运行级回归测试。
+- 分离任务历史与作品生命周期：清历史只移除任务事实和 Prompt；删除单件作品、清空作品库与删除孤儿文件分别确认。作品最小索引不保存 Provider、Model 或任务关系。
+- 将 DSH 支持窗口从单一 `>=0.1.2-rc.1 <0.1.3-0` 扩展为同时声明已实测的 `0.1.5-rc.1`；Host Doctor、README、用户指南、公开路线图与市场声明同步，其余预览版继续保持不宣称兼容。
+
+## [0.1.3] - 2026-09-08
+
+### Added
+
+- 新增公开的 Task/Attempt v2 语义契约，以及零网络纯函数真值表；冻结受理、自动 failover、观察、取消、产物交付、旧状态兼容和移动端用户状态的不可违反规则。
+
+- 新增最小 Provider 提交契约、脱敏错误分类、写前持久化 Hook、零网络 Fake Provider 和旧任务纯规范化器；普通提交异常默认归为受理未知，只有明确 `not_accepted` 才能自动切换候选。
+
+- 新增 Task v2 复制落盘与单调 revision 原语，并覆盖图片、视频、转写和 TTS：一次用户请求只创建一个 Task，每次候选在 HTTP 请求前写入 Attempt；视频和转写进一步区分上传与提交 stage。明确 4xx 拒绝才允许 failover，5xx、网络异常及缺失必要响应会以受理未知停止。
+
+- 新增图片故障注入测试，覆盖 429 后异步/同步混合候选安全切换、500/网络失败/缺远端 ID 后零重复提交、API Key 不落任务文件、同步与异步生成成功后交付失败不重新生成、未知取消及提交中断恢复。
+
+- 图片、视频、转写和 TTS Agent 工具开始读取 v2 事实轴：交付失败会明确表述为“生成成功但交付失败”，受理或结果未知会停止等待并要求人工确认。
+
+- 新增 Task v2 运行时故障矩阵，覆盖盯守超时、连续轮询异常、远端明确失败、重启恢复、供应商缺失、交付中断、SSE 慢消费者和人工接管；全部使用本地 Fake/fixture，不发送计费请求。
+
+- 新增无需安装或启动 DSH 的离线 `doctor()`、`dsh-iris doctor` CLI 与 `--json` 输出；检查运行时、依赖、私有存储、配置、模型、任务、临时文件和产物，使用稳定的 0/1/2 退出码。
+
+- 新增公开架构、安全边界和故障注入矩阵文档。
+
+### Changed
+
+- 将 v0.1.3 聚焦为“防重复计费与事实可信”：离线 Doctor v0 与最薄 CLI 保留在本版，完整 Host Adapter、Provider conformance 和依赖 DSH 运行时的 Doctor 扩展顺延到 0.1.4。
+
+- 工作台、泡泡和任务详情开始消费 v2 派生用户态：排队/运行仍属于活动任务，观察暂停、受理或结果未知、生成成功但交付失败进入独立“需要处理”分区；旧任务继续按原四态显示。
+
+- 状态快照新增进程 epoch 与单调 revision，客户端拒绝迟到快照；SSE 对慢消费者只保留最新待发状态。
+
+- 任务详情新增重新观察、重新交付与知情重试：前两者禁止新生成提交；知情重试必须确认可能重复计费，并用新旧 Task 关系保留审计线索。
+
+- 待处理任务新增“标为已读/恢复提醒”；知情重试创建新任务后自动归档原提醒并展示关联，避免同一异常重复占用泡泡角标。只有明确的 Task v1 才显示“旧任务 · 只读”，热更新字段缺失不再误标新任务。
 
 ## [0.1.2] - 2026-09-06
 
@@ -118,7 +171,9 @@
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/mokuyoaxis/dsh-iris/releases/tag/v0.1.0

package/README.en.md

@@ -54,7 +54,7 @@ Early versions read models and credentials from the maintainer's local ai-paint
 
 ## Quickest start
 
-With DeepSeek Harness `0.1.2-rc.1` installed and `pnpm` on your PATH, add Iris to the Web profile:
+With a supported DeepSeek Harness (`>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1`) installed and `pnpm` on your PATH, add Iris to the Web profile:
 
 ```bash
 dsh plugin --profile web add @mokuyoaxis/dsh-iris
@@ -86,6 +86,7 @@ DSH profiles and plugin commands follow the [official installation docs](https:/
 - Visual question answering, long-image OCR, target grounding, cropping, and pixel-diff analysis
 - Video frame extraction and multimodal video summarization
 - Asynchronous task tracking, restart recovery, and token-authorized media playback
+- An independent work library that survives task-history cleanup and can re-index older `outputs/`
 - A multi-provider model pool with per `provider + model` capability assignment
 - Three file sources: browser upload, session attachments, and host paths
 - Workbench-independent composer prompt optimization with current-session and JSON-configured fixed model routing
@@ -103,9 +104,9 @@ After installing the plugin, add a provider in the Iris workbench and assign mod
 
 dsh-iris ships as a native DSH plugin with a server side and a web client. The server registers 14 agent tools and reuses the host's tool, routing, and lifecycle services; the client hooks into the settings page, the conversation input area, and the global floating layer through DSH's module loader. The plugin never starts a separate service or listens on an extra port.
 
-Automated tests currently cover plugin loading, tool registration, client seats, and routing behavior. Version 0.1.1 completed host smoke tests on Linux ARM64 — in both a clean and a real web profile — against DSH `0.1.2-rc.1` on Node.js `22.23.2`: the browser startup graph, the full combined bundle, the Iris client factory, and the three UI seats present at that time were verified. The fourth prompt-optimizer seat added in 0.1.2 has now been rendered in a live Android browser; configuration loading, a real session-model optimization with thinking actually `off`, preview write-back, independent disabling and re-enabling, and the loop from a short draft to a succeeded image-generation task are verified. Browser-side cancellation and JSON operations have automated HTTP/configuration coverage; a step-by-step live-device record is still pending. Iris itself keeps Node.js `>=20.10` as its own floor.
+Automated tests currently cover plugin loading, tool registration, client seats, and routing behavior. Version 0.1.1 completed host smoke tests on Linux ARM64 — in both a clean and a real web profile — against DSH `0.1.2-rc.1` on Node.js `22.23.2`: the browser startup graph, the full combined bundle, the Iris client factory, and the three UI seats present at that time were verified. The fourth prompt-optimizer seat added in 0.1.2 has now been rendered in a live Android browser; configuration loading, a real session-model optimization with thinking actually `off`, preview write-back, independent disabling and re-enabling, and the loop from a short draft to a succeeded image-generation task are verified. Browser-side cancellation and JSON operations have automated HTTP/configuration coverage; a step-by-step live-device record is still pending. Iris itself keeps Node.js `>=20.10` as its own floor. Version 0.1.4 additionally completed a live host load of 14 tools, two Skills, four route groups, and four UI slots on a daily DSH `0.1.5-rc.1` host.
 
-Iris 0.1.1–0.1.2 explicitly supports DSH `>=0.1.2-rc.1 <0.1.3-0` and no longer works with the legacy client runtime of DSH 0.1.0/0.1.1. DSH is still evolving quickly; later preview versions must pass verification before the supported range widens, and the compatibility badge is not an official certification. If DSH requires a newer Node.js, DSH wins.
+Iris 0.1.4 explicitly supports the two verified DSH windows `>=0.1.2-rc.1 <0.1.3-0` and `0.1.5-rc.1`, and no longer works with the legacy client runtime of DSH 0.1.0/0.1.1. Other preview versions have no host canary and are not claimed as compatible; the range widens only after verification passes, and the compatibility badge is not an official certification. If DSH requires a newer Node.js, DSH wins.
 
 ## Tools
 
@@ -158,19 +159,40 @@ By default, the optimizer uses the model selected for the current session and fa
 
 Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options.
 
-Generation capabilities accept multiple candidate models. Iris only tries the next candidate when the upload, the submission, or a synchronous generation fails; once a remote service has accepted a task, Iris never resubmits it automatically — that is how duplicate tasks and double billing are avoided. Accepted asynchronous tasks remain under the task system's watch.
+Generation capabilities accept multiple candidate models. Iris tries the next candidate only when the provider explicitly proves that the request was not accepted. A 500 response, timeout, disconnect, missing response, polling failure, or local persistence failure never authorizes automatic resubmission. Once accepted, Iris may only resume observation or delivery.
+
+The workbench lists paused observation, unknown acceptance/outcome, and successful generation with failed delivery under “Needs attention.” Re-observe never submits; re-deliver never regenerates; acknowledge/restore only changes the local reminder queue; only an explicitly confirmed informed retry creates a linked new task and may incur duplicate charges. Creating that task archives the original reminder while preserving its unknown facts and audit link. See [Task semantics](docs/TASK_SEMANTICS.md), [Architecture](docs/ARCHITECTURE.md), [Security](docs/SECURITY.md), and the [Fault-injection matrix](docs/FAULT_INJECTION.md).
 
 ![Task lifecycle and acceptance boundary](docs/assets/diagrams/iris-task-lifecycle.png)
 
 Transcription is a separate `transcribe` capability and does not consume the TTS or vision model configuration.
 
+## Capability health and model verification
+
+The workbench and main bubble expose four persistent health states: gray means unconfigured; blue means configured but unverified, or that success evidence is older than seven days; green means the exact provider × model × capability recently passed an explicit probe or real task; muted red is reserved for explicit 401/403 or authentication/permission failures. Text and evidence time accompany color, and critical provider configuration changes invalidate old evidence.
+
+Iris performs no background probes. Rate limits, network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance never overwrite a recent green state with red, trigger a hidden retry, or create hidden cost. Vision, image, and TTS can be probed per model; video and transcription require real user tasks. Host Doctor checks only DSH/Iris loading and host ports—it does not validate providers or models. See [Provider and capability health](docs/PROVIDER_HEALTH.md) for the state and failover contract.
+
+## Offline diagnostics
+
+No DSH installation or running host is required, and no provider request is sent:
+
+```bash
+npx @mokuyoaxis/dsh-iris doctor
+npx @mokuyoaxis/dsh-iris doctor --json
+```
+
+The installed binary is `dsh-iris`. Exit code `0` is healthy, `1` means warnings, and `2` means hard errors. Offline Doctor checks Node.js, sharp, ffmpeg/ffprobe, a real but cleaned-up storage write probe, configuration, models/assignments, task semantics, temporary files, and orphaned or missing artifacts.
+
+A running DSH instance also provides a “Host diagnostics” card in the Iris workbench and exposes the authenticated `/iris/api/doctor` JSON. It checks the DSH version, plugin, 14 tools, two Skills, four route groups, Browser/attachment/model capabilities, client version, and four UI Slots. It reads only safe snapshots and registration evidence; it never calls Browser, models, or providers. See [Host Doctor](docs/HOST_DOCTOR.md).
+
 ## Composed workflow example
 
 Iris ships two agent skills (`iris-verify-ui` and `iris-compose-media`) that chain multiple tools into bounded, reviewable media workflows. The example below is "look → redraw → self-check": understand the source image first, then generate, review against concrete mismatches, and only deliver once the review passes.
 
 ![Composed workflow example](docs/assets/diagrams/iris-workflow-compose.png)
 
-SVG versions and editable drawio sources of the figures above live in [`docs/assets/diagrams/`](docs/assets/diagrams/). Diagram labels are currently in Chinese.
+The repository also carries SVG versions and editable drawio sources under [`docs/assets/diagrams/`](docs/assets/diagrams/); the npm package ships only the PNGs shown above. Diagram labels are currently in Chinese.
 
 ## Data and tasks
 
@@ -178,9 +200,10 @@ Runtime data lives under `$DSH_HOME/iris/v1/` by default:
 
 | Location | Contents |
 |---|---|
-| `providers.json` | Providers and capability assignments; file mode 0600 |
+| `providers.json` | Providers, capability assignments, and redacted health evidence; file mode 0600 |
 | `prompt-optimizer.json` | Imported optimizer prompt, target templates, model route, and generation settings; file mode 0600 |
 | `tasks.json` | Task metadata and attachment indexes; up to 500 records |
+| `artifacts.json` | Minimal work-library index and random access tokens; no prompt, provider, or task relationship |
 | `outputs/` | Generated and processed media |
 | `uploads/` | Temporary copies of browser uploads |
 
@@ -188,6 +211,8 @@ On first load, 0.1.1 tightens POSIX permissions across an existing `$DSH_HOME/ir
 
 Asynchronous tasks are polled in the background. After a plugin restart, Iris can re-adopt tasks that are still running remotely. Cancellation signals propagate through local waits and polling; whether the remote computation itself can be cancelled depends on the provider's API.
 
+The work library has its own lifecycle: clearing terminal task history does not delete works, and older media can be recovered by re-indexing `outputs/`. Deleting one work or clearing the library deletes the actual files behind a separate confirmation. See [Work library v0](docs/ARTIFACT_LIBRARY.md) (Chinese). Favorites, tags, and search remain future work after the full Artifact Manifest.
+
 Audio and video are served through Iris media links that carry random capability tokens. Images are, wherever possible, also saved as DSH durable attachments so they stay usable in the conversation.
 
 ## Security notes
@@ -198,7 +223,7 @@ Audio and video are served through Iris media links that carry random capability
 - `IRIS_TRUSTED_HOSTS` is not an authentication mechanism. When exposing DSH to the public internet or an untrusted network, configure authentication and HTTPS at the reverse proxy or host layer.
 - Paid model probes run one capability at a time and always confirm before a real provider call; video and transcription never submit empty-sample paid probes automatically.
 - HTML screenshots render inside a sandboxed page without same-origin privileges; scripts and external network access are disabled by default.
-- Media links use random capability tokens, and file paths are resolved only from task records.
+- Media links use random capability tokens, and file paths are resolved only from task records or the minimal work-library index.
 - Iris provides no account system of its own; multi-user isolation and access control are the responsibility of the DeepSeek Harness deployment.
 
 ## Known limitations
@@ -220,6 +245,16 @@ When the plugin is enabled, it automatically registers the two bundled skills th
 
 From 0.1.2, as long as the host provides the DSH skill registry, regular npm installs can discover and load both skills from any project directory — no need to clone this repository or configure a skill search path. When the project directory contains same-name skills, DSH's native precedence keeps using the project versions; if the skill registry is unavailable, the 14 Iris tools still load on their own.
 
+For deterministic selection, invoke either skill with DSH's `/name` form:
+
+```text
+/iris-compose-media Inspect my uploaded product photo, create a matching poster, then verify the requested constraints
+
+/iris-verify-ui Compare the current screenshot with the reference, locate regressions, and return an evidence-based verdict
+```
+
+Natural-language discovery remains available. Do not force the composition skill for a single draw, OCR, or transcription action; ask directly or name the matching Iris tool. Skills plan tool use but never bypass Iris task, cost-confirmation, or safety boundaries.
+
 ## Development and verification
 
 Run in the project directory:
@@ -239,6 +274,7 @@ Releases are triggered by `v*` tags through `.github/workflows/release.yml`: the
 - [Roadmap](docs/ROADMAP.md) (Chinese)
 - [File access across environments](docs/file-access-across-environments.md) (Chinese)
 - [Android 16 screenshot gallery](docs/screenshots.md)
+- [Task/Attempt v2 semantics (Chinese)](docs/TASK_SEMANTICS.md)
 
 ## License
 

package/README.md

@@ -54,7 +54,7 @@ Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体
 
 ## 最快开始
 
-已经安装 DeepSeek Harness `0.1.2-rc.1` 且 `pnpm` 在 PATH 中时，把 Iris 加入 Web profile：
+已经安装受支持的 DeepSeek Harness（`>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1`）且 `pnpm` 在 PATH 中时，把 Iris 加入 Web profile：
 
 ```bash
 dsh plugin --profile web add @mokuyoaxis/dsh-iris
@@ -86,6 +86,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
 - 视频抽帧与多模态内容摘要
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
+- 独立作品库：清除任务历史后仍可浏览本地作品，并可重新索引旧 `outputs/`
 - 多供应商模型池，以及按 `供应商 + 模型` 分配能力
 - 浏览器上传、会话附件和宿主路径三种文件来源
 - 独立于工作台的对话框提示词优化，支持当前会话模型与 JSON 固定模型路由
@@ -103,9 +104,9 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 dsh-iris 按 DeepSeek Harness 插件形态提供服务端与 Web 客户端入口：服务端注册 14 个 Agent 工具，并复用宿主的工具、路由和生命周期服务；客户端通过 DSH 模块加载器接入设置页、会话输入区和全局悬浮层。插件不会启动独立服务或额外监听端口。
 
-当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。0.1.1 已在 Linux ARM64 的干净与真实 Web profile 中，使用 DSH `0.1.2-rc.1`、Node.js `22.23.2` 完成宿主烟测；浏览器启动图、完整组合 bundle、Iris 客户端工厂和当时的三个 UI 座位均已验证。0.1.2 新增的第四个提示词优化座位已在 Android 浏览器真机确认渲染，配置读取、真实会话模型优化（实际 thinking `off`）、预览写回、独立关闭与重新启用，以及从短草稿到图片生成任务成功的闭环均已验证；浏览器端取消和 JSON 操作已有自动化 HTTP/配置覆盖，尚待补充真机逐项记录。Iris 自身仍以 Node.js `>=20.10` 为最低基线。
+当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。0.1.1 已在 Linux ARM64 的干净与真实 Web profile 中，使用 DSH `0.1.2-rc.1`、Node.js `22.23.2` 完成宿主烟测；浏览器启动图、完整组合 bundle、Iris 客户端工厂和当时的三个 UI 座位均已验证。0.1.2 新增的第四个提示词优化座位已在 Android 浏览器真机确认渲染，配置读取、真实会话模型优化（实际 thinking `off`）、预览写回、独立关闭与重新启用，以及从短草稿到图片生成任务成功的闭环均已验证；浏览器端取消和 JSON 操作已有自动化 HTTP/配置覆盖，尚待补充真机逐项记录。Iris 自身仍以 Node.js `>=20.10` 为最低基线。0.1.4 另在 Android/Linux 日常 DSH `0.1.5-rc.1` 上完成 14 工具、2 项 Skill、4 组路由与 4 个 UI Slot 的实机装载验证。
 
-Iris 0.1.1–0.1.2 明确支持 DSH `>=0.1.2-rc.1 <0.1.3-0`，不再兼容 0.1.0/0.1.1 的旧客户端 Runtime。DSH 仍在快速演进，后续预览版须经验证后再扩大范围；兼容徽章不代表官方认证。若 DSH 要求更高 Node 版本，以 DSH 为准。
+Iris 0.1.4 明确支持 DSH `>=0.1.2-rc.1 <0.1.3-0` 与 `0.1.5-rc.1` 这两个已实测窗口，不再兼容 0.1.0/0.1.1 的旧客户端 Runtime。其余预览版未经宿主 canary，不宣称兼容，验证通过后再扩大范围；兼容徽章不代表官方认证。若 DSH 要求更高 Node 版本，以 DSH 为准。
 
 ## 工具
 
@@ -158,19 +159,40 @@ Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入
 
 能力分配使用 `providerId::modelId` 作为模型身份。同名模型如果来自不同供应商或不同账号，会被视为两个独立选项。
 
-生成类能力可以配置多个候选模型。Iris 只会在上传、提交或同步生成阶段失败时尝试下一个候选项；远端服务一旦受理任务，就不会自动重新提交，以免产生重复任务或重复计费。已经受理的异步任务由任务系统继续跟踪。
+生成类能力可以配置多个候选模型。Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
+
+工作台把观察暂停、受理/结果未知和生成成功但交付失败单列为“需要处理”。“重新观察”不会提交；“重新交付”不会重新生成；“标为已读/恢复提醒”只改变本地提醒队列；只有“知情重试”会创建新任务，并要求用户逐次确认潜在重复费用。新任务创建后，原提醒自动归档但保留未知事实和新旧任务关联。任务语义、架构、安全边界与故障证据分别见 [`TASK_SEMANTICS.md`](docs/TASK_SEMANTICS.md)、[`ARCHITECTURE.md`](docs/ARCHITECTURE.md)、[`SECURITY.md`](docs/SECURITY.md) 和 [`FAULT_INJECTION.md`](docs/FAULT_INJECTION.md)。
 
 ![生成任务生命周期与受理边界](docs/assets/diagrams/iris-task-lifecycle.png)
 
 转写是独立的 `transcribe` 能力，不会占用 TTS 或视觉能力的模型配置。
 
+## 能力健康与模型验证
+
+工作台与主泡泡使用四色健康状态：灰色表示未配置，蓝色表示已配置但尚未验证或成功证据已超过 7 天，绿色表示对应“供应商 × 模型 × 能力”近期实测或真实任务成功，暗红色只表示明确的 401/403 或认证/权限失败。界面同时显示文字和证据时间；关键供应商配置变化会使旧证据失效。
+
+Iris 不做后台探测。429、网络、5xx、内容安全、取消和受理未知不会把近期绿色改成红色，也不会触发隐形重试或费用。模型池可逐项实测视觉、图片和 TTS；视频与转写必须用真实任务验证。Host Doctor 只核验 DSH/Iris 的装载与 Host Port，不会验证供应商或模型。完整状态、failover 汇总和安全规则见 [Provider 与能力健康状态](docs/PROVIDER_HEALTH.md)。
+
+## 离线诊断
+
+无需安装或启动 DSH，也不会发送供应商请求：
+
+```bash
+npx @mokuyoaxis/dsh-iris doctor
+npx @mokuyoaxis/dsh-iris doctor --json
+```
+
+安装后的二进制名是 `dsh-iris`。退出码 `0` 表示正常、`1` 表示有警告、`2` 表示有硬错误。离线 Doctor 检查 Node、sharp、ffmpeg/ffprobe、数据目录真实写入、配置、模型/分配、任务语义、临时文件和孤儿/缺失产物。
+
+运行中的 DSH 另在 Iris 工作台提供“宿主诊断”卡片，并公开已认证的 `/iris/api/doctor` JSON：检查 DSH 版本、插件、14 个工具、两项 Skill、四组路由、Browser/附件/模型能力、客户端版本和四个 UI Slot。它只读取安全快照与注册证据，不调用 Browser、模型或 Provider；详见 [Host Doctor](docs/HOST_DOCTOR.md)。
+
 ## 组合工作流示例
 
 Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），把多个工具编排成有界、可复核的媒体工作流。下例是「看图 → 重绘 → 自检」：先理解原图，再生成，复核针对具体偏差，只有复核通过才交付。
 
 ![组合工作流示例](docs/assets/diagrams/iris-workflow-compose.png)
 
-图的 SVG 版本与可编辑 drawio 源文件位于 [`docs/assets/diagrams/`](docs/assets/diagrams/)。
+仓库的 [`docs/assets/diagrams/`](docs/assets/diagrams/) 另提供 SVG 版本与可编辑 drawio 源文件；npm 包只随附 README 直接展示的 PNG。
 
 ## 数据与任务
 
@@ -178,9 +200,10 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 | 位置 | 内容 |
 |---|---|
-| `providers.json` | 供应商和能力分配，文件权限为 0600 |
+| `providers.json` | 供应商、能力分配和脱敏健康证据，文件权限为 0600 |
 | `prompt-optimizer.json` | 用户导入的优化 Prompt、目标模板、模型路由和生成参数，文件权限为 0600 |
 | `tasks.json` | 任务元数据和附件索引，最多保留 500 条 |
+| `artifacts.json` | 作品库最小索引与随机访问令牌，不含 Prompt、Provider 或任务关系 |
 | `outputs/` | 生成和处理后的媒体文件 |
 | `uploads/` | 浏览器上传的临时输入副本 |
 
@@ -188,6 +211,8 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 异步任务会在后台轮询。插件重启后，可以继续接管仍在远端执行的任务。取消信号会传递到本地等待与轮询流程；是否能取消远端计算，取决于供应商接口。
 
+作品库与任务历史相互独立：清理终态任务不会删除作品，新旧媒体可在工作台分页浏览，也可用“找回本地作品”重新扫描 `outputs/`。删除作品或清空作品库会删除实际文件并单独确认；详见[作品库 v0](docs/ARTIFACT_LIBRARY.md)。收藏、标签和搜索留待完整 Artifact Manifest。
+
 音频和视频通过带随机令牌的 Iris 媒体链接访问。图片会尽量转存为 DSH 持久附件，方便在会话中继续使用。
 
 ## 安全说明
@@ -198,7 +223,7 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 - `IRIS_TRUSTED_HOSTS` 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。
 - 模型实测只按单项能力运行，并在真实供应商调用前确认；视频和转写不会用空样本自动提交付费探针。
 - HTML 截图在不具备同源权限的沙箱页面中渲染，脚本和外部网络默认不可用。
-- 媒体链接使用随机能力令牌，文件路径只从任务记录解析。
+- 媒体链接使用随机能力令牌，文件路径只从任务记录或最小作品索引解析。
 - Iris 不提供独立账号体系，多用户隔离和访问控制由 DeepSeek Harness 部署负责。
 
 ## 已知限制
@@ -220,6 +245,16 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，14 个 Iris 工具仍可独立装载。
 
+用户想稳定指定方法时，可直接用 DSH 的 `/name` 形式：
+
+```text
+/iris-compose-media 分析我上传的产品照，生成同构图海报，再检查是否符合要求
+
+/iris-verify-ui 对比当前截图和参考图，定位偏差并给出有证据的结论
+```
+
+也可以继续用自然语言让 Agent 自动发现。单步绘图、OCR、转写等无需强行唤起组合 Skill，直接说需求或指定对应 Iris 工具即可。Skill 只规划工具链，不会绕过 Iris 的任务、费用确认和安全边界。
+
 ## 开发与验证
 
 在项目目录运行：
@@ -239,6 +274,7 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 - [路线图](docs/ROADMAP.md)
 - [文件访问与跨环境](docs/file-access-across-environments.md)
 - [Android 16 真机截图画廊](docs/screenshots.md)
+- [Task/Attempt v2 语义契约](docs/TASK_SEMANTICS.md)
 
 ## License
 

package/bin/dsh-iris.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { doctor, formatDoctorReport } from '../lib/doctor.js';
+
+function usage() {
+  return [
+    'Usage: dsh-iris doctor [--json]',
+    '',
+    'Runs offline diagnostics only. It does not start DSH or send provider requests.'
+  ].join('\n');
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(usage());
+  process.exitCode = 0;
+} else if (args[0] !== 'doctor' || args.some((arg, index) => index > 0 && arg !== '--json')) {
+  console.error(usage());
+  process.exitCode = 2;
+} else {
+  const report = await doctor();
+  console.log(args.includes('--json') ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
+  process.exitCode = report.exitCode;
+}