@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

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

@@ -35,11 +35,13 @@ Do not add an analysis, transcription, or review step merely because a tool exis
 
 ## Resolve media inputs
 
-- Use `iris_look_at_image` for an absolute image path visible to the host.
+- For edits to an existing Core image, pass its ID as `source_artifact_id` to `iris_edit_image` with the requested change. This creates a new Task and Artifact while keeping the source intact; it requires a configured chat image model.
+- PNG, JPEG and WebP can be used directly; do not convert a generated PNG to JPEG merely to call vision or OCR. Core IDs and host paths remain separate inputs.
+- Use `iris_look_at_image` for a host-visible absolute `image_path` or an existing Core image `artifact_id` (choose one).
 - Use `iris_relook_attachment` for an image attachment already present in the session or produced by Iris.
-- Use `iris_long_ocr` when exact text from an image matters more than a visual description.
-- Video and audio tools require host-visible absolute `video_path` or `audio_path` values. A browser-local path, `content://` URI, or ordinary web URL is not a host path; request an upload or exported host path.
-- Keep every returned attachment ID, task ID, and output path that a later step needs. Do not invent or reconstruct identifiers.
+- Use `iris_long_ocr` when exact text from an image matters more than a visual description; choose exactly one of `image_path`, Core `artifact_id`, or session `attachment_id`. `iris_locate` accepts the same three sources for original-pixel bounding boxes.
+- Video and audio file inputs require host-visible absolute `video_path` or `audio_path` values. Video summaries can instead consume existing Core `frame_artifact_ids`. A browser-local path, `content://` URI, or ordinary web URL is not a host path; request an upload or exported host path.
+- Keep every returned Core Artifact ID, attachment ID, task ID, and output path that a later step needs. Core `artifact_id` and session `attachment_id` are distinct; do not use either as a file path or invent identifiers.
 
 An attachment returned by `iris_draw_image` can be passed as `first_frame_attachment_id` to `iris_generate_video`. An existing host image uses `first_frame_path`. The local path returned by `iris_speak_text` can be passed as `audio_path` for S2V.
 
@@ -48,6 +50,7 @@ An attachment returned by `iris_draw_image` can be passed as `first_frame_attach
 Choose the minimum chain, then read only the matching section of [references/workflows.md](references/workflows.md):
 
 - inspect an image, then draw: `iris_look_at_image` or `iris_relook_attachment` → `iris_draw_image`;
+- edit a Core image, then inspect: `iris_edit_image` → `iris_look_at_image` using the new Artifact ID;
 - 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`;
@@ -55,6 +58,8 @@ Choose the minimum chain, then read only the matching section of [references/wor
 
 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.
 
+If frames are already saved by `iris_video_frames`, pass its returned `frame_artifact_ids` to `iris_media_summarize` instead of extracting again. This reads the original timestamps and frame order without the video file or ffmpeg. Omit `video_path`, `max_frames`, `target_width`, and `transcribe:true`; supply existing speech as `transcribe_text` when available.
+
 ## Control cost and iteration
 
 - 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.
@@ -72,7 +77,7 @@ When a generation tool returns a Task, or the user asks to retry, recover, cance
 - 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 an attachment is missing, request a re-upload or host path. If `ffmpeg`/`ffprobe` is unavailable, new video frame extraction cannot run; summaries can still use existing Core frame IDs.
 - If vision is unavailable but the creation prompt is complete, skip source analysis only when the requested result still remains valid.
 
 ## Report the result

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

@@ -9,6 +9,12 @@ Read only the section matching the chosen workflow. Keep paid steps bounded by t
 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.
 
+## Edit a Core image, then inspect
+
+1. Resolve the source Core Artifact ID; one static PNG, JPEG or WebP image up to 20 MiB is supported.
+2. Call `iris_edit_image` with `source_artifact_id` and a focused modification prompt, optionally an explicit model. The original stays intact and the edited Artifact records its source.
+3. Inspect the new Artifact ID only when review is requested. Preserve the Task ID if acceptance or delivery is uncertain; do not repeat the edit automatically.
+
 ## 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`.
@@ -18,7 +24,7 @@ Read only the section matching the chosen workflow. Keep paid steps bounded by t
 
 ## Summarize a video, then narrate
 
-1. Call `iris_media_summarize` with `transcribe=true` unless the user wants visual-only analysis.
+1. Call `iris_media_summarize` with `video_path` and `transcribe=true` unless the user wants visual-only analysis. If Core frames already exist, use their `frame_artifact_ids` instead and optionally provide `transcribe_text`; omit `transcribe=true` and sampling options for existing frames.
 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.

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

@@ -22,6 +22,7 @@ Ask one concise question only when a missing reference, target state, theme, or
 ## Prepare the inputs
 
 1. Identify each image source:
+   - Existing Core image: pass `artifact_id` to look/locate/OCR. Crop and pixel diff still need a supported path or attachment; export the Artifact explicitly if those steps require it.
    - Host absolute path: pass `image_path`.
    - Current-session or Iris-produced attachment: pass `attachment_id`.
    - Browser-local path, `content://` URI, or ordinary web URL: do not assume the host can read it. Ask for an upload or a host-accessible file.
@@ -45,7 +46,7 @@ When raw HTML needs capture, call `iris_html_screenshot` with the same HTML wrap
 
 ### 2. Inspect semantics
 
-Inspect the current and reference images separately. Call `iris_look_at_image` for a host path and `iris_relook_attachment` for an attachment.
+Inspect the current and reference images separately. Call `iris_look_at_image` for a Core Artifact ID or host path and `iris_relook_attachment` for an attachment.
 
 Each vision call sees only one image. Ask the same structured questions for both images:
 

package/CHANGELOG.md

@@ -4,6 +4,102 @@
 
 ## [Unreleased]
 
+后续未归入版本的变更在此记录。
+
+## [0.2.1] - 2026-10-09
+
+0.2.1 的更新重点是 **完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。模型发现与能力分类、模型级图片协议、视觉输入和作品管理共同支持这套流程。要求仍为 Node.js ≥ 22.0.0，DSH 插件仅支持 `0.2.0-rc.2`；包名、配置版本和生产依赖保持不变。完整范围见 [0.2.1 发布说明](docs/releases/0.2.1.md)。
+
+### Added
+
+- 生图模型可独立设置 `imageProtocol`，分别选择 DashScope、OpenAI Images、聊天生图或 Responses 生图；省略或 `auto` 时继承账号默认。同账号的模型可使用不同接口，生成、实测和恢复按实际协议绑定，不扫描接口或自动探测。
+- 聊天生图兼容非流式 Chat Completions 图片消息；Responses 支持同步单图、已完成的 `image_generation_call` 及网关图片消息。生成结果按真实字节保存为 PNG/JPEG/WebP Core Artifact，MIME、后缀和内容哈希一致。纯文字 200、缺图或未完成响应不会宣称成功或自动重提。
+- Artifact ID 聊天改图：DSH `iris_edit_image`、Core 图片卡“改图”与 CLI `run image` 的 `source_artifact_id` 共用 `openai-chat-images`。修改版另存为新 Artifact，记录 `derived-from` 及来源引用，原图保留；编辑池只选择聊天生图模型。详见 [Artifact 聊天改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。
+- 独立视觉 CLI：`vision look / locate / ocr / summarize`，支持严格显式模型选择、JSON/文本、结果文件和摘要拼图输出；DSH 与 CLI 复用共享视觉业务。纯视觉不创建 Task/Artifact，主动音轨转写使用 Core。
+- 看图、定位和 OCR 支持 `artifact_id`；视频摘要支持 `frame_artifact_ids`。只读核验 Core 原字节、MIME 和哈希，不要求原文件或临时导出；已有视频帧无需再次抽帧或 ffmpeg。
+- 账号与模型可配置 `visionInput.maxBytes/maxDimension`，模型逐字段覆盖账号，默认发送预算 8 MiB。工作台和 CLI `models vision-input` 可设置或恢复继承；看图、OCR 分块、定位和聊天改图按实际候选准备发送副本，Core 原图、下载与哈希不变。
+- 工作台统一 Core/旧版图片、视频、音频和文本，每页 24 项，支持媒体、来源和产物类型过滤、真实匹配计数。Core 图片卡直接看图/OCR/改图，识别结果可取消、复制和下载，并明确 OCR 部分完成。
+- 作品详情、显式跨页选择、ID 复制与混合来源 ZIP 下载，单次最多 200 项、下载上限 128 MiB。Core 删除先预览，再确认移入可恢复回收区；恢复不覆盖冲突文件。详见 [工作台作品管理](docs/WORKBENCH_ARTIFACTS.md)。
+- CLI 补齐 S2V 数字人视频、HTML 截图、账号/模型/能力分配管理、模型发现与显式实测、有界 `task wait`、分页过滤、批量查询/导出，以及 JSON 文件和 stdin 输入。
+- CLI `core delete/cleanup/transactions/restore` 提供默认预览、引用和活跃任务保护、明确选择后的隔离、哈希核对恢复及失败补偿；不提供永久 purge。
+- 对话泡泡增加本次改写规则、原样前缀/后缀、“只组装”、可编辑结果和原文/改动对照。规则按次传入，v1 配置保持不变；未扩展后续独立提示词优化系统。
+
+### Changed
+
+- 提示词优化、单图看图/重看、OCR、定位、视频拼图摘要及生成后自述迁入共享 Text/Vision Model Ports。准备与候选共用整体预算，严格检查正常终态；取消、超时、截断或协议错误停止后续生成，超长正文明确失败。
+- OCR 整次操作最多 32 块、64 次生成、120 秒；先按转正后的长图切片，再按候选预算处理每块，记录实际发送尺寸与字节数，缩小时提示细字风险，区分完成、部分完成和失败。
+- 定位显式要求模型返回 0–1000 归一化坐标，依据实际发送尺寸和 EXIF 方向换算回原图像素，向外取整供裁剪；接受经核验的 DSH 附件规范化，不猜测返回坐标域。
+- 模型路由区分短时限流和明确耗尽。短时 429 按 `Retry-After`（默认 60 秒）冷却，以琥珀色显示；到期只恢复候选资格，不自动验证。明确免费额度或预算耗尽以红色持续停用至手动实测成功，重启后仍跳过。DSH、CLI、OCR 共用账号 × 模型规则。
+- S2V 首帧与音频迁入共享 Core Attempt 上传链，各候选使用自己的账号；HTML 截图经独立 Chromium Browser Port 或 DSH 宿主保存 Core PNG。配置写入使用私有备份、原子替换和竞争写保护。
+- 修改模型图片协议只使对应生图验证失效，不解除限流或耗尽停用；发现保留手工能力、协议覆盖和输入预算。原图引用参与 Core 删除与清理保护。
+
+### Fixed
+
+- 修复 4K 生图响应的 base64 校验触发调用栈溢出，保留原字节交付与字符、padding 校验。
+- 修复视觉探针图片过小造成的能力误判，改用 128×128 红色 PNG。
+- 修复 OCR 显式 `overlap: 0` 被入口默认值覆盖，以及失败块导致后续原段号丢失。
+- 修复视频摘要时间戳标签未绘制、十帧以上按文件名字典序排列造成的时序错乱；交付与模型输入使用同一张拼图。
+- 保护提示词写回时的新草稿、忙碌状态和结构化引用，旧请求迟到结果不覆盖新操作；不支持的显式 reasoning effort 在生成前拒绝。
+- 修正跨平台 CLI 测试的文件 URL、路径、权限与信号断言；缺少可选 ffmpeg/ffprobe 时只跳过相应视频段。
+
+### 已知限制
+- 浏览器/移动端完整作品管理，以及真实异步任务重启后的 CLI 接管尚未完成验收；已有本地测试和 rc.2 服务隔离检查不替代这些验证。
+- Responses 当前仅同步单图；聊天改图不支持 mask、多参考图或连续编辑历史。独立 Images 编辑与原生 Gemini/Fal 协议未在本版接入。
+
+### 后续方向
+
+- 继续适配其他协议，并规划 Music 音乐生成功能；均属于后续工作，不纳入 0.2.1。详见 [路线图](docs/ROADMAP.md#后续功能方向)。
+
+## [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
@@ -171,7 +267,9 @@
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...v0.2.1
+[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

package/README.en.md

@@ -3,22 +3,22 @@
 </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>
 
-<p align="center"><strong>A multimodal media production runtime · currently shipped as a DeepSeek Harness plugin</strong></p>
+<p align="center"><strong>A multimodal media production runtime · DSH plugin and standalone CLI</strong></p>
 
 <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>
 
-dsh-iris gives agents and the Iris workbench image, video, speech, and visual understanding capabilities, and it can optimize any draft directly in the DSH composer. It connects to Alibaba Cloud DashScope (Bailian) and to OpenAI Images–compatible services. Configuration and task management live in the Iris workbench, and a floating Iris bubble in the bottom-right corner is the quick entry point.
+dsh-iris gives agents, the Iris workbench and a standalone CLI image, video, speech and visual understanding capabilities. Each image model can use DashScope, OpenAI Images, chat image generation or Responses. Shared Core Artifacts connect generation, vision, OCR and chat editing. The DSH workbench provides configuration and task management, while the 🫧 bubble offers draft optimization in the composer.
 
 ## A real generation example
 
@@ -44,7 +44,39 @@ 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 0.2.1 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, completing the OpenAI-compatible image and vision workflow. Core internals have not been frozen as a public SDK.
+
+> Version support: Iris `0.2.x` 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.
+
+## What's new in 0.2.1
+
+**Complete the OpenAI-compatible image and vision workflow:** image generation → Core Artifact → vision/OCR by ID → chat editing → new Artifact, shared by the CLI and DSH workbench.
+
+- **Models and protocols:** discover models and classify capabilities, then choose image protocols per model; models within one account can use Images, chat or Responses interfaces.
+- **Image delivery:** preserve PNG/JPEG/WebP bytes and handle large base64 image responses.
+- **Artifact editing:** edit from a Core image card, `iris_edit_image`, or the CLI; save a linked new image while preserving the source.
+- **Standalone vision:** look, locate, OCR and video summaries with explicit model selection and direct image/frame Artifact inputs.
+- **Input budgets:** configure account/model sending limits, preserve originals, report OCR resizing and map locate coordinates to source pixels.
+- **Library and CLI management:** pagination, filters, selection across pages, ZIP downloads and recoverable Core deletion; S2V, HTML screenshots, configuration and bounded waiting.
+- **Model recovery:** amber for temporary 429 cooldown; red for confirmed quota or budget exhaustion until a manual test succeeds.
+
+See the [0.2.1 release notes](docs/releases/0.2.1.md) and [CHANGELOG](CHANGELOG.md) for scope and pending checks.
+
+Future work includes additional protocol adapters and **music generation**; see the [roadmap](docs/ROADMAP.md#后续功能方向).
+
+## Two ways to use Iris
+
+| | Path A: DSH plugin | Path B: Headless CLI |
+|---|---|---|
+| 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) | Explicit `task observe`; 0.2.1 also offers bounded `task wait` |
+| 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,18 +86,58 @@ Early versions read models and credentials from the maintainer's local ai-paint
 
 ## Quickest start
 
-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:
+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.1` | 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.1
+
+Install the pinned release into your Web profile:
 
-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`.
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1
+dsh web
+```
+
+The plugin loads on the next DSH start. The web UI defaults to `http://127.0.0.1:3080`; open the complete URL if startup output includes authentication parameters. Reload the backend and refresh the web client after updating.
+
+### Standalone CLI: install 0.2.1
+
+Install in your own project without DSH:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.1
+npx dsh-iris --help
+```
+
+### Choosing a version in dsh-market
 
-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).
+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.1 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 provider base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, image protocol selection, and failover notes are in the [user guide](user_guide.md) (Chinese).
 
 Once configured, minimal instructions can be as simple as:
 
@@ -77,6 +149,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)
@@ -93,20 +167,29 @@ DSH profiles and plugin commands follow the [official installation docs](https:/
 
 ## 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.1 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
+- `ffmpeg` and `ffprobe` for extracting frames or summarizing a video file; summaries of existing Core frames need neither
 
 After installing the plugin, add a provider in the Iris workbench and assign models to the capabilities you need. Provider keys are kept in Iris's host-side configuration; on POSIX systems, Iris's own directories and files are tightened to `0700` and `0600` respectively, and neither the UI nor the API ever returns full keys. On Windows, file modes are not equivalent to ACLs — keep relying on your user directory and system account permissions.
 
 ## 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. Iris 0.2.1 server registers 15 agent tools, including image editing, 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.
+
+| 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 |
+| `0.2.1` | Only `0.2.0-rc.2` | Installed-service checks cover 15 tools and 31 boundaries; complete browser/mobile and real asynchronous restart acceptance remain pending |
 
-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.
+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.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.
+Iris 0.2.x 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
 
@@ -115,6 +198,7 @@ Iris 0.1.4 explicitly supports the two verified DSH windows `>=0.1.2-rc.1 <0.1.3
 | Tool | Purpose |
 |---|---|
 | `iris_draw_image` | Generate images from a prompt |
+| `iris_edit_image` | Edit a source Artifact into a new image with a chat image model, preserving provenance |
 | `iris_generate_video` | Text-to-video, image-to-video, or S2V digital-human video |
 | `iris_speak_text` | Synthesize speech from text |
 | `iris_transcribe_audio` | Transcribe audio to text |
@@ -141,6 +225,12 @@ Iris 0.1.4 explicitly supports the two verified DSH windows `>=0.1.2-rc.1 <0.1.3
 
 ## File inputs
 
+Look, locate and OCR accept a local path, session attachment or Core image `artifact_id`; summaries can reuse `frame_artifact_ids`. Artifact inputs are read-only and checked against their MIME type and content hash. PNG/JPEG/WebP inputs need no manual JPEG conversion. See [vision CLI](docs/VISION_CLI.md).
+
+Look, OCR chunks, locate and chat editing prepare sending copies using account/model budgets, with an 8 MiB default. Core originals, downloaded dimensions and hashes stay intact. OCR reports resizing and small-text risk; locate returns source-pixel coordinates. See [input budgets](docs/CLI_MANAGEMENT.md#看图输入预算).
+
+Chat editing uses a source Artifact ID and saves a linked new image; it requires a model configured for chat image generation. See [Artifact editing](docs/CLI_MANAGEMENT.md#artifact-聊天改图) and [workbench management](docs/WORKBENCH_ARTIFACTS.md) for filtering, selection, downloads and recovery.
+
 Iris accepts three file sources, in the recommended order:
 
 1. **Browser upload** — best for local files and cross-environment access; 64 MB per file.
@@ -151,15 +241,17 @@ Uploads are stored under `$DSH_HOME/iris/v1/uploads/` and kept for 7 days by def
 
 ## Conversation prompt optimization
 
+The 0.2.1 adds per-operation rules, assembly without a model call and editable comparisons. Rules are not persisted and no standalone prompt CLI is added. See the [prompt optimizer guide](docs/PROMPT_OPTIMIZER.md).
+
 Iris adds a borderless, text-free “🫧” control directly to the DSH composer, so the workbench does not need to be open. It opens a translucent glass panel with background blur and soft depth; on narrow screens and Android browsers it becomes a safe-area-aware, internally scrollable bottom sheet to prevent overlap and overflow. It reads only the current unsent plain-text draft and offers general, image, video, and start-to-end-frame video targets. The result is previewed first and is written back only after confirmation; Iris never sends it automatically. Drafts containing structured `@` or `/` references are left untouched for now so their identities are not lost.
 
 By default, the optimizer uses the model selected for the current session and falls back to DSH's default model when the session has none. The request carries no chat history, tools, attachments, or workspace content—only the current draft and target template. To prevent reasoning tokens from exhausting the generation budget before visible text is complete, `generation.reasoningEffort` defaults to `off-if-supported`: reasoning is disabled only when DSH model metadata explicitly advertises such an effort; otherwise the provider default is used, and the session High/Low setting is not inherited. JSON may select `provider-default`, `inherit`, or an exact effort ID advertised by the model. For predictable cost and latency, use a `fixed` route with a lightweight non-reasoning model. You can also export `prompt-optimizer.json`, change `route.mode` to `fixed`, name another `provider` and `model` already registered in DSH, and import it again. “Reset to defaults” restores Iris's built-in prompt, target templates, session-model routing, and generation settings. The composer control can be disabled independently and re-enabled from the Iris workbench; disabling it does not stop the workbench, agent tools, or task runtime. An optimization call may incur charges from the selected text model.
 
 ## 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).
 
@@ -169,9 +261,9 @@ Transcription is a separate `transcribe` capability and does not consume the TTS
 
 ## 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.
+The workbench and main bubble show gray for unconfigured, blue for unverified, green for success within seven days, and muted red for authentication or permission failures. The 0.2.1 also shows amber for temporary 429 cooldown and bright red for confirmed free quota or budget exhaustion, with a reason and recovery condition.
 
-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.
+Iris performs no background probes. Temporary 429 responses use `Retry-After`, or a 60-second default cooldown. Expiry restores candidate eligibility without a verification request. Confirmed free quota or budget exhaustion persists across restarts until an explicit model test succeeds; test buttons remain available. Vision, image, and TTS have built-in test samples; video and transcription tests require real input through the CLI. Network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance do not overwrite recent success evidence. Host Doctor only checks loading and host ports. See [Provider and capability health](docs/PROVIDER_HEALTH.md).
 
 ## Offline diagnostics
 
@@ -184,7 +276,7 @@ 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).
+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, current 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
 
@@ -202,34 +294,35 @@ Runtime data lives under `$DSH_HOME/iris/v1/` by default:
 |---|---|
 | `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 |
+| `core-v0/` | New tasks, attempts, Artifact objects, manifests and recoverable quarantine transactions |
+| `tasks.json` | Legacy task metadata and attachment indexes; up to 500 records |
+| `artifacts.json` | Legacy work-library index and random access tokens; no prompt, provider, or task relationship |
+| `outputs/` | Legacy generated and processed media |
 | `uploads/` | Temporary copies of browser uploads |
 
 On first load, 0.1.1 tightens POSIX permissions across an existing `$DSH_HOME/iris/v1/` tree without modifying file contents or following symlinks. Large media downloads stream to a private temporary file and are moved into place atomically, instead of loading a whole video into memory.
 
 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.
+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/`. Legacy deletion removes actual files with separate confirmation; see [Work library v0](docs/ARTIFACT_LIBRARY.md). Core deletion uses preview and recoverable quarantine; see [workbench management](docs/WORKBENCH_ARTIFACTS.md). Favorites, tags and search remain future work.
 
-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.
+Legacy media links carry random capability tokens. Core media uses random Artifact IDs and host/browser origin guards. 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 or the minimal work-library index.
+- Legacy media links use random capability tokens; Core media reads verify Artifact content hashes. A host allowlist does not replace user authentication.
 - Iris provides no account system of its own; multi-user isolation and access control are the responsibility of the DeepSeek Harness deployment.
 
 ## Known limitations
 
 - `sharp` bundles native components; glibc Linux, Windows, and macOS are the primary targets. Non-standard environments such as bare Termux may need extra work.
-- Video frame extraction and video summaries require system-installed `ffmpeg` and `ffprobe`.
+- Video-file frame extraction and summaries require system-installed `ffmpeg` and `ffprobe`; summaries of existing Core frames need neither.
 - HTML screenshots load no remote scripts, fonts, or images; inline the resources you need first.
 - Under WSL, containers, and remote deployments, browser paths usually cannot be handed to the host directly — prefer uploading files.
 - Provider model lists are candidate sets only; whether a model truly supports a capability is settled by real calls.
@@ -243,7 +336,7 @@ When the plugin is enabled, it automatically registers the two bundled skills th
 | [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | Combine screenshots, semantic inspection, element grounding, cropping, and pixel comparison into evidence-based UI acceptance |
 | [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Chain two or more Iris tools into media workflows: inspect-then-draw, image-to-video, video summary with narration, S2V, and more |
 
-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.
+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 Iris tools still load on their own.
 
 For deterministic selection, invoke either skill with DSH's `/name` form:
 
@@ -263,9 +356,9 @@ 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.
+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 first from `docs/releases/<version>.md`, otherwise from the matching CHANGELOG section), and npm publish happens when an `NPM_TOKEN` secret is configured. No local GitHub credentials are needed.
 
 ## Documentation