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

package/lib/watermark.js

@@ -0,0 +1,137 @@
+/**
+ * Logo 水印（F-125）：assets 分类 → 列举可选水印 → 给整份 deck 的页面盖 logo。
+ *
+ * 负责人口径（2026-10-23）：
+ * - assets 里按分类放素材，至少有一类 `logo`，可以放多个；
+ * - 用户跟 Agent 说「我要加水印」，能选哪个 logo；默认盖 **右上角**；
+ * - 每个页面都盖；原图不覆盖——水印产物写新的 revision（vNNN），旧图保留。
+ *
+ * 实现：纯 node（zlib）自己解 / 编 PNG（见 lib/png.js），不引 sharp/canvas。
+ * 页面图与 logo 都必须是 PNG；SVG logo 会明确提示先转 PNG，而不是静默跳过。
+ *
+ * @module dsh-plugin-deck-studio/watermark
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import { compositeLogo, decodePng, encodePng } from "./png.js";
+
+/** 水印位置（默认右上角）。 */
+export const WATERMARK_POSITIONS = ["top-right", "top-left", "bottom-right", "bottom-left", "center"];
+
+export const WATERMARK_POSITION_LABELS = {
+  "top-right": "右上角（默认）",
+  "top-left": "左上角",
+  "bottom-right": "右下角",
+  "bottom-left": "左下角",
+  center: "居中",
+};
+
+const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".svg"]);
+
+/** 资产分类根目录：仓库 `assets/`（按子目录分类，如 logo/）。 */
+export function assetsRootOf(repoRoot) {
+  return join(repoRoot, "assets");
+}
+
+/**
+ * 扫描 assets/ 下的分类与素材。
+ * @returns {{categories: Array<{category: string, items: Array<{id: string, name: string, category: string, format: string, bytes: number, path: string, watermarkable: boolean}>}>}}
+ */
+export function listAssets(repoRoot) {
+  const root = assetsRootOf(repoRoot);
+  if (!existsSync(root)) return { categories: [], root };
+  const categories = [];
+  for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const dir = join(root, entry.name);
+    const items = [];
+    for (const file of readdirSync(dir).sort()) {
+      const ext = extname(file).toLowerCase();
+      if (!IMAGE_EXTS.has(ext) || file.startsWith(".")) continue;
+      const path = join(dir, file);
+      const stat = statSync(path);
+      if (!stat.isFile()) continue;
+      items.push({
+        id: `${entry.name}/${file}`,
+        name: file,
+        category: entry.name,
+        format: ext.replace(".", ""),
+        bytes: stat.size,
+        path,
+        // 只有 PNG 能直接合成（zlib 自己解）；SVG/JPG 明确提示先转 PNG。
+        watermarkable: ext === ".png",
+      });
+    }
+    if (items.length) categories.push({ category: entry.name, items });
+  }
+  return { categories, root };
+}
+
+/** 支持做水印的素材（PNG），供 Agent 选择。 */
+export function listWatermarkAssets(repoRoot) {
+  const { categories, root } = listAssets(repoRoot);
+  const items = categories.flatMap((category) => category.items).filter((item) => item.watermarkable);
+  return { root, categories, items };
+}
+
+/**
+ * 按 Agent 给的名字找素材：id（logo/x.png）/ 文件名（x.png）/ 基名（x）都可以；
+ * 找不到或有歧义都返回候选，让 Agent 能自己纠正而不是瞎猜。
+ */
+export function findAsset(repoRoot, query) {
+  // 找素材时把 SVG/JPG 也算进来：用户报了 SVG 名字时要能明确说「需要先转 PNG」，
+  // 而不是回一句「没找到」。
+  const { categories } = listAssets(repoRoot);
+  const items = categories.flatMap((category) => category.items);
+  const raw = String(query ?? "").trim();
+  if (!raw) return { ok: false, reason: "empty", candidates: items };
+  const needle = raw.toLowerCase().replace(/\\/g, "/");
+  const qualified = needle.includes("/") ? needle : null;
+  const matches = items.filter((item) => {
+    const id = item.id.toLowerCase();
+    const name = item.name.toLowerCase();
+    const stem = name.replace(/\.[^.]+$/, "");
+    if (qualified) return id === qualified || id.endsWith(`/${qualified}`);
+    return name === needle || stem === needle || id === needle;
+  });
+  if (matches.length === 1) return { ok: true, asset: matches[0] };
+  if (matches.length > 1) return { ok: false, reason: "ambiguous", candidates: matches };
+  // 宽松兜底：唯一子串命中
+  const loose = items.filter((item) => item.id.toLowerCase().includes(needle) || item.name.toLowerCase().includes(needle));
+  if (loose.length === 1) return { ok: true, asset: loose[0] };
+  if (loose.length > 1) return { ok: false, reason: "ambiguous", candidates: loose };
+  return { ok: false, reason: "not-found", candidates: items };
+}
+
+/** 把一张页面 PNG + logo PNG 合成水印后的 PNG Buffer。 */
+export function watermarkPng({ pageBuffer, logoBuffer, position = "top-right", opacity = 0.85, scale = 0.14, margin = 0.04 }) {
+  const page = decodePng(pageBuffer);
+  const logo = decodePng(logoBuffer);
+  const { image, placement } = compositeLogo({ page, logo, position, opacity, scale, margin });
+  return { buffer: encodePng(image), size: `${image.width}x${image.height}`, placement };
+}
+
+/** 给 Agent 看的一行位置说明。 */
+export function positionLine() {
+  return WATERMARK_POSITIONS.map((key) => `${key}（${WATERMARK_POSITION_LABELS[key]}）`).join(" / ");
+}
+
+/** 报告里用的相对路径（不把本机绝对路径泄给用户/Agent）。 */
+export function displayPath(repoRoot, path) {
+  try {
+    const rel = relative(repoRoot, path);
+    return rel.startsWith("..") ? basename(path) : rel;
+  } catch {
+    return basename(path);
+  }
+}
+
+/** 读 PNG 文件（水印流程用，统一错误文案）。 */
+export function readPngFile(path) {
+  const buffer = readFileSync(path);
+  if (!buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+    throw new Error(`不是 PNG：${basename(path)}`);
+  }
+  return buffer;
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "private": false,
+  "description": "Deckline：DSH image deck 工作台插件 —— 原生 Chat + 整页图片 deck 工作区 + 设计风格（design）库；出图按页留痕、可点名批量连出，产物本地可追踪。",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deck",
+    "image-deck",
+    "presentation",
+    "slides",
+    "deckline"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.1.7-0 <0.3.0"
+  },
+  "scripts": {
+    "verify": "node verify/smoke.mjs",
+    "prepublishOnly": "node verify/smoke.mjs",
+    "prepack": "node scripts/prepack-assets.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "renderer",
+        "layout",
+        "sidebar"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuna78/dsh-deck-studio.git",
+    "directory": "plugin/deck-studio"
+  },
+  "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",
+  "bugs": {
+    "url": "https://github.com/yuna78/dsh-deck-studio/issues"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0"
+  },
+  "author": "Yuna",
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/",
+    "ui/",
+    "seeds/",
+    "cordis.patch.yml",
+    "cordis.example.yml"
+  ]
+}

package/seeds/docs/assets/screenshots/manual/legend.json

@@ -0,0 +1,12 @@
+{
+  "02-deck-pages": {
+    "1": "脚本 tab",
+    "2": "出图节点 / 模型",
+    "3": "内容密度",
+    "4": "添加页面",
+    "5": "全屏演示",
+    "6": "导出",
+    "7": "微调 script",
+    "8": "重新出图"
+  }
+}

package/seeds/docs/compat.md

@@ -0,0 +1,134 @@
+# DSH 兼容矩阵（定期回归记录）
+
+> 口径：DSH 处于 prerelease 阶段，没有 stable 线；本项目**定期批次**回归，不逐 rc 跟。
+> 每个批次记录：证实的版本、验证范围、断点、复现方式。已知限制与路线见 [productization.md](productization.md) 与 [install.md](install.md)。
+
+## 当前支持声明
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| `peerDependencies["@deepseek-ai/dsh"]` | `>=0.1.7-0 <0.2.0 \|\| >=0.2.0-0 <0.3.0 \|\| >=0.2.1-0 <0.3.0` | 装到 0.3+ 会被 DSH 的 peer 检查拦下 |
+| `engines.dsh` | `>=0.1.7-0 <0.3.0` | 元数据口径，同 peer |
+| `engines.node` | `^22.19.0 \|\| >=24.0.0` | 与 DSH 运行时要求一致；**Node 23 不在范围内** |
+| 已验证版本 | `0.1.7-rc.2`（旧基线）· `0.2.1-rc.2`（2026-10-21：隔离环境 + 本地全局升级后真机回归） | 见下表 |
+
+## 回归记录
+
+### 批次 1 · 2026-10-21 · DSH `0.2.1-rc.2`
+
+隔离环境，不动本机 `0.1.7-rc.2` 与运行中的 deck-studio profile：
+
+```bash
+# 临时安装（Node 必须 ^22.19 || >=24；本机默认 Node 23.11 不满足，用 nvm v24.21.0）
+npm i --prefix /tmp/dsh02 @deepseek-ai/dsh@0.2.1-rc.2
+export DSH_HOME=/tmp/dsh02-home PATH="$HOME/.nvm/versions/node/v24.21.0/bin:$PATH"
+dsh --profile deckline-02 --from-default-profile web --dump-config
+dsh plugin --profile deckline-02 add <repo>/plugin/deck-studio
+dsh --profile deckline-02 --port 13290
+```
+
+| 检查项 | 结果 | 证据 |
+|---|---|---|
+| `dsh -V` / CLI 启动 | ✅ `0.2.1-rc.2` | 需 Node 24（0.2.x 的 `bin.js` 用 `import.meta.main`，Node 23 会静默不执行） |
+| 插件安装（本地 link） | ✅ 无 peer 冲突，进入 `dsh.profile.bundles` | `dsh plugin add` 输出 `+ dsh-plugin-deck-studio link:…` |
+| 组合配置（根 mount / preset / tools） | ✅ `deck-studio`、`preset-deck-studio`、`deck-studio-tools` 均在 `--dump-config` 中 | 无组合报错 |
+| Web 启动 + 插件装载 | ✅ 侧栏出现「Deckline」，`/api/deck-studio.app` iframe 加载 | 截图 `/tmp/f86-02-home.png` |
+| Deckline 首页 | ✅ Decks / Designs / 资源库 / Conversations + 数据（designs 11） | `/tmp/f86-02-app-home.png` |
+| Designs 列表 + 预设风格 | ✅ 11 个风格（含 8 个预设），「导入预设风格」入口在 | `/tmp/f86-02-designs.png` |
+| Design 详情（BIZ / PCL） | ✅ 3/4 张样张、风格定义、样张墙 | `/tmp/f86-02-design-biz.png` |
+| 样张媒体 GET | ✅ 200 / 1,383,788 bytes | `/api/deck-studio.media?…designs%2FBIZ%2Fsample-v001.png` |
+| 设置面板（节点自配口径） | ✅ 显示「生图配置未就绪 / 未配置 endpoint / key 未配置」+ docs 指引 | `/tmp/f86-02-settings.png` |
+| 控制台 / 页面异常 | ✅ 0 console error、0 pageerror | 同上脚本输出 |
+| Agent 工具链路 | ⏭ 未验证（隔离 home 无 LLM key） | 下批用真 key 跑 `S01/S02` + `--only` |
+| 真出图（real render） | ⏭ 未验证 | 需本机节点/key；fake 模式已验证 |
+
+**观察项（不阻塞）**：iframe 内导航时 `/plugins/events`（DSH 的插件事件 SSE）报 `ERR_ABORTED`，
+页面功能与数据均正常，判断为导航时主动中断连接，记录待后续批次复核。
+
+**结论**：`0.2.1-rc.2` 在「插件安装 → 组合 → Web 加载 → Deckline 应用/样张/设置」链路上可用；
+agent 工具链路与真出图待下批补验。支持声明暂不收紧到 0.2.x-only，保持 `0.1.7–0.2.x` 区间。
+
+## 下批要做（每月 / 或 DSH 0.3 发布前）
+
+1. 真出图探活 1 页（0.2.1 上，确认 image adapter 无破坏）；
+2. 合并评估脚本修复：S11「读到的原文含报错字样」误报、S13 台账表解析口径；
+3. 复核 `/plugins/events` ERR_ABORTED；
+4. 若 DSH 发布 0.3.x：先按本表跑一遍，再更新 `peerDependencies` / 本文件 / README 支持声明。
+
+### 批次 2 · 2026-10-21 · DSH `0.2.1-rc.2` 真机 + Agent 链路（本地全局升级后）
+
+批次 1 的隔离环境没有 LLM key，Agent 链路未验证；本机升级到 `0.2.1-rc.2` 后用真 key 补验，同时发现一个
+0.2.x 的破坏性差异并已修复。
+
+| 检查项 | 结果 | 证据 |
+|---|---|---|
+| 真机数据迁移 | ✅ decks 5→7 / designs 11 / conversations 20 均保留 | 升级回归（见下节「本地环境升级记录」） |
+| persona 提示词变量 | ❌→✅ 0.2.x 只注册 `provider` / `model` 两个变量；插件 persona suffix 里的 `{{cwd}}` 使每个 Agent 回合直接 `turn/end` 报 `unknown prompt variable "{{cwd}}"`，Chat 完全不回话 | 会话 `session.v4.jsonl.zstd` 的 `turn/end` error；修复 commit `1dd8695`（改成静态「工作目录是本 deck 仓库根目录，以工具返回路径为准」）+ smoke 增加禁 `{{cwd}}` 断言 |
+| Agent 全场景评估 | ✅ 16 场景中 15 通过（S01–S16） | `.deck/eval/run-20261021-000149/report.md` |
+| S11 假失败 | ✅ 复跑 PASS（eval 误报：`deck_file_read` 读到 `smoke.mjs` 原文里含「未知 deck」字样被当成工具报错） | 临时补丁复跑 `.deck/eval/run-20261021-001453/report.md`；正式修复待评估脚本合并 |
+| S13 新增场景 | ⏭ 非 0.2.1 回归：检查器按标准台账表解析，agent 用自定义台账表 → 解析 0 条 | 同 report.md；属 WIP 场景口径问题 |
+| 工具链路 | ✅ 真实调用 overview / 读文件 / 读文档 / 文档更新 / script 提案 / note_change / style_update | eval 每回合工具序列 |
+| real 出图探活（adapter） | ✅ 2026-10-21 在 DSH 0.2.1 的 Node 24 上跑 `createRealRenderer`：POST 200 / 18.5s，1024×1024 PNG 1.3MB，图片内容与 prompt 一致 | `/tmp/f94-probe/out5/image.png`；探针脚本一次性放 /tmp，不入库 |
+| CDN 下载抖动 | ⚠️→✅ 中转返回 `data[0].url` 走 Cloudflare CDN，本网络下连续 4 次 `ETIMEDOUT` 后第 5 次成功；插件已加**5 次指数退避重试**（`lib/render.js`） | probe 日志 `fetch#2–#6`；smoke 新增重试测试 |
+| smoke / 公开包 | ✅ 47/47；96 文件 / 5.87 MB（含 4 份英文文档） | `smoke.mjs` / `build-public-bundle.mjs` |
+
+**结论**：`0.2.1-rc.2` 上插件与 Agent 链路可用，但 **persona 提示词变量只能用 `provider` / `model`**；
+本仓已修复并加 smoke 防回归；real 出图 adapter 已在 0.2.1 的 Node 24 上以一页 1024×1024 探活通过。
+
+**操作观察（不阻塞）**：13090 重启后约 1 分钟内，`/api/deck-studio.app` 可能还没把 `STATE.data.active`
+挂好（脚本直接 `goto` 会误判「工作台没加载」）；等插件 patch 应用完成或先 warm-up 一次再跑自动化。
+`/plugins/events` 仍是导航时 `ERR_ABORTED`，功能正常。
+
+## 本地环境升级记录（2026-10-21 已执行）
+
+**升级前**：全局 `@deepseek-ai/dsh@0.1.7-rc.2`（2026-09-27 安装），本机默认 Node `v23.11.0`，
+运行中的服务靠 `~/.local/bin/dsh` 启动壳固定 Node `v24.21.0`。
+**升级后**：`0.2.1-rc.2`（npm `latest`），启动壳不变（仍固定 Node 24）。
+
+```bash
+# 备份（仓库外）
+~/dsh-upgrade-backup-20261020/{profiles.tar.gz, dsh-0.1.7-rc.2/}
+# 用 Node 24 的 npm 升级全局包（保持 /opt/homebrew 前缀，启动壳路径不变）
+~/.nvm/versions/node/v24.21.0/bin/npm i -g --prefix /opt/homebrew @deepseek-ai/dsh@0.2.1-rc.2
+# 重启 deck-studio（进程环境带 relay keys，见下）
+cd <repo> && dsh --profile deck-studio --no-open
+```
+
+**回归结果**：
+
+| 检查项 | 结果 |
+|---|---|
+| `dsh --version`（经启动壳） | ✅ `0.2.1-rc.2` |
+| `--dump-config --profile deck-studio` | ✅ 0 stderr，插件/预设/tools 条目不丢 |
+| deck-studio 启动 13090 | ✅ 正常打印 token，无迁移报错 |
+| 既有数据 | ✅ 迁移成功：decks 5 / designs 11 / 资源库 2 / Conversations 20，会话与治理数据都在 |
+| Deckline 应用 | ✅ 首页 / Design 列表 / Deck 工作台（意图/脚本/Design/日志… + image storyboard） |
+| 出图节点 | ✅ 工作台显示「默认节点 / gpt-image-2.5-sunburst 等 3 个模型」；节点 `/v1/models` 探活 200 |
+| 页面异常 | ✅ 0 pageerror；首次加载有 2 条资源 404，二次加载 0 条（判断为瞬时，记录观察） |
+| `/plugins/events` SSE | ⚠️ 导航时 `ERR_ABORTED`（与隔离测试一致，功能正常，继续观察） |
+
+**升级后必须知道的运行要求**：
+- **启动进程要带 relay keys**：`WOCHENG_API_KEY`（LLM，来自本机 `relays.secret.env` 的 `RELAY_B_WOCHENG_KEY`）
+  与 出图节点 key（profile 里 `apiKeyEnv` 指定的环境变量）。不带 key 时服务能起，但 chat / 出图会失败。
+  本机以 `set -a; . ~/.agents/skills/gpt-image/relays.secret.env; set +a; export WOCHENG_API_KEY="$RELAY_B_WOCHENG_KEY"` 后再启动。
+- 开发用 `web`（3080）进程仍是升级前启动的旧版，下次重启自动用 0.2.1。
+
+**回滚**：`~/.nvm/versions/node/v24.21.0/bin/npm i -g --prefix /opt/homebrew @deepseek-ai/dsh@0.1.7-rc.2`
+（或从备份目录恢复包）→ 解压 `profiles.tar.gz` 覆盖 `~/.dsh/profiles` → 重启。
+
+## 已知安装失败：缺 DSH 内置包
+
+- 症状：`dsh --profile <your> --port 13090` 启动时报
+  `failed to import loader entry preset-deck-studio (@deepseek-ai/dsh-agent-preset): Cannot find package '@deepseek-ai/dsh-agent-preset'`。
+- 原因：当前 `dsh` 不是完整 npm 发行版（常见于从源码 checkout / 自编译，或 PATH 里指向了旧安装）。
+- 处理：`which -a dsh` 确认实际路径 → 用 `npm i -g @deepseek-ai/dsh@0.2.1-rc.2` 的发行版启动；
+  已在本机验证 0.2.1-rc.2 正常。详见 [install.md](install.md) §4.3。
+
+## 最低版本与 0.1.5
+
+- Deckline 要求 **DSH ≥ 0.1.7 < 0.3**；**0.1.5 及更早不支持**（没有 preset 需要的
+  `@deepseek-ai/dsh-agent-preset` 等内置包，启动会直接报 `Cannot find package`）。
+- 用 `dsh --version` 确认；是 0.1.x 旧安装（常见于源码 checkout / 旧 PATH）时，改用
+  `npm i -g @deepseek-ai/dsh@0.2.1-rc.2` 的发行版，并确认 `which -a dsh` 第一个是它。
+- 升级后建议重建 deckline profile（`dsh --profile deckline --from-default-profile web --dump-config` 后再
+  `dsh plugin --profile deckline add ...`），避免沿用旧版本的 profile 模板。

package/seeds/docs/install.en.md

@@ -0,0 +1,252 @@
+# Install & configure (Deckline · DSH plugin)
+
+Deckline (`dsh-plugin-deck-studio`) is an **image-deck workbench plugin** for DeepSeek Harness (DSH):
+native DSH chat on the left, a full-page image-deck workspace in the middle, and library / Designs /
+assets / conversations on the right. It is not a standalone app — it runs on a DSH profile.
+
+> Target users: people who build content and presentations with DSH. After setup you can edit a deck
+> from its script, render slide images on request (single page or a named batch), manage governance documents, register your own
+> design styles (with sample images) and start from 8 preset styles.
+
+## 0. Prerequisites
+
+| Dependency | Version | Notes |
+|---|---|---|
+| Node.js | `^22.19` or `≥ 24` | Same as the DSH runtime; Node 23 is not supported |
+| pnpm | 10+ | DSH uses pnpm to manage profile dependencies |
+| DSH | `≥ 0.1.7 < 0.3` | `npm i -g @deepseek-ai/dsh`; verified on 0.1.7-rc.2 / 0.2.1-rc.2, see [compat.md](compat.md) |
+| An LLM provider key | — | e.g. `WOCHENG_API_KEY` (configured in the profile, see DSH docs) |
+| An image node key | — | For real renders; the fake mode lets you try the flow first (section 4) |
+
+```sh
+node -v && pnpm -v && dsh --version
+```
+
+## 1. Installation (pick one of three)
+
+### A. From npm (recommended once published)
+
+```sh
+# 1) create a deckline profile (based on the web template shipped with DSH)
+dsh --profile deckline --from-default-profile web
+
+# 2) install the plugin; dsh plugin add adds the bundle to the profile and enables it
+dsh plugin --profile deckline add dsh-plugin-deck-studio
+```
+
+### B. From the Git repository (public repo, no npm account needed)
+
+```sh
+dsh --profile deckline --from-default-profile web
+dsh plugin --profile deckline add "github:<your-account>/dsh-deck-studio#path:/plugin/deck-studio"
+```
+
+> pnpm's support for git subdirectories varies by version; if `#path:` fails, use C (clone + local install).
+
+### C. Local clone (recommended for development / debugging)
+
+```sh
+git clone https://github.com/<your-account>/dsh-deck-studio.git
+cd dsh-deck-studio
+pnpm install --ignore-scripts   # optional: skip if you only run the plugin
+
+dsh --profile deckline --from-default-profile web
+dsh plugin --profile deckline add "$PWD/plugin/deck-studio"
+```
+
+Verify the installation:
+
+```sh
+dsh --profile deckline --dump-config | grep -n "deck-studio" | head
+```
+
+Seeing both `deck-studio` and `preset-deck-studio` means the install succeeded.
+
+## 2. First configuration: decks / workspace / port
+
+All Deckline configuration lives in the **profile patch**: `~/.dsh/profiles/deckline/cordis.patch.yml`.
+The repository ships a copy-paste example:
+[`plugin/deck-studio/cordis.example.yml`](../plugin/deck-studio/cordis.example.yml).
+
+The minimum (append to the profile's `cordis.patch.yml`):
+
+```yaml
+# your deck source directory (read-only; any existing deck directory works)
+- id: deck-studio
+  name: 'dsh-plugin-deck-studio'
+  config:
+    displayName: 'Deckline'
+    userName: 'Yuna'
+    # where new decks are created; empty = the plugin's internal .deck/projects/<id>/source
+    projectsRoot: '/absolute/path/to/your/sharing'
+    decks:
+      - id: my-deck
+        label: 'My deck'
+        sourceRoot: '/absolute/path/to/my-deck'
+```
+
+> `decks[].sourceRoot` is read-only: Deckline never writes to the source directory; all edits and
+> revisions live in `.deck/`. You can also start with **＋ New Deck** if you have no deck yet.
+
+### Per-deck project rules (optional)
+
+Drop a `deck.rules.md` at the root of a deck project to describe the creative constraints for that deck
+(audience, taboos, brand, facts that must be respected). The Deck Agent reads and follows it on every
+`deck_source_overview`:
+
+```md
+# Project rules
+- Audience: internal business and IT, no technical background assumed
+- Taboos: no unverified efficiency numbers; never name real customers
+- Visual: cream paper + colored pencil, no 3D
+```
+
+- It only constrains **that one deck** and does not affect other decks; without the file there are no rules.
+- It **cannot override** the product's hard rules (read-only source decks / QA gates / no fabrication /
+  user confirmation). In a conflict the hard rules win and the agent says so.
+- Max 8 KB; it is never written back and never triggers any automatic action.
+- Do not name it `AGENTS.md`: that belongs to DSH workspace instructions and Deckline does not depend on it
+  (see `docs/adr/0020` in the development repo).
+
+## 2.5 Where the data lives: source deck / documents / images / exports
+
+Deckline keeps data in two places: **your deck source** (`projectsRoot`, plain markdown + source images)
+and **runtime data** (`dataRoot`: working copies / renders / events). If you cannot find files after
+creating a deck, check this table first.
+
+| Content | Location | Notes |
+|---|---|---|
+| New deck source documents | `<projectsRoot>/<dir>/` | `intent.md` / `script.md` / `style-reference.md`; confirmed `docs/*.md` are written back here; `prompts/`, `pages/`, `outputs/` sit alongside |
+| Working copies + governance docs | `<dataRoot>/decks/<deckId>/docs/` | changelog / feedback / research / materials / review / fact-check…; stay here until confirmed |
+| Script revisions | `<dataRoot>/decks/<deckId>/script/revisions/vNNN.md` | copy-on-write; `current.md` is always latest |
+| Rendered page images | `<dataRoot>/decks/<deckId>/slides/<pageId>/versions/<vNNN>/image.png` | one directory per revision, with `prompt.txt` / `content.json` / `qa.json`; old revisions are never overwritten |
+| Style samples | `<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/sample-vNNN.png` (or your own `designs/<ABBR>/`) | samples imported / pasted in the UI |
+| Exports | your browser's download folder | zips from "Export" (PDF / PPTX / handoff package) |
+
+- **`dataRoot` defaults to `$DSH_HOME/deckline`** (usually `~/.dsh/deckline`) — never inside the plugin
+  package, so plugin upgrades do not touch it. Override with `dataRoot: '/your/path'` in the profile patch,
+  or the `DSH_DECK_DATA_ROOT` env var.
+- **`projectsRoot`** decides where new decks are created; if unset they go to `<dataRoot>/projects/<deckId>/source`.
+- **Managed source decks are read-only**: Deckline never writes to a deck registered via `decks[].sourceRoot`.
+- **Backup**: archive `dataRoot` and `projectsRoot` together (documents + images + events):
+  ```sh
+  tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<your projectsRoot>"
+  ```
+- The workbench **Settings** panel shows the current data directory; in the development repo the data root
+  is the repo's `.deck/` (configured explicitly in the profile).
+
+## 3. Start
+
+```sh
+dsh --profile deckline --port 13090
+```
+
+Open the `http://127.0.0.1:13090/?token=…` URL printed in the terminal.
+`--port` is optional; the default is 13090 to avoid colliding with DSH's web profile on 3080.
+
+## 4. Configure the image key (required for real renders)
+
+Deckline supports:
+
+- **fake mode** (default, offline): renders placeholder SVGs, enough to try the whole flow;
+- **real mode**: calls an OpenAI-compatible `/v1/images/generations` node for real images.
+
+> The plugin **ships no image node address** (provider-neutral): real mode requires your own endpoint
+> and key. Otherwise the Settings panel says "no endpoint / key configured" and rendering fails loudly
+> instead of silently hitting a default node.
+
+### 4.1 Environment variables (simplest)
+
+```sh
+# image node (any OpenAI-compatible relay works)
+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 / secret manager only
+```
+
+### 4.2 Profile patch (recommended: multiple nodes + team-shared config)
+
+Override the `deck-studio` render config in `~/.dsh/profiles/deckline/cordis.patch.yml`:
+
+```yaml
+- id: deck-studio
+  name: 'dsh-plugin-deck-studio'
+  config:
+    # …keep the displayName / decks from above
+    render:
+      mode: real
+      size: '2560x1440'
+      default: 'main/gpt-image-2.5-sunburst'
+      nodes:
+        - id: main
+          name: 'Main node'
+          endpoint: 'https://your-image-relay.example.com/v1/images/generations'
+          # choose one: the environment variable name, or a local key file (KEY=VALUE, chmod 600, never in git)
+          apiKeyEnv: 'DSH_DECK_IMAGE_API_KEY'
+          apiKeyFile: '~/.config/image-relay.env'
+          models:
+            - 'gpt-image-2.5-sunburst'
+            - 'gpt-image-2'
+```
+
+Key points:
+
+- **Keys never go into the repo or into plain-text profile config**: the config only holds `apiKeyEnv`
+  (environment variable name) or `apiKeyFile` (local file path).
+- The workbench **Settings** panel shows whether each node's key is configured (boolean + source only,
+  never the key itself).
+- When no key is configured or the mode is still fake, the Settings panel shows a hint.
+- Model names must match what your relay actually serves; for OpenAI-compatible `gpt-image-2`-series ids,
+  consult the node's `/v1/models`.
+
+## 5. Adding your own designs (two ways)
+
+### Way 1: in the UI (recommended, supports pasting images)
+
+1. Home → **Designs** → **＋ Add style**;
+2. Fill in name / abbreviation / visual description (used as the prompt);
+3. In the "sample images" area **paste with ⌘V, drag and drop, or pick files** (png/jpg/webp, multiple,
+   ≤12 MB each);
+4. Creating it also creates the style, a 0-page canvas and a design conversation; the samples appear
+   immediately on the Designs card and in the preview.
+
+To add samples to an existing style: click the **eye** icon on the style card → "＋ Add sample" at the
+bottom of the preview (paste / pick files work the same way).
+
+### Way 2: drop files on disk
+
+Samples live under `designs/<ABBR>/` (ABBR is your style abbreviation):
+
+- canvas directory (recommended): `.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`;
+- or `designs/<ABBR>/` inside any managed deck source (Deckline scans and merges them).
+
+Refresh the page afterwards. png / jpg / webp are supported; names are free-form
+(`sample-01.jpg` and similar keep them ordered).
+
+### Use preset styles (no prompt writing needed)
+
+**＋ Import preset styles** on the Designs page imports all 8 bundled styles (business consulting /
+premium dark / Japanese minimal / magazine editorial / tech blueprint / hand-drawn whiteboard /
+Swiss minimal / aurora gradient), each with samples. See [styles.md](styles.md).
+
+## 6. Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| Port already in use | `dsh --profile deckline --port 13100`; or kill the old process with `lsof -tiTCP:13090 -sTCP:LISTEN` |
+| Page 404 / blank | Make sure the plugin bundle is enabled: `dsh --profile deckline --dump-config \| grep deck-studio` |
+| No "render" button / render fails | Check the key state in Settings; confirm `render.mode: real`; `curl` the node endpoint |
+| New decks land in the wrong place | Set `projectsRoot`; otherwise they go to the plugin data directory `.deck/projects/` |
+| Where are data / samples | See section 2.5: source decks in `projectsRoot`, working copies / renders in `dataRoot` (default `~/.dsh/deckline`) |
+| Upgrading the plugin | `dsh plugin --profile deckline install <spec>`, or `add` the new version again |
+
+## 7. Developers: local verification
+
+```sh
+node plugin/deck-studio/verify/smoke.mjs        # 46 contract tests (no network or key needed)
+node scripts/harness-check.mjs                 # instruction-chain / link / redaction / ledger gate
+dsh --profile deck-studio --no-open             # development profile (port configured locally)
+```
+
+The plugin has no third-party runtime dependencies (Node built-ins only). Changes to
+`plugin/deck-studio/index.js` require a profile restart; changes to `ui/` html/css hot-reload.