dsh-plugin-deck-studio 0.0.0-stage → 0.2.3

package/seeds/docs/install.md

@@ -0,0 +1,304 @@
+# 安装与配置（Deckline · DSH 插件）
+
+简体中文 · [English](install.en.md)
+
+Deckline（`dsh-plugin-deck-studio`）是 DeepSeek Harness（DSH）的 **image deck 工作台插件**：
+左侧 DSH 原生 Chat、中间整页图片 deck 工作区、右侧资料库 / Designs / 资源库 / 会话。
+它不是独立 App，必须挂在 DSH 的 profile 上运行。
+
+> 目标用户：用 DSH 做内容/演示的人。装完后你可以：读 script 改 deck、按页出图（可点名批量连出）、管理治理文档、
+> 登记自己的设计风格（上传样张），并用 8 个预设风格直接开工。
+
+## 0. 前置条件
+
+| 依赖 | 版本 | 说明 |
+|---|---|---|
+| Node.js | `^22.19` 或 `≥ 24` | 与 DSH 运行时一致；Node 23 不在支持范围 |
+| pnpm | 10+ | DSH 用 pnpm 管理 profile 依赖 |
+| DSH | `≥ 0.1.7 < 0.3`（0.1.5 不支持） | **用 npm 全局安装的发行版**：`npm i -g @deepseek-ai/dsh@0.2.1-rc.2`；已验证 0.2.1-rc.2，见 [compat.md](compat.md)。从源码自编译的 dsh 若缺内置包（如 `@deepseek-ai/dsh-agent-preset`）会启动失败，见 4.3 |
+| 一个 LLM provider key | — | 例：`WOCHENG_API_KEY`（profile 里配置，见 DSH 文档） |
+| 一个 image 节点 key | — | 生成整页图用；可先用 fake 模式体验（见第 4 节） |
+
+```sh
+node -v && pnpm -v && dsh --version
+```
+
+## 1. 安装（三种方式，选一种）
+
+### A. 从 npm 安装（推荐，所有人同一条命令）
+
+```sh
+# 1) 建一个 deckline profile（基于 DSH 自带 web 模板）
+dsh --profile deckline --from-default-profile web
+
+# 2) 装插件；dsh plugin add 会自动把组合包加入 profile 并默认启用
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.3
+```
+
+### B. 从 Git 仓库安装（可选；仓库未公开时需要 GitHub 权限）
+
+```sh
+dsh --profile deckline --from-default-profile web
+dsh plugin --profile deckline add "github:<你的账号>/dsh-deck-studio#path:/plugin/deck-studio"
+```
+
+> pnpm 对 git 子目录的支持随版本变化；如果 `#path:` 报错，用方式 C（clone 后本地安装）最稳。
+
+### C. 本地 clone 安装（开发 / 调试推荐）
+
+```sh
+git clone https://github.com/<你的账号>/dsh-deck-studio.git
+cd dsh-deck-studio
+pnpm install --ignore-scripts   # 可选：只跑插件的话可跳过
+
+dsh --profile deckline --from-default-profile web
+dsh plugin --profile deckline add "$PWD/plugin/deck-studio"
+```
+
+安装完成后检查：
+
+```sh
+dsh --profile deckline --dump-config | grep -n "deck-studio" | head
+```
+
+看到 `deck-studio` 与 `preset-deck-studio` 两行即安装成功。
+
+## 2. 首次配置：decks / 工作区 / 端口
+
+Deckline 的配置都在 **profile patch 层**：`~/.dsh/profiles/deckline/cordis.patch.yml`。
+仓库里给了可直接抄的样例：[`plugin/deck-studio/cordis.example.yml`](../plugin/deck-studio/cordis.example.yml)。
+
+最少需要（追加到 profile 的 `cordis.patch.yml` 末尾）：
+
+```yaml
+# 你的 deck 源目录（只读引用；可以是任意已有 deck 目录）
+- id: deck-studio
+  name: 'dsh-plugin-deck-studio'
+  config:
+    displayName: 'Deckline'
+    userName: ''            # 留空 = 首页只显示「欢迎你」；填了就显示「XX，欢迎你」
+    # 新建 deck 落盘根：留空 = 插件内部 .deck/projects/<id>/source
+    projectsRoot: '/absolute/path/to/your/sharing'
+    decks:
+      - id: my-deck
+        label: '我的 deck'
+        sourceRoot: '/absolute/path/to/my-deck'
+```
+
+> `decks[].sourceRoot` 只读：Deckline 永远不写源目录，编辑产物和版本都在 `.deck/` 里。
+> 没有现成 deck 也可以先用「＋ 新建 Deck」建一个。
+
+### 每个 deck 的项目规则（可选）
+
+在 deck 项目根放一个 `deck.rules.md`，就这份 deck 的创作约束写清楚（受众、禁忌、品牌、必须遵守的事实），
+Deck Agent 每次 `deck_source_overview` 时会读到并遵守：
+
+```md
+# 项目规则
+- 受众：公司内部业务与 IT，不假设技术背景
+- 禁忌：不承诺未经验证的效率数字；不点名真实客户
+- 视觉：米白纸张 + 彩铅，不要 3D
+```
+
+- 只约束**这一份 deck**，不影响其他 deck；不写就等于没有规则（可选能力）。
+- 它**不能覆盖**产品硬纪律（客户源只读 / QA 门禁 / 不编造 / 需用户确认）——冲突时以硬纪律为准，Agent 会说明。
+- 上限 8 KB；读取时不会回写，也不会因为文件内容自动执行任何操作。
+- 不叫 `AGENTS.md`：`AGENTS.md` 属于 DSH 的工作区指令，Deckline 不依赖它（见开发仓库的 `docs/adr/0020`）。
+
+## 2.5 数据在哪里：源 deck / 文档 / 图片 / 导出
+
+Deckline 的数据分两处：**你的 deck 源**（`projectsRoot`，纯 md + 源图）和**运行数据**（`dataRoot`，
+工作副本 / 出图 / 事件）。新建 deck 后找不到文件时，先看这张表。
+
+| 内容 | 位置 | 说明 |
+|---|---|---|
+| 新建 deck 的源文档 | `<projectsRoot>/<目录名>/` | `intent.md` / `script.md` / `style-reference.md`；确认后的 `docs/*.md` 回写到这里；`prompts/`、`pages/`、`outputs/` 同层 |
+| 工作副本 + 治理文档 | `<dataRoot>/decks/<deckId>/docs/` | changelog / feedback / research / materials / review / fact-check 等；确认前只在这里 |
+| script 全文 revision | `<dataRoot>/decks/<deckId>/script/revisions/vNNN.md` | copy-on-write，`current.md` 始终最新 |
+| 出图整页图片 | `<dataRoot>/decks/<deckId>/slides/<pageId>/versions/<vNNN>/image.png` | 每版一目录，同放 `prompt.txt` / `content.json` / `qa.json`；旧版本不覆盖 |
+| 风格样张 | `<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/sample-vNNN.png`（或你放的 `designs/<ABBR>/`） | 界面里导入 / 粘贴的样张 |
+| 导出包 | 浏览器下载目录 | 「导出」生成的 zip（PDF / PPTX / 交接包），不写进上面两处 |
+
+- **`dataRoot` 默认 `$DSH_HOME/deckline`**（通常是 `~/.dsh/deckline`）——不在插件包里，升级插件不会覆盖；
+  可在 profile patch 配 `dataRoot: '/your/path'`，或环境变量 `DSH_DECK_DATA_ROOT` 覆盖。
+- **`projectsRoot`** 决定新建 deck 落在哪；不配置时落在 `<dataRoot>/projects/<deckId>/source`。
+- **受控源 deck 只读**：`decks[].sourceRoot` 指向的已有 deck 目录，插件永远不写。
+- **备份**：把 `dataRoot` 和 `projectsRoot` 一起打包即可（文档 + 图 + 事件都在里面）：
+  ```sh
+  tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<你的 projectsRoot>"
+  ```
+- 工作台「设置」面板会显示当前数据目录；本仓库开发时数据根在仓库 `.deck/`（profile 里显式配置）。
+- **preset 工具实例要和根挂载用同一个数据根**（F-98）：DSH 面板路由与 Agent 工具是两个实例，根挂载里覆盖了
+  `dataRoot` / `projectsRoot` 时，preset 的 `deck-studio-tools` 也要写同一组值（推荐 YAML 锚点），
+  否则新建 deck 只进一边的注册表，Agent 会报「未知 deck：…」。
+
+## 3. 启动
+
+```sh
+dsh --profile deckline --port 13090
+```
+
+浏览器打开终端打印的 `http://127.0.0.1:13090/?token=…`。
+`--port` 可换；不换默认 13090，避免和 DSH web profile 的 3080 冲突。
+
+## 4. 配置生图 key（正式出图必看）
+
+Deckline 支持：
+
+- **fake 模式**（默认，不联网）：出占位 SVG，能完整体验流程；
+- **real 模式**：调用 OpenAI 兼容的 `/v1/images/generations` 节点出真图。
+
+> 插件**不内置任何出图节点地址**（provider 中立）：real 模式必须自己配 endpoint + key，
+> 否则设置面板会提示「还没配地址 / key」，出图会明确报错而不是偷偷打到一个默认节点。
+
+### 4.0 在界面里配（推荐，保存即生效）
+
+不需要改 profile、不需要重启：
+
+1. 打开工作台，进任意 deck（没有 deck 就先新建一个）；
+2. 右栏点 **⚙ 设置**；
+3. 填：**模式**（fake / real）、**生图节点 endpoint**、**模型**、**key 环境变量名**（或 **key 文件路径**）、**出图尺寸**；
+4. 点 **保存并生效**。
+
+保存后写入本机数据目录 `~/.dsh/deckline/render-settings.json`（开发仓库里是 `.deck/render-settings.json`，
+已 gitignore）：节点可直存 API key（0600，界面只显示「已保存」，payload 不回显），也可改用变量名 / key 文件；
+下次启动自动生效，并覆盖 profile 里的 render 配置。
+
+key 仍然只放本机：
+
+```sh
+export DSH_DECK_IMAGE_API_KEY="sk-…"      # 名字和设置页填的一致
+```
+
+> 设置页适合自己用；要把同一套配置分发给团队，再用下面的 profile patch。
+
+### 4.1 用环境变量（最简单）
+
+```sh
+# 生图节点（任意 OpenAI 兼容中转都行）
+export DSH_DECK_IMAGE_ENDPOINT="https://your-image-relay.example.com/v1/images/generations"
+export DSH_DECK_IMAGE_MODEL="your-image-model"
+export DSH_DECK_IMAGE_API_KEY="sk-…"          # 只放在你的 shell / 密钥管理里
+```
+
+### 4.2 用 profile patch（推荐：多节点 + 团队共享配置）
+
+在 `~/.dsh/profiles/deckline/cordis.patch.yml` 里覆盖 `deck-studio` 的 render 配置：
+
+```yaml
+- id: deck-studio
+  name: 'dsh-plugin-deck-studio'
+  config:
+    # …上面的 displayName / decks 保持
+    render:
+      mode: real
+      size: '2560x1440'
+      default: 'main/gpt-image-2.5-sunburst'
+      nodes:
+        - id: main
+          name: '主节点'
+          endpoint: 'https://your-image-relay.example.com/v1/images/generations'
+          # 修图（deck_image_edit）用的 edits 端点；不填就由上面的 endpoint 派生
+          # （/v1/images/generations → /v1/images/edits）。
+          # editEndpoint: 'https://your-image-relay.example.com/v1/images/edits'
+          # 中转只吃 JSON、不收 multipart 时改 json（默认 multipart）
+          # editTransport: 'multipart'
+          # 二选一：环境变量名，或本机 key 文件（KEY=VALUE 格式，chmod 600，永不进 git）
+          apiKeyEnv: 'DSH_DECK_IMAGE_API_KEY'
+          apiKeyFile: '~/.config/image-relay.env'
+          models:
+            - 'gpt-image-2.5-sunburst'
+            - 'gpt-image-2'
+```
+
+要点：
+
+- **key 不进仓库、不进 profile 的明文配置**：配置里只出现 `apiKeyEnv`（环境变量名）或 `apiKeyFile`（本机文件路径）。
+- 工作台「设置」面板会显示每个节点的 **key 是否配置**（只显示布尔值和来源，不显示 key 本身）。
+- 没配 key / 仍是 fake 模式时，设置面板会直接给出提示。
+- 模型名填你的中转实际开放的模型；常见 OpenAI 兼容名 `gpt-image-2` 系列的模型 id 以节点 `/v1/models` 为准。
+- 工作台「设置 → 出图节点」可以直接切换线路，也能**新增 / 编辑 / 删除节点**：填 名称 + 接口地址 + API Key +
+  模型名即可（key 存本机 `.deck/render-settings.json`，0600，不进 git；也可改用 env / key 文件）；
+  切换写当前 deck 的 `render-selection.json`，下一次出图生效，不用重启。
+- **修图**（`deck_image_edit`）需要节点支持 `POST /v1/images/edits`（multipart：`image` + `prompt` + `size` + `model`）。
+  回车节点通常和出图同源；不填 `editEndpoint` 就按上面的规则派生，派生不出来（自定义路径）时工具会明确报错、不猜地址。
+  只吃 JSON 的中转设 `editTransport: 'json'`（底图转 data URL 放在 `image` 字段）。
+
+## 5. 自己加 design（两种方式）
+
+### 方式一：在界面里加（推荐，可以贴图）
+
+1. 首页 → **Designs** → **＋ 添加风格**；
+2. 填名称 / 缩写 / 画面描述（prompt 用）；
+3. 在「样张图片」区 **直接 ⌘V 粘贴、拖入、或点选文件**（png/jpg/webp，可多张，≤12MB/张）；
+4. 创建后会：建风格 + 0 页空白画布 + 一个 design 会话，样张立刻出现在 Designs 卡与预览里。
+
+已有风格想补样张：点风格卡右上角 **眼睛** → 预览弹层底部「＋ 添加样张」，同样支持粘贴 / 选文件。
+
+### 方式二：放文件到磁盘
+
+样张存在 `designs/<ABBR>/` 下（ABBR 是你的风格缩写）：
+
+- 画布目录（推荐）：`.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`；
+- 或任何受控 deck 源里的 `designs/<ABBR>/`（Deckline 会自动扫描并合并展示）。
+
+放完刷新页面即可。支持 png / jpg / webp；命名随意（`sample-01.jpg` 之类便于排序）。
+
+### 用预设风格（不用自己写 prompt）
+
+Designs 页 **＋ 导入预设风格** 会一次导入 8 个自带风格（商务咨询 / 高端深色 fancy / 日系极简 /
+杂志编辑 / 科技蓝图 / 手绘白板 / 瑞士极简 / 渐变极光），每个都带样张，见 [docs/styles.md](styles.md)。
+
+## 6. 排障
+
+| 现象 | 处理 |
+|---|---|
+| 端口被占 | `dsh --profile deckline --port 13100`；或 `lsof -tiTCP:13090 -sTCP:LISTEN` 杀掉旧进程 |
+| 页面 404 / 白屏 | 确认插件组合包已启用：`dsh --profile deckline --dump-config \| grep deck-studio` |
+| 没有「生图」按钮 / 出图失败 | 设置面板看 key 是否配置；确认 `render.mode: real`；节点 endpoint 可 `curl` 通 |
+| 新 deck 目录落错位置 | 配 `projectsRoot`；否则落在插件数据目录 `.deck/projects/` |
+| 数据 / 样张在哪 | 见 §2.5：源 deck 在 `projectsRoot`，工作副本 / 出图在 `dataRoot`（默认 `~/.dsh/deckline`） |
+| 升级插件 | `dsh plugin --profile deckline install <spec>`，或重新 `add` 新版本 |
+
+## 7. 开发者：本地验证
+
+```sh
+node plugin/deck-studio/verify/smoke.mjs        # 契约冒烟 46 项（无需网络与 key）
+node scripts/harness-check.mjs                 # 指令链 / 链接 / 脱敏 / 台账门禁
+dsh --profile deck-studio --no-open             # 本仓开发 profile（端口按本机配置）
+```
+
+插件无第三方运行时依赖（只用 Node 内置模块）；改 `plugin/deck-studio/index.js` 需要重启 profile，
+只改 `ui/` 里的 html/css 会热更新。
+
+## 2.5 首次启动会自动准备好什么（bootstrap）
+
+装完第一次启动（DSH 0.2.x 会先弹一次 Preview Notice，点 **Continue** 即可），Deckline 默认做四件事：
+
+| 现象 | 默认行为 | 不想要怎么办 |
+|---|---|---|
+| 左侧 DSH 外壳栏（工作区 / 会话） | 收起隐藏，只留 Deckline 导航 | profile 里 `hideShellSidebar: false` |
+| Decks 页 | 自动登记 **Deckline 示例手册**（仓库 `samples/deckline-intro`，只读） | 配了任意 `decks[]` 就不登记；或 `bootstrap: false` |
+| 资源库 | 自动拷入品牌素材（logo / mark）到 `<dataRoot>/resources` | 该目录非空时不动；或 `bootstrap: false` |
+| Designs 页 | 自动导入 8 个预设风格（含样张） | 已有风格时不重复；或 `bootstrap: false` |
+| 问候语 / 新 deck 作者 | 首次启动弹「先记个名字」，存 `<dataRoot>/user.json`；首页显示「XX，欢迎你」，新 deck 的 owner / 封面作者默认用它 | 点「稍后」不写；之后可在 profile 里用 `userName` 覆盖 |
+
+自举只在「空」的时候发生，重复启动不会覆盖你已有的内容；想彻底关掉，在 profile patch 里给根挂载加
+`bootstrap: false`（见 `plugin/deck-studio/cordis.patch.yml` 里两项都开了这个开关）。
+
+## 4.3 启动报 `Cannot find package '@deepseek-ai/dsh-agent-preset'`
+
+说明当前跑的不是完整的 DSH 发行版：Deckline 的 preset 子树用的是 DSH 内置包
+`@deepseek-ai/dsh-agent-preset` / `@deepseek-ai/dsh-persona`，它们随 npm 发行版一起安装；从源码 checkout
+或不完整的自编译安装里可能没有。
+
+```sh
+which -a dsh          # 看实际用的是哪个 dsh
+dsh --version
+npm i -g @deepseek-ai/dsh@0.2.1-rc.2   # 用 npm 发行版
+hash -r
+dsh --profile deckline --port 13090
+```
+
+如果必须用源码版 DSH，需要在那个安装里补齐 `@deepseek-ai/dsh-agent-preset` 依赖，或把本插件的
+preset 子树挂载去掉（只保留工作台，不在 Chat 里用 Deck Agent）——不推荐，Deckline 的核心流程依赖 Agent 工具。

package/seeds/docs/manual.en.md

@@ -0,0 +1,294 @@
+# Deckline Manual · Every Button Explained
+
+> This is the **operator's manual**: screen by screen, what each button does, when to use it, and what happens after you click.
+> New here? Read **§2 Talking to the agent** first — most work is one sentence; buttons are the fallback.
+> Screenshots carry a callout box right next to each numbered dot, so you don't have to cross-reference; the numbered
+> list below each figure stays for searching and validation. When the UI changes, run `npm run manual:shots` to
+> regenerate the figures and validate the numbering.
+> Install: [install.en.md](install.en.md) · Styles: [styles.en.md](styles.en.md) · Sample deck: [sample-deck.en.md](sample-deck.en.md).
+>
+> All screenshots come from the built-in sample deck (`samples/deckline-intro`); no customer material is shown.
+
+## 0. Three things to remember
+
+1. **Chat on the left, deck workspace in the middle.** The left pane is DSH's native chat (where you talk to the
+   agent), the middle is the deck workspace, the right pane is library / context / inspector / settings. Every
+   change is backed by script, diff, revision and governance docs.
+2. **Renders are per page.** The tool renders one page per call, but you can just say "render P04–P06" or
+   "render the whole deck" and the agent renders them in sequence — no need to confirm each page. Each page keeps
+   its prompt, image, revisions, QA and events. Re-render whenever you like — old versions are never overwritten.
+3. **Source directories are read-only.** Controlled deck sources are never modified; all output lands in the
+   local `.deck/` workspace (gitignored, never committed).
+
+Lost? The **Manual** item at the bottom of the left nav is this document (with screenshots, readable inside the
+app), or just ask the Chat "how do I export a PPTX?" — the agent looks up the built-in FAQ and answers for the
+current UI.
+
+## 1. Home
+
+![Figure 1 · Home: decks / designs / assets / conversations](assets/screenshots/manual/01-home.png)
+
+1. **＋ New Deck** — opens the new-deck dialog (see §10) where you set title, audience, pages and style.
+2. **Decks** — deck list. Each card shows page count, governance score, linked style, rules chip and nine document-status dots.
+3. **Designs** — style catalog: built-in presets plus your own registered styles. Click a card to preview samples;
+   eye icon previews, trash icon deletes (local decks only).
+4. **Assets** — logos, avatars, QR codes: `<dataRoot>/resources/` is a **shared library** visible from every deck,
+   and a deck's own `resources/` / source `assets/` are registered automatically; click to preview. Drop an image
+   in and refresh; white logos automatically get a dark thumbnail backdrop.
+5. **Conversations** — chat sessions bound to a deck / design; click one to continue that conversation.
+6. **Deck card** — opens the workspace. The trash icon appears only for locally created decks (controlled sources
+   don't show it).
+
+## 2. Talking to the agent (the section to read first)
+
+Just say it in the left chat — no tool names needed. To get precise work, put three things in the sentence:
+**which pages** (P03 / P04–P06 / the whole deck), **what outcome** (edit copy / render / switch style /
+fill docs), and **what to reference** (another page, material, style, reference image).
+Batching needs no ceremony: name several pages or the whole deck and the agent works through them in page order,
+stopping only where it genuinely needs you.
+
+### 2.1 Kick-off and first draft
+
+| You say | The agent does |
+|---|---|
+| "Read the material, tell me how you'd tell this story — no proposals yet" | Reads intent / material / project rules → returns a storyline judgement, leaves the script alone. |
+| "Write a 10-page script along these lines for <audience>, 3–5 sentences per page" | Drafts the page-by-page script (title / subtitle / body / visual brief) → shows a diff for confirmation. |
+| "Give me 3 title options for P01, I'll pick one" | Offers options for P01 only; nothing lands. |
+| "Outline first: one line per page, then expand after I edit" | Returns the page list and one-line claims only. |
+
+### 2.2 Editing copy (one page / several / whole deck)
+
+| You say | The agent does |
+|---|---|
+| "P03 is too long — cut to 3 sentences, keep the 47% figure" | Edits P03's body only → proposal diff → lands after your confirmation. |
+| "Make P04–P06 follow the same three-part structure" | Batch-proposes those three pages → one diff per page → lands together once confirmed. |
+| "Replace 'empower' with something concrete across the deck" | Proposes changes deck-wide and lists which pages / sentences changed. |
+| "Add a 2023→2025 comparison to P07 — no numbers that aren't in the material" | Checks the material → writes only sourced facts, otherwise lists open questions. |
+| "Merge P02 and P03 without losing anything" | Shows a merge plan plus new copy first, then lands after confirmation. |
+
+### 2.3 Rendering (per page, batches welcome)
+
+| You say | The agent does |
+|---|---|
+| "Render P03 — visuals: …" | Renders one page; new revision, old image kept. |
+| "Render P04–P06" / "render the whole deck" | Renders continuously in page order, no per-page confirmation; reports exactly which pages failed. |
+| "Re-render P05 — cleaner, bigger headline" | Rewrites that page's brief / prompt → new revision. |
+| "Fill in the pages that have no image yet" | Renders only missing pages, leaves existing images alone. |
+| "Render a draft version so I can see the direction" | Works even without a brief: builds a draft prompt from title / body and marks it draft. |
+| "Retouch P03 — remove the bottom-right watermark, bigger headline" | Edits the current page image in place (new revision, old one kept); the script is untouched. |
+
+### 2.4 Styles and samples
+
+| You say | The agent does |
+|---|---|
+| "Give me 3 layout briefs, I'll pick one, then render samples continuously" | Offers candidates → after your pick, renders samples with the same style prompt. |
+| "Switch this deck to the FYI style" | Rebinds the style → flags pages whose briefs are stale → re-renders after you confirm. |
+| "Samples are too busy — calmer, more whitespace" | Edits styleBrief → saves under `designs/<ABBR>/` → renders new samples. |
+| "Use this image's layout as a reference, not its content" | Reads the reference → extracts layout language → brief first, render second. |
+
+### 2.5 Adding / removing / restructuring pages
+
+| You say | The agent does |
+|---|---|
+| "Add a page after P05 about …; this round only that page" | Calls the add-page tool → diff → lands after confirmation; touches only the new page. |
+| "Swap P08 and P09" | Calls the structure tool → shows a diff for confirmation. |
+| "Delete P11" | Proposes the deletion → lands after confirmation (controlled sources: working copy only). |
+
+### 2.6 Governance docs and handoff
+
+| You say | The agent does |
+|---|---|
+| "Complete the supporting-materials doc; list anything unsourced as a question" | Reads material → fills the nine docs → lists open questions instead of inventing. |
+| "Export the handoff bundle" | Exports a zip (script + prompts + page images + nine docs) and reports pages without images. |
+| "Run a review and fact-check pass before delivery" | Checks both → lists gaps and risks; doesn't sign off for you. |
+
+### 2.7 Troubleshooting
+
+| You say | The agent does |
+|---|---|
+| "This page failed to render — why?" | Reads QA / events → explains whether QA rejected it, the node errored, or no key is configured. |
+| "The image looks stale — which revision is live?" | Reads revisions / events → reports current version and timestamp. |
+| "Why did the export skip pages?" | Checks which pages have images and lists the missing ones. |
+
+### 2.8 Specific vs useless
+
+- Good: "Cut P03's body to 3 sentences, keep the 47% figure." Bad: "Make it better" — the agent can only ask back.
+- Good: "Render P04–P06." Bad: "Render a few more" — unnamed pages are never touched.
+- Good: "Switch to FYI, show me affected pages first." Bad: "Change the style" — it will ask which one.
+
+Behaviour boundaries (also product hard rules): edits always go through a diff and land only after your confirmation;
+renders keep per-page versions and never overwrite old images; a failed QA gate is reported honestly, never bypassed;
+unsourced numbers / cases are listed as questions, never invented.
+
+## 3. Workspace layout and the Deck tab
+
+> Deck screenshots in this manual start at the middle column: the left pane is DSH's native chat (see §0), omitted
+> from the figures so no local session content ends up in the docs.
+
+![Figure 2 · Deck tab and toolbar](assets/screenshots/manual/02-deck-pages.png)
+
+1. **Script tab** — switch to the page-by-page script view (other tabs: intent / Design / changelog / feedback /
+   research / materials / review / fact-check / governance).
+2. **Render node / model** — which node and model to use for the next render. The `key` badge only says whether a
+   key is configured; it never shows the key.
+3. **Content density** — auto / concise / medium / dense. Controls how much text the agent writes per page;
+   `auto` lets the agent judge each page (the default).
+4. **＋ Add page** — append a page; optionally describe what it should say. `Send to chat` hands it to the agent,
+   `Copy only` just copies the prompt.
+5. **▶ Present** — start a fullscreen, one-page-per-screen presentation from the current page (see §9).
+6. **Export ▾** — export PDF / PPTX (one full-page image per slide) / handoff bundle (zip: script + prompts +
+   page images + nine docs). Slides without an image are skipped and the status line reports "N/M pages" plus
+   the missing ids; only a deck with zero images is refused.
+7. **Edit script** — open the page editor (see §11) to change that page's script / layout / visual brief.
+8. **Re-render** — render a new revision from the current script; the previous image is kept. A page without a
+   visual brief also renders: the system builds a draft prompt from title / body and tags it `draft`, so adding a
+   brief later and re-rendering is the normal path (old images are never overwritten).
+
+The left pane is chat: `＋` new session, `↗` open in a separate window, `▾` switch bound session. Sessions bind to
+the deck automatically — whichever deck you're in is the deck the agent edits. Click a full-page image to zoom and
+page through images.
+
+## 4. Script tab
+
+![Figure 3 · Script tab](assets/screenshots/manual/03-script.png)
+
+1. **Design tab** — go link or switch the style.
+2. **Style / density strip** — shows the linked style, how many pages have a visual brief, and the density setting.
+   Read-only here; change it in the Deck toolbar or Design tab.
+3. **Page content** — one card per page: title, subtitle, body, visual brief. The `prompt` fold holds the
+   visualBrief sent to the image model. The `body N chars · target 100–200` / `prompt · target 400–600 chars`
+   badges show whether a page matches the current density; out-of-range pages are highlighted, so you can check
+   "the agent said it changed it" against what the page actually contains.
+4. **Edit** — edit this page's script in place (same dialog as §11).
+
+Batch actions on this tab: `Confirm all` (confirm pending briefs / proposals and write them back), `Clean old
+proposals` / `Clean stale proposals`, `Reject all`, `Let the agent rewrite these N pages in <style>` (when briefs
+are stale), and per-row `Confirm` / `Reject` / `Confirm this page`.
+
+## 5. Design tab and the other document tabs
+
+![Figure 4 · Design tab](assets/screenshots/manual/04-design.png)
+
+1. **Style samples** — thumbnails of this style's existing samples; click to enlarge. The sample wall is how you
+   align the look.
+2. **Style picker** — choose one of the registered styles; the list shows abbreviation, name and sample count.
+3. **Switch to this style** — rebind the deck (existing images aren't re-rendered; stale briefs get flagged).
+4. **Unlink** — remove the style binding; rendering then uses only the global style.
+
+This tab also has `Link to this deck` (when unlinked, with confirmation), `＋ Add sample`, `Open sample wall (N)`
+and `Copy template` (copy the style prompt template).
+
+The remaining tabs are the nine governance documents: **changelog** (what changed and why), **feedback**,
+**research** (external sources and citations), **materials** (data / charts / references), **review** (pre-delivery
+review), **fact-check** (numbers and claims), **governance** (doc coverage + project rules).
+
+## 6. Governance tab
+
+![Figure 5 · Governance tab](assets/screenshots/manual/05-governance.png)
+
+1. **Governance score** — *handoff completeness* of the nine docs. Missing docs never block rendering or
+   exporting; fill them in only when you actually hand the deck off.
+2. **Copy template** — copy the `deck.rules.md` template (audience / taboos / visuals / fact sources, scoped to
+   this one deck).
+3. **Document rows** — status per document (complete / needs work / draft / missing) plus what's missing; click to
+   read.
+4. **Let the agent fill it** — have the agent draft this document from existing material (or `scaffold in the
+   working copy` first when there's no material).
+
+The tab also has `Copy path` (copy the working-copy path) and a read-only project-rules card (configured /
+not configured + template).
+
+## 7. Right pane
+
+Opening a deck defaults the right pane to **Inspector** (clicking any page in the middle also switches to it);
+the home screen defaults to **Library**. Picking Library / Context manually is remembered.
+
+- **Library** — inventory of this deck's *source* directory. Each row says required or optional and what it is for:
+  `script.md` is the only required file; `build/deck.yaml` / `outputs/full/final` / `CURRENT.md` / `feedback.md`
+  are optional and their absence does not affect rendering or editing.
+- **Context** — what the agent has read this session: documents, current brief, referenced facts. Use it to see
+  why the agent wrote something.
+- **Inspector** — properties of the selected page: layout, brief, revision, QA verdict. The body box shows only
+  this page's body (when the script has a `**正文**` field, claims / visual notes / prompt stay out of it, and
+  saving only rewrites that line). `Save and git commit`
+  writes back to the working copy with an automatic git commit; then re-render from the Deck tab.
+
+### 6.1 Settings (render node / model / size)
+
+One node is just four things; to add a line, fill in: name / endpoint / API key / model names.
+The list is collapsed by default; the form opens when you click "Edit" on a node or "+ New node" (the figure shows the list only).
+
+![Figure 6 · Settings: nodes, models and keys](assets/screenshots/manual/06-settings.png)
+
+1. **Active** — the node / model this deck renders with; a switch applies to the next render.
+2. **Mode** — `fake` = placeholder images, offline and free (default); `real` = actual rendering.
+3. **Image size** — `WxH`, default `2560x1440`.
+4. **+ New node** — opens an empty form for a new line; "Edit" on a card opens it for an existing one.
+5. **Render node list** — each node shows its endpoint, model buttons and Edit / Delete; clicking a model switches
+   this deck to that line (next render, no restart), "Use this node" picks its first model, and Delete is disabled
+   when only one node remains.
+6. **key status** — only "saved / not set" or "from env"; the value is never echoed.
+
+The opened form has just four fields: **node name / endpoint / API key / model names**. Saving makes the line this
+deck's render line automatically (no need to click "Use this node"); "Cancel" collapses it. The key is stored
+locally in `.deck/render-settings.json` (0600, gitignored) and shown only as "saved".
+
+`real` mode needs at least one node with endpoint + model + key. If you would rather not store the key locally,
+open **Advanced: environment variable / key file** and give the env var name or a `KEY=VALUE` file.
+
+Once saved, the settings-page node list wins over the profile; key values stay in the local data file and are
+never returned by any API.
+
+## 8. Fullscreen presenting
+
+`▶ Present` starts a one-page-per-screen presentation:
+
+| Input | Effect |
+|---|---|
+| `↑` `↓` `←` `→` / `PageUp` `PageDown` / space / wheel / click | next / previous page |
+| `Esc` / `✕ Exit` | leave presentation |
+| `‹` `›` | previous / next page |
+
+Works on laptops without PageUp/PageDown; if the browser denies true fullscreen it falls back to an in-page overlay.
+
+## 9. New Deck dialog
+
+![Figure 7 · New Deck](assets/screenshots/manual/07-new-deck.png)
+
+1. **Topic / title** — required; used on the cover and in the docs.
+2. **Pages** — expected page count (1–40; the agent may adjust as content demands).
+3. **Content density** — auto / concise / medium / dense (same as the toolbar control).
+4. **Audience** — who is listening (group, level, what they care about).
+5. **Topic to cover** — one or two sentences.
+6. **Intent / takeaway** — what people should remember or decide; the more specific, the better the first draft.
+7. **Style** — preselect a registered style (defaults to GRD aurora); you can also link a style later in Design.
+8. **Create and start chat** — creates the deck plus a bound chat session (recommended); `Cancel` / `✕` closes
+   without leaving data behind.
+
+## 10. Page editor (Edit script)
+
+| Control | Effect |
+|---|---|
+| Title / subtitle / body / prompt | Edit this page's script and prompt directly. |
+| `Save and git commit` | Write back to the working copy with an automatic git commit; then re-render from the Deck tab. |
+| `Re-render` | Save and immediately render a new revision. |
+| `Cancel` / `✕` | Discard changes. |
+
+## 11. Project rules `deck.rules.md`
+
+A deck can ship a `deck.rules.md` (≤8KB) in its source directory, scoped to that deck: audience, taboos, visual
+requirements, fact sources. New decks get a template automatically — it only takes effect once you fill it in; the
+home screen marks it with a rules chip. It **cannot** override product hard rules (read-only source, QA gate, no
+fabrication, explicit confirmation); suspicious instructions are flagged, never executed.
+
+## 12. Where data lives
+
+| Path | Contents |
+|---|---|
+| `<source dir>` | deck sources (script / intent / prompts / materials…). Controlled sources are read-only. |
+| `.deck/decks/<deckId>/slides/pNN/versions/vNNN/` | per-revision artifacts: `image.png`, `prompt.txt`, `content.json`, `qa.json`. |
+| `.deck/render-settings.json` | render settings saved from the settings pane (endpoint / model / key variable / size; no key values). |
+| `.deck/*.json` | deck / design / session binding registries. |
+| `exports/` | exported PDF / PPTX / handoff bundles. |
+
+`.deck/` and `exports/` are gitignored; the repository only ships code, docs, samples and preset styles.