dsh-plugin-deck-studio 0.2.2 → 0.2.4

package/seeds/docs/manual.md

@@ -0,0 +1,258 @@
+# Deckline 使用手册 · 每个按钮都算数
+
+> 这一份是**操作手册**：按界面区域逐个说明按钮做什么、什么时候用、点了之后会发生什么。
+> 第一次用先看 **§2 跟 Agent 怎么说**——多数事情是一句话的事，按钮只是补充。
+> 截图上的数字圈旁边直接标了说明框（不用来回对照），下面仍保留编号清单，方便搜索和核对；界面改版后跑
+> `npm run manual:shots` 会重出图并校验编号。
+> 安装见 [install.md](install.md)，风格清单见 [styles.md](styles.md)，示例 deck 的产出过程见 [sample-deck.md](sample-deck.md)。
+>
+> 截图全部来自仓库内置示例 deck（`samples/deckline-intro`），不含任何客户素材。
+
+## 0. 先记住三件事
+
+1. **对话在 Chat 里，deck 在工作区里。** 左侧是 DSH 原生 Chat（跟 Agent 说话的地方），中间是 deck 工作区，
+   右边是资料库 / 上下文 / 页面属性 / 设置。所有改动都有 script、diff、revision、治理文档撑底。
+2. **出图以页为单位。** 工具一次出一页，但你可以直接说「出 P04–P06」或「整份都出」，Agent 会连续出完，不用每页等确认；
+   每页保留 prompt、图片、版本、QA 与事件，不满意就再出一版，旧版不丢。
+3. **源目录只读。** 受控 deck 的源文件不会被改写；所有产物落在本机 `.deck/`（已 gitignore，不进仓库）。
+
+找不到按钮时：左导航最下面的 **使用手册** 就是这份文档（带截图，可以在应用里直接搜读）；
+也可以直接在左侧 Chat 里问「怎么导出 PPTX」「换风格怎么弄」——Agent 会查内置 FAQ 再按当前界面回答。
+
+## 1. 首页
+
+![图 1 · 首页：deck / 风格 / 资源 / 会话](assets/screenshots/manual/01-home.png)
+
+1. **＋ 新建 Deck** —— 打开新建弹窗（见 §10），填主题、受众、页数、风格后建 deck。
+2. **Decks** —— deck 列表。每张卡显示页数、治理分数、关联风格、规则 chip 和 9 份文档状态圆点。
+3. **Designs** —— 风格清单：内置预设 + 自己登记的风格，点卡片看样张，眼睛图标预览、垃圾桶删除（仅本机新建的）。
+4. **资源库** —— logo / 头像 / 二维码等素材：`<dataRoot>/resources/` 是**共享资源库**（所有 deck 都能看到），
+   deck 自己的 `resources/` / 源 `assets/` 也会自动登记；点开预览。放图后刷新即出现，白色 logo 缩略图会自动加深底。
+5. **Conversations** —— 会话列表：哪个 Chat 会话绑定了哪个 deck / design，点一条继续那段对话。
+6. **deck 卡片** —— 点卡片进入工作区；卡片右上角垃圾桶只对本机新建 deck 出现（受控源 deck 没有）。
+
+## 2. 跟 Agent 怎么说（最常用）
+
+左侧 Chat 里说人话就行，不用记工具名。想让 Agent 干得准，一句话里尽量带三样：**指哪页**（P03 / P04–P06 / 整份）、
+**要什么结果**（改内容 / 出图 / 换风格 / 补文档）、**参照什么**（别的页、材料、风格、参考图）。
+批量不用一页一页来：点名多页或整份，Agent 会按页序连续做完，只在关键处停下来问你。
+
+### 2.1 开工与起稿
+
+| 你说 | Agent 会 |
+|---|---|
+| 「先读材料，说说这份 deck 你打算怎么讲，先别提案」 | 读 intent / 材料 / 项目规则 → 返回故事线判断，不动 script。 |
+| 「按这个思路写 10 页 script，受众是…，每页 3–5 句」 | 写逐页 script（标题 / 副标题 / 正文 / 画面要求）→ 出 diff 等你确认。 |
+| 「P01 先给我 3 个不同角度的标题，我选一个」 | 只对 P01 给候选，不落版。 |
+| 「先列个目录：每页一句话，我改完你再展开」 | 只给页面清单和一句话主张，不写正文。 |
+
+### 2.2 改内容（单页 / 多页 / 整份）
+
+| 你说 | Agent 会 |
+|---|---|
+| 「P03 正文太长，压到 3 句，保留 47% 这个数字」 | 只改 P03 的正文 → 提案 diff → 你确认后落版。 |
+| 「P04–P06 都改成同一套三段式结构」 | 批量提案这三页 → 一页一条 diff，确认后一起落版。 |
+| 「整份把『赋能』换成更具体的动词」 | 全文提案，列出改了哪几页、哪几句。 |
+| 「P07 加 2023→2025 的对比，材料里没有的数字别编」 | 查材料 → 有依据才写，没有就列成问题问你。 |
+| 「P02 和 P03 合并，别丢信息」 | 先给合并方案 + 新页文案，确认后再落版。 |
+
+### 2.3 出图（按页，可点名批量）
+
+| 你说 | Agent 会 |
+|---|---|
+| 「P03 出图，画面是……」 | 单页出图，新版本，旧图保留。 |
+| 「出 P04–P06」/「整份都出」 | 按页序连续出完，不用每页等确认；失败的页如实报哪几页没成。 |
+| 「P05 重出，画面更简洁、标题更大」 | 改这页画面要求 / prompt → 新 revision。 |
+| 「还没图的页按顺序补上」 | 只补没图的页，不动已有图。 |
+| 「先用自动草稿出一版看看方向」 | 没有画面要求也能出：系统用标题 / 正文拼 draft prompt 并标注 draft。 |
+| 「P03 的图修一下：去掉右下角水印，标题再大一点」 | 拿这页最新版本图当底图改局部，出新版本；旧图不覆盖，script 不动。 |
+
+### 2.4 风格与样张
+
+| 你说 | Agent 会 |
+|---|---|
+| 「给我 3 个版面 brief，我选一个，再按选中的连续出样张」 | 先给候选 → 你确认 → 用同一份风格提示词连续出样张。 |
+| 「把这份 deck 换成 FYI 风格」 | 换绑 → 标出画面要求过期的页 → 你确认后重出。 |
+| 「样张太花，收一点，留白多一点」 | 改 styleBrief → 存进 `designs/<缩写>/` → 再出样张。 |
+| 「参考这张图的排版，但别照抄内容」 | 读参考图 → 提炼版面语言 → 先给 brief 再出图。 |
+
+### 2.5 加页 / 删页 / 调结构
+
+| 你说 | Agent 会 |
+|---|---|
+| 「在 P05 后面加一页讲……，我这轮只要这一页」 | 调加页工具 → 给 diff → 确认后落版；只处理新增页。 |
+| 「P08 和 P09 换顺序」 | 调结构工具 → 给 diff 等你确认。 |
+| 「删掉 P11」 | 提案删除 → 确认后落版（受控源只改工作副本，源不动）。 |
+
+### 2.6 治理文档与交接
+
+| 你说 | Agent 会 |
+|---|---|
+| 「把支撑材料补全，没依据的列成问题」 | 读材料 → 填 9 份文档台账 → 没依据的列问题，不编。 |
+| 「导出交接包给我」 | 导出 zip（script + prompts + 每页图 + 9 份文档），并说明哪几页没图。 |
+| 「交付前帮我过一遍审稿和事实核对」 | 逐项核对 → 列出缺项和风险，不替你签字。 |
+
+### 2.7 排错
+
+| 你说 | Agent 会 |
+|---|---|
+| 「这页出图失败，看看为什么」 | 读 QA / 事件 → 说明是 QA 拒绝、节点报错还是 key 没配。 |
+| 「图是旧的，确认现在用的是哪版」 | 读 revision / 事件 → 报当前版本和时间。 |
+| 「为什么导出少了几页」 | 检查每页有没有图，列出缺图页。 |
+
+### 2.8 说清楚 vs 说了等于没说
+
+- 好：「P03 正文压到 3 句，保留 47%」；不好：「帮我优化一下」——Agent 只能反问。
+- 好：「出 P04–P06」；不好：「多出几张」——没点名时它不会自己扩到没说的页。
+- 好：「换 FYI，先给我看受影响的页」；不好：「换个风格」——它会先问你换哪个。
+
+几条行为边界（也是产品硬纪律）：改 script 一定先出 diff、你确认后才落版；出图按页留版本，旧图不覆盖；
+QA 不过会如实说原因，不会绕过；没依据的数字 / 案例不编，会列成问题问你。
+
+## 3. 工作区布局与 Deck tab
+
+> 手册里的 deck 截图从中间栏开始：左栏是 DSH 原生 Chat（见 §0 第 1 条），图里省略，免得把本机会话内容带进手册。
+
+![图 2 · Deck tab 与工具栏](assets/screenshots/manual/02-deck-pages.png)
+
+1. **脚本 tab** —— 切到逐页 script 视图（其余 tab：意图 / Design / 修改日志 / 反馈 / 调研 / 支撑材料 / 审稿 / 事实核对 / 治理）。
+2. **出图节点 / 模型** —— 选这次出图用哪个节点、哪个模型；`key` 徽标只显示是否配好，不显示 key 值。
+   右栏「设置 → 出图节点」也能一键切换（点模型 / 用这个节点），并能新增、编辑、删除节点；下一次出图生效、不用重启。
+3. **内容密度** —— auto / 简洁 / 适中 / 信息密集。决定 Agent 写 script 时每页多少字；`auto` = 由 Agent 按这一页内容判断，默认值。
+4. **＋ 添加页面** —— 在 deck 末尾加一页；可顺手写这一页要讲什么，`发送到 Chat` 让 Agent 接着写，`只复制` 只拿 prompt。
+5. **▶ 全屏演示** —— 从当前页开始一页一屏放映（见 §9）。
+6. **导出 ▾** —— 导出 PDF / PPTX（每页一张整页图）/ 交接包（zip：script + prompts + 每页图 + 9 份文档）。
+   还没出图的页会跳过，状态栏告诉你「N/M 页」和缺哪几页；只有一页都没出图时才会拒绝导出。
+7. **微调 script** —— 打开页面编辑弹窗（见 §11），改这一页的 script / 版式 / 画面要求。
+8. **重新出图** —— 让 Agent 按当前 script 再出一版图（新 revision，不覆盖旧图）。
+
+左栏是 Chat：顶部 `＋` 新开会话、`↗` 独立窗口打开、`▾` 切换已绑定会话。会话与 deck 自动绑定：
+在哪个 deck 里聊，Agent 就操作哪个 deck。点整页图可放大预览，左右翻页看图。
+
+## 4. 脚本 tab
+
+![图 3 · 脚本 tab](assets/screenshots/manual/03-script.png)
+
+1. **Design tab** —— 去 Design 页关联 / 更换风格。
+2. **风格 / 密度说明条** —— 显示当前关联风格、画面要求覆盖了几页、内容密度口径；不在这里改，只用来核对。
+3. **逐页内容** —— 每页一张卡：标题、副标题、正文、画面要求；`提示词` 折叠区是发给模型的 visualBrief。
+   没有画面要求也能直接出图：系统用标题 / 正文拼「自动草稿」prompt 并标注 draft，之后补一条 brief 重出即可（旧图不覆盖）。
+   卡片上的 `正文 xx 字 · 目标 100–200` / `提示词 · 目标 400–600 字` 是按当前内容密度算的达标标记，
+   超出范围会标黄——用来核对「Agent 说改了」和「页面实际内容」是否一致。
+4. **微调** —— 直接改这一页 script（同 §11 的编辑弹窗）。
+
+脚本 tab 还有一批批量按钮：`全部确认落版`（把待确认 brief / 提案一次确认并写回源）、
+`清理旧提案` / `清理过期提案`、`全部驳回`、`让 Agent 按 <风格> 重写这 N 页`（brief 与风格不一致时出现）、
+`按当前密度检查 / 重写`（密度设成固定字数时出现，会把不达标的页列出来让 Agent 批量提案）、
+单行 `确认` / `驳回` / `这一页全部确认`。
+
+## 5. Design tab 与其余文档 tab
+
+![图 4 · Design tab](assets/screenshots/manual/04-design.png)
+
+1. **风格样张** —— 当前风格已出过的样张缩略图，点开看大图；样张墙用于对齐视觉。
+2. **风格选择** —— 从已登记风格里选一个；列表里显示它的缩写、名称、样张数。
+3. **更换到这个风格** —— 换绑（已有图不会重出，但会提示哪些页 brief 过期）。
+4. **解除关联** —— 解除风格绑定，之后只带全局风格。
+
+Design 页还有 `关联到本 deck`（未关联时出现，需二次确认）、`＋ 添加样张`、`打开样张墙（N 张）`、`复制模板`（复制风格 prompt 模板）。
+
+其余 tab 是 9 份治理文档的入口：**修改日志**（每页改了什么、为什么）、**反馈**（用户反馈与处理）、
+**调研**（外部资料台账与引用）、**支撑材料**（数据/图表/引用来源）、**审稿**（交付前意见）、
+**事实核对**（数字与事实对照表）、**治理**（文档齐备度 + 项目规则）。
+
+## 6. 治理 tab
+
+![图 5 · 治理 tab](assets/screenshots/manual/05-governance.png)
+
+1. **治理分** —— 9 份文档齐备度评分，交付前尽量清零缺项。
+2. **复制模板** —— 复制 `deck.rules.md` 模板（项目规则：受众 / 禁忌 / 视觉 / 事实来源，只约束这一个 deck）。
+3. **文档状态行** —— 每份文档的状态（齐备 / 待补 / 草案 / 缺失）+ 缺什么；点开看正文。
+4. **让 Agent 补** —— 让 Agent 读现有材料后起草这份文档（无材料时先 `先在工作副本打骨架`）。
+
+治理页还有 `复制路径`（复制文档工作副本路径）和项目规则只读卡片（已配置 / 未配置 + 模板）。
+
+## 7. 右栏
+
+打开 deck 时右栏默认是 **Inspector**（点中间任意一页也会切过来）；首页默认是 **Library**；手动切到 Library / Context 后会保持你的选择。
+
+- **Library** —— 当前 deck 源目录的文件清单：每项标「必需 / 可选」和用途（`script.md` 是唯一必需；`build/deck.yaml` / `outputs/full/final` / `CURRENT.md` / `feedback.md` 都是可选项，缺失不影响出图和编辑）。
+- **Context** —— 这次会话的上下文：Agent 读过的文档、当前 brief、引用的事实，用来判断「它为什么这么写」。
+- **Inspector** —— 当前选中页的属性：版式、brief、revision、QA 结论；正文框只显示这一页的**正文**（script 里有 `**正文**：` 字段时不会把主张 / 画面说明 / 提示词塞进来，保存也只改这一行）；`保存并 git 提交` 写回工作副本并自动 git，随后回 Deck tab 可 `重新出图`。
+
+### 6.1 设置（出图节点 / 模型 / 尺寸）
+
+设置页就是一条线路的全部配置，小白只要照着中转给的 **4 个信息**填：名称 / 接口地址 / API Key / 模型名。
+平时只显示节点列表；点「＋ 新增节点」或某个节点的「编辑」，下面的表单才展开（图里是收起状态）。
+
+![图 6 · 设置：节点、模型与 key](assets/screenshots/manual/06-settings.png)
+
+1. **当前生效** —— 这个 deck 现在用哪个节点 / 模型出图；切换后下一次出图生效。
+2. **模式** —— `fake` = 占位图，不联网、不花钱（默认）；`real` = 真出图。
+3. **出图尺寸** —— `宽x高`，默认 `2560x1440`。
+4. **＋ 新增节点** —— 展开空表单，加一条新线路；也可以点节点卡上的「编辑」改现有线路。
+5. **出图节点列表** —— 每个节点显示接口地址、模型按钮和「编辑 / 删除」；点某个模型直接切到那条线路
+   （下一次出图生效，不重启），点「用这个节点」用第一个模型；删除只剩一个节点时是灰的。
+6. **key 状态** —— 只显示「已保存 / 未配置」或「来自环境变量」，不会回显明文。
+
+展开后的表单就 4 项：**节点名称 / 接口地址 / API Key / 模型名**。保存后这条线路自动成为当前 deck
+的出图线路（不用再点「用这个节点」）；点「取消编辑」收起表单。key 存本机
+`.deck/render-settings.json`（0600，已 gitignore），界面只显示「已保存」，不回显明文。
+
+`real` 模式要求至少一个节点配好接口地址 + 模型 + key。不想把 key 存本机的，可以展开
+「高级：用环境变量 / key 文件」，填环境变量名或 `KEY=VALUE` 文件路径（二选一）。
+
+设置页保存的节点列表优先于 profile：第一次保存后以设置页列表为准（profile 里新加的节点不再自动出现）；
+key 值只存在本机数据文件里，任何接口都不会回显。
+
+## 8. 全屏演示
+
+`▶ 全屏演示` 进入一页一屏放映：
+
+| 操作 | 效果 |
+|---|---|
+| `↑` `↓` `←` `→` / `PageUp` `PageDown` / 空格 / 滚轮 / 点画面 | 翻页 |
+| `Esc` / `✕ 退出` | 退出演示 |
+| `‹` `›` | 上一页 / 下一页 |
+
+笔记本没有 PageUp/PageDown 也能翻；浏览器不允许真全屏时自动退化成页面内全屏。
+
+## 9. 新建 Deck 弹窗
+
+![图 7 · 新建 Deck](assets/screenshots/manual/07-new-deck.png)
+
+1. **主题 / 标题** —— 必填；会进封面与文档。
+2. **页数** —— 期望页数（1–40，Agent 会按内容微调）。
+3. **内容密度** —— auto / 简洁 / 适中 / 信息密集（同工具栏「密度」）。
+4. **受众 / 用户** —— 讲给谁听（人群、层级、关心什么）。
+5. **想讲什么话题** —— 一两句话的 topic。
+6. **意图 / 带走什么** —— 听完希望大家记住 / 决定什么；越具体，Agent 起稿越准。
+7. **风格** —— 预选登记风格（默认 GRD 渐变极光），也可以先不选、之后再在 Design 页关联。
+8. **创建并开始对话** —— 建 deck + 建会话直接开聊（推荐）；`取消` / `✕` 关闭不留垃圾数据。
+
+## 10. 页面编辑弹窗（微调 script）
+
+| 控件 | 作用 |
+|---|---|
+| 正标题 / 副标题 / 正文 / 提示词 | 直接改这一页的 script 与 prompts。 |
+| `保存并 git 提交` | 写回工作副本 + 自动 git；随后回 Deck tab 可 `重新出图`。 |
+| `重新出图` | 保存后立即让 Agent 出一版新图。 |
+| `取消` / `✕` | 放弃修改。 |
+
+## 11. 项目规则 `deck.rules.md`
+
+每个 deck 可以在源目录放一份 `deck.rules.md`（≤8KB），只约束这个 deck：受众、禁忌、视觉要求、事实来源。
+新建 deck 时自动生成模板，填了才生效；首页用「规则」chip 标出来。
+它**不能**覆盖产品硬纪律（源只读、QA 门禁、不编造、需要你确认），疑似越权内容只会被标出来，不会被执行。
+
+## 12. 数据放在哪
+
+| 路径 | 内容 |
+|---|---|
+| `<源目录>` | deck 源文件（script / intent / prompts / materials…）。受控源只读。 |
+| `.deck/decks/<deckId>/slides/pNN/versions/vNNN/` | 每页每个 revision：`image.png`、`prompt.txt`、`content.json`、`qa.json`。 |
+| `.deck/render-settings.json` | 设置页保存的出图配置（endpoint / 模型 / key 变量名 / 尺寸；不含 key 值）。 |
+| `.deck/*.json` | deck / 风格 / 会话绑定登记表。 |
+| `exports/` | 导出产物（PDF / PPTX / 交接包）。 |
+
+`.deck/` 与 `exports/` 都在 `.gitignore` 里；仓库只带代码、文档、示例与预设风格。

package/seeds/docs/productization.en.md

@@ -0,0 +1,212 @@
+# Productization plan (Deckline · DSH image-deck plugin)
+
+简体中文 · [English](productization.en.md)
+
+> Goal: turn "a DSH plugin that works on Yuna's machine" into a product that **anyone can install in
+> 5 minutes, configure with their own decks and image key, and start using**.
+>
+> This document is the full plan + current-state inventory + phased acceptance. Execution is tracked in
+> `docs/feedback.md` (F-54…F-57) and `tasks.md` (P27).
+
+## 1. Product shape and positioning
+
+- **Shape**: a DSH (DeepSeek Harness) **bundle plugin** + a dedicated profile (`deckline`).
+  Not a standalone app; DSH owns chat / models / permissions, Deckline owns the "full-page image deck"
+  workbench.
+- **One-liner**: turn "who is this for, what is the point, how do slides get made" into a traceable
+  pipeline — discuss in chat → script / intent / governance documents → per-page image prompt →
+  one-page renders + revisions → export / handoff.
+- **Non-goals**: no HTML deck renderer (separate project); no default batch rendering of a whole deck;
+  never modify the user's deck source directory.
+- **Target users**: consultants / trainers / internal communicators / content creators who already use
+  DSH or are willing to install it.
+
+## 2. Current state (available / gaps)
+
+| Capability | Current state | Productization gap |
+|---|---|---|
+| DSH plugin form | ✅ bundle + preset + client panel | Package metadata is clean (MIT / direct name / no personal paths, see §10) |
+| Installation | ✅ three ways: npm direct name / git subdirectory / local clone (`docs/install.md`) | npm not published yet (owner action) |
+| Configuration | ✅ profile patch + `cordis.example.yml` + env conventions (personal paths all moved to the local patch) | Team-shared config templates (Phase 3) |
+| Image key | ✅ `apiKeyEnv` / `apiKeyFile`; UI only shows whether a key is configured | Docs + clearer guidance in the Settings panel |
+| Styles | ✅ add style (paste/upload/drag) + 8 presets | Presets ship with the plugin + one-click import (done) |
+| Data | ✅ `.deck/` fully gitignored, source decks read-only | "where is data / how to back up / how to migrate" docs |
+| Verification | ✅ smoke 46 + harness gate + 16-scenario agent eval + real-machine Playwright checks | CI / public fixtures (Phase 1) |
+| Docs | ✅ README (zh/en) + install / styles / sample-deck docs (zh/en) + compatibility matrix | productization English, contributing guide, screenshots (Phase 2) |
+
+## 3. Phased plan (recommended cadence)
+
+### Phase 0 · Installable (v0.1, 1–2 days)
+
+- [x] Plugin package metadata: `repository` / `homepage` / `keywords` / `peerDependencies`;
+- [x] Default config template: `plugin/deck-studio/cordis.example.yml` (decks / projectsRoot / render nodes);
+- [x] Install docs `docs/install.md` (npm / git / local, key config, troubleshooting);
+- [x] README made public-facing (intro / 5-minute install / config / adding a design / styles);
+- [x] Preset styles ship with the plugin: `seeds/styles/*.json` + `seeds/samples/*.jpg` + "＋ Import preset styles";
+- [x] Adding a design supports paste / drag / file picker; existing styles can take more samples;
+- [x] Image key: Settings panel shows nodes + "key configured" + missing-key hints;
+- [x] Moved personal config from the **plugin default patch** into the profile patch (distributable defaults) — migrated and verified via `--dump-config`.
+
+**Acceptance**: a clean machine (macOS/Linux, Node `^22.19` or `≥24` + pnpm + DSH) following the README
+can: start → create a deck → create a style (paste an image) → see key status in Settings → run one render
+in fake mode.
+
+### Phase 1 · Distributable (v0.1.0, ready; release awaits the owner)
+
+- [x] **License: MIT** (owner decision, 2026-10-21) — `LICENSE` in the repo, package metadata aligned;
+- [x] **Direct package name**: `dsh-plugin-deck-studio`, no org / scope; `private: false`;
+- [x] **Public scope** (owner decision): plugin + public docs + preset designs (seeds) + 1 sample deck + 1 sample logo;
+  → `scripts/build-public-bundle.mjs` produces a **whitelisted clean directory** (no internal ledgers / client
+  names / personal paths / git history);
+- [x] Sample logo: `assets/logo/deckline-logo.svg|png` + mark; referenced at the top of README;
+- [x] Sample deck: `samples/deckline-intro/` (10-page Deckline product handbook source + paste-ready
+  walkthrough in `docs/sample-deck.md`);
+- [x] Privacy scan: plugin code sanitized (all client names / personal paths / key names replaced), the
+  bundler has a built-in forbidden-word scan;
+- [x] `CHANGELOG.md` + v0.1.0;
+- [ ] **Publish the repository**: `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`
+  (after owner confirmation; do not push the development repo — its history contains internal process docs and client information);
+- [ ] `npm publish dsh-plugin-deck-studio` (npm account + 2FA required);
+- [ ] Add 3 real screenshots/GIF at the top of README (before going public);
+- [ ] GitHub Actions:
+  - `ci.yml`: `node --check` + smoke (`plugin/deck-studio/verify/smoke.mjs`) + commit message lint;
+  - `release.yml`: `npm publish` on tag (via `NPM_TOKEN` secret);
+- [x] Version compatibility: `peerDependencies` / `engines.dsh` declare `0.1.7–0.2.x`; `docs/compat.md`
+  records two regression batches (0.1.7-rc.2 / 0.2.1-rc.2).
+
+### Phase 2 · Easy onboarding (v0.3, 1 week)
+
+- [ ] First-run wizard: when there are no decks, guide through "new deck / import preset styles / configure key";
+- [ ] "New Deck" form can pick a preset style (currently free-text only);
+- [ ] Style library page: preview / search / tags (business, fancy, Japanese…), apply to a new deck in one click;
+- [ ] Data management: visualize the `.deck` location, backup/export button (zip);
+- [ ] i18n: Chinese + English (DSH itself supports multiple languages) — public docs are bilingual; UI strings pending;
+- [ ] Error reporting: actionable render failure reasons (key / quota / model name / size).
+
+### Phase 3 · Collaborative (v0.4+)
+
+- [ ] Multi-user / team-shared profile config templates (keys never shared);
+- [ ] Style-pack marketplace (community contributes `seeds/styles`, PRs validated for schema + samples);
+- [ ] Render cost estimation / usage stats (per node);
+- [ ] Deck source adapters for more directory conventions (currently scans `outputs/full/final`, `outputs/final`, `pages`, `images`, `exports`).
+
+### Phase 4 · Optional (on demand)
+
+- Desktop build (DSH desktop already exists), Docker image, SaaS hosting;
+- Object storage / image CDN integration (renders go straight to a CDN);
+- HTML deck renderer (separate project, not in this repository).
+
+## 4. How the Git repo goes public (concrete steps)
+
+> Owner decision: **public scope = plugin + public docs + preset designs + 1 sample deck + 1 sample logo**.
+> The current development repo's git history contains internal ledgers (feedback / tasks / client names /
+> personal paths) and **must not be pushed directly**. Generate a clean whitelisted directory, then create
+> a new public repository from it.
+
+```sh
+# 1) Generate the clean directory (whitelist + privacy scan; output in dist/public, gitignored)
+node scripts/build-public-bundle.mjs
+#    ✔ whitelist + privacy scan pass (see script output), no /Users/ paths, no client names, no keys
+
+# 2) Create the public repo (after owner confirmation; account yuna78)
+gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push
+
+# 3) Fill in repo metadata: About = "DSH image deck workbench plugin",
+#    Topics = deepseek-harness, dsh-plugin, image-deck, presentation, deck
+# 4) Tag / release
+cd dist/public && git tag v0.1.0 && git push origin v0.1.0
+gh release create v0.1.0 --notes "First public release: install via dsh plugin add dsh-plugin-deck-studio"
+
+# 5) npm publish (Phase 1)
+cd plugin/deck-studio
+npm publish --access public     # npm account + 2FA required
+```
+
+**Public bundle contents (whitelist)**:
+
+- `README.md` / `LICENSE` / `CHANGELOG.md`;
+- `docs/`: `productization.md` + `productization.en.md`, `install.md` + `install.en.md`, `styles.md` + `styles.en.md`,
+  `sample-deck.md` + `sample-deck.en.md`, `compat.md`;
+- `plugin/deck-studio/`: the plugin itself (host + client + ui + lib + seeds preset styles/samples + verify smoke);
+- `samples/deckline-intro/`: sample deck source (README / intent / script);
+- `assets/logo/`: sample logo (svg + png).
+
+**Not public**: `CURRENT.md` / `HANDOVER.md` / `tasks.md` / `docs/feedback.md` / `docs/architecture.md` /
+`docs/adr/` / `docs/research/` / `fixtures/` (contain local references to client material) / `.deck/` (runtime
+data) / git history.
+
+**Cleanup already done**:
+
+1. Personal paths in `cordis.patch.yml` → profile patch; the repo carries a generic bundle patch + `cordis.example.yml`;
+2. Plugin `package.json`: `private: false`, MIT, direct package name, repository / homepage / peerDependencies;
+3. Plugin code sanitized: client names, personal paths and env var names in `client.js` / `lib/config.js` /
+   `lib/deck-workspace.js` / `lib/render-nodes.js` / `lib/source-adapter.js` / `lib/tools.js` / `verify/smoke.mjs`
+   replaced with generic examples;
+4. The bundler has a built-in forbidden-word scan (client names / `/Users/` / `sk-` / private key names); a hit
+   aborts the build.
+
+## 5. Install and distribution matrix
+
+| Method | Command | For |
+|---|---|---|
+| npm | `dsh plugin --profile deckline add dsh-plugin-deck-studio` | Regular users (after publish) |
+| Git | `dsh plugin --profile deckline add "github:yuna78/dsh-deck-studio#path:/plugin/deck-studio"` | People tracking main |
+| Local clone | `dsh plugin --profile deckline add "$PWD/plugin/deck-studio"` | Developers / customization |
+
+All three land in `~/.dsh/profiles/deckline/`; after installing, users only edit the **profile patch**
+(decks / projectsRoot / render nodes) and never the plugin package — that boundary is what makes
+"anyone can install it" true.
+
+## 6. Configuration conventions (image key)
+
+- Configuration exists in exactly two places: the **profile patch** (structure) and **env vars / key files** (credentials);
+- The structure only holds `apiKeyEnv` (variable name) or `apiKeyFile` (local path), **never a plaintext key**;
+- The workbench Settings panel only shows the `keyConfigured` boolean + source name;
+- Multiple nodes supported (primary / backup / different models), each with its own key;
+- Missing key: fake mode still runs the full flow; real mode reports where to configure it.
+
+## 7. Style ecosystem (the productization differentiator)
+
+- **Preset bundle ships with the plugin**: `plugin/deck-studio/seeds/styles/<ABBR>.json` (definitions with
+  `styleBrief` + `baselineBriefs`) + `seeds/samples/<ABBR>-0{1,2,3}.jpg` (3 baseline samples);
+- **One-click import**: Designs page "＋ Import preset styles", existing abbreviations are skipped (idempotent);
+- **Add your own**: paste/upload/drag in the UI; or drop images into `designs/<ABBR>/`;
+- **Contribute**: a PR adds one JSON + 3 baseline samples (schema: abbr / name / description / constraints /
+  reference / styleBrief / baselineBriefs);
+- Known limitation: samples illustrate a style, not guarantee verbatim reproduction of their text (a general
+  image-model limitation); for exact text, overlay HTML/Mermaid text afterwards.
+
+## 8. Risks and boundaries
+
+| Risk | Description | Mitigation |
+|---|---|---|
+| DSH plugin API changes | The plugin depends on the DSH version | Declared peer range + CI smoke + compatibility docs |
+| Credential leakage | Users paste a key into the patch | Docs stress apiKeyEnv / apiKeyFile; Settings never echoes keys |
+| Runaway render cost | Users batch-render everything | Named batches / whole-deck renders are allowed (per-page revisions, single-page retries); no one-click button, to avoid accidents |
+| Client data | Deck sources may be sensitive | Sources read-only, output local under `.deck`, repo carries no data; export packages sanitized |
+| Model quality | Garbled text, broken layouts | Style prompt constraints + "little text, English" advice + post-edit overlays |
+
+## 9. Milestones (suggested)
+
+- **M1 (this week)**: Phase 0 complete + 8 preset styles imported and usable locally;
+- **M2 (next week)**: repository public + v0.1.0 release + 2 external users install successfully;
+- **M3 (within two weeks)**: npm publish + CI + first-run wizard;
+- **M4 (one month)**: style library page + bilingual UI + community style packs.
+
+## 10. Decisions made (2026-10-21)
+
+| # | Decision | Outcome | Implementation |
+|---|---|---|---|
+| 1 | License | **MIT** | `LICENSE` + package.json `license: MIT` |
+| 2 | Package name | **Direct, no org**: `dsh-plugin-deck-studio` | package.json `name` / `private: false` |
+| 3 | Public scope | Plugin + docs + preset designs + **1 sample deck** + **1 sample logo** | `scripts/build-public-bundle.mjs` whitelist; no internal ledgers or history |
+| 4 | Brand | **Deckline** confirmed (repo name stays `dsh-deck-studio`) | README / UI / logo |
+| 5 | Public account | GitHub `yuna78`; repo `yuna78/dsh-deck-studio` (public) | `gh repo create` + push after owner confirmation |
+
+**Two actions still waiting on the owner**:
+
+1. Confirm going public: run `node scripts/build-public-bundle.mjs`, then
+   `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`;
+2. npm publish: `cd plugin/deck-studio && npm publish --access public` (needs npm login + 2FA).
+
+CI / release / screenshots come in the iterations after this round.