@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

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,80 @@
 
 ## [Unreleased]
 
-当前没有尚未发布的用户可见变更。
+暂无。
+
+## [0.2.0] - 2026-10-01
+
+Iris 0.2.0 要求 Node.js ≥ 22.0.0，DSH 插件仅支持 `0.2.0-rc.2`；旧宿主继续固定安装 `@mokuyoaxis/dsh-iris@0.1.4`。包名与仓库名保留，第二个真实 Host Adapter 完成后再更名。
+
+### Added
+
+- 增加中英文 [Agent 简要 Prompt](docs/AGENT_QUICKSTART.md)，按宿主版本选择固定 npm 0.2.0 或 0.1.4，并明确 CLI、profile 与任务观察的使用边界。
+- 增加 [Text/Vision Model Port v0 内部契约](docs/MODEL_PORT_CONTRACT.md)，约定共享输入、完整终态、取消/预算、安全错误与逐项迁移门禁；真实 DSH/CLI 消费者尚未切换。
+- 实现 Text/Vision M1 纯契约与调用控制，包含单次/整体预算、显式候选策略、取消与晚到结果处理，并补 test-only Fake Port 和共用离线 conformance；真实适配器、提示词优化及视觉消费者尚未接入，未新增公开 export。
+- 增加像素块几何母题的 IRIS 标志与图形标（彩色/单色/反白共 6 个 SVG），由 `scripts/gen-logo.mjs` 从设计矩阵可复现生成，含最小尺寸、留白与配色规范（`docs/assets/logo/`）；初始泡泡采用同源内联像素图形标，后续曲线替换见下方 Changed；0.1.x 渐变临时字标不再使用，源码文件暂留作历史兼容。
+- 增加 Core 任务的注意力处置（Host 偏好式，与 legacy 体验对齐）：工作台 attention 行（失败/取回失败/受理未知）提供「不再提醒」与「移除」，已受理行提供「恢复提醒」，高级诊断保留完整记录并标注处置状态、可「恢复显示」。处置存于 `$DSH_HOME/iris/v1/core-attention.json`（0600、原子写、损坏降级为无偏好），**零 Core 写入**——任务与产物记录绝不删除。重试成功自动静默：若某 attention 任务存在 `retriedFrom` 指向它的后继且后者已成功交付，则旧任务从任务区自动静默（纯事实派生，刷新不回归；后继后续失败则静默随之撤销）。CLI 无提醒概念，不受影响。
+
+- 发布 Headless CLI：无需加载 DSH 即可执行本地裁剪、图片 diff、视频抽帧及图片/视频/语音/转写任务，并跨进程观察任务、检查和导出 Artifact。
+- Headless CLI 增加只读的 `providers list`、`capabilities list` 与显式数据根 Core Doctor；异常退出后可经 Doctor 核对并回显陈旧 owner PID，使用 `runtime recover` 写私有审计后释放租约。活跃或证据不完整时拒绝恢复，不自动解锁。
+- 增加实例化 Core Runtime，提供显式数据根、单写者租约、reader、取消和有序释放。
+
+### Changed
+
+- 0.2.0 的 Node.js 最低要求统一为 22.0.0，npm 元数据、Doctor、README、用户指南与 CI 同步。Node 22 已包含上游退出阶段 FinalizationRegistry 无限循环修复（nodejs/node#51290）；补充确定性退出回归及最低版本重复退出验证，移除临时 GDB 取证步骤。已发布 0.1.4 的历史要求不变。
+- 0.2.0 的 DSH engines、五项可选客户端 peers 和 Host Doctor 收敛到准确的 `0.2.0-rc.2`，不再声明旧 DSH 支持；已发布 Iris 0.1.4 的历史范围不变，README 和用户指南补充 `@mokuyoaxis/dsh-iris@0.1.4` 固定安装与 npm tarball 下载方式。
+- 悬浮泡泡以曲线鸢尾花 SVG 替换像素块剪影，采用紫色花瓣、金色花心与青绿叶片；提供透明矢量源和按钮概念预览，保留现有健康状态与交互。
+- 适配 DSH `0.2.0-rc.2`，通过真实安装服务隔离验收；未推定其他 0.2 版本兼容，已发布 npm 0.1.4 包不包含这些后续修改。验证范围见 [rc.2 适配说明](docs/DSH_RC2_ADAPTATION.md)。
+- CLI、DSH 与知情重试共用四类生成的参数规范化：文本修剪、图片数量、视频时长及 size/voice 长度使用同一规则，非法参数在提交前拒绝。DSH 的 diff/抽帧工具和工作台动作消费已有 Core Command，结果保存为 Artifact 并可经 CLI 导出；宿主继续负责附件展示。
+- 协议工厂改用内部注册表；媒体协议与视觉类型分别处理。导入和重载保留用户显式配置，未知协议在联网前返回稳定错误；未知端点的自动 OpenAI Images 兼容回退带 `protocolInferred` 标记，并在供应商管理区提示确认。
+- CLI 与 DSH 共用配置模型解析，均接受裸模型名与供应商复合引用；运行时不再注入厂商默认模型。旧裸账号的兼容目录改为在配置写入时物化，CLI 读取不迁移配置；显式空模型池仍保持为空。
+- 模型发现改为合并更新：手工项优先、保留远端未再返回的旧项、按 ID 去重，编辑已有模型也会标记为手工配置。
+- CLI 与 DSH 的供应商可用性及旧分配对象解析共用规则：未声明 `enabled` 时默认启用，缺少端点或必要凭据时不进入候选链；旧 `{providerId, id}` 分配格式在两入口一致生效。
+- 临时文件上传统一经过 Provider Adapter 的可选 `prepareInput` 能力；DashScope 由协议闭包持有凭据与端点，OpenAI Images 在上传前明确拒绝。上传错误统一脱敏为未受理分类，但 Core 转写的准备失败不伪造已落盘的 Task/Attempt。
+
+- 精简 README、路线图和 Core/Host 契约，把版本施工记录留在 CHANGELOG 与验收文档。
+- DSH 继续加载同一个 npm 插件入口；Core 与 Host Adapter 分离，不引入额外 daemon。
+- 阿里云百炼支持独立 Workspace `mediaBaseUrl`、官方模型目录分页与能力元数据；模型池保持有序安全 failover，并保护用户手工能力覆盖。
+
+### Fixed
+
+- 修复 Model Port 使用超大合法 timeout 时，deadline 浮点舍入放大剩余预算而导致端口误判为非法输入的问题；剩余预算不超过原始输入，并补确定性边界回归。
+- 修复 DSH 会话附件扫描丢失字节数和尺寸导致真实 `readImage()` 完整性检查失败；rc.2 默认视觉候选明确绑定 Provider/模型并先确认图片能力；客户端支持主视图持有者和无参数快照通知，并随插件卸载释放会话订阅。
+- 修复 Core 知情重试直接透传外部字段的问题：转写的 `audio_url` 和图生视频的 `img_data_url` 现在分别转换为 Adapter 所需字段，保留重新提供的音频地址与首帧；未知参数不会静默丢弃。
+- 关闭 Runtime 时，已接纳的操作会先收到取消信号并完成收束，避免操作尚未建立上下文就被释放。
+- Artifact 导出不覆盖已有文件，检查会拒绝缺失或大小不一致的对象。
+- CLI 对可捕获的 SIGINT/SIGTERM 会中止在途请求并释放写者租约；`auth:'none'` 的媒体请求不再发送空的 Bearer 头或沿用旧 Key，缺省 bearer 配置仍要求 Key。
+- 修复显式租约恢复在中途 I/O 失败时引用未定义状态变量的问题；失败仍返回稳定的恢复错误码，并尽力保留原租约与审计证据。
+
+- 明确 0.2.0 的 Core 生命周期末端边界：DSH 工作台现有删除、清空与孤儿清理只作用于 legacy `outputs/`，DSH 与 Headless CLI 都不删除 Core Task/Artifact；Doctor 只报告孤立对象、未提交 Manifest 和未解析条目。Core 删除与清理继续列入 0.2.x，不建议手工改动 `core-v0`。
+
+### Security
+
+- 同一物理数据根只允许一个 writer；reader 不创建、修复或迁移数据。
+- Headless Command 结果和错误不返回输入文件或数据根的绝对路径。
+
+## [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
 
@@ -150,7 +223,9 @@
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...v0.2.0
+[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

package/README.en.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <img src="docs/assets/iris-wordmark.svg" width="520" alt="IRIS wordmark">
+  <img src="docs/assets/logo/iris-interim-flower.png" width="400" alt="IRIS line-art iris flower (interim logo)">
 </p>
 
 <h1 align="center">Iris Media for DSH</h1>
@@ -13,7 +13,7 @@
 <p align="center">
   <a href="#deepseek-harness-adaptation"><img alt="DeepSeek Harness compatible" src="https://img.shields.io/badge/DeepSeek%20Harness-compatible-4D6BFE.svg?style=flat-square"></a>
   <a href="https://www.npmjs.com/package/@mokuyoaxis/dsh-iris"><img alt="npm version" src="https://img.shields.io/npm/v/%40mokuyoaxis%2Fdsh-iris.svg?style=flat-square"></a>
-  <a href="https://nodejs.org/"><img alt="Node.js 20.10 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D20.10-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js 22 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D22-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
   <a href="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml/badge.svg"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
@@ -44,7 +44,23 @@ These captures come from an Android browser connected to DSH under Termux/PRoot
 
 The project is at an early stage; interfaces and configuration formats may still change between releases.
 
-Iris's long-term direction is a media production core that can run on its own and plug into different agent hosts. DeepSeek Harness is the first supported host, and the current version still requires DSH — a standalone Core, CLI, and workbench are on the roadmap but not yet available.
+Iris is evolving toward a media production core that can run independently and plug into different agent hosts. Version 0.2.0 provides both a DSH plugin and a headless CLI media path (crop, image/video/TTS/transcription submission, task observation, artifact export). Core internals have not been frozen as a public SDK.
+
+> Version support: Iris `0.2.0` requires Node.js `>=22.0.0` and its DSH plugin supports only the exact host version `0.2.0-rc.2`. Older DSH hosts should pin `@mokuyoaxis/dsh-iris@0.1.4` as described below instead of following npm latest. Iris and DSH have independent version numbers.
+
+## Two ways to use Iris
+
+| | Path A: DSH plugin (0.2.0) | Path B: Headless CLI (0.2.0) |
+|---|---|---|
+| Who it's for | DeepSeek Harness users who want agent tools, the workbench, and in-chat prompt optimization | Users who want media generation, task tracking, and artifact export from the command line without DSH |
+| Entry point | Choose a pinned release under "Quickest start" below | `dsh-iris run ...` — see [Headless CLI](docs/HEADLESS_CLI.md) |
+| Data location | `$DSH_HOME/iris/v1/` (Core data root `core-v0`) | Any absolute path passed via `--data-root` |
+| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | No — explicit single-step `task observe` |
+| Dependencies | DSH `0.2.0-rc.2` and Node.js ≥ 22 | Node.js ≥ 22 and `sharp` only (`ffmpeg` for video frames) |
+
+Both paths read and write the same Core Task/Artifact facts: point the CLI at the `core-v0` data root of a DSH profile to inspect/export DSH-generated artifacts, and vice versa. Only one writer is allowed per data root.
+
+> Install size note: image processing depends on `sharp` and its prebuilt binaries (~27 MB). On uncommon platforms (e.g. some ARM proot environments) a failed sharp install is detected by `dsh-iris doctor`; image actions become unavailable while everything else keeps working.
 
 ## Relationship with ai-paint
 
@@ -54,16 +70,47 @@ 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:
+Check the host with `dsh --version` and ensure `pnpm` is on your PATH. Iris and DSH have independent version numbers; choose a matching combination:
+
+| Your DSH | Iris choice | Source |
+|---|---|---|
+| `0.2.0-rc.2` | `0.2.0` | Pinned npm release |
+| `>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1` | Stable `0.1.4` | Pinned npm release |
+| Other versions | No current support claim | Check host adaptation before installing |
+
+### Older DSH: install stable 0.1.4
+
+For the older DSH range above, add the pinned release to the Web profile:
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
 dsh web
 ```
 
-> The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
+To download the published npm package separately:
+
+```bash
+npm pack @mokuyoaxis/dsh-iris@0.1.4
+```
+
+This writes a `.tgz` to the current directory. Use `npm install @mokuyoaxis/dsh-iris@0.1.4` if you only want a regular npm dependency; that does not add a DSH profile layer. Pinning `@0.1.4` keeps selecting the old stable release after latest changes. See [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack/). Version 0.1.4 does not contain the 0.2.0 Core media CLI or the later DSH rc.2 adaptation.
+
+### DSH 0.2.0-rc.2: install 0.2.0
+
+Install the pinned npm release into the Web profile:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0
+dsh web
+```
 
-To try it from a source checkout, replace `@mokuyoaxis/dsh-iris` in the first command with `.`. The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`.
+The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`. Open the complete URL if startup output includes authentication parameters. Version 0.2.0's compatibility metadata admits only DSH rc.2.
+
+### Choosing a version in dsh-market
+
+The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: 0.2.0 is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
+
+> The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
 
 After the first start, open "Settings → Iris workbench → + Add provider", enter your DashScope base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, OpenAI Images–compatible configuration, and failover notes are in the [user guide](user_guide.md) (Chinese).
 
@@ -77,6 +124,8 @@ Summarize /absolute/path/demo.mp4 with Iris, then turn the summary into speech.
 
 DSH profiles and plugin commands follow the [official installation docs](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md). Generating images, videos, or speech may incur provider charges.
 
+For a copyable installation and usage prompt, see [Agent quickstart prompt](docs/AGENT_QUICKSTART.md).
+
 ## Feature overview
 
 ![Iris architecture overview](docs/assets/diagrams/iris-architecture.png)
@@ -86,13 +135,14 @@ 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
 
 ## Prerequisites
 
-- A Node.js version that satisfies your DeepSeek Harness release's requirement; dsh-iris itself requires at least 20.10
+- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.0 requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
 - A working DeepSeek Harness environment with `pnpm` on the PATH
 - At least one supported media or vision provider
 - `ffmpeg` and `ffprobe` on the system, for video frame extraction and video summaries
@@ -101,11 +151,19 @@ After installing the plugin, add a provider in the Iris workbench and assign mod
 
 ## DeepSeek Harness adaptation
 
-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.
+dsh-iris remains a native DSH plugin. Its server registers 14 agent tools and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen 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.
+| Iris version | DSH range | Verification |
+|---|---|---|
+| Published stable `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | Historical clean and daily Web profiles on Linux ARM64 |
+| Published stable `0.1.4` | `0.1.5-rc.1` | Historical daily Android/Linux profile checks |
+| `0.2.0` | Only `0.2.0-rc.2` | Installed-service isolation checks, Core diff, and SlotRegistry; user demonstration reported successful, with detailed browser actions and asynchronous restart/rollback verification continuing |
 
-Iris 0.1.1–0.1.3 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.
+See the [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) for scope. The published npm 0.1.4 package does not contain these later changes.
+
+Iris 0.2.0 no longer claims older DSH support; historical validation does not automatically cover this version. DSH `0.2.0` stable and other rc versions are also outside its support range. Automated checks cover server loading, tool and Skill registration, routes, the client bundle, and UI slots separately so Doctor can identify which boundary failed.
+
+Core and the DSH Adapter are being separated: DSH keeps loading the same npm package, while the Adapter maps host capabilities into Core. A DSH API change should require an Adapter or client-bridge fix, not a rewrite of Task or Artifact semantics. Version 0.2.0 includes the headless CLI. The `dsh` prefix will be removed after a second real Host Adapter is implemented and accepted, with a new npm package at that point; see the [roadmap](docs/ROADMAP.md).
 
 ## Tools
 
@@ -156,9 +214,9 @@ By default, the optimizer uses the model selected for the current session and fa
 
 ## Model assignment and failover
 
-Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options.
+Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options. Discovery prefers provider capability metadata, falls back to name rules, and preserves explicit user overrides. Alibaba Cloud media calls may use a separate Workspace `mediaBaseUrl`.
 
-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.
+Generation capabilities accept multiple candidate models. Every request starts at the head of the ordered list; this is safe failover, not round-robin. 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).
 
@@ -166,6 +224,12 @@ The workbench lists paused observation, unknown acceptance/outcome, and successf
 
 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:
@@ -175,7 +239,9 @@ 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. 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. It cannot verify a running DSH host, browser service, or live provider.
+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
 
@@ -183,7 +249,7 @@ Iris ships two agent skills (`iris-verify-ui` and `iris-compose-media`) that cha
 
 ![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
 
@@ -191,9 +257,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 |
 
@@ -201,17 +268,19 @@ 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
 
 - Provider keys are never returned by status endpoints.
-- The DashScope media protocol only sends keys to official Alibaba Cloud HTTPS domains; any other base URL defaults to the OpenAI Images–compatible protocol.
+- The DashScope media protocol only sends keys to official Alibaba Cloud HTTPS, regional, or Workspace domains. A separate `mediaBaseUrl` may split media from vision/chat traffic; other addresses default to the OpenAI Images–compatible protocol.
 - `/iris/*` accepts loopback Host headers only by default; LAN or reverse-proxy deployments must set `IRIS_TRUSTED_HOSTS` explicitly, and state-changing requests are also checked against cross-site origins.
 - `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
@@ -233,6 +302,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:
@@ -241,7 +320,7 @@ Run in the project directory:
 
 Tests cover config merging, model identity, task lifecycle, generation actions, HTTP/SSE routing, client interactions, and security boundaries. The project is pure ES Modules with no build step.
 
-The test scheduler runs on Node.js, launching one process per file and stopping at the first failure — no Bash involved. Temporary directories use system APIs and are cleaned up on exit. GitHub Actions defines a Linux/Windows × Node.js 20.10/22 matrix, and a pre-release hook re-runs the full suite. DSH host smoke tests on native Windows/WSL are still pending real-machine verification.
+The test scheduler runs on Node.js, launching one process per file and stopping at the first failure — no Bash involved. Temporary directories use system APIs and are cleaned up on exit. GitHub Actions defines a Linux/Windows × Node.js 22.0.0/latest 22.x matrix, with repeated natural-exit checks on the minimum version, and a pre-release hook re-runs the full suite. DSH host smoke tests on native Windows/WSL are still pending real-machine verification.
 
 Releases are triggered by `v*` tags through `.github/workflows/release.yml`: the full test suite runs first, then the tarball is packaged, a GitHub Release is created with the workflow's built-in `GITHUB_TOKEN` (tarball attached; release notes taken from the matching CHANGELOG section), and npm publish happens when an `NPM_TOKEN` secret is configured. No local GitHub credentials are needed.