dsh-plugin-deck-studio 0.2.2 → 0.2.4

package/README.md

@@ -10,7 +10,10 @@ DSH（DeepSeek Harness）的 **image deck 工作台插件**：左侧原生 Chat
 dsh --profile deckline --from-default-profile web
 
 # 2) 安装本插件（安装后会自动注册 bundle，无需手动改配置文件）
-dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.2
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
+
+# 国内网络建议走镜像（否则从 npmjs.org 拉 20 MB 包可能很慢）
+npm_config_registry=https://registry.npmmirror.com dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
 
 # 3) 启动，浏览器打开终端打印的带 token 链接
 dsh --profile deckline --port 13090
@@ -22,6 +25,8 @@ dsh --profile deckline --port 13090
 dsh --profile deckline --dump-config | grep -c "preset-deck-critic"
 ```
 
+在 npmjs.com 搜 `deckline` 或 `ppt dsh` 也能找到。也可以在 DSH「插件 → 发现」里加索引源 `https://cdn.jsdelivr.net/gh/yuna78/dsh-deck-studio@main/market-index.json` 后点安装。
+
 从源码 / Git 安装、Windows、以及完整配置（数据目录 / deck 源 / 出图节点 / key）见仓库文档：
 
 - [docs/install.md](https://github.com/yuna78/dsh-deck-studio/blob/main/docs/install.md)（中文）

package/lib/config.js

@@ -9,6 +9,7 @@
  * @module dsh-plugin-deck-studio/config
  */
 
+import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { DEFAULT_MAX_REVIEWERS, HARD_MAX_REVIEWERS } from "./review-personas.js";
 import { fileURLToPath } from "node:url";
@@ -16,9 +17,20 @@ import { fileURLToPath } from "node:url";
 /** 插件包根目录（lib/ 的上一级——本文件住在 lib/ 里）。 */
 export const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 
-/** 仓库根：插件住在 `<repo>/plugin/deck-studio/`。 */
+/**
+ * 资产根：开发仓库根 `<repo>/plugin/deck-studio/` 的上一级。
+ *
+ * npm 安装时插件在 `<profile>/node_modules/dsh-plugin-deck-studio`，上两级是 node_modules，
+ * 那里没有 samples / docs；公开包把手册与示例 deck 一起打进包内 `seeds/`（prepack 生成），
+ * 这种情况回退到 `seeds/`，否则「使用手册」和首次启动的示例 deck 在 npm 安装下是空的。
+ */
 export function repoRootFrom(pluginDir = PLUGIN_DIR) {
-  return resolve(pluginDir, "..", "..");
+  const repo = resolve(pluginDir, "..", "..");
+  const looksLikeRepo = existsSync(join(repo, "samples", "deckline-intro", "script.md")) || existsSync(join(repo, "docs", "manual.md"));
+  if (looksLikeRepo) return repo;
+  const bundled = join(pluginDir, "seeds");
+  if (existsSync(join(bundled, "docs", "manual.md"))) return bundled;
+  return repo;
 }
 
 /**

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
-  "description": "Deckline：DSH image deck 工作台插件 —— 原生 Chat + 整页图片 deck 工作区 + 设计风格（design）库；出图按页留痕、可点名批量连出，产物本地可追踪。",
+  "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -19,7 +19,14 @@
     "image-deck",
     "presentation",
     "slides",
-    "deckline"
+    "ppt",
+    "pptx",
+    "powerpoint",
+    "ai-ppt",
+    "slide-deck",
+    "deckline",
+    "幻灯片",
+    "演示文稿"
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
@@ -27,7 +34,8 @@
   },
   "scripts": {
     "verify": "node verify/smoke.mjs",
-    "prepublishOnly": "node verify/smoke.mjs"
+    "prepublishOnly": "node verify/smoke.mjs",
+    "prepack": "node scripts/prepack-assets.mjs"
   },
   "dsh": {
     "bundle": {

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,127 @@
+# 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`，功能正常。
+
+## 升级记录（0.2.1-rc.2，验证机）
+
+**升级前**：全局 `@deepseek-ai/dsh@0.1.7-rc.2`；**升级后**：`0.2.1-rc.2`（npm `latest`）。
+
+```bash
+# 建议先备份 profile（仓库外）
+tar -czf ~/dsh-profiles-backup.tgz -C ~/.dsh profiles
+# 升级全局包（Node 需 ^22.19 || >=24）
+npm i -g @deepseek-ai/dsh@0.2.1-rc.2
+# 重启 profile
+dsh --profile deckline --no-open
+```
+
+**回归结果**：
+
+| 检查项 | 结果 |
+|---|---|
+| `dsh --version` | ✅ `0.2.1-rc.2` |
+| `--dump-config` | ✅ 0 stderr，插件 / 预设 / tools 条目不丢 |
+| 启动 13090 | ✅ 正常打印 token，无迁移报错 |
+| 既有数据 | ✅ 升级后 decks / designs / 资源库 / Conversations / 治理数据都在 |
+| Deckline 应用 | ✅ 首页 / Design 列表 / Deck 工作台（意图 / 脚本 / Design / 日志… + image storyboard） |
+| 出图节点 | ✅ 节点 `/v1/models` 探活 200 |
+| 页面异常 | ✅ 0 pageerror |
+
+**运行要求**：LLM 与出图节点的 key 由 profile / 环境变量提供（出图节点见 `apiKeyEnv`）。不带 key 时服务能起，
+但 chat / 出图会失败；fake 模式下不配 key 也能走完整流程。
+
+**回滚**：`npm i -g @deepseek-ai/dsh@0.1.7-rc.2` → 解压备份的 `profiles` 覆盖 `~/.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. `DEEPSEEK_API_KEY` / `OPENAI_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.