chore: release v2.1.0

feat(baoyu-post-to-wechat,baoyu-post-to-weibo,baoyu-post-to-x): cascade Mermaid PNG preprocessing into publishing pipelines
feat(baoyu-markdown-to-html): render Mermaid code blocks to PNG via headless Chrome
2026-07-12 05:51:44 +08:00 · 2026-05-24 21:27:57 -05:00 · 2026-05-24 21:27:53 -05:00 · 2026-05-24 21:27:43 -05:00 · 2026-05-24 21:27:38 -05:00 · 2026-05-24 21:27:33 -05:00
155 changed files with 11984 additions and 22983 deletions
@@ -6,7 +6,7 @@
  },
  "metadata": {
    "description": "Skills shared by Baoyu for improving daily work efficiency",
-    "version": "1.117.5"
+    "version": "2.1.0"
  },
  "plugins": [
    {
@@ -22,8 +22,9 @@
        "./skills/baoyu-danger-gemini-web",
        "./skills/baoyu-danger-x-to-markdown",
        "./skills/baoyu-diagram",
+        "./skills/baoyu-electron-extract",
        "./skills/baoyu-format-markdown",
-        "./skills/baoyu-imagine",
+        "./skills/baoyu-image-gen",
        "./skills/baoyu-infographic",
        "./skills/baoyu-markdown-to-html",
        "./skills/baoyu-post-to-weibo",
@@ -32,9 +33,9 @@
        "./skills/baoyu-slide-deck",
        "./skills/baoyu-translate",
        "./skills/baoyu-url-to-markdown",
-        "./skills/baoyu-image-cards",
-        "./skills/baoyu-youtube-transcript",
-        "./skills/baoyu-wechat-summary"
+        "./skills/baoyu-wechat-summary",
+        "./skills/baoyu-xhs-images",
+        "./skills/baoyu-youtube-transcript"
      ]
    }
  ]
@@ -0,0 +1,40 @@
+name: codex-imagegen tests
+
+on:
+  push:
+    paths:
+      - 'scripts/codex-imagegen/**'
+      - 'scripts/codex-imagegen.sh'
+      - '.github/workflows/codex-imagegen-tests.yml'
+  pull_request:
+    paths:
+      - 'scripts/codex-imagegen/**'
+      - 'scripts/codex-imagegen.sh'
+      - '.github/workflows/codex-imagegen-tests.yml'
+  workflow_dispatch:
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Show Bun version
+        run: bun --version
+
+      - name: Run unit tests
+        working-directory: scripts/codex-imagegen
+        run: bun test
+
+      - name: Bundle smoke test (catches import/syntax errors)
+        run: bun build --target=node scripts/codex-imagegen/main.ts --outfile /tmp/main-build.js
+
+      - name: Help output smoke test
+        run: bun scripts/codex-imagegen/main.ts --help
@@ -2,6 +2,57 @@

 English | [中文](./CHANGELOG.zh.md)

+## 2.1.0 - 2026-05-24
+
+### Features
+- `baoyu-markdown-to-html`: render fenced ` ```mermaid ` code blocks to local PNG via shared Chrome (CDP) before the standard image-placeholder pipeline runs. New CLI flags: `--mermaid-theme <default|forest|dark|neutral|base>`, `--mermaid-scale <N>` (default `2` for @2x resolution), `--mermaid-bg <white|transparent|#hex>`, and `--no-mermaid` to disable rendering. Generated images land in `imgs/.mermaid-cache/mermaid-<hash>.png` and are deduplicated/reused across runs by a 12-char SHA-256 over `(code, theme, scale, background, mermaid version)`. The browser-side `<pre class="mermaid">` path is retained as a graceful fallback when Chrome is unavailable or a single block fails to render
+- `baoyu-post-to-wechat`, `baoyu-post-to-weibo`, `baoyu-post-to-x`: cascade the same Mermaid → PNG preprocessing into the WeChat / Weibo / X publishing pipelines so diagrams appear as real images in the published posts (previously they fell through as unrendered `<pre>` blocks). Existing `WECHATIMGPH_*` / `WBIMGPH_*` / `XIMGPH_*` placeholder pipelines pick up the generated PNGs unchanged
+- `baoyu-md` package: new exports `preprocessMermaidInMarkdown`, `extractMermaidBlocks`, `replaceMermaidBlocks`, `hashMermaidCode`, and `MERMAID_VERSION` (skills inject the render function so the package stays Chrome-free)
+- `baoyu-chrome-cdp` package: new `./mermaid` subexport providing `renderMermaidToPng(code, outputPath, options)` backed by a process-singleton CDP connection that reuses the shared Chrome profile and ships the vendored Mermaid 10.9.1 UMD bundle as an asset
+
+## 2.0.1 - 2026-05-24
+
+### Fixes
+- `baoyu-post-to-wechat`: convert `newspic` (image-text) `content` from HTML to plain text before sending to the WeChat draft API. The previous behavior passed raw HTML, triggering error 45166 (invalid content) when multiple images pushed the body over WeChat's length limit. The new `htmlToPlainText` helper turns `<br>` and block-closing tags into line breaks, strips remaining tags, decodes named/numeric (decimal and hex) entities, and collapses whitespace (by @Go1dFinger, [#164](https://github.com/JimLiu/baoyu-skills/pull/164), closes [#163](https://github.com/JimLiu/baoyu-skills/issues/163))
+
+### Credits
+- `baoyu-post-to-wechat` newspic plain-text fix contributed by @Go1dFinger ([#164](https://github.com/JimLiu/baoyu-skills/pull/164))
+
+## 2.0.0 - 2026-05-24
+
+### Breaking
+- Removed `baoyu-imagine` skill. All functionality (providers, scripts, references) now lives under `baoyu-image-gen`. The skill is registered in `marketplace.json` under the new name and its `homepage` URL has changed to `#baoyu-image-gen`.
+- Removed `baoyu-image-cards` skill. All functionality (styles, layouts, palettes, presets) now lives under `baoyu-xhs-images`. The skill is registered in `marketplace.json` under the new name.
+- Cross-skill `## Image Generation Tools` examples in `baoyu-article-illustrator`, `baoyu-comic`, `baoyu-cover-image`, `baoyu-infographic`, and `baoyu-slide-deck` now reference `baoyu-image-gen` instead of `baoyu-imagine`.
+
+### Migration
+- Existing `~/.baoyu-skills/baoyu-imagine/EXTEND.md` and `.baoyu-skills/baoyu-imagine/EXTEND.md` configs are auto-renamed to `…/baoyu-image-gen/EXTEND.md` on first run via the legacy-path resolver in `scripts/main.ts`.
+- Users invoking the skill via slash command should switch from `/baoyu-imagine ...` to `/baoyu-image-gen ...` and from any `baoyu-image-cards` reference to `baoyu-xhs-images`.
+
+## 1.119.0 - 2026-05-24
+
+### Features
+- `baoyu-electron-extract`: new skill that extracts resources and JavaScript from any installed Electron app's `app.asar`. Restores original sources from embedded `sourcesContent` in `.js.map` files when present (TypeScript/JSX included) or formats minified JS/CSS with Prettier in place when not. Source-map paths are resolved relative to each `.js.map` file first, so bundler-relative entries like `../../src/main.ts` restore to readable paths under `restored/` instead of hashed placeholders. Always skips `node_modules` and `webpack/runtime/*` entries. Auto-discovers apps on macOS (`/Applications`, `~/Applications`) and Windows (`%LOCALAPPDATA%\Programs`, `%PROGRAMFILES%`, `%PROGRAMFILES(X86)%`, `%APPDATA%`); other platforms can pass `--asar <path>` explicitly. Safety: refuses to write to `/`, the user home, or the current working directory, and refuses non-empty existing output dirs without `--force`
+
+## 1.118.0 - 2026-05-21
+
+### Features
+- `codex-imagegen`: new image-generation backend for non-Codex runtimes (e.g., Claude Code) — spawns `codex exec --json --sandbox danger-full-access` and delegates to Codex CLI's built-in `image_gen` tool, so no `OPENAI_API_KEY` is required. Ships with idempotency cache, file-lock concurrency control, JSONL event-stream parsing, PNG magic-byte validation, and exponential-backoff retries (by @yelban, #158)
+- `baoyu-cover-image`: wire `SKILL.md` to call the `codex-imagegen` wrapper when `preferred_image_backend: codex-imagegen` is set, with `--timeout` documented for slow networks
+
+### Refactor
+- `codex-imagegen`: enforce `--prompt` / `--prompt-file` mutual exclusion in code (was docs-only)
+- `codex-imagegen`: replace `(opts as any).__promptFile` hack with a typed `promptFile` field on `CliOptions`
+- `codex-imagegen`: replace inline `cp|mv ... generated_images` regex with the shared `findCpToTarget` helper
+- `codex-imagegen`: propagate `attempts` on error responses (previously hardcoded to `0`)
+- `codex-imagegen`: drop dead `parseFinalJson()` + matching test (wrapper ignores agent-reported JSON in favor of disk verification)
+
+### Security
+- `codex-imagegen`: reject `--image` / `--ref` paths containing shell metacharacters before interpolating them into the agent instruction sent to `codex exec --sandbox danger-full-access`
+
+### Credits
+- `codex-imagegen` backend contributed by @yelban (#158)
+
 ## 1.117.5 - 2026-05-21

 ### Credits
@@ -2,6 +2,57 @@

 [English](./CHANGELOG.md) | 中文

+## 2.1.0 - 2026-05-24
+
+### 新功能
+- `baoyu-markdown-to-html`：在标准图片占位符流水线之前,通过共享 Chrome（CDP）把 ` ```mermaid ` 围栏代码块渲染为本地 PNG。新增 CLI 参数 `--mermaid-theme <default|forest|dark|neutral|base>`、`--mermaid-scale <N>`（默认 `2`,即 @2x 分辨率）、`--mermaid-bg <white|transparent|#hex>`,以及用于关闭渲染的 `--no-mermaid`。生成的图片落在 `imgs/.mermaid-cache/mermaid-<hash>.png`,跨次运行通过对 `(code, theme, scale, background, mermaid 版本)` 取 SHA-256 前 12 位进行去重/复用。Chrome 不可用或单块渲染失败时,保留浏览器侧 `<pre class="mermaid">` 兜底
+- `baoyu-post-to-wechat`、`baoyu-post-to-weibo`、`baoyu-post-to-x`:在微信 / 微博 / X 发布流水线中同步接入上述 Mermaid → PNG 预处理,Mermaid 图能以真图形式出现在已发布的稿件中(此前会落到未渲染的 `<pre>` 块)。现有的 `WECHATIMGPH_*` / `WBIMGPH_*` / `XIMGPH_*` 占位符流水线无需改动,会直接拾取生成的 PNG
+- `baoyu-md` 包:新增导出 `preprocessMermaidInMarkdown`、`extractMermaidBlocks`、`replaceMermaidBlocks`、`hashMermaidCode`、`MERMAID_VERSION`(渲染函数由 skill 注入,本包不再反向依赖 Chrome)
+- `baoyu-chrome-cdp` 包:新增 `./mermaid` 子导出,提供 `renderMermaidToPng(code, outputPath, options)`,底层为进程级单例 CDP 连接,复用共享 Chrome profile,并把 Mermaid 10.9.1 UMD 资产打入包内
+
+## 2.0.1 - 2026-05-24
+
+### 修复
+- `baoyu-post-to-wechat`：发布 `newspic`（图文）时，将 `content` 字段从 HTML 转换为纯文本后再提交微信草稿接口。此前直接传 HTML，多图场景下内容长度超出限制会触发错误 45166（invalid content）。新增 `htmlToPlainText` 工具：把 `<br>` 和块级闭合标签转成换行、剥离其余标签、解码命名实体与十进制/十六进制数字实体、合并多余空白 (by @Go1dFinger, [#164](https://github.com/JimLiu/baoyu-skills/pull/164), 关联 [#163](https://github.com/JimLiu/baoyu-skills/issues/163))
+
+### 致谢
+- `baoyu-post-to-wechat` 的 newspic 纯文本修复由 @Go1dFinger 贡献（[#164](https://github.com/JimLiu/baoyu-skills/pull/164)）
+
+## 2.0.0 - 2026-05-24
+
+### 破坏性变更
+- 移除 `baoyu-imagine` skill。所有功能（providers、脚本、references）合并入 `baoyu-image-gen`，`marketplace.json` 改用新名称注册，`homepage` 链接更新为 `#baoyu-image-gen`
+- 移除 `baoyu-image-cards` skill。所有功能（样式、布局、配色、预设）合并入 `baoyu-xhs-images`，`marketplace.json` 改用新名称注册
+- 其它 skill（`baoyu-article-illustrator`、`baoyu-comic`、`baoyu-cover-image`、`baoyu-infographic`、`baoyu-slide-deck`）中 `## Image Generation Tools` 示例统一改用 `baoyu-image-gen`，不再引用 `baoyu-imagine`
+
+### 迁移说明
+- 旧的 `~/.baoyu-skills/baoyu-imagine/EXTEND.md` 与 `.baoyu-skills/baoyu-imagine/EXTEND.md` 配置文件会被 `scripts/main.ts` 中的 legacy-path 解析器自动重命名到 `…/baoyu-image-gen/EXTEND.md`，首次运行时迁移
+- 通过斜杠命令调用时，请将 `/baoyu-imagine ...` 改为 `/baoyu-image-gen ...`；将所有 `baoyu-image-cards` 改为 `baoyu-xhs-images`
+
+## 1.119.0 - 2026-05-24
+
+### 新功能
+- `baoyu-electron-extract`：新增 skill，可从任意已安装的 Electron 应用的 `app.asar` 中提取资源和 JavaScript。`.js.map` 文件内嵌 `sourcesContent` 时还原原始源码（含 TypeScript/JSX），否则用 Prettier 原地美化压缩后的 JS/CSS。source-map 路径先相对各 `.js.map` 文件解析，因此 `../../src/main.ts` 这类打包器相对路径会还原为 `restored/` 下的可读路径，而不是哈希占位符。始终跳过 `node_modules` 和 `webpack/runtime/*` 条目。macOS 下自动从 `/Applications` 和 `~/Applications` 发现应用，Windows 下从 `%LOCALAPPDATA%\Programs`、`%PROGRAMFILES%`、`%PROGRAMFILES(X86)%`、`%APPDATA%` 发现；其他平台请用 `--asar <path>` 显式指定。安全：拒绝写入 `/`、用户主目录或当前工作目录，未加 `--force` 时拒绝写入非空的已有输出目录
+
+## 1.118.0 - 2026-05-21
+
+### 新功能
+- `codex-imagegen`：新增面向非 Codex 运行时（如 Claude Code）的图像生成后端 —— 通过 `codex exec --json --sandbox danger-full-access` 调用 Codex CLI 内置的 `image_gen` 工具，无需 `OPENAI_API_KEY`。内置幂等缓存、文件锁并发控制、JSONL 事件流解析、PNG 魔术字节校验和指数退避重试 (by @yelban, #158)
+- `baoyu-cover-image`：在 `SKILL.md` 中接入 `codex-imagegen` 包装脚本（当 `preferred_image_backend: codex-imagegen` 时生效），并补充慢网络下的 `--timeout` 参数说明
+
+### 重构
+- `codex-imagegen`：在代码中强制校验 `--prompt` 与 `--prompt-file` 互斥（此前仅在文档说明）
+- `codex-imagegen`：将 `(opts as any).__promptFile` 这一 hack 改为 `CliOptions` 上类型化的 `promptFile` 字段
+- `codex-imagegen`：用复用的 `findCpToTarget` 辅助函数替换内联的 `cp|mv ... generated_images` 正则
+- `codex-imagegen`：错误返回时正确透传 `attempts`（此前硬编码为 `0`）
+- `codex-imagegen`：删除无用的 `parseFinalJson()` 函数及对应测试（包装脚本以磁盘校验为准，不再依赖 agent 自报 JSON）
+
+### 安全
+- `codex-imagegen`：在拼入发往 `codex exec --sandbox danger-full-access` 的 agent 指令前，拒绝包含 shell 元字符的 `--image` / `--ref` 路径
+
+### 致谢
+- `codex-imagegen` 后端由 @yelban 贡献 (#158)
+
 ## 1.117.5 - 2026-05-21

 ### 致谢
@@ -1,6 +1,6 @@
 # CLAUDE.md

-Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.107.0**.
+Claude Code marketplace plugin providing AI-powered content generation skills. Version: **2.0.0**.

 ## Architecture

@@ -31,7 +31,7 @@ Execute: `${BUN_X} skills/<skill>/scripts/main.ts [options]`

 - **Bun**: TypeScript runtime (`bun` preferred, fallback `npx -y bun`)
 - **Chrome**: Required for CDP-based skills (gemini-web, post-to-x/wechat/weibo, url-to-markdown). All CDP skills share a single profile, override via `BAOYU_CHROME_PROFILE_DIR` env var. Platform paths: [docs/chrome-profile.md](docs/chrome-profile.md)
- **Image generation APIs**: `baoyu-imagine` requires API key (OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, or Replicate) configured in EXTEND.md
+- **Image generation APIs**: `baoyu-image-gen` requires API key (OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, or Replicate) configured in EXTEND.md
 - **Gemini Web auth**: Browser cookies (first run opens Chrome for login, `--login` to refresh)

 ## Security
@@ -64,14 +64,23 @@ Skills that prompt users for choices MUST declare the tool-selection convention

 ## Image Generation Tools

-Skills that render images MUST declare the backend-selection convention **inline** in exactly one place per `SKILL.md` — a `## Image Generation Tools` section near the top (after `## User Input Tools`). Do NOT link out to [docs/image-generation-tools.md](docs/image-generation-tools.md); that doc is the author-side canonical source — copy its body into each SKILL.md. Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) elsewhere in a skill are treated as examples — other runtimes substitute their local equivalent under the rule. The rule is stateless: use whatever backend is available; if multiple, ask the user once; if none, ask how to proceed. Every rendered image's full prompt must be written to a standalone `prompts/NN-*.md` file before any backend is invoked. Backend skills (`baoyu-imagine`, `baoyu-image-gen`, `baoyu-danger-gemini-web`) are exempt — they render directly rather than selecting a backend.
+Skills that render images MUST declare the backend-selection convention **inline** in exactly one place per `SKILL.md` — a `## Image Generation Tools` section near the top (after `## User Input Tools`). Do NOT link out to [docs/image-generation-tools.md](docs/image-generation-tools.md); that doc is the author-side canonical source — copy its body into each SKILL.md. Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) elsewhere in a skill are treated as examples — other runtimes substitute their local equivalent under the rule. The rule is stateless: use whatever backend is available; if multiple, ask the user once; if none, ask how to proceed. Every rendered image's full prompt must be written to a standalone `prompts/NN-*.md` file before any backend is invoked. Backend skills (`baoyu-image-gen`, `baoyu-danger-gemini-web`) are exempt — they render directly rather than selecting a backend.

-## Deprecated Skills
+### `codex-imagegen` Backend

-| Skill | Note |
-|-------|------|
-| `baoyu-image-gen` | Superseded by `baoyu-imagine`. Not in `.claude-plugin/marketplace.json`. Kept functional — sync any cross-cutting changes with `baoyu-imagine`. |
-| `baoyu-xhs-images` | Superseded by `baoyu-image-cards`. Not in `.claude-plugin/marketplace.json`. Kept functional — sync any cross-cutting changes with `baoyu-image-cards`. Do NOT update README for this skill. |
+A backend for non-Codex runtimes (e.g., Claude Code) that generates images by spawning `codex exec --json --sandbox danger-full-access` and delegating to Codex CLI's built-in `image_gen` tool. Uses the user's Codex subscription — no `OPENAI_API_KEY` required.
+
+Invoke via:
+
+```bash
+./scripts/codex-imagegen.sh \
+  --image <output.png> \
+  --prompt-file prompts/01-cover.md \
+  --aspect 16:9 \
+  --cache-dir ~/.cache/baoyu-codex-imagegen
+```
+
+Stdout emits a single JSON line: `{"status":"ok","path":...,"bytes":N,...}`. On failure, `{"status":"error","error_kind":...}`. Skills route here by setting `preferred_image_backend: codex-imagegen` in EXTEND.md. Full reference: [docs/codex-imagegen-backend.md](docs/codex-imagegen-backend.md).

 ## Release Process

@@ -11,6 +11,8 @@ Skills shared by Baoyu for improving daily work efficiency with AI Agents (Claud

 ## Installation

+> **Tip**: This repository contains 20+ skills. Install only the ones you actually need — bulk-installing every skill adds unnecessary context overhead for your AI agent on every run.
+
 ### Quick Install (Recommended)

 ```bash
@@ -32,7 +34,7 @@ This repository now supports publishing each `skills/baoyu-*` directory as an in
 ClawHub installs skills individually, not as one marketplace bundle. After publishing, users can install specific skills such as:

 ```bash
-clawhub install baoyu-imagine
+clawhub install baoyu-image-gen
 clawhub install baoyu-markdown-to-html
 ```

@@ -724,67 +726,67 @@ Post content to Weibo (微博). Supports regular posts with text, images, and vi

 AI-powered generation backends.

-#### baoyu-imagine
+#### baoyu-image-gen

 AI SDK-based image generation using OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope (Aliyun Tongyi Wanxiang), MiniMax, Jimeng (即梦), Seedream (豆包), and Replicate APIs. Supports text-to-image, reference images, aspect ratios, custom sizes, batch generation, and quality presets.

 ```bash
 # Basic generation (auto-detect provider)
-/baoyu-imagine --prompt "A cute cat" --image cat.png
+/baoyu-image-gen --prompt "A cute cat" --image cat.png

 # With aspect ratio
-/baoyu-imagine --prompt "A landscape" --image landscape.png --ar 16:9
+/baoyu-image-gen --prompt "A landscape" --image landscape.png --ar 16:9

 # High quality (2k)
-/baoyu-imagine --prompt "A banner" --image banner.png --quality 2k
+/baoyu-image-gen --prompt "A banner" --image banner.png --quality 2k

 # Specific provider
-/baoyu-imagine --prompt "A cat" --image cat.png --provider openai --model gpt-image-2
+/baoyu-image-gen --prompt "A cat" --image cat.png --provider openai --model gpt-image-2

 # Azure OpenAI (model = deployment name)
-/baoyu-imagine --prompt "A cat" --image cat.png --provider azure --model gpt-image-2
+/baoyu-image-gen --prompt "A cat" --image cat.png --provider azure --model gpt-image-2

 # OpenRouter
-/baoyu-imagine --prompt "A cat" --image cat.png --provider openrouter
+/baoyu-image-gen --prompt "A cat" --image cat.png --provider openrouter

 # OpenRouter with reference images
-/baoyu-imagine --prompt "Make it blue" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png
+/baoyu-image-gen --prompt "Make it blue" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png

 # DashScope (Aliyun Tongyi Wanxiang)
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope

 # DashScope with custom size
-/baoyu-imagine --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872
+/baoyu-image-gen --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872

 # Z.AI GLM-Image
-/baoyu-imagine --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai
+/baoyu-image-gen --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai

 # MiniMax
-/baoyu-imagine --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax
+/baoyu-image-gen --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax

 # MiniMax with subject reference
-/baoyu-imagine --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9
+/baoyu-image-gen --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9

 # Replicate (default: google/nano-banana-2)
-/baoyu-imagine --prompt "A cat" --image cat.png --provider replicate
+/baoyu-image-gen --prompt "A cat" --image cat.png --provider replicate

 # Replicate Seedream 4.5
-/baoyu-imagine --prompt "A studio portrait" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2
+/baoyu-image-gen --prompt "A studio portrait" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2

 # Replicate Wan 2.7 Image Pro
-/baoyu-imagine --prompt "A concept frame" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152
+/baoyu-image-gen --prompt "A concept frame" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152

 # Jimeng (即梦)
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider jimeng
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider jimeng

 # Seedream (豆包)
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider seedream
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider seedream

 # With reference images (Google, OpenAI, Azure OpenAI, OpenRouter, Replicate, MiniMax, or Seedream 5.0/4.5/4.0)
-/baoyu-imagine --prompt "Make it blue" --image out.png --ref source.png
+/baoyu-image-gen --prompt "Make it blue" --image out.png --ref source.png

 # Batch mode
-/baoyu-imagine --batchfile batch.json --jobs 4 --json
+/baoyu-image-gen --batchfile batch.json --jobs 4 --json
 ```

 **Options**:
@@ -863,7 +865,7 @@ AI SDK-based image generation using OpenAI GPT Image 2, Azure OpenAI, Google, Op
 - MiniMax reference images are sent as `subject_reference`; the current API is specialized toward character / portrait consistency.
 - Jimeng does not support reference images.
 - Seedream reference images are supported by Seedream 5.0 / 4.5 / 4.0, not Seedream 3.0.
- Replicate defaults to `google/nano-banana-2`. `baoyu-imagine` only enables Replicate advanced options for `google/nano-banana*`, `bytedance/seedream-4.5`, `bytedance/seedream-5-lite`, `wan-video/wan-2.7-image`, and `wan-video/wan-2.7-image-pro`.
+- Replicate defaults to `google/nano-banana-2`. `baoyu-image-gen` only enables Replicate advanced options for `google/nano-banana*`, `bytedance/seedream-4.5`, `bytedance/seedream-5-lite`, `wan-video/wan-2.7-image`, and `wan-video/wan-2.7-image-pro`.
 - Replicate currently saves exactly one output image per request. `--n > 1` is blocked locally instead of silently dropping extra results.
 - Replicate model behavior is family-specific: nano-banana uses `--quality` / `--ar`, Seedream uses validated `--size` / `--ar`, and Wan uses validated `--size` (with `--ar` converted locally to a concrete size).

@@ -1154,12 +1156,49 @@ Summarize WeChat group chat highlights into a structured digest. Extracts topics
 - Normal and roast (毒舌) digest versions
 - Profile backfill from historical digests

+#### baoyu-electron-extract
+
+Extract resources and JavaScript from any installed Electron app's `app.asar`. When `.js.map` files embed `sourcesContent`, restores the original source tree (TypeScript/JSX included); otherwise formats the minified JS/CSS with Prettier in place. Always skips `node_modules`. Works on macOS and Windows; pass `--asar <path>` on other platforms.
+
+```bash
+# Extract by app name (default output: ~/Downloads/Codex-electron-extract/)
+/baoyu-electron-extract Codex
+
+# Extract by absolute path (.app bundle, install dir, or .asar file)
+/baoyu-electron-extract "/Applications/Visual Studio Code.app"
+/baoyu-electron-extract --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
+
+# Custom output directory
+/baoyu-electron-extract Codex --output ~/work/codex-source
+
+# Preview discovery without writing anything
+/baoyu-electron-extract Codex --dry-run
+
+# Overwrite an existing output directory
+/baoyu-electron-extract Codex --force
+```
+
+**Options**:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<app>` | App name or absolute path (required unless `--asar`) | — |
+| `--output`, `-o` | Output directory | `~/Downloads/<AppName>-electron-extract` |
+| `--asar` | Override the resolved `.asar` path | auto-discovered |
+| `--force`, `-f` | Allow writing into a non-empty existing output dir | false |
+| `--skip-format` | Skip Prettier formatting | false |
+| `--skip-restore` | Skip source-map restoration | false |
+| `--no-unpacked` | Don't copy `app.asar.unpacked/` alongside | false |
+| `--dry-run` | Print resolved paths and exit without writing | false |
+| `--json` | Emit one JSON-line summary on stdout | false |
+
+**Output layout**: `extract-report.json` (counts, warnings, paths), `extracted/` (raw asar, formatted in place when no map), `extracted.unpacked/` (native modules if present), and `restored/` (rebuilt source tree from `.js.map` files).
+
 ## Environment Configuration

 Some skills require API keys or custom configuration. Environment variables can be set in `.env` files:

 **Load Priority** (higher priority overrides lower):
-1. CLI environment variables (e.g., `OPENAI_API_KEY=xxx /baoyu-imagine ...`)
+1. CLI environment variables (e.g., `OPENAI_API_KEY=xxx /baoyu-image-gen ...`)
 2. `process.env` (system environment)
 3. `<cwd>/.baoyu-skills/.env` (project-level)
 4. `~/.baoyu-skills/.env` (user-level)
@@ -11,6 +11,8 @@

 ## 安装

+> **提示**：本仓库已收录 20+ 个 skill，请按需安装你真正会用到的那几个，不要一次性全装 —— 每个加载的 skill 都会在 Agent 每次运行时占用额外上下文。
+
 ### 快速安装（推荐）

 ```bash
@@ -32,7 +34,7 @@ npx skills add jimliu/baoyu-skills
 ClawHub 按“单个 skill”安装，不是把整个 marketplace 一次性装进去。发布后，用户可以按需安装：

 ```bash
-clawhub install baoyu-imagine
+clawhub install baoyu-image-gen
 clawhub install baoyu-markdown-to-html
 ```

@@ -715,67 +717,67 @@ accounts:

 AI 驱动的生成后端。

-#### baoyu-imagine
+#### baoyu-image-gen

 基于 AI SDK 的图像生成，支持 OpenAI GPT Image 2、Azure OpenAI、Google、OpenRouter、DashScope（阿里通义万相）、MiniMax、即梦（Jimeng）、豆包（Seedream）和 Replicate API。支持文生图、参考图、宽高比、自定义尺寸、批量生成和质量预设。

 ```bash
 # 基础生成（自动检测服务商）
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png

 # 指定宽高比
-/baoyu-imagine --prompt "风景图" --image landscape.png --ar 16:9
+/baoyu-image-gen --prompt "风景图" --image landscape.png --ar 16:9

 # 高质量（2k 分辨率）
-/baoyu-imagine --prompt "横幅图" --image banner.png --quality 2k
+/baoyu-image-gen --prompt "横幅图" --image banner.png --quality 2k

 # 指定服务商
-/baoyu-imagine --prompt "一只猫" --image cat.png --provider openai --model gpt-image-2
+/baoyu-image-gen --prompt "一只猫" --image cat.png --provider openai --model gpt-image-2

 # Azure OpenAI（model 为部署名称）
-/baoyu-imagine --prompt "一只猫" --image cat.png --provider azure --model gpt-image-2
+/baoyu-image-gen --prompt "一只猫" --image cat.png --provider azure --model gpt-image-2

 # OpenRouter
-/baoyu-imagine --prompt "一只猫" --image cat.png --provider openrouter
+/baoyu-image-gen --prompt "一只猫" --image cat.png --provider openrouter

 # OpenRouter + 参考图
-/baoyu-imagine --prompt "把它变成蓝色" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png
+/baoyu-image-gen --prompt "把它变成蓝色" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png

 # DashScope（阿里通义万相）
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope

 # DashScope 自定义尺寸
-/baoyu-imagine --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872
+/baoyu-image-gen --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872

 # Z.AI GLM-Image
-/baoyu-imagine --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai
+/baoyu-image-gen --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai

 # MiniMax
-/baoyu-imagine --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax
+/baoyu-image-gen --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax

 # MiniMax + 角色参考图
-/baoyu-imagine --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9
+/baoyu-image-gen --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9

 # Replicate（默认：google/nano-banana-2）
-/baoyu-imagine --prompt "一只猫" --image cat.png --provider replicate
+/baoyu-image-gen --prompt "一只猫" --image cat.png --provider replicate

 # Replicate Seedream 4.5
-/baoyu-imagine --prompt "一张影棚人像" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2
+/baoyu-image-gen --prompt "一张影棚人像" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2

 # Replicate Wan 2.7 Image Pro
-/baoyu-imagine --prompt "一张概念分镜" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152
+/baoyu-image-gen --prompt "一张概念分镜" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152

 # 即梦（Jimeng）
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider jimeng
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider jimeng

 # 豆包（Seedream）
-/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider seedream
+/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider seedream

 # 带参考图（Google、OpenAI、Azure OpenAI、OpenRouter、Replicate、MiniMax 或 Seedream 5.0/4.5/4.0）
-/baoyu-imagine --prompt "把它变成蓝色" --image out.png --ref source.png
+/baoyu-image-gen --prompt "把它变成蓝色" --image out.png --ref source.png

 # 批量模式
-/baoyu-imagine --batchfile batch.json --jobs 4 --json
+/baoyu-image-gen --batchfile batch.json --jobs 4 --json
 ```

 **选项**：
@@ -854,7 +856,7 @@ AI 驱动的生成后端。
 - MiniMax 参考图会走 `subject_reference`，当前能力更偏角色 / 人像一致性。
 - 即梦不支持参考图。
 - 豆包参考图能力仅适用于 Seedream 5.0 / 4.5 / 4.0，不适用于 Seedream 3.0。
- Replicate 默认模型改为 `google/nano-banana-2`。`baoyu-imagine` 目前只对 `google/nano-banana*`、`bytedance/seedream-4.5`、`bytedance/seedream-5-lite`、`wan-video/wan-2.7-image` 和 `wan-video/wan-2.7-image-pro` 开启本地能力识别与校验。
+- Replicate 默认模型改为 `google/nano-banana-2`。`baoyu-image-gen` 目前只对 `google/nano-banana*`、`bytedance/seedream-4.5`、`bytedance/seedream-5-lite`、`wan-video/wan-2.7-image` 和 `wan-video/wan-2.7-image-pro` 开启本地能力识别与校验。
 - Replicate 当前只保存单张输出图，`--n > 1` 会在本地直接报错，避免多图结果被静默丢弃。
 - Replicate 的参数能力按模型家族区分：nano-banana 走 `--quality` / `--ar`，Seedream 走校验后的 `--size` / `--ar`，Wan 走校验后的 `--size`（`--ar` 会先在本地换算成具体尺寸）。

@@ -1145,12 +1147,49 @@ AI 驱动的生成后端。
 - 正常版和毒舌版两种风格
 - 支持从历史摘要回溯初始化画像

+#### baoyu-electron-extract
+
+从任意已安装的 Electron 应用的 `app.asar` 中提取资源和 JavaScript。当 `.js.map` 内嵌 `sourcesContent` 时，还原原始源码树（含 TypeScript/JSX）；否则用 Prettier 原地美化压缩后的 JS/CSS。始终跳过 `node_modules`。支持 macOS 和 Windows，其他平台请用 `--asar <path>` 指定 asar 文件。
+
+```bash
+# 按应用名提取（默认输出：~/Downloads/<AppName>-electron-extract/）
+/baoyu-electron-extract Codex
+
+# 按绝对路径提取（.app 包、安装目录或 .asar 文件均可）
+/baoyu-electron-extract "/Applications/Visual Studio Code.app"
+/baoyu-electron-extract --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
+
+# 自定义输出目录
+/baoyu-electron-extract Codex --output ~/work/codex-source
+
+# 仅预览发现的路径，不写入任何文件
+/baoyu-electron-extract Codex --dry-run
+
+# 覆盖已存在的输出目录
+/baoyu-electron-extract Codex --force
+```
+
+**选项**：
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `<app>` | 应用名或绝对路径（未给 `--asar` 时必填） | — |
+| `--output`, `-o` | 输出目录 | `~/Downloads/<AppName>-electron-extract` |
+| `--asar` | 覆盖解析得到的 `.asar` 路径 | 自动发现 |
+| `--force`, `-f` | 允许写入非空的已有输出目录 | false |
+| `--skip-format` | 跳过 Prettier 格式化 | false |
+| `--skip-restore` | 跳过 source-map 还原 | false |
+| `--no-unpacked` | 不复制同级的 `app.asar.unpacked/` | false |
+| `--dry-run` | 打印解析路径后退出，不写文件 | false |
+| `--json` | 在 stdout 输出一行 JSON 概要 | false |
+
+**输出结构**：`extract-report.json`（计数、警告、路径），`extracted/`（asar 原始内容，无 map 时原地美化），`extracted.unpacked/`（存在时复制的原生模块），以及 `restored/`（基于 `.js.map` 重建的源码树）。
+
 ## 环境配置

 部分技能需要 API 密钥或自定义配置。环境变量可以在 `.env` 文件中设置：

 **加载优先级**（高优先级覆盖低优先级）：
-1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-imagine ...`）
+1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-image-gen ...`）
 2. `process.env`（系统环境变量）
 3. `<cwd>/.baoyu-skills/.env`（项目级）
 4. `~/.baoyu-skills/.env`（用户级）
@@ -0,0 +1,256 @@
+# `codex-imagegen` Backend
+
+Generate images via Codex CLI's built-in `image_gen` tool from non-Codex runtimes (e.g., Claude Code). The wrapper spawns `codex exec --json` and lets the user's existing Codex subscription drive image generation — **no `OPENAI_API_KEY` required**.
+
+This backend implements the `preferred_image_backend: codex-imagegen` config key already referenced in several `SKILL.md` files across this repo.
+
+## Features
+
+| Feature | Status |
+|---------|--------|
+| **Reliability**: retry + exponential backoff | Default 2 retries |
+| **Verification**: confirms `image_gen` was actually invoked (not bypassed) | Checks `$CODEX_HOME/generated_images/{thread_id}/` |
+| **Verification**: PNG magic-byte sanity check | ✓ |
+| **Idempotency cache**: reuses output for same prompt+aspect+refs | `--cache-dir` |
+| **Concurrency control**: file lock prevents parallel `codex exec` collisions | Built-in |
+| **Structured logging**: JSONL log file | `--log-file` |
+| **Token usage returned** | Embedded in result JSON |
+| **`--ref` reference images** | Repeatable |
+| **Unit tests** | 16 tests (parser / cache / validator) |
+| **Error classification**: retryable vs non-retryable | 9 `error_kind` values |
+
+## Why this backend
+
+| Scenario | Conventional backend | This backend |
+|----------|---------------------|--------------|
+| You have a Codex subscription | OpenAI Images API costs add up per image | Subscription already covers it — zero marginal API cost |
+| No `OPENAI_API_KEY` available | `baoyu-image-gen` needs an API key | `codex login` is enough |
+| Want to use GPT Image 2 | Only via OpenAI API | Codex's `image_gen` *is* GPT Image 2 |
+
+## Prerequisites
+
+```bash
+npm install -g @openai/codex
+codex login            # signs in with your OpenAI account (subscription)
+codex --version        # confirm >= 0.130
+```
+
+`bun` is preferred for running the wrapper. On macOS:
+
+```bash
+brew install oven-sh/bun/bun
+```
+
+If `bun` is missing, the shell entrypoint falls back to `npx -y bun`.
+
+## Usage
+
+### Direct CLI
+
+```bash
+# Inline prompt
+./scripts/codex-imagegen.sh \
+  --image /tmp/cat.png \
+  --prompt "A friendly orange cat, watercolor"
+
+# Prompt from file
+./scripts/codex-imagegen.sh \
+  --image cover.png \
+  --prompt-file prompts/01-cover.md \
+  --aspect 16:9
+
+# Verbose mode for debugging
+./scripts/codex-imagegen.sh -v --image dog.png --prompt "A corgi" --aspect 1:1
+```
+
+On success, stdout emits a single JSON line:
+
+```json
+{"status":"ok","path":"/tmp/cat.png","bytes":2567101,"elapsed_seconds":53}
+```
+
+On failure, exit code is non-zero and stderr contains the error message.
+
+### Enabling within image skills
+
+Image-generating skills (e.g., `baoyu-cover-image`, `baoyu-article-illustrator`) already support a `preferred_image_backend` preference. To route them through this backend, set the following in the corresponding `EXTEND.md`:
+
+```yaml
+# ~/.baoyu-skills/baoyu-cover-image/EXTEND.md
+preferred_image_backend: codex-imagegen
+```
+
+When the LLM runs the skill, it reads the preference and — guided by the `### codex-imagegen Backend` section in `CLAUDE.md` — invokes `scripts/codex-imagegen.sh`.
+
+> **Note**: The integration is mediated by the LLM reading `CLAUDE.md`. It is not a hard binding. If a skill does not route to the backend automatically, mentioning it explicitly in the prompt works.
+
+## Parameters
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--image <path>` | ✓ | Output PNG path (absolute recommended; relative paths are resolved against cwd) |
+| `--prompt <text>` | one of | Prompt string (mutually exclusive with `--prompt-file`) |
+| `--prompt-file <path>` | one of | Read prompt from file (mutually exclusive with `--prompt`) |
+| `--aspect <ratio>` | | Aspect ratio. Default `1:1`. Common: `16:9`, `9:16`, `4:3`, `2.35:1` |
+| `--ref <file>` | | Reference image path (repeatable) |
+| `--timeout <ms>` | | `codex exec` timeout in ms. Default `300000` |
+| `--retries <n>` | | Retry count on retryable errors. Default `2` (total attempts = retries + 1) |
+| `--retry-delay <ms>` | | Base delay between retries (exponential backoff). Default `1500` |
+| `--cache-dir <path>` | | Enable idempotency cache (reuses output for same prompt+aspect+refs) |
+| `--log-file <path>` | | Structured JSONL log path (appended) |
+| `-v` / `--verbose` | | Mirror log entries to stderr |
+| `-h` / `--help` | | Show usage |
+
+## Structured Output
+
+On success, stdout contains a single JSON line:
+
+```json
+{
+  "status": "ok",
+  "path": "/tmp/owl.png",
+  "bytes": 1693831,
+  "elapsed_seconds": 87,
+  "thread_id": "019e40e8-daef-7c60-943d-5e7bb3f6cb3d",
+  "attempts": 1,
+  "cached": false,
+  "usage": {
+    "input": 110899,
+    "cached_input": 83456,
+    "output": 457,
+    "reasoning": 47
+  },
+  "tool_calls": [
+    {"tool": "shell", "status": "completed"},
+    {"tool": "agent_message", "status": "completed"}
+  ]
+}
+```
+
+Cache hits return with `elapsed_seconds: 0`, `cached: true`, `attempts: 0`.
+
+On failure, exit code is `1` and the JSON contains `error` and `error_kind`:
+
+```json
+{
+  "status": "error",
+  "error": "image_gen was not invoked: no PNG in ...",
+  "error_kind": "no_image_gen_tool_use"
+}
+```
+
+## Error Kinds
+
+| `error_kind` | Retryable | Meaning |
+|--------------|-----------|---------|
+| `codex_not_installed` | ✗ | `codex` CLI not found |
+| `invalid_args` | ✗ | Argument parsing error |
+| `prompt_file_missing` | ✗ | `--prompt-file` path does not exist |
+| `spawn_failed` | ✓ | `codex exec` exited non-zero |
+| `timeout` | ✓ | Exceeded `--timeout` |
+| `no_image_gen_tool_use` | ✓ | Agent did not invoke `image_gen` (it took another path) |
+| `output_missing` | ✓ | Output file not created |
+| `invalid_png` | ✓ | Output is not a valid PNG |
+| `agent_refused` | ✓ | No `thread_id` in event stream (Codex refused to respond) |
+| `lock_busy` | ✗ | Concurrency lock acquisition timed out |
+
+## Measured Performance
+
+| Metric | Value |
+|--------|-------|
+| First-run latency | 50–90 s |
+| Cache-hit latency | < 0.3 s |
+| Output dimensions | 1024×1024, 1672×941 (16:9), etc. — chosen by `image_gen` |
+| Output format | PNG (RGB, 8-bit) |
+| Token usage per call | ~110k input (~80k cached) + ~500 output |
+| Quota source | Codex subscription (does not consume OpenAI API quota) |
+| Default timeout | 300 s (5 min) |
+
+## Limitations & Risks
+
+1. **5–10× slower than direct API**. `codex exec` cold-starts the agent, loads the built-in `image_gen` SKILL.md, and runs reasoning before invoking the tool. Cache hits avoid this for repeated prompts.
+2. **ToS gray area**. Codex's `image_gen` tool is designed for interactive use. Invoking it programmatically via `codex exec` from an external agent is not explicitly addressed by current OpenAI policies. Suggested guardrails:
+   - Personal, low-volume use is reasonable.
+   - Not recommended for production automation or high-volume batch jobs.
+   - Users are responsible for ensuring their usage complies with applicable terms of service.
+3. **Sandbox permissions**. The wrapper passes `--sandbox danger-full-access` so the spawned agent can move the rendered PNG out of `$CODEX_HOME/generated_images/`. This is necessary because the agent must `cp`/`mv` the file to the user-specified output path.
+4. **Concurrency = 1**. The file lock serializes concurrent invocations to avoid `codex exec` collisions. Parallel calls queue.
+
+## Troubleshooting
+
+| Symptom | `error_kind` | Resolution |
+|---------|--------------|------------|
+| `command not found: codex` | `codex_not_installed` | `npm install -g @openai/codex` |
+| `codex exec` fails | `spawn_failed` | Check `codex login` status; inspect `raw_log` path |
+| Timeout | `timeout` | Pass `--timeout 600000` (10 min) for slow networks |
+| Agent skipped `image_gen` | `no_image_gen_tool_use` | Auto-retries; consider sharpening the prompt — abstract prompts let the agent wander |
+| Output missing | `output_missing` | Agent did not `cp` to the target path; check `raw_log` for the actual save location under `generated_images/` |
+| Lock held | `lock_busy` | Wait for the in-flight request to finish; or `rm ~/.cache/baoyu-codex-imagegen/codex-exec.lock` |
+| Low image quality | — | Sharpen the prompt, try a different aspect, or supply `--ref` |
+
+## Architecture
+
+```
+scripts/codex-imagegen.sh        # thin bash entrypoint
+scripts/codex-imagegen/
+├── main.ts        # parseArgs → cache → lock → retry loop → emit JSON
+├── types.ts       # CliOptions, GenerateResult, GenError, ErrorKind
+├── spawn.ts       # spawn codex exec --json --sandbox danger-full-access
+├── parser.ts      # parse JSONL event stream → toolCalls, usage, thread_id
+├── validator.ts   # verify image_gen invocation + PNG magic + file size
+├── cache.ts       # cacheKey(sha256), FileLock, lookup/store
+├── logger.ts      # JsonLogger (verbose stderr + JSONL file)
+├── parser.test.ts
+├── cache.test.ts
+└── validator.test.ts
+```
+
+Run tests:
+
+```bash
+cd scripts/codex-imagegen && bun test
+```
+
+## Internal Flow
+
+```mermaid
+flowchart LR
+    CC[Claude Code / any caller]
+    WRAPPER[scripts/codex-imagegen.sh]
+    CODEX["codex exec --json<br/>--sandbox danger-full-access"]
+    AGENT[Codex agent]
+    TOOL[image_gen built-in tool]
+    DEFAULT["$CODEX_HOME/<br/>generated_images/{thread_id}/"]
+    OUT[/specified OUTPUT path/]
+
+    CC -->|exec wrapper| WRAPPER
+    WRAPPER -->|stdin: instruction| CODEX
+    CODEX --> AGENT
+    AGENT -->|tool call| TOOL
+    TOOL -->|writes file| DEFAULT
+    AGENT -->|agent cp/mv| OUT
+    WRAPPER -->|verify + parse| CC
+
+    classDef cc fill:#1e40af,color:#fff,stroke:#93c5fd
+    classDef cdx fill:#7c2d12,color:#fff,stroke:#fdba74
+    class CC,WRAPPER cc
+    class CODEX,AGENT,TOOL cdx
+```
+
+## Design Decisions
+
+1. **Bash entrypoint + TypeScript implementation** — the shell wrapper picks the runtime (`bun` preferred, falling back to `npx -y bun`); TypeScript handles the orchestration, parsing, retry, cache, and logging. This mirrors the project's existing `scripts/*.mjs` and `skills/<skill>/scripts/main.ts` pattern.
+2. **`--sandbox danger-full-access`** — necessary so the spawned agent can `cp`/`mv` the rendered PNG out of `$CODEX_HOME/generated_images/` to the user-specified path. Standard sandboxes block this.
+3. **Parse the JSONL event stream** — the final `agent_message` and intermediate `command_execution` events let the wrapper verify what actually happened (was `image_gen` called? did `cp` reach the right destination?), which is far more reliable than scraping freeform stdout.
+4. **Infrastructure, not a skill** — this backend is a CLI utility that skills route to via `preferred_image_backend`. It belongs in `scripts/`, not `skills/`, because it has no `SKILL.md` and is never loaded directly by an agent.
+5. **File lock instead of internal queue** — keeps the implementation small and works across multiple shell sessions or processes invoking the same wrapper concurrently.
+
+## Related Files
+
+| File | Role |
+|------|------|
+| `scripts/codex-imagegen.sh` | CLI entrypoint |
+| `scripts/codex-imagegen/` | TypeScript implementation |
+| `docs/codex-imagegen-backend.md` | This document |
+| `CLAUDE.md` | Tells LLMs how to invoke this backend |
+| `.github/workflows/codex-imagegen-tests.yml` | CI unit tests |
@@ -165,11 +165,11 @@ Standard snippet (copy verbatim):

 When this skill needs to render an image:

- **Use whatever image-generation tool or skill is available** in the current runtime — e.g., Codex `imagegen`, Hermes `image_generate`, `baoyu-imagine`, or any equivalent the user has installed.
+- **Use whatever image-generation tool or skill is available** in the current runtime — e.g., Codex `imagegen`, Hermes `image_generate`, `baoyu-image-gen`, or any equivalent the user has installed.
 - **If multiple are available**, ask the user **once** at the start which to use (batch with any other initial questions).
 - **If none are available**, tell the user and ask how to proceed.

 **Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) above are examples — substitute the local equivalents under the same rule.
 ```
@@ -1,6 +1,6 @@
 # Image Generation Tools

-Skills in this repo are loaded by multiple agent runtimes (Claude Code, Codex, Hermes, other agents, bare CLI). Each runtime exposes a different image-generation capability — some have a runtime-native tool (Codex `imagegen`, Hermes `image_generate`), others rely on an installed skill (`baoyu-imagine`, or user-defined). This document defines the canonical **backend-selection rule** every skill that renders images follows so skills stay portable.
+Skills in this repo are loaded by multiple agent runtimes (Claude Code, Codex, Hermes, other agents, bare CLI). Each runtime exposes a different image-generation capability — some have a runtime-native tool (Codex `imagegen`, Hermes `image_generate`), others rely on an installed skill (`baoyu-image-gen`, or user-defined). This document defines the canonical **backend-selection rule** every skill that renders images follows so skills stay portable.

 ## The Rule

@@ -9,9 +9,9 @@ When a skill needs to render an image, resolve the backend in this order:
 1. **Current-request override** — if the user names a specific backend in the current message, use it.
 2. **Saved preference** — if the skill's `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
 3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
-   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
+   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-image-gen`) unless the user has explicitly pinned a different `preferred_image_backend`.
   - **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
-   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
+   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-image-gen`), use it.
   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
 4. **If none are available**, tell the user and ask how to proceed.

@@ -27,7 +27,7 @@ Each image-consuming skill's `EXTEND.md` carries a single `preferred_image_backe
 |---|---|
 | `auto` (default) | Apply the auto-select rule — runtime-native preferred, fall back to only installed backend, ask if multiple non-native. |
 | `ask` | Always confirm the backend on every run, even when a runtime-native tool exists. |
-| `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) | Pin this backend when available; fall back to `auto` if it isn't. |
+| `<backend-id>` (e.g., `codex-imagegen`, `baoyu-image-gen`, `image_generate`) | Pin this backend when available; fall back to `auto` if it isn't. |

 The field is **absent-equals-auto**: older `EXTEND.md` files without this field behave exactly as if `preferred_image_backend: auto` were set. No schema version bump is needed to introduce it.

@@ -41,8 +41,8 @@ Each `SKILL.md` that renders images includes **exactly one** `## Image Generatio

 Each skill's `references/config/preferences-schema.md` (and its `EXTEND.md` template in `first-time-setup.md`) lists `preferred_image_backend` alongside other preference fields. First-time setup does NOT ask the user about the backend — `auto` is set silently. Users who want to pin a specific backend edit `EXTEND.md` later, and each skill's `## Changing Preferences` section documents the common one-line edits.

-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) in this document and in SKILL.md are **examples** — agents in other runtimes apply the rule above and substitute the local equivalent. Skill-specific parameters for these backends are illustrative; runtimes without those knobs can omit them.
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) in this document and in SKILL.md are **examples** — agents in other runtimes apply the rule above and substitute the local equivalent. Skill-specific parameters for these backends are illustrative; runtimes without those knobs can omit them.

 ## Backend Skills Are Exempt

-Skills that **are themselves** image-generation backends — currently `baoyu-imagine`, `baoyu-image-gen` (deprecated), and `baoyu-danger-gemini-web` — do NOT include a `## Image Generation Tools` section. They render directly via their own provider integrations and have no need to "select a backend." The rule applies only to consumer skills that delegate rendering to whatever backend the runtime exposes.
+Skills that **are themselves** image-generation backends — currently `baoyu-image-gen`, `baoyu-image-gen` (deprecated), and `baoyu-danger-gemini-web` — do NOT include a `## Image Generation Tools` section. They render directly via their own provider integrations and have no need to "select a backend." The rule applies only to consumer skills that delegate rendering to whatever backend the runtime exposes.
@@ -28,7 +28,7 @@ Skills that require image generation MUST delegate to available image generation
 5. On failure, auto-retry once before reporting error
 ```

-**Batch Parallel** (`baoyu-imagine` only): concurrent workers with per-provider throttling via `batch.max_workers` in EXTEND.md.
+**Batch Parallel** (`baoyu-image-gen` only): concurrent workers with per-provider throttling via `batch.max_workers` in EXTEND.md.

 ## Output Path Convention

@@ -0,0 +1,729 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/mermaid.ts
+var exports_mermaid = {};
+__export(exports_mermaid, {
+  renderMermaidToPng: () => renderMermaidToPng,
+  closeRenderer: () => closeRenderer,
+  MermaidRenderError: () => MermaidRenderError
+});
+module.exports = __toCommonJS(exports_mermaid);
+var import_node_child_process2 = require("node:child_process");
+var import_node_fs2 = __toESM(require("node:fs"));
+var import_node_path2 = __toESM(require("node:path"));
+var import_node_process2 = __toESM(require("node:process"));
+var import_node_url = require("node:url");
+
+// src/index.ts
+var import_node_child_process = require("node:child_process");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_net = __toESM(require("node:net"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_process = __toESM(require("node:process"));
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function getFreePort(fixedEnvName) {
+  const fixed = fixedEnvName ? Number.parseInt(import_node_process.default.env[fixedEnvName] ?? "", 10) : NaN;
+  if (Number.isInteger(fixed) && fixed > 0)
+    return fixed;
+  return await new Promise((resolve, reject) => {
+    const server = import_node_net.default.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a free TCP port.")));
+        return;
+      }
+      const port = address.port;
+      server.close((err) => {
+        if (err)
+          reject(err);
+        else
+          resolve(port);
+      });
+    });
+  });
+}
+function findChromeExecutable(options) {
+  for (const envName of options.envNames ?? []) {
+    const override = import_node_process.default.env[envName]?.trim();
+    if (override && import_node_fs.default.existsSync(override))
+      return override;
+  }
+  const candidates = import_node_process.default.platform === "darwin" ? options.candidates.darwin ?? options.candidates.default : import_node_process.default.platform === "win32" ? options.candidates.win32 ?? options.candidates.default : options.candidates.default;
+  for (const candidate of candidates) {
+    if (import_node_fs.default.existsSync(candidate))
+      return candidate;
+  }
+  return;
+}
+function resolveSharedChromeProfileDir(options = {}) {
+  for (const envName of options.envNames ?? []) {
+    const override = import_node_process.default.env[envName]?.trim();
+    if (override)
+      return import_node_path.default.resolve(override);
+  }
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+  if (options.wslWindowsHome) {
+    return import_node_path.default.join(options.wslWindowsHome, ".local", "share", appDataDirName, profileDirName);
+  }
+  const base = import_node_process.default.platform === "darwin" ? import_node_path.default.join(import_node_os.default.homedir(), "Library", "Application Support") : import_node_process.default.platform === "win32" ? import_node_process.default.env.APPDATA ?? import_node_path.default.join(import_node_os.default.homedir(), "AppData", "Roaming") : import_node_process.default.env.XDG_DATA_HOME ?? import_node_path.default.join(import_node_os.default.homedir(), ".local", "share");
+  return import_node_path.default.join(base, appDataDirName, profileDirName);
+}
+async function fetchWithTimeout(url, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return await fetch(url, { redirect: "follow" });
+  const ctl = new AbortController;
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { redirect: "follow", signal: ctl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchJson(url, options = {}) {
+  const response = await fetchWithTimeout(url, options.timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return await response.json();
+}
+async function isDebugPortReady(port, timeoutMs = 3000) {
+  try {
+    const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+    return !!version.webSocketDebuggerUrl;
+  } catch {
+    return false;
+  }
+}
+function parseDevToolsActivePort(filePath) {
+  try {
+    const content = import_node_fs.default.readFileSync(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim();
+    if (port > 0 && wsPath)
+      return { port, wsPath };
+  } catch {}
+  return null;
+}
+async function findExistingChromeDebugPort(options) {
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const parsed = parseDevToolsActivePort(import_node_path.default.join(options.profileDir, "DevToolsActivePort"));
+  if (parsed && parsed.port > 0 && await isDebugPortReady(parsed.port, timeoutMs))
+    return parsed.port;
+  if (import_node_process.default.platform === "win32")
+    return null;
+  try {
+    const result = import_node_child_process.spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+    if (result.status !== 0 || !result.stdout)
+      return null;
+    const lines = result.stdout.split(`
+`).filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+    for (const line of lines) {
+      const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs))
+        return port;
+    }
+  } catch {}
+  return null;
+}
+async function waitForChromeDebugPort(port, timeoutMs, options) {
+  const start = Date.now();
+  let lastError = null;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs: 5000 });
+      if (version.webSocketDebuggerUrl)
+        return version.webSocketDebuggerUrl;
+      lastError = new Error("Missing webSocketDebuggerUrl");
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+  if (options?.includeLastError && lastError) {
+    throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  throw new Error("Chrome debug port not ready");
+}
+
+class CdpConnection {
+  ws;
+  nextId = 0;
+  pending = new Map;
+  eventHandlers = new Map;
+  defaultTimeoutMs;
+  constructor(ws, defaultTimeoutMs = 15000) {
+    this.ws = ws;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.method) {
+          const handlers = this.eventHandlers.get(msg.method);
+          if (handlers) {
+            handlers.forEach((handler) => handler(msg.params));
+          }
+        }
+        if (msg.id) {
+          const pending = this.pending.get(msg.id);
+          if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer)
+              clearTimeout(pending.timer);
+            if (msg.error?.message)
+              pending.reject(new Error(msg.error.message));
+            else
+              pending.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+    this.ws.addEventListener("close", () => {
+      for (const [id, pending] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (pending.timer)
+          clearTimeout(pending.timer);
+        pending.reject(new Error("CDP connection closed."));
+      }
+    });
+  }
+  static async connect(url, timeoutMs, options) {
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connection timeout.")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP connection failed."));
+      });
+    });
+    return new CdpConnection(ws, options?.defaultTimeoutMs ?? 15000);
+  }
+  on(method, handler) {
+    if (!this.eventHandlers.has(method)) {
+      this.eventHandlers.set(method, new Set);
+    }
+    this.eventHandlers.get(method)?.add(handler);
+  }
+  off(method, handler) {
+    this.eventHandlers.get(method)?.delete(handler);
+  }
+  async send(method, params, options) {
+    const id = ++this.nextId;
+    const message = { id, method };
+    if (params)
+      message.params = params;
+    if (options?.sessionId)
+      message.sessionId = options.sessionId;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const result = await new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }, timeoutMs) : null;
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(message));
+    });
+    return result;
+  }
+  close() {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+async function launchChrome(options) {
+  await import_node_fs.default.promises.mkdir(options.profileDir, { recursive: true });
+  const args = [
+    `--remote-debugging-port=${options.port}`,
+    `--user-data-dir=${options.profileDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...options.extraArgs ?? []
+  ];
+  if (options.headless)
+    args.push("--headless=new");
+  if (options.url)
+    args.push(options.url);
+  return import_node_child_process.spawn(options.chromePath, args, { stdio: "ignore" });
+}
+async function openPageSession(options) {
+  let targetId;
+  let createdTarget = false;
+  if (options.reusing) {
+    const created = await options.cdp.send("Target.createTarget", { url: options.url });
+    targetId = created.targetId;
+    createdTarget = true;
+  } else {
+    const targets = await options.cdp.send("Target.getTargets");
+    const existing = targets.targetInfos.find(options.matchTarget);
+    if (existing) {
+      targetId = existing.targetId;
+    } else {
+      const created = await options.cdp.send("Target.createTarget", { url: options.url });
+      targetId = created.targetId;
+      createdTarget = true;
+    }
+  }
+  const { sessionId } = await options.cdp.send("Target.attachToTarget", { targetId, flatten: true });
+  if (options.activateTarget ?? true) {
+    await options.cdp.send("Target.activateTarget", { targetId });
+  }
+  if (options.enablePage)
+    await options.cdp.send("Page.enable", {}, { sessionId });
+  if (options.enableRuntime)
+    await options.cdp.send("Runtime.enable", {}, { sessionId });
+  if (options.enableDom)
+    await options.cdp.send("DOM.enable", {}, { sessionId });
+  if (options.enableNetwork)
+    await options.cdp.send("Network.enable", {}, { sessionId });
+  return { sessionId, targetId, createdTarget };
+}
+
+// src/mermaid.ts
+class MermaidRenderError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "MermaidRenderError";
+    if (options?.cause !== undefined) {
+      this.cause = options.cause;
+    }
+  }
+}
+function resolveRenderScale(scale) {
+  const resolved = scale ?? 2;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render scale: ${scale}`);
+  }
+  return resolved;
+}
+function resolveMinWidth(minWidth) {
+  if (minWidth === undefined)
+    return;
+  if (!Number.isFinite(minWidth) || minWidth <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render minWidth: ${minWidth}`);
+  }
+  return minWidth;
+}
+var CHROME_CANDIDATES = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
+  ],
+  default: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+    "/usr/bin/microsoft-edge"
+  ]
+};
+var wslHome;
+function getWslWindowsHome() {
+  if (wslHome !== undefined)
+    return wslHome;
+  if (!import_node_process2.default.env.WSL_DISTRO_NAME) {
+    wslHome = null;
+    return null;
+  }
+  try {
+    const raw = import_node_child_process2.execSync('cmd.exe /C "echo %USERPROFILE%"', {
+      encoding: "utf-8",
+      timeout: 5000
+    }).trim().replace(/\r/g, "");
+    wslHome = import_node_child_process2.execSync(`wslpath -u "${raw}"`, {
+      encoding: "utf-8",
+      timeout: 5000
+    }).trim() || null;
+  } catch {
+    wslHome = null;
+  }
+  return wslHome;
+}
+function getProfileDir() {
+  return resolveSharedChromeProfileDir({
+    envNames: ["BAOYU_CHROME_PROFILE_DIR", "MERMAID_RENDER_PROFILE_DIR"],
+    wslWindowsHome: getWslWindowsHome()
+  });
+}
+function resolveAssetsDir() {
+  const here = import_node_url.fileURLToPath(undefined);
+  const dir = import_node_path2.default.dirname(here);
+  const candidates = [
+    import_node_path2.default.resolve(dir, "..", "assets"),
+    import_node_path2.default.resolve(dir, "assets")
+  ];
+  for (const candidate of candidates) {
+    if (import_node_fs2.default.existsSync(import_node_path2.default.join(candidate, "mermaid.min.js")))
+      return candidate;
+  }
+  throw new MermaidRenderError(`Cannot locate mermaid.min.js. Looked in: ${candidates.join(", ")}`);
+}
+var cachedMermaidScript = null;
+function loadMermaidScript() {
+  if (cachedMermaidScript)
+    return cachedMermaidScript;
+  const assetsDir = resolveAssetsDir();
+  cachedMermaidScript = import_node_fs2.default.readFileSync(import_node_path2.default.join(assetsDir, "mermaid.min.js"), "utf-8");
+  return cachedMermaidScript;
+}
+var rendererState = null;
+var connectingPromise = null;
+var exitHookInstalled = false;
+function installExitHook() {
+  if (exitHookInstalled)
+    return;
+  exitHookInstalled = true;
+  const cleanup = () => {
+    const state = rendererState;
+    rendererState = null;
+    if (!state)
+      return;
+    try {
+      state.cdp.close();
+    } catch {}
+    if (state.ownsChrome && state.chrome) {
+      try {
+        state.chrome.kill("SIGTERM");
+      } catch {}
+    }
+  };
+  import_node_process2.default.on("exit", cleanup);
+  import_node_process2.default.on("beforeExit", cleanup);
+}
+async function tryConnectExisting(port) {
+  try {
+    const wsUrl = await waitForChromeDebugPort(port, 5000, { includeLastError: true });
+    return await CdpConnection.connect(wsUrl, 5000);
+  } catch {
+    return null;
+  }
+}
+async function ensureRenderer() {
+  if (rendererState)
+    return rendererState;
+  if (connectingPromise)
+    return await connectingPromise;
+  connectingPromise = (async () => {
+    const profileDir = getProfileDir();
+    const existingPort = await findExistingChromeDebugPort({ profileDir });
+    if (existingPort) {
+      const cdp2 = await tryConnectExisting(existingPort);
+      if (cdp2) {
+        const state2 = {
+          cdp: cdp2,
+          chrome: null,
+          port: existingPort,
+          ownsChrome: false
+        };
+        rendererState = state2;
+        installExitHook();
+        return state2;
+      }
+    }
+    const chromePath = findChromeExecutable({
+      candidates: CHROME_CANDIDATES,
+      envNames: ["BAOYU_CHROME_PATH", "MERMAID_RENDER_CHROME_PATH"]
+    });
+    if (!chromePath) {
+      throw new MermaidRenderError("Chrome not found. Install Google Chrome / Chromium / Edge, or set BAOYU_CHROME_PATH.");
+    }
+    const port = await getFreePort("MERMAID_RENDER_DEBUG_PORT");
+    const chrome = await launchChrome({
+      chromePath,
+      profileDir,
+      port,
+      headless: true,
+      extraArgs: [
+        "--disable-blink-features=AutomationControlled",
+        "--disable-gpu",
+        "--hide-scrollbars"
+      ]
+    });
+    const wsUrl = await waitForChromeDebugPort(port, 30000, { includeLastError: true });
+    const cdp = await CdpConnection.connect(wsUrl, 30000);
+    const state = { cdp, chrome, port, ownsChrome: true };
+    rendererState = state;
+    installExitHook();
+    return state;
+  })();
+  try {
+    return await connectingPromise;
+  } finally {
+    connectingPromise = null;
+  }
+}
+function buildHostHtml(code, theme, background) {
+  const script = loadMermaidScript();
+  const safeCode = code.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const safeTheme = JSON.stringify(theme);
+  const cssBackground = background === "transparent" ? "transparent" : background;
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  html, body {
+    margin: 0;
+    padding: 0;
+    background: ${cssBackground};
+    font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Hiragino Sans GB", "Noto Sans CJK SC", sans-serif;
+  }
+  #host {
+    display: inline-block;
+    padding: 16px;
+  }
+  #host svg {
+    max-width: none !important;
+  }
+</style>
+</head>
+<body>
+<div id="host"><div class="mermaid">${safeCode}</div></div>
+<script>${script}</script>
+<script>
+  window.__mermaidReady = false;
+  window.__mermaidError = null;
+  try {
+    mermaid.initialize({ startOnLoad: false, theme: ${safeTheme}, securityLevel: "loose" });
+    mermaid.run({ querySelector: ".mermaid" })
+      .then(function () { window.__mermaidReady = true; })
+      .catch(function (err) { window.__mermaidError = String(err && err.message || err); });
+  } catch (err) {
+    window.__mermaidError = String(err && err.message || err);
+  }
+</script>
+</body>
+</html>`;
+}
+async function evaluate(cdp, sessionId, expression) {
+  const result = await cdp.send("Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+    awaitPromise: false
+  }, { sessionId });
+  const exception = result.exceptionDetails;
+  if (exception) {
+    return {
+      value: undefined,
+      exceptionText: exception.exception?.description ?? exception.text ?? "evaluation failed"
+    };
+  }
+  return { value: result.result.value };
+}
+async function waitForMermaidSvg(cdp, sessionId, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const status = await evaluate(cdp, sessionId, `(function () {
+        if (window.__mermaidError) {
+          return { ready: false, error: window.__mermaidError, rect: null };
+        }
+        var svg = document.querySelector(".mermaid svg");
+        if (!svg) return { ready: false, error: null, rect: null };
+        var bbox = svg.getBoundingClientRect();
+        return {
+          ready: window.__mermaidReady === true,
+          error: null,
+          rect: {
+            x: bbox.x,
+            y: bbox.y,
+            width: bbox.width,
+            height: bbox.height,
+          },
+        };
+      })()`);
+    if (status.exceptionText) {
+      throw new MermaidRenderError(`Mermaid evaluation failed: ${status.exceptionText}`);
+    }
+    const value = status.value;
+    if (value?.error) {
+      throw new MermaidRenderError(`Mermaid render failed: ${value.error}`);
+    }
+    if (value?.ready && value.rect && value.rect.width > 0 && value.rect.height > 0) {
+      const host = await evaluate(cdp, sessionId, `(function () {
+          var host = document.getElementById("host");
+          if (!host) return null;
+          var rect = host.getBoundingClientRect();
+          return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+        })()`);
+      if (host.value)
+        return host.value;
+      return value.rect;
+    }
+    await sleep(80);
+  }
+  throw new MermaidRenderError(`Mermaid render timed out after ${timeoutMs}ms`);
+}
+async function withPageSession(state, fn) {
+  let session = null;
+  try {
+    session = await openPageSession({
+      cdp: state.cdp,
+      reusing: !state.ownsChrome,
+      url: "about:blank",
+      matchTarget: () => false,
+      enablePage: true,
+      enableRuntime: true
+    });
+    return await fn(session.sessionId, session.targetId);
+  } finally {
+    if (session?.createdTarget) {
+      try {
+        await state.cdp.send("Target.closeTarget", { targetId: session.targetId });
+      } catch {}
+    }
+  }
+}
+async function renderMermaidToPng(code, outputPath, options = {}) {
+  const theme = options.theme ?? "default";
+  const scale = resolveRenderScale(options.scale);
+  const minWidth = resolveMinWidth(options.minWidth);
+  const background = options.background ?? "white";
+  const timeoutMs = options.timeoutMs ?? 15000;
+  if (!code.trim()) {
+    throw new MermaidRenderError("Mermaid code is empty");
+  }
+  await import_node_fs2.default.promises.mkdir(import_node_path2.default.dirname(outputPath), { recursive: true });
+  const state = await ensureRenderer();
+  const html = buildHostHtml(code, theme, background);
+  return await withPageSession(state, async (sessionId) => {
+    await state.cdp.send("Emulation.setDeviceMetricsOverride", {
+      width: 1280,
+      height: 800,
+      deviceScaleFactor: 1,
+      mobile: false
+    }, { sessionId });
+    await state.cdp.send("Page.setDocumentContent", { frameId: await getFrameId(state.cdp, sessionId), html }, { sessionId });
+    const rect = await waitForMermaidSvg(state.cdp, sessionId, timeoutMs);
+    const cssWidth = Math.max(1, Math.ceil(rect.width));
+    const cssHeight = Math.max(1, Math.ceil(rect.height));
+    const targetCssWidth = Math.max(cssWidth, Math.ceil(minWidth ?? cssWidth));
+    const captureScale = scale * (targetCssWidth / cssWidth);
+    const bitmapWidth = Math.max(1, Math.ceil(cssWidth * captureScale));
+    const bitmapHeight = Math.max(1, Math.ceil(cssHeight * captureScale));
+    await state.cdp.send("Emulation.setDeviceMetricsOverride", {
+      width: cssWidth,
+      height: cssHeight,
+      deviceScaleFactor: 1,
+      mobile: false
+    }, { sessionId });
+    const shot = await state.cdp.send("Page.captureScreenshot", {
+      format: "png",
+      clip: {
+        x: rect.x,
+        y: rect.y,
+        width: cssWidth,
+        height: cssHeight,
+        scale: captureScale
+      },
+      captureBeyondViewport: true
+    }, { sessionId });
+    const buffer = Buffer.from(shot.data, "base64");
+    await import_node_fs2.default.promises.writeFile(outputPath, buffer);
+    return {
+      width: bitmapWidth,
+      height: bitmapHeight,
+      bytes: buffer.length
+    };
+  });
+}
+async function getFrameId(cdp, sessionId) {
+  const result = await cdp.send("Page.getFrameTree", {}, { sessionId });
+  return result.frameTree.frame.id;
+}
+async function closeRenderer() {
+  const state = rendererState;
+  rendererState = null;
+  if (!state)
+    return;
+  try {
+    state.cdp.close();
+  } catch {}
+  if (state.ownsChrome && state.chrome) {
+    try {
+      state.chrome.kill("SIGTERM");
+    } catch {}
+  }
+}
@@ -0,0 +1,665 @@
+// src/mermaid.ts
+import { execSync } from "node:child_process";
+import fs2 from "node:fs";
+import path2 from "node:path";
+import process2 from "node:process";
+import { fileURLToPath } from "node:url";
+
+// src/index.ts
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function getFreePort(fixedEnvName) {
+  const fixed = fixedEnvName ? Number.parseInt(process.env[fixedEnvName] ?? "", 10) : NaN;
+  if (Number.isInteger(fixed) && fixed > 0)
+    return fixed;
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a free TCP port.")));
+        return;
+      }
+      const port = address.port;
+      server.close((err) => {
+        if (err)
+          reject(err);
+        else
+          resolve(port);
+      });
+    });
+  });
+}
+function findChromeExecutable(options) {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override && fs.existsSync(override))
+      return override;
+  }
+  const candidates = process.platform === "darwin" ? options.candidates.darwin ?? options.candidates.default : process.platform === "win32" ? options.candidates.win32 ?? options.candidates.default : options.candidates.default;
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate))
+      return candidate;
+  }
+  return;
+}
+function resolveSharedChromeProfileDir(options = {}) {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override)
+      return path.resolve(override);
+  }
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+  if (options.wslWindowsHome) {
+    return path.join(options.wslWindowsHome, ".local", "share", appDataDirName, profileDirName);
+  }
+  const base = process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support") : process.platform === "win32" ? process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming") : process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+  return path.join(base, appDataDirName, profileDirName);
+}
+async function fetchWithTimeout(url, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return await fetch(url, { redirect: "follow" });
+  const ctl = new AbortController;
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { redirect: "follow", signal: ctl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchJson(url, options = {}) {
+  const response = await fetchWithTimeout(url, options.timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return await response.json();
+}
+async function isDebugPortReady(port, timeoutMs = 3000) {
+  try {
+    const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+    return !!version.webSocketDebuggerUrl;
+  } catch {
+    return false;
+  }
+}
+function parseDevToolsActivePort(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim();
+    if (port > 0 && wsPath)
+      return { port, wsPath };
+  } catch {}
+  return null;
+}
+async function findExistingChromeDebugPort(options) {
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const parsed = parseDevToolsActivePort(path.join(options.profileDir, "DevToolsActivePort"));
+  if (parsed && parsed.port > 0 && await isDebugPortReady(parsed.port, timeoutMs))
+    return parsed.port;
+  if (process.platform === "win32")
+    return null;
+  try {
+    const result = spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+    if (result.status !== 0 || !result.stdout)
+      return null;
+    const lines = result.stdout.split(`
+`).filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+    for (const line of lines) {
+      const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs))
+        return port;
+    }
+  } catch {}
+  return null;
+}
+async function waitForChromeDebugPort(port, timeoutMs, options) {
+  const start = Date.now();
+  let lastError = null;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs: 5000 });
+      if (version.webSocketDebuggerUrl)
+        return version.webSocketDebuggerUrl;
+      lastError = new Error("Missing webSocketDebuggerUrl");
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+  if (options?.includeLastError && lastError) {
+    throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  throw new Error("Chrome debug port not ready");
+}
+
+class CdpConnection {
+  ws;
+  nextId = 0;
+  pending = new Map;
+  eventHandlers = new Map;
+  defaultTimeoutMs;
+  constructor(ws, defaultTimeoutMs = 15000) {
+    this.ws = ws;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.method) {
+          const handlers = this.eventHandlers.get(msg.method);
+          if (handlers) {
+            handlers.forEach((handler) => handler(msg.params));
+          }
+        }
+        if (msg.id) {
+          const pending = this.pending.get(msg.id);
+          if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer)
+              clearTimeout(pending.timer);
+            if (msg.error?.message)
+              pending.reject(new Error(msg.error.message));
+            else
+              pending.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+    this.ws.addEventListener("close", () => {
+      for (const [id, pending] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (pending.timer)
+          clearTimeout(pending.timer);
+        pending.reject(new Error("CDP connection closed."));
+      }
+    });
+  }
+  static async connect(url, timeoutMs, options) {
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connection timeout.")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP connection failed."));
+      });
+    });
+    return new CdpConnection(ws, options?.defaultTimeoutMs ?? 15000);
+  }
+  on(method, handler) {
+    if (!this.eventHandlers.has(method)) {
+      this.eventHandlers.set(method, new Set);
+    }
+    this.eventHandlers.get(method)?.add(handler);
+  }
+  off(method, handler) {
+    this.eventHandlers.get(method)?.delete(handler);
+  }
+  async send(method, params, options) {
+    const id = ++this.nextId;
+    const message = { id, method };
+    if (params)
+      message.params = params;
+    if (options?.sessionId)
+      message.sessionId = options.sessionId;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const result = await new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }, timeoutMs) : null;
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(message));
+    });
+    return result;
+  }
+  close() {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+async function launchChrome(options) {
+  await fs.promises.mkdir(options.profileDir, { recursive: true });
+  const args = [
+    `--remote-debugging-port=${options.port}`,
+    `--user-data-dir=${options.profileDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...options.extraArgs ?? []
+  ];
+  if (options.headless)
+    args.push("--headless=new");
+  if (options.url)
+    args.push(options.url);
+  return spawn(options.chromePath, args, { stdio: "ignore" });
+}
+async function openPageSession(options) {
+  let targetId;
+  let createdTarget = false;
+  if (options.reusing) {
+    const created = await options.cdp.send("Target.createTarget", { url: options.url });
+    targetId = created.targetId;
+    createdTarget = true;
+  } else {
+    const targets = await options.cdp.send("Target.getTargets");
+    const existing = targets.targetInfos.find(options.matchTarget);
+    if (existing) {
+      targetId = existing.targetId;
+    } else {
+      const created = await options.cdp.send("Target.createTarget", { url: options.url });
+      targetId = created.targetId;
+      createdTarget = true;
+    }
+  }
+  const { sessionId } = await options.cdp.send("Target.attachToTarget", { targetId, flatten: true });
+  if (options.activateTarget ?? true) {
+    await options.cdp.send("Target.activateTarget", { targetId });
+  }
+  if (options.enablePage)
+    await options.cdp.send("Page.enable", {}, { sessionId });
+  if (options.enableRuntime)
+    await options.cdp.send("Runtime.enable", {}, { sessionId });
+  if (options.enableDom)
+    await options.cdp.send("DOM.enable", {}, { sessionId });
+  if (options.enableNetwork)
+    await options.cdp.send("Network.enable", {}, { sessionId });
+  return { sessionId, targetId, createdTarget };
+}
+
+// src/mermaid.ts
+class MermaidRenderError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "MermaidRenderError";
+    if (options?.cause !== undefined) {
+      this.cause = options.cause;
+    }
+  }
+}
+function resolveRenderScale(scale) {
+  const resolved = scale ?? 2;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render scale: ${scale}`);
+  }
+  return resolved;
+}
+function resolveMinWidth(minWidth) {
+  if (minWidth === undefined)
+    return;
+  if (!Number.isFinite(minWidth) || minWidth <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render minWidth: ${minWidth}`);
+  }
+  return minWidth;
+}
+var CHROME_CANDIDATES = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
+  ],
+  default: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+    "/usr/bin/microsoft-edge"
+  ]
+};
+var wslHome;
+function getWslWindowsHome() {
+  if (wslHome !== undefined)
+    return wslHome;
+  if (!process2.env.WSL_DISTRO_NAME) {
+    wslHome = null;
+    return null;
+  }
+  try {
+    const raw = execSync('cmd.exe /C "echo %USERPROFILE%"', {
+      encoding: "utf-8",
+      timeout: 5000
+    }).trim().replace(/\r/g, "");
+    wslHome = execSync(`wslpath -u "${raw}"`, {
+      encoding: "utf-8",
+      timeout: 5000
+    }).trim() || null;
+  } catch {
+    wslHome = null;
+  }
+  return wslHome;
+}
+function getProfileDir() {
+  return resolveSharedChromeProfileDir({
+    envNames: ["BAOYU_CHROME_PROFILE_DIR", "MERMAID_RENDER_PROFILE_DIR"],
+    wslWindowsHome: getWslWindowsHome()
+  });
+}
+function resolveAssetsDir() {
+  const here = fileURLToPath(import.meta.url);
+  const dir = path2.dirname(here);
+  const candidates = [
+    path2.resolve(dir, "..", "assets"),
+    path2.resolve(dir, "assets")
+  ];
+  for (const candidate of candidates) {
+    if (fs2.existsSync(path2.join(candidate, "mermaid.min.js")))
+      return candidate;
+  }
+  throw new MermaidRenderError(`Cannot locate mermaid.min.js. Looked in: ${candidates.join(", ")}`);
+}
+var cachedMermaidScript = null;
+function loadMermaidScript() {
+  if (cachedMermaidScript)
+    return cachedMermaidScript;
+  const assetsDir = resolveAssetsDir();
+  cachedMermaidScript = fs2.readFileSync(path2.join(assetsDir, "mermaid.min.js"), "utf-8");
+  return cachedMermaidScript;
+}
+var rendererState = null;
+var connectingPromise = null;
+var exitHookInstalled = false;
+function installExitHook() {
+  if (exitHookInstalled)
+    return;
+  exitHookInstalled = true;
+  const cleanup = () => {
+    const state = rendererState;
+    rendererState = null;
+    if (!state)
+      return;
+    try {
+      state.cdp.close();
+    } catch {}
+    if (state.ownsChrome && state.chrome) {
+      try {
+        state.chrome.kill("SIGTERM");
+      } catch {}
+    }
+  };
+  process2.on("exit", cleanup);
+  process2.on("beforeExit", cleanup);
+}
+async function tryConnectExisting(port) {
+  try {
+    const wsUrl = await waitForChromeDebugPort(port, 5000, { includeLastError: true });
+    return await CdpConnection.connect(wsUrl, 5000);
+  } catch {
+    return null;
+  }
+}
+async function ensureRenderer() {
+  if (rendererState)
+    return rendererState;
+  if (connectingPromise)
+    return await connectingPromise;
+  connectingPromise = (async () => {
+    const profileDir = getProfileDir();
+    const existingPort = await findExistingChromeDebugPort({ profileDir });
+    if (existingPort) {
+      const cdp2 = await tryConnectExisting(existingPort);
+      if (cdp2) {
+        const state2 = {
+          cdp: cdp2,
+          chrome: null,
+          port: existingPort,
+          ownsChrome: false
+        };
+        rendererState = state2;
+        installExitHook();
+        return state2;
+      }
+    }
+    const chromePath = findChromeExecutable({
+      candidates: CHROME_CANDIDATES,
+      envNames: ["BAOYU_CHROME_PATH", "MERMAID_RENDER_CHROME_PATH"]
+    });
+    if (!chromePath) {
+      throw new MermaidRenderError("Chrome not found. Install Google Chrome / Chromium / Edge, or set BAOYU_CHROME_PATH.");
+    }
+    const port = await getFreePort("MERMAID_RENDER_DEBUG_PORT");
+    const chrome = await launchChrome({
+      chromePath,
+      profileDir,
+      port,
+      headless: true,
+      extraArgs: [
+        "--disable-blink-features=AutomationControlled",
+        "--disable-gpu",
+        "--hide-scrollbars"
+      ]
+    });
+    const wsUrl = await waitForChromeDebugPort(port, 30000, { includeLastError: true });
+    const cdp = await CdpConnection.connect(wsUrl, 30000);
+    const state = { cdp, chrome, port, ownsChrome: true };
+    rendererState = state;
+    installExitHook();
+    return state;
+  })();
+  try {
+    return await connectingPromise;
+  } finally {
+    connectingPromise = null;
+  }
+}
+function buildHostHtml(code, theme, background) {
+  const script = loadMermaidScript();
+  const safeCode = code.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const safeTheme = JSON.stringify(theme);
+  const cssBackground = background === "transparent" ? "transparent" : background;
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  html, body {
+    margin: 0;
+    padding: 0;
+    background: ${cssBackground};
+    font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Hiragino Sans GB", "Noto Sans CJK SC", sans-serif;
+  }
+  #host {
+    display: inline-block;
+    padding: 16px;
+  }
+  #host svg {
+    max-width: none !important;
+  }
+</style>
+</head>
+<body>
+<div id="host"><div class="mermaid">${safeCode}</div></div>
+<script>${script}</script>
+<script>
+  window.__mermaidReady = false;
+  window.__mermaidError = null;
+  try {
+    mermaid.initialize({ startOnLoad: false, theme: ${safeTheme}, securityLevel: "loose" });
+    mermaid.run({ querySelector: ".mermaid" })
+      .then(function () { window.__mermaidReady = true; })
+      .catch(function (err) { window.__mermaidError = String(err && err.message || err); });
+  } catch (err) {
+    window.__mermaidError = String(err && err.message || err);
+  }
+</script>
+</body>
+</html>`;
+}
+async function evaluate(cdp, sessionId, expression) {
+  const result = await cdp.send("Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+    awaitPromise: false
+  }, { sessionId });
+  const exception = result.exceptionDetails;
+  if (exception) {
+    return {
+      value: undefined,
+      exceptionText: exception.exception?.description ?? exception.text ?? "evaluation failed"
+    };
+  }
+  return { value: result.result.value };
+}
+async function waitForMermaidSvg(cdp, sessionId, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const status = await evaluate(cdp, sessionId, `(function () {
+        if (window.__mermaidError) {
+          return { ready: false, error: window.__mermaidError, rect: null };
+        }
+        var svg = document.querySelector(".mermaid svg");
+        if (!svg) return { ready: false, error: null, rect: null };
+        var bbox = svg.getBoundingClientRect();
+        return {
+          ready: window.__mermaidReady === true,
+          error: null,
+          rect: {
+            x: bbox.x,
+            y: bbox.y,
+            width: bbox.width,
+            height: bbox.height,
+          },
+        };
+      })()`);
+    if (status.exceptionText) {
+      throw new MermaidRenderError(`Mermaid evaluation failed: ${status.exceptionText}`);
+    }
+    const value = status.value;
+    if (value?.error) {
+      throw new MermaidRenderError(`Mermaid render failed: ${value.error}`);
+    }
+    if (value?.ready && value.rect && value.rect.width > 0 && value.rect.height > 0) {
+      const host = await evaluate(cdp, sessionId, `(function () {
+          var host = document.getElementById("host");
+          if (!host) return null;
+          var rect = host.getBoundingClientRect();
+          return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+        })()`);
+      if (host.value)
+        return host.value;
+      return value.rect;
+    }
+    await sleep(80);
+  }
+  throw new MermaidRenderError(`Mermaid render timed out after ${timeoutMs}ms`);
+}
+async function withPageSession(state, fn) {
+  let session = null;
+  try {
+    session = await openPageSession({
+      cdp: state.cdp,
+      reusing: !state.ownsChrome,
+      url: "about:blank",
+      matchTarget: () => false,
+      enablePage: true,
+      enableRuntime: true
+    });
+    return await fn(session.sessionId, session.targetId);
+  } finally {
+    if (session?.createdTarget) {
+      try {
+        await state.cdp.send("Target.closeTarget", { targetId: session.targetId });
+      } catch {}
+    }
+  }
+}
+async function renderMermaidToPng(code, outputPath, options = {}) {
+  const theme = options.theme ?? "default";
+  const scale = resolveRenderScale(options.scale);
+  const minWidth = resolveMinWidth(options.minWidth);
+  const background = options.background ?? "white";
+  const timeoutMs = options.timeoutMs ?? 15000;
+  if (!code.trim()) {
+    throw new MermaidRenderError("Mermaid code is empty");
+  }
+  await fs2.promises.mkdir(path2.dirname(outputPath), { recursive: true });
+  const state = await ensureRenderer();
+  const html = buildHostHtml(code, theme, background);
+  return await withPageSession(state, async (sessionId) => {
+    await state.cdp.send("Emulation.setDeviceMetricsOverride", {
+      width: 1280,
+      height: 800,
+      deviceScaleFactor: 1,
+      mobile: false
+    }, { sessionId });
+    await state.cdp.send("Page.setDocumentContent", { frameId: await getFrameId(state.cdp, sessionId), html }, { sessionId });
+    const rect = await waitForMermaidSvg(state.cdp, sessionId, timeoutMs);
+    const cssWidth = Math.max(1, Math.ceil(rect.width));
+    const cssHeight = Math.max(1, Math.ceil(rect.height));
+    const targetCssWidth = Math.max(cssWidth, Math.ceil(minWidth ?? cssWidth));
+    const captureScale = scale * (targetCssWidth / cssWidth);
+    const bitmapWidth = Math.max(1, Math.ceil(cssWidth * captureScale));
+    const bitmapHeight = Math.max(1, Math.ceil(cssHeight * captureScale));
+    await state.cdp.send("Emulation.setDeviceMetricsOverride", {
+      width: cssWidth,
+      height: cssHeight,
+      deviceScaleFactor: 1,
+      mobile: false
+    }, { sessionId });
+    const shot = await state.cdp.send("Page.captureScreenshot", {
+      format: "png",
+      clip: {
+        x: rect.x,
+        y: rect.y,
+        width: cssWidth,
+        height: cssHeight,
+        scale: captureScale
+      },
+      captureBeyondViewport: true
+    }, { sessionId });
+    const buffer = Buffer.from(shot.data, "base64");
+    await fs2.promises.writeFile(outputPath, buffer);
+    return {
+      width: bitmapWidth,
+      height: bitmapHeight,
+      bytes: buffer.length
+    };
+  });
+}
+async function getFrameId(cdp, sessionId) {
+  const result = await cdp.send("Page.getFrameTree", {}, { sessionId });
+  return result.frameTree.frame.id;
+}
+async function closeRenderer() {
+  const state = rendererState;
+  rendererState = null;
+  if (!state)
+    return;
+  try {
+    state.cdp.close();
+  } catch {}
+  if (state.ownsChrome && state.chrome) {
+    try {
+      state.chrome.kill("SIGTERM");
+    } catch {}
+  }
+}
+export {
+  renderMermaidToPng,
+  closeRenderer,
+  MermaidRenderError
+};
@@ -5,6 +5,7 @@
  "files": [
    "dist",
    "src/**/*.ts",
+    "assets",
    "!src/**/*.test.ts"
  ],
  "exports": {
@@ -14,7 +15,14 @@
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    },
-    "./src/*": "./src/*"
+    "./mermaid": {
+      "types": "./src/mermaid.ts",
+      "import": "./dist/mermaid.js",
+      "require": "./dist/mermaid.cjs",
+      "default": "./dist/mermaid.js"
+    },
+    "./src/*": "./src/*",
+    "./assets/*": "./assets/*"
  },
  "description": "Shared Chrome DevTools Protocol utilities for baoyu skills.",
  "main": "./dist/index.cjs",
@@ -33,7 +41,7 @@
    "access": "public"
  },
  "scripts": {
-    "build": "node ../../scripts/build-shared-package.mjs",
+    "build": "node ../../scripts/build-shared-package.mjs --entry-out src/index.ts:index --entry-out src/mermaid.ts:mermaid --asset assets:assets",
    "prepack": "bun run build"
  },
  "engines": {
@@ -0,0 +1,499 @@
+import { execSync, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+  CdpConnection,
+  findChromeExecutable,
+  findExistingChromeDebugPort,
+  getFreePort,
+  launchChrome,
+  openPageSession,
+  resolveSharedChromeProfileDir,
+  sleep,
+  waitForChromeDebugPort,
+  type PageSession,
+  type PlatformCandidates,
+} from "./index.js";
+
+export class MermaidRenderError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "MermaidRenderError";
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+export interface MermaidRenderOptions {
+  theme?: string;
+  scale?: number;
+  background?: string;
+  timeoutMs?: number;
+  minWidth?: number;
+}
+
+export interface MermaidRenderResult {
+  width: number;
+  height: number;
+  bytes: number;
+}
+
+function resolveRenderScale(scale: number | undefined): number {
+  const resolved = scale ?? 2;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render scale: ${scale}`);
+  }
+  return resolved;
+}
+
+function resolveMinWidth(minWidth: number | undefined): number | undefined {
+  if (minWidth === undefined) return undefined;
+  if (!Number.isFinite(minWidth) || minWidth <= 0) {
+    throw new MermaidRenderError(`Invalid Mermaid render minWidth: ${minWidth}`);
+  }
+  return minWidth;
+}
+
+const CHROME_CANDIDATES: PlatformCandidates = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+  ],
+  default: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+    "/usr/bin/microsoft-edge",
+  ],
+};
+
+let wslHome: string | null | undefined;
+function getWslWindowsHome(): string | null {
+  if (wslHome !== undefined) return wslHome;
+  if (!process.env.WSL_DISTRO_NAME) {
+    wslHome = null;
+    return null;
+  }
+  try {
+    const raw = execSync('cmd.exe /C "echo %USERPROFILE%"', {
+      encoding: "utf-8",
+      timeout: 5_000,
+    }).trim().replace(/\r/g, "");
+    wslHome = execSync(`wslpath -u "${raw}"`, {
+      encoding: "utf-8",
+      timeout: 5_000,
+    }).trim() || null;
+  } catch {
+    wslHome = null;
+  }
+  return wslHome;
+}
+
+function getProfileDir(): string {
+  return resolveSharedChromeProfileDir({
+    envNames: ["BAOYU_CHROME_PROFILE_DIR", "MERMAID_RENDER_PROFILE_DIR"],
+    wslWindowsHome: getWslWindowsHome(),
+  });
+}
+
+function resolveAssetsDir(): string {
+  const here = fileURLToPath(import.meta.url);
+  const dir = path.dirname(here);
+  const candidates = [
+    path.resolve(dir, "..", "assets"),
+    path.resolve(dir, "assets"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, "mermaid.min.js"))) return candidate;
+  }
+  throw new MermaidRenderError(
+    `Cannot locate mermaid.min.js. Looked in: ${candidates.join(", ")}`,
+  );
+}
+
+let cachedMermaidScript: string | null = null;
+function loadMermaidScript(): string {
+  if (cachedMermaidScript) return cachedMermaidScript;
+  const assetsDir = resolveAssetsDir();
+  cachedMermaidScript = fs.readFileSync(path.join(assetsDir, "mermaid.min.js"), "utf-8");
+  return cachedMermaidScript;
+}
+
+interface RendererState {
+  cdp: CdpConnection;
+  chrome: ChildProcess | null;
+  port: number | null;
+  ownsChrome: boolean;
+}
+
+let rendererState: RendererState | null = null;
+let connectingPromise: Promise<RendererState> | null = null;
+let exitHookInstalled = false;
+
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  const cleanup = () => {
+    const state = rendererState;
+    rendererState = null;
+    if (!state) return;
+    try { state.cdp.close(); } catch {}
+    if (state.ownsChrome && state.chrome) {
+      try { state.chrome.kill("SIGTERM"); } catch {}
+    }
+  };
+  process.on("exit", cleanup);
+  process.on("beforeExit", cleanup);
+}
+
+async function tryConnectExisting(port: number): Promise<CdpConnection | null> {
+  try {
+    const wsUrl = await waitForChromeDebugPort(port, 5_000, { includeLastError: true });
+    return await CdpConnection.connect(wsUrl, 5_000);
+  } catch {
+    return null;
+  }
+}
+
+async function ensureRenderer(): Promise<RendererState> {
+  if (rendererState) return rendererState;
+  if (connectingPromise) return await connectingPromise;
+
+  connectingPromise = (async (): Promise<RendererState> => {
+    const profileDir = getProfileDir();
+    const existingPort = await findExistingChromeDebugPort({ profileDir });
+    if (existingPort) {
+      const cdp = await tryConnectExisting(existingPort);
+      if (cdp) {
+        const state: RendererState = {
+          cdp,
+          chrome: null,
+          port: existingPort,
+          ownsChrome: false,
+        };
+        rendererState = state;
+        installExitHook();
+        return state;
+      }
+    }
+
+    const chromePath = findChromeExecutable({
+      candidates: CHROME_CANDIDATES,
+      envNames: ["BAOYU_CHROME_PATH", "MERMAID_RENDER_CHROME_PATH"],
+    });
+    if (!chromePath) {
+      throw new MermaidRenderError(
+        "Chrome not found. Install Google Chrome / Chromium / Edge, or set BAOYU_CHROME_PATH.",
+      );
+    }
+
+    const port = await getFreePort("MERMAID_RENDER_DEBUG_PORT");
+    const chrome = await launchChrome({
+      chromePath,
+      profileDir,
+      port,
+      headless: true,
+      extraArgs: [
+        "--disable-blink-features=AutomationControlled",
+        "--disable-gpu",
+        "--hide-scrollbars",
+      ],
+    });
+
+    const wsUrl = await waitForChromeDebugPort(port, 30_000, { includeLastError: true });
+    const cdp = await CdpConnection.connect(wsUrl, 30_000);
+    const state: RendererState = { cdp, chrome, port, ownsChrome: true };
+    rendererState = state;
+    installExitHook();
+    return state;
+  })();
+
+  try {
+    return await connectingPromise;
+  } finally {
+    connectingPromise = null;
+  }
+}
+
+function buildHostHtml(code: string, theme: string, background: string): string {
+  const script = loadMermaidScript();
+  const safeCode = code
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+  const safeTheme = JSON.stringify(theme);
+  const cssBackground = background === "transparent" ? "transparent" : background;
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  html, body {
+    margin: 0;
+    padding: 0;
+    background: ${cssBackground};
+    font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Hiragino Sans GB", "Noto Sans CJK SC", sans-serif;
+  }
+  #host {
+    display: inline-block;
+    padding: 16px;
+  }
+  #host svg {
+    max-width: none !important;
+  }
+</style>
+</head>
+<body>
+<div id="host"><div class="mermaid">${safeCode}</div></div>
+<script>${script}</script>
+<script>
+  window.__mermaidReady = false;
+  window.__mermaidError = null;
+  try {
+    mermaid.initialize({ startOnLoad: false, theme: ${safeTheme}, securityLevel: "loose" });
+    mermaid.run({ querySelector: ".mermaid" })
+      .then(function () { window.__mermaidReady = true; })
+      .catch(function (err) { window.__mermaidError = String(err && err.message || err); });
+  } catch (err) {
+    window.__mermaidError = String(err && err.message || err);
+  }
+</script>
+</body>
+</html>`;
+}
+
+async function evaluate<T = unknown>(
+  cdp: CdpConnection,
+  sessionId: string,
+  expression: string,
+): Promise<{ value: T | undefined; exceptionText?: string }> {
+  const result = await cdp.send<{
+    result: { value?: T };
+    exceptionDetails?: { text?: string; exception?: { description?: string } };
+  }>(
+    "Runtime.evaluate",
+    {
+      expression,
+      returnByValue: true,
+      awaitPromise: false,
+    },
+    { sessionId },
+  );
+  const exception = result.exceptionDetails;
+  if (exception) {
+    return {
+      value: undefined,
+      exceptionText: exception.exception?.description ?? exception.text ?? "evaluation failed",
+    };
+  }
+  return { value: result.result.value };
+}
+
+interface BoundingRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+async function waitForMermaidSvg(
+  cdp: CdpConnection,
+  sessionId: string,
+  timeoutMs: number,
+): Promise<BoundingRect> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const status = await evaluate<{
+      ready: boolean;
+      error: string | null;
+      rect: BoundingRect | null;
+    }>(
+      cdp,
+      sessionId,
+      `(function () {
+        if (window.__mermaidError) {
+          return { ready: false, error: window.__mermaidError, rect: null };
+        }
+        var svg = document.querySelector(".mermaid svg");
+        if (!svg) return { ready: false, error: null, rect: null };
+        var bbox = svg.getBoundingClientRect();
+        return {
+          ready: window.__mermaidReady === true,
+          error: null,
+          rect: {
+            x: bbox.x,
+            y: bbox.y,
+            width: bbox.width,
+            height: bbox.height,
+          },
+        };
+      })()`,
+    );
+    if (status.exceptionText) {
+      throw new MermaidRenderError(`Mermaid evaluation failed: ${status.exceptionText}`);
+    }
+    const value = status.value;
+    if (value?.error) {
+      throw new MermaidRenderError(`Mermaid render failed: ${value.error}`);
+    }
+    if (value?.ready && value.rect && value.rect.width > 0 && value.rect.height > 0) {
+      const host = await evaluate<BoundingRect | null>(
+        cdp,
+        sessionId,
+        `(function () {
+          var host = document.getElementById("host");
+          if (!host) return null;
+          var rect = host.getBoundingClientRect();
+          return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+        })()`,
+      );
+      if (host.value) return host.value;
+      return value.rect;
+    }
+    await sleep(80);
+  }
+  throw new MermaidRenderError(`Mermaid render timed out after ${timeoutMs}ms`);
+}
+
+async function withPageSession<T>(
+  state: RendererState,
+  fn: (sessionId: string, targetId: string) => Promise<T>,
+): Promise<T> {
+  let session: PageSession | null = null;
+  try {
+    session = await openPageSession({
+      cdp: state.cdp,
+      reusing: !state.ownsChrome,
+      url: "about:blank",
+      matchTarget: () => false,
+      enablePage: true,
+      enableRuntime: true,
+    });
+    return await fn(session.sessionId, session.targetId);
+  } finally {
+    if (session?.createdTarget) {
+      try {
+        await state.cdp.send("Target.closeTarget", { targetId: session.targetId });
+      } catch {}
+    }
+  }
+}
+
+export async function renderMermaidToPng(
+  code: string,
+  outputPath: string,
+  options: MermaidRenderOptions = {},
+): Promise<MermaidRenderResult> {
+  const theme = options.theme ?? "default";
+  const scale = resolveRenderScale(options.scale);
+  const minWidth = resolveMinWidth(options.minWidth);
+  const background = options.background ?? "white";
+  const timeoutMs = options.timeoutMs ?? 15_000;
+
+  if (!code.trim()) {
+    throw new MermaidRenderError("Mermaid code is empty");
+  }
+
+  await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
+
+  const state = await ensureRenderer();
+  const html = buildHostHtml(code, theme, background);
+
+  return await withPageSession(state, async (sessionId) => {
+    await state.cdp.send(
+      "Emulation.setDeviceMetricsOverride",
+      {
+        width: 1280,
+        height: 800,
+        deviceScaleFactor: 1,
+        mobile: false,
+      },
+      { sessionId },
+    );
+
+    await state.cdp.send(
+      "Page.setDocumentContent",
+      { frameId: await getFrameId(state.cdp, sessionId), html },
+      { sessionId },
+    );
+
+    const rect = await waitForMermaidSvg(state.cdp, sessionId, timeoutMs);
+
+    const cssWidth = Math.max(1, Math.ceil(rect.width));
+    const cssHeight = Math.max(1, Math.ceil(rect.height));
+    const targetCssWidth = Math.max(cssWidth, Math.ceil(minWidth ?? cssWidth));
+    const captureScale = scale * (targetCssWidth / cssWidth);
+    const bitmapWidth = Math.max(1, Math.ceil(cssWidth * captureScale));
+    const bitmapHeight = Math.max(1, Math.ceil(cssHeight * captureScale));
+
+    await state.cdp.send(
+      "Emulation.setDeviceMetricsOverride",
+      {
+        width: cssWidth,
+        height: cssHeight,
+        deviceScaleFactor: 1,
+        mobile: false,
+      },
+      { sessionId },
+    );
+
+    const shot = await state.cdp.send<{ data: string }>(
+      "Page.captureScreenshot",
+      {
+        format: "png",
+        clip: {
+          x: rect.x,
+          y: rect.y,
+          width: cssWidth,
+          height: cssHeight,
+          scale: captureScale,
+        },
+        captureBeyondViewport: true,
+      },
+      { sessionId },
+    );
+
+    const buffer = Buffer.from(shot.data, "base64");
+    await fs.promises.writeFile(outputPath, buffer);
+
+    return {
+      width: bitmapWidth,
+      height: bitmapHeight,
+      bytes: buffer.length,
+    };
+  });
+}
+
+async function getFrameId(cdp: CdpConnection, sessionId: string): Promise<string> {
+  const result = await cdp.send<{ frameTree: { frame: { id: string } } }>(
+    "Page.getFrameTree",
+    {},
+    { sessionId },
+  );
+  return result.frameTree.frame.id;
+}
+
+export async function closeRenderer(): Promise<void> {
+  const state = rendererState;
+  rendererState = null;
+  if (!state) return;
+  try { state.cdp.close(); } catch {}
+  if (state.ownsChrome && state.chrome) {
+    try { state.chrome.kill("SIGTERM"); } catch {}
+  }
+}
@@ -5,6 +5,8 @@ export * from "./document.js";
 export * from "./extend-config.js";
 export * from "./html-builder.js";
 export * from "./images.js";
+export * from "./mermaid-preprocess.js";
+export * from "./mermaid-utils.js";
 export * from "./renderer.js";
 export * from "./themes.js";
 export * from "./types.js";
@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  preprocessMermaidInMarkdown,
+  type MermaidRenderFn,
+} from "./mermaid-preprocess.ts";
+
+function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mermaid-preprocess-test-"));
+  return fn(dir).finally(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+}
+
+const stubPngBytes = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+const stubRender: MermaidRenderFn = async (_code, outPath) => {
+  await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+  await fs.promises.writeFile(outPath, stubPngBytes);
+};
+
+test("preprocessMermaidInMarkdown skips when disabled", async () => {
+  await withTempDir(async (baseDir) => {
+    const markdown = "```mermaid\ngraph TD\nA-->B\n```";
+    const result = await preprocessMermaidInMarkdown(markdown, {
+      baseDir,
+      renderFn: stubRender,
+      enabled: false,
+    });
+    assert.equal(result.markdown, markdown);
+    assert.equal(result.images.length, 0);
+  });
+});
+
+test("preprocessMermaidInMarkdown skips when renderFn is missing", async () => {
+  await withTempDir(async (baseDir) => {
+    const markdown = "```mermaid\ngraph TD\nA-->B\n```";
+    const result = await preprocessMermaidInMarkdown(markdown, { baseDir });
+    assert.equal(result.markdown, markdown);
+    assert.equal(result.images.length, 0);
+  });
+});
+
+test("preprocessMermaidInMarkdown deduplicates identical blocks via hashed cache", async () => {
+  await withTempDir(async (baseDir) => {
+    const block = "```mermaid\ngraph TD\nA-->B\n```";
+    const markdown = `${block}\n\nsome text\n\n${block}\n\nother text\n\n\`\`\`mermaid\nflowchart LR\nX-->Y\n\`\`\``;
+
+    let renderCalls = 0;
+    const renderFn: MermaidRenderFn = async (code, outPath) => {
+      renderCalls += 1;
+      await stubRender(code, outPath, {});
+    };
+
+    const result = await preprocessMermaidInMarkdown(markdown, {
+      baseDir,
+      renderFn,
+    });
+
+    assert.equal(renderCalls, 2, "should render two distinct blocks");
+    assert.equal(result.images.length, 3, "all three blocks produce image entries");
+    const uniqueHashes = new Set(result.images.map((image) => image.hash));
+    assert.equal(uniqueHashes.size, 2);
+
+    const matches = result.markdown.match(/!\[Mermaid diagram\]/g) ?? [];
+    assert.equal(matches.length, 3);
+    assert.ok(!result.markdown.includes("```mermaid"));
+  });
+});
+
+test("preprocessMermaidInMarkdown reuses cached files (cached=true when file exists)", async () => {
+  await withTempDir(async (baseDir) => {
+    const markdown = "```mermaid\ngraph TD\nA-->B\n```";
+
+    let renderCalls = 0;
+    const renderFn: MermaidRenderFn = async (code, outPath) => {
+      renderCalls += 1;
+      await stubRender(code, outPath, {});
+    };
+
+    const first = await preprocessMermaidInMarkdown(markdown, { baseDir, renderFn });
+    assert.equal(renderCalls, 1);
+    assert.equal(first.images[0]!.cached, false);
+
+    const second = await preprocessMermaidInMarkdown(markdown, { baseDir, renderFn });
+    assert.equal(renderCalls, 1, "second pass hits cache");
+    assert.equal(second.images[0]!.cached, true);
+  });
+});
+
+test("preprocessMermaidInMarkdown survives renderFn errors and keeps raw block", async () => {
+  await withTempDir(async (baseDir) => {
+    const markdown = "```mermaid\ninvalid syntax!!\n```\n\nrest";
+    const errors: string[] = [];
+    const failingRender: MermaidRenderFn = async () => {
+      throw new Error("render boom");
+    };
+
+    const result = await preprocessMermaidInMarkdown(markdown, {
+      baseDir,
+      renderFn: failingRender,
+      onError: (error) => {
+        errors.push(error instanceof Error ? error.message : String(error));
+      },
+    });
+
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0], "render boom");
+    assert.equal(result.images.length, 0);
+    assert.ok(result.markdown.includes("```mermaid"));
+    assert.ok(result.markdown.includes("rest"));
+  });
+});
+
+test("preprocessMermaidInMarkdown writes PNGs under imgs/.mermaid-cache/", async () => {
+  await withTempDir(async (baseDir) => {
+    const markdown = "```mermaid\ngraph TD\nA-->B\n```";
+    const result = await preprocessMermaidInMarkdown(markdown, {
+      baseDir,
+      renderFn: stubRender,
+    });
+    assert.equal(result.images.length, 1);
+    const image = result.images[0]!;
+    assert.ok(image.localPath.includes(path.join("imgs", ".mermaid-cache")));
+    assert.ok(image.mdRef.includes("imgs/.mermaid-cache/"));
+    assert.ok(fs.existsSync(image.localPath));
+  });
+});
@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  MERMAID_VERSION,
+  extractMermaidBlocks,
+  hashMermaidCode,
+  replaceMermaidBlocks,
+  type MermaidBlock,
+} from "./mermaid-utils.js";
+
+export interface MermaidRenderOptions {
+  theme?: string;
+  scale?: number;
+  background?: string;
+  minWidth?: number;
+}
+
+export type MermaidRenderFn = (
+  code: string,
+  outputPath: string,
+  options: MermaidRenderOptions,
+) => Promise<void>;
+
+export interface MermaidPreprocessOptions extends MermaidRenderOptions {
+  baseDir: string;
+  imgSubdir?: string;
+  renderFn?: MermaidRenderFn;
+  enabled?: boolean;
+  alt?: string;
+  onError?: (error: unknown, block: MermaidBlock) => void;
+}
+
+export interface MermaidPreprocessedImage {
+  raw: string;
+  code: string;
+  hash: string;
+  localPath: string;
+  mdRef: string;
+  cached: boolean;
+}
+
+export interface MermaidPreprocessResult {
+  markdown: string;
+  images: MermaidPreprocessedImage[];
+}
+
+export async function preprocessMermaidInMarkdown(
+  markdown: string,
+  options: MermaidPreprocessOptions,
+): Promise<MermaidPreprocessResult> {
+  const {
+    baseDir,
+    imgSubdir = "imgs/.mermaid-cache",
+    renderFn,
+    enabled = true,
+    theme,
+    scale,
+    background,
+    minWidth,
+    alt = "Mermaid diagram",
+    onError,
+  } = options;
+
+  if (!enabled || !renderFn) {
+    return { markdown, images: [] };
+  }
+
+  const blocks = extractMermaidBlocks(markdown);
+  if (blocks.length === 0) {
+    return { markdown, images: [] };
+  }
+
+  const cacheDir = path.resolve(baseDir, imgSubdir);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const replacements = new Map<string, string>();
+  const images: MermaidPreprocessedImage[] = [];
+  const renderedHashes = new Set<string>();
+
+  for (const block of blocks) {
+    const hash = hashMermaidCode({
+      code: block.code,
+      theme,
+      scale,
+      background,
+      minWidth,
+      version: MERMAID_VERSION,
+    });
+    const filename = `mermaid-${hash}.png`;
+    const localPath = path.join(cacheDir, filename);
+    const mdRef = `![${alt}](${path.posix.join(imgSubdir, filename)})`;
+
+    const cached = fs.existsSync(localPath);
+
+    if (!cached && !renderedHashes.has(hash)) {
+      try {
+        await renderFn(block.code, localPath, { theme, scale, background, minWidth });
+        renderedHashes.add(hash);
+      } catch (error) {
+        if (onError) {
+          onError(error, block);
+        } else {
+          console.error(
+            `[mermaid] render failed for block (hash ${hash}): ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+        continue;
+      }
+    }
+
+    if (!fs.existsSync(localPath)) {
+      continue;
+    }
+
+    replacements.set(block.raw, mdRef);
+    images.push({
+      raw: block.raw,
+      code: block.code,
+      hash,
+      localPath,
+      mdRef,
+      cached,
+    });
+  }
+
+  const newMarkdown = replaceMermaidBlocks(markdown, replacements);
+  return { markdown: newMarkdown, images };
+}
@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MERMAID_VERSION,
+  extractMermaidBlocks,
+  hashMermaidCode,
+  replaceMermaidBlocks,
+} from "./mermaid-utils.ts";
+
+test("extractMermaidBlocks finds fenced mermaid blocks at the top level", () => {
+  const markdown = `Intro
+
+\`\`\`mermaid
+graph TD
+  A --> B
+\`\`\`
+
+Outro`;
+
+  const blocks = extractMermaidBlocks(markdown);
+  assert.equal(blocks.length, 1);
+  assert.equal(blocks[0]!.code.trim(), "graph TD\n  A --> B");
+  assert.equal(blocks[0]!.infoString, "");
+  assert.ok(blocks[0]!.raw.includes("```mermaid"));
+});
+
+test("extractMermaidBlocks preserves info-string suffixes", () => {
+  const markdown = "```mermaid theme=dark\nflowchart LR\n  A --> B\n```";
+  const blocks = extractMermaidBlocks(markdown);
+  assert.equal(blocks.length, 1);
+  assert.equal(blocks[0]!.infoString, "theme=dark");
+});
+
+test("extractMermaidBlocks finds blocks nested inside lists", () => {
+  const markdown = `Steps:
+
+1. First, render the diagram:
+
+   \`\`\`mermaid
+   sequenceDiagram
+     Alice->>Bob: Hello
+   \`\`\`
+
+2. Then do something else.`;
+
+  const blocks = extractMermaidBlocks(markdown);
+  assert.equal(blocks.length, 1);
+  assert.equal(blocks[0]!.code.includes("sequenceDiagram"), true);
+});
+
+test("extractMermaidBlocks ignores non-mermaid fences and empty blocks", () => {
+  const markdown = `\`\`\`ts
+const x = 1;
+\`\`\`
+
+\`\`\`mermaid
+
+\`\`\`
+
+\`\`\`mermaidsomething
+not a real lang
+\`\`\``;
+
+  const blocks = extractMermaidBlocks(markdown);
+  assert.equal(blocks.length, 1);
+  assert.equal(blocks[0]!.infoString, "something");
+  assert.equal(blocks[0]!.code.trim(), "not a real lang");
+});
+
+test("replaceMermaidBlocks performs exact string replacement", () => {
+  const markdown = "before\n\n```mermaid\ngraph TD\nA-->B\n```\n\nafter";
+  const blocks = extractMermaidBlocks(markdown);
+  const map = new Map([[blocks[0]!.raw, "![diagram](img.png)"]]);
+  const replaced = replaceMermaidBlocks(markdown, map);
+  assert.equal(replaced, "before\n\n![diagram](img.png)\n\nafter");
+});
+
+test("replaceMermaidBlocks leaves markdown unchanged when no replacements match", () => {
+  const markdown = "hello\n\nworld";
+  const replaced = replaceMermaidBlocks(markdown, new Map([["nope", "x"]]));
+  assert.equal(replaced, markdown);
+});
+
+test("hashMermaidCode is stable for the same inputs", () => {
+  const a = hashMermaidCode({ code: "graph TD\nA-->B" });
+  const b = hashMermaidCode({ code: "graph TD\nA-->B" });
+  assert.equal(a, b);
+  assert.equal(a.length, 12);
+});
+
+test("hashMermaidCode defaults to 2x render scale", () => {
+  const implicit = hashMermaidCode({ code: "graph TD\nA-->B" });
+  const explicit = hashMermaidCode({ code: "graph TD\nA-->B", scale: 2 });
+  assert.equal(implicit, explicit);
+});
+
+test("hashMermaidCode ignores trailing whitespace", () => {
+  const a = hashMermaidCode({ code: "graph TD\nA-->B" });
+  const b = hashMermaidCode({ code: "graph TD\nA-->B   \n\n" });
+  assert.equal(a, b);
+});
+
+test("hashMermaidCode reflects theme/scale/background/version changes", () => {
+  const base = hashMermaidCode({ code: "graph TD\nA-->B" });
+  assert.notEqual(base, hashMermaidCode({ code: "graph TD\nA-->B", theme: "dark" }));
+  assert.notEqual(base, hashMermaidCode({ code: "graph TD\nA-->B", scale: 3 }));
+  assert.notEqual(base, hashMermaidCode({ code: "graph TD\nA-->B", minWidth: 860 }));
+  assert.notEqual(base, hashMermaidCode({ code: "graph TD\nA-->B", background: "#000" }));
+  assert.notEqual(base, hashMermaidCode({ code: "graph TD\nA-->B", version: "x.y.z" }));
+});
+
+test("MERMAID_VERSION matches the vendored bundle (10.x)", () => {
+  assert.match(MERMAID_VERSION, /^10\./);
+});
@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { Marked, type Tokens } from "marked";
+
+export const MERMAID_VERSION = "10.9.1";
+
+export interface MermaidBlock {
+  raw: string;
+  code: string;
+  infoString: string;
+}
+
+export interface HashMermaidInput {
+  code: string;
+  theme?: string;
+  scale?: number;
+  background?: string;
+  minWidth?: number;
+  version?: string;
+}
+
+export function extractMermaidBlocks(markdown: string): MermaidBlock[] {
+  const blocks: MermaidBlock[] = [];
+  const lexer = new Marked({ breaks: true });
+  const tokens = lexer.lexer(markdown);
+  walkTokens(tokens, (token) => {
+    if (token.type !== "code") return;
+    const codeToken = token as Tokens.Code;
+    const lang = (codeToken.lang ?? "").trim();
+    if (!lang.startsWith("mermaid")) return;
+    const infoString = lang.slice("mermaid".length).trim();
+    const code = codeToken.text ?? "";
+    if (code.trim() === "") return;
+    blocks.push({
+      raw: codeToken.raw,
+      code,
+      infoString,
+    });
+  });
+  return blocks;
+}
+
+export function replaceMermaidBlocks(
+  markdown: string,
+  replacements: Map<string, string>,
+): string {
+  let result = markdown;
+  for (const [raw, replacement] of replacements) {
+    if (!raw || replacement === undefined) continue;
+    result = result.split(raw).join(replacement);
+  }
+  return result;
+}
+
+export function hashMermaidCode(input: HashMermaidInput): string {
+  const payload = JSON.stringify({
+    code: input.code.replace(/\s+$/g, ""),
+    theme: input.theme ?? "default",
+    scale: input.scale ?? 2,
+    minWidth: input.minWidth ?? null,
+    background: input.background ?? "white",
+    version: input.version ?? MERMAID_VERSION,
+  });
+  return createHash("sha256").update(payload).digest("hex").slice(0, 12);
+}
+
+type AnyToken = { type?: string; tokens?: AnyToken[]; items?: AnyToken[] };
+
+function walkTokens(tokens: AnyToken[], visit: (token: AnyToken) => void): void {
+  for (const token of tokens) {
+    visit(token);
+    if (Array.isArray(token.tokens)) walkTokens(token.tokens, visit);
+    if (Array.isArray(token.items)) walkTokens(token.items, visit);
+  }
+}
@@ -119,7 +119,6 @@ function wrapInlineCode(value: string): string {
 export function initRenderer(opts: IOpts = {}): RendererAPI {
  const footnotes: [number, string, string][] = [];
  let footnoteIndex = 0;
-  let codeIndex = 0;
  const listOrderedStack: boolean[] = [];
  const listCounters: number[] = [];
  const isBrowser = typeof window !== "undefined";
@@ -208,20 +207,7 @@ export function initRenderer(opts: IOpts = {}): RendererAPI {

    code({ text, lang = "" }: Tokens.Code): string {
      if (lang.startsWith("mermaid")) {
-        if (isBrowser) {
-          clearTimeout(codeIndex as any);
-          codeIndex = setTimeout(async () => {
-            const windowRef = typeof window !== "undefined" ? (window as any) : undefined;
-            if (windowRef && windowRef.mermaid) {
-              const mermaid = windowRef.mermaid;
-              await mermaid.run();
-            } else {
-              const mermaid = await import("mermaid");
-              await mermaid.default.run();
-            }
-          }, 0) as any as number;
-        }
-        return `<pre class="mermaid">${text}</pre>`;
+        return `<pre class="mermaid">${escapeHtml(text)}</pre>`;
      }
      const langText = lang.split(" ")[0];
      const isLanguageRegistered = hljs.getLanguage(langText);
@@ -9,27 +9,33 @@ import { pathToFileURL } from "node:url";
 async function main() {
  const options = parseArgs(process.argv.slice(2));
  const packageDir = path.resolve(options.packageDir);
-  const entryPath = path.resolve(packageDir, options.entry);
  const outDir = path.resolve(packageDir, options.outDir);

  await fs.rm(outDir, { recursive: true, force: true });
  await fs.mkdir(outDir, { recursive: true });

  const bun = resolveBunRuntime();
-  runBuild(bun, {
-    entryPath,
-    external: options.external,
-    format: "esm",
-    outfile: path.join(outDir, "index.js"),
-  });
-  const cjsOutfile = path.join(outDir, "index.cjs");
-  runBuild(bun, {
-    entryPath,
-    external: options.external,
-    format: "cjs",
-    outfile: cjsOutfile,
-  });
-  await scrubCommonJsSourceFileUrls(cjsOutfile, packageDir);
+  const entries = options.entries.length > 0
+    ? options.entries
+    : [{ source: options.entry, name: "index" }];
+
+  for (const entry of entries) {
+    const entryPath = path.resolve(packageDir, entry.source);
+    runBuild(bun, {
+      entryPath,
+      external: options.external,
+      format: "esm",
+      outfile: path.join(outDir, `${entry.name}.js`),
+    });
+    const cjsOutfile = path.join(outDir, `${entry.name}.cjs`);
+    runBuild(bun, {
+      entryPath,
+      external: options.external,
+      format: "cjs",
+      outfile: cjsOutfile,
+    });
+    await scrubCommonJsSourceFileUrls(cjsOutfile, packageDir);
+  }

  for (const asset of options.assets) {
    const source = path.resolve(packageDir, asset.source);
@@ -45,6 +51,7 @@ function parseArgs(argv) {
    outDir: "dist",
    external: [],
    assets: [],
+    entries: [],
  };

  for (let index = 0; index < argv.length; index += 1) {
@@ -57,6 +64,10 @@ function parseArgs(argv) {
      options.entry = readArgValue(argv, ++index, arg);
      continue;
    }
+    if (arg === "--entry-out") {
+      options.entries.push(parseEntryOutArg(readArgValue(argv, ++index, arg)));
+      continue;
+    }
    if (arg === "--out-dir") {
      options.outDir = readArgValue(argv, ++index, arg);
      continue;
@@ -79,6 +90,14 @@ function parseArgs(argv) {
  return options;
 }

+function parseEntryOutArg(value) {
+  const [source, name] = value.split(":");
+  if (!source || !name) {
+    throw new Error(`Invalid --entry-out value: ${value} (expected <source>:<name>)`);
+  }
+  return { source, name };
+}
+
 function readArgValue(argv, index, flag) {
  const value = argv[index];
  if (!value) {
@@ -153,12 +172,13 @@ function printUsage() {
  console.log(`Usage: build-shared-package.mjs [options]

 Options:
-  --package-dir <dir>  Package root (default: current directory)
-  --entry <file>       Entry file relative to package root (default: src/index.ts)
-  --out-dir <dir>     Output directory relative to package root (default: dist)
-  --external <name>   Leave a module external (can be repeated)
-  --asset <src[:dst]> Copy an asset directory/file into out-dir (can be repeated)
-  -h, --help          Show help`);
+  --package-dir <dir>     Package root (default: current directory)
+  --entry <file>          Entry file relative to package root (default: src/index.ts)
+  --entry-out <src:name>  Add an entry that emits <name>.js / <name>.cjs (repeatable)
+  --out-dir <dir>         Output directory relative to package root (default: dist)
+  --external <name>       Leave a module external (can be repeated)
+  --asset <src[:dst]>     Copy an asset directory/file into out-dir (can be repeated)
+  -h, --help              Show help`);
 }

 main().catch((error) => {
@@ -0,0 +1,19 @@
+#!/bin/bash
+# codex-imagegen: generate images via Codex CLI's built-in image_gen tool
+# Thin shell wrapper — implementation in codex-imagegen/main.ts (Bun TypeScript)
+#
+# Usage: ./codex-imagegen.sh --help
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if command -v bun &>/dev/null; then
+    BUN_X="bun"
+elif command -v npx &>/dev/null; then
+    BUN_X="npx -y bun"
+else
+    echo "Error: bun or npx required. Install: brew install oven-sh/bun/bun" >&2
+    exit 1
+fi
+
+exec $BUN_X "$SCRIPT_DIR/codex-imagegen/main.ts" "$@"
@@ -0,0 +1,63 @@
+import { test, expect } from "bun:test";
+import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
+
+test("cacheKey is deterministic and order-independent for refs", () => {
+  const k1 = cacheKey("hello", "16:9", ["a.png", "b.png"]);
+  const k2 = cacheKey("hello", "16:9", ["b.png", "a.png"]);
+  expect(k1).toBe(k2);
+  const k3 = cacheKey("hello", "16:9", []);
+  expect(k3).not.toBe(k1);
+  const k4 = cacheKey("hello", "1:1", []);
+  expect(k4).not.toBe(k3);
+});
+
+test("lookupCache returns null on miss, path on hit", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
+  try {
+    expect(await lookupCache(dir, "abc")).toBeNull();
+    const fake = path.join(dir, "abc.png");
+    await writeFile(fake, Buffer.alloc(2000));
+    expect(await lookupCache(dir, "abc")).toBe(fake);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("storeCache copies source into cache", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
+  const src = path.join(dir, "src.png");
+  try {
+    await writeFile(src, Buffer.from("xxxx".repeat(1000)));
+    await storeCache(dir, "key1", src);
+    const cached = await lookupCache(dir, "key1");
+    expect(cached).not.toBeNull();
+    const a = await readFile(src);
+    const b = await readFile(cached!);
+    expect(a.equals(b)).toBe(true);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("FileLock prevents concurrent acquisition", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-lock-"));
+  try {
+    const lockPath = path.join(dir, "x.lock");
+    const lock1 = new FileLock(lockPath);
+    const lock2 = new FileLock(lockPath);
+    await lock1.acquire(1000);
+    let lock2Acquired = false;
+    const p = lock2.acquire(500).then(() => (lock2Acquired = true)).catch(() => {});
+    await new Promise((r) => setTimeout(r, 300));
+    expect(lock2Acquired).toBe(false);
+    await lock1.release();
+    await p;
+    expect(lock2Acquired).toBe(true);
+    await lock2.release();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile, copyFile, stat } from "node:fs/promises";
+import { existsSync, openSync, closeSync } from "node:fs";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+export function cacheKey(prompt: string, aspect: string, refs: string[]): string {
+  const h = createHash("sha256");
+  h.update(prompt);
+  h.update("|");
+  h.update(aspect);
+  h.update("|");
+  for (const r of [...refs].sort()) h.update(r);
+  return h.digest("hex").slice(0, 16);
+}
+
+export async function lookupCache(cacheDir: string, key: string): Promise<string | null> {
+  const entry = path.join(cacheDir, `${key}.png`);
+  try {
+    const s = await stat(entry);
+    if (s.size > 1000) return entry;
+  } catch {}
+  return null;
+}
+
+export async function storeCache(cacheDir: string, key: string, sourcePath: string): Promise<void> {
+  await mkdir(cacheDir, { recursive: true });
+  const entry = path.join(cacheDir, `${key}.png`);
+  await copyFile(sourcePath, entry);
+}
+
+export class FileLock {
+  private fd: number | null = null;
+  constructor(private lockPath: string) {}
+
+  async acquire(timeoutMs = 30_000): Promise<void> {
+    const start = Date.now();
+    await mkdir(path.dirname(this.lockPath), { recursive: true });
+    while (Date.now() - start < timeoutMs) {
+      try {
+        this.fd = openSync(this.lockPath, "wx");
+        return;
+      } catch (e: any) {
+        if (e.code !== "EEXIST") throw e;
+        if (await this.isStale()) {
+          try {
+            await this.release(true);
+          } catch {}
+          continue;
+        }
+        await delay(200);
+      }
+    }
+    throw new Error(`Failed to acquire lock at ${this.lockPath} within ${timeoutMs}ms`);
+  }
+
+  private async isStale(): Promise<boolean> {
+    try {
+      const s = await stat(this.lockPath);
+      return Date.now() - s.mtimeMs > 10 * 60 * 1000;
+    } catch {
+      return true;
+    }
+  }
+
+  async release(force = false): Promise<void> {
+    if (this.fd != null) {
+      try {
+        closeSync(this.fd);
+      } catch {}
+      this.fd = null;
+    }
+    if (existsSync(this.lockPath) || force) {
+      const { unlink } = await import("node:fs/promises");
+      try {
+        await unlink(this.lockPath);
+      } catch {}
+    }
+  }
+}
@@ -0,0 +1,39 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export interface LogEntry {
+  ts: string;
+  level: "info" | "warn" | "error";
+  event: string;
+  [k: string]: unknown;
+}
+
+export class JsonLogger {
+  constructor(private logFile: string | null, public verbose: boolean) {}
+
+  async log(level: LogEntry["level"], event: string, extra: Record<string, unknown> = {}): Promise<void> {
+    const entry: LogEntry = { ts: new Date().toISOString(), level, event, ...extra };
+    const line = JSON.stringify(entry);
+    if (this.verbose) process.stderr.write(`[${level}] ${event} ${jsonExtras(extra)}\n`);
+    if (this.logFile) {
+      await mkdir(path.dirname(this.logFile), { recursive: true });
+      await appendFile(this.logFile, line + "\n", "utf-8");
+    }
+  }
+
+  info(event: string, extra?: Record<string, unknown>) {
+    return this.log("info", event, extra);
+  }
+  warn(event: string, extra?: Record<string, unknown>) {
+    return this.log("warn", event, extra);
+  }
+  error(event: string, extra?: Record<string, unknown>) {
+    return this.log("error", event, extra);
+  }
+}
+
+function jsonExtras(extra: Record<string, unknown>): string {
+  const entries = Object.entries(extra);
+  if (entries.length === 0) return "";
+  return entries.map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+}
@@ -0,0 +1,325 @@
+import { readFile, mkdir, copyFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { GenError, type CliOptions, type GenerateResult } from "./types.ts";
+import { runCodexExec } from "./spawn.ts";
+import { findCpToTarget, verifyImageGenWasInvoked, verifyOutput } from "./validator.ts";
+import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
+import { JsonLogger } from "./logger.ts";
+
+const HELP = `codex-imagegen — generate images via Codex CLI's image_gen tool
+
+Usage:
+  codex-imagegen --image <output.png> [--prompt <text> | --prompt-file <path>] [options]
+
+Required:
+  --image <path>          Output PNG path
+  --prompt <text>         Prompt text (or use --prompt-file)
+  --prompt-file <path>    Read prompt from file
+
+Options:
+  --aspect <ratio>        Aspect ratio (1:1, 16:9, 9:16, 4:3, 2.35:1). Default: 1:1
+  --ref <file>            Reference image (repeatable)
+  --timeout <ms>          Codex exec timeout in ms. Default: 300000
+  --retries <n>           Retry attempts on retryable errors. Default: 2
+  --retry-delay <ms>      Base retry delay (exponential). Default: 1500
+  --cache-dir <path>      Enable idempotency cache. Disabled by default.
+  --log-file <path>       Append JSONL log
+  -v, --verbose           Verbose stderr logging
+  -h, --help              Show this help
+
+Stdout: single JSON line on success or failure.
+`;
+
+const SHELL_METACHAR = /[;|&`$<>\n\r()'"]/;
+
+function assertSafePath(label: string, value: string): void {
+  if (SHELL_METACHAR.test(value)) {
+    throw new GenError(
+      "invalid_args",
+      `${label} contains shell metacharacters and would be unsafe to interpolate into the codex instruction: ${value}`,
+      false,
+    );
+  }
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const opts: CliOptions = {
+    prompt: "",
+    promptFile: null,
+    outputPath: "",
+    aspect: "1:1",
+    refImages: [],
+    timeoutMs: 300_000,
+    retries: 2,
+    retryDelayMs: 1500,
+    cacheDir: null,
+    logFile: null,
+    verbose: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case "--prompt": opts.prompt = next(); break;
+      case "--prompt-file": opts.promptFile = next(); break;
+      case "--image": opts.outputPath = next(); break;
+      case "--aspect": opts.aspect = next(); break;
+      case "--ref": opts.refImages.push(next()); break;
+      case "--timeout": opts.timeoutMs = Number(next()); break;
+      case "--retries": opts.retries = Number(next()); break;
+      case "--retry-delay": opts.retryDelayMs = Number(next()); break;
+      case "--cache-dir": opts.cacheDir = next(); break;
+      case "--log-file": opts.logFile = next(); break;
+      case "-v":
+      case "--verbose": opts.verbose = true; break;
+      case "-h":
+      case "--help": process.stdout.write(HELP); process.exit(0);
+      default: throw new GenError("invalid_args", `Unknown argument: ${a}`, false);
+    }
+  }
+  if (!opts.outputPath) throw new GenError("invalid_args", "--image is required", false);
+  if (opts.prompt && opts.promptFile) {
+    throw new GenError("invalid_args", "--prompt and --prompt-file are mutually exclusive", false);
+  }
+  if (!opts.prompt && !opts.promptFile) {
+    throw new GenError("invalid_args", "--prompt or --prompt-file required", false);
+  }
+
+  // Resolve every filesystem path to absolute up front, so behavior is
+  // independent of the caller's cwd. This matters when the wrapper is
+  // invoked from a skill running in an arbitrary working directory.
+  const cwd = process.cwd();
+  const toAbs = (p: string) => (path.isAbsolute(p) ? p : path.resolve(cwd, p));
+
+  opts.outputPath = toAbs(opts.outputPath);
+  if (opts.promptFile) opts.promptFile = toAbs(opts.promptFile);
+  opts.refImages = opts.refImages.map(toAbs);
+  if (opts.cacheDir) opts.cacheDir = toAbs(opts.cacheDir);
+  if (opts.logFile) opts.logFile = toAbs(opts.logFile);
+
+  // The output and ref paths are interpolated raw into the agent instruction
+  // sent to `codex exec --sandbox danger-full-access`. A path containing shell
+  // metacharacters could be misread by the agent's shell when it cp's the
+  // result into place. Reject upfront rather than trusting the agent to quote.
+  assertSafePath("--image path", opts.outputPath);
+  for (const ref of opts.refImages) assertSafePath("--ref path", ref);
+
+  return opts;
+}
+
+async function loadPrompt(opts: CliOptions): Promise<string> {
+  if (opts.prompt) return opts.prompt;
+  const file = opts.promptFile!;
+  try {
+    return await readFile(file, "utf-8");
+  } catch {
+    throw new GenError("prompt_file_missing", `Prompt file not found: ${file}`, false);
+  }
+}
+
+function buildInstruction(prompt: string, opts: CliOptions): string {
+  const refHint = opts.refImages.length > 0
+    ? `\nREFERENCE IMAGES (attached above): ${opts.refImages.length} image(s) provided for style/composition guidance.\n`
+    : "";
+  return `You have an internal tool called image_gen for image generation. Use it.
+
+TASK: Generate an image with the spec below, then save to disk.
+
+PROMPT:
+${prompt}
+
+ASPECT RATIO: ${opts.aspect}
+OUTPUT PATH: ${opts.outputPath}
+${refHint}
+STEPS:
+1. Call image_gen with the prompt and aspect ratio above${opts.refImages.length > 0 ? " (using the attached reference images for guidance)" : ""}.
+2. Move or copy the resulting image from Codex default location ($CODEX_HOME/generated_images/...) to: ${opts.outputPath}
+3. Verify with: ls -la ${opts.outputPath}
+4. Reply with ONLY this JSON line (no markdown fences, no other text):
+   {"status":"ok","path":"${opts.outputPath}","bytes":<file_size_in_bytes>}
+
+HARD CONSTRAINTS:
+- Do NOT use curl, wget, Python, or any external API.
+- Do NOT use bash to fabricate an image; only image_gen produces real pixels.
+- Use ONLY the image_gen internal tool.`;
+}
+
+async function attemptGenerate(
+  opts: CliOptions,
+  instruction: string,
+  attempt: number,
+  log: JsonLogger,
+): Promise<{ bytes: number; threadId: string | null; usage: any; toolCalls: any[] }> {
+  await log.info("attempt.start", { attempt, output: opts.outputPath, aspect: opts.aspect });
+
+  const run = await runCodexExec({
+    instruction,
+    timeoutMs: opts.timeoutMs,
+    refImages: opts.refImages,
+  });
+
+  await log.info("codex.completed", {
+    duration_ms: run.durationMs,
+    thread_id: run.threadId,
+    tool_calls: run.toolCalls.length,
+    usage: run.usage,
+    raw_log: run.rawLogPath,
+  });
+
+  // verify: thread id must be present
+  if (!run.threadId) {
+    throw new GenError("agent_refused", "No thread id in event stream");
+  }
+
+  // verify: image_gen was actually invoked (check $CODEX_HOME/generated_images/{threadId}/)
+  const ver = await verifyImageGenWasInvoked(run.threadId);
+  if (!ver.ok) {
+    // secondary verify: did tool_calls include cp/mv from generated_images to our target
+    if (!findCpToTarget(run.toolCalls, opts.outputPath)) {
+      throw new GenError("no_image_gen_tool_use", `image_gen was not invoked: ${ver.reason}`);
+    }
+  }
+
+  // verify output
+  const { bytes } = await verifyOutput(opts.outputPath);
+
+  return {
+    bytes,
+    threadId: run.threadId,
+    usage: run.usage,
+    toolCalls: run.toolCalls.map((tc) => ({ tool: tc.tool, status: tc.status })),
+  };
+}
+
+async function generate(opts: CliOptions, log: JsonLogger): Promise<GenerateResult> {
+  const startEpoch = Date.now();
+  const prompt = await loadPrompt(opts);
+
+  // Cache lookup
+  if (opts.cacheDir) {
+    const key = cacheKey(prompt, opts.aspect, opts.refImages);
+    const cached = await lookupCache(opts.cacheDir, key);
+    if (cached) {
+      await mkdir(path.dirname(opts.outputPath), { recursive: true });
+      await copyFile(cached, opts.outputPath);
+      const s = await stat(opts.outputPath);
+      await log.info("cache.hit", { key, source: cached });
+      return {
+        status: "ok",
+        path: opts.outputPath,
+        bytes: s.size,
+        elapsed_seconds: 0,
+        thread_id: null,
+        attempts: 0,
+        cached: true,
+        usage: null,
+        tool_calls: [],
+      };
+    }
+    await log.info("cache.miss", { key });
+  }
+
+  // lock to prevent concurrent codex exec
+  const lockDir = opts.cacheDir ?? path.join(homedir(), ".cache", "baoyu-codex-imagegen");
+  const lock = new FileLock(path.join(lockDir, "codex-exec.lock"));
+  try {
+    await lock.acquire(60_000);
+  } catch (e) {
+    throw new GenError("lock_busy", String(e), false);
+  }
+
+  await mkdir(path.dirname(opts.outputPath), { recursive: true });
+  const instruction = buildInstruction(prompt, opts);
+
+  let lastErr: GenError | null = null;
+  let lastAttempt = 0;
+  try {
+    for (let attempt = 1; attempt <= opts.retries + 1; attempt++) {
+      lastAttempt = attempt;
+      try {
+        const result = await attemptGenerate(opts, instruction, attempt, log);
+
+        // write to cache
+        if (opts.cacheDir) {
+          const key = cacheKey(prompt, opts.aspect, opts.refImages);
+          await storeCache(opts.cacheDir, key, opts.outputPath);
+          await log.info("cache.stored", { key });
+        }
+
+        return {
+          status: "ok",
+          path: opts.outputPath,
+          bytes: result.bytes,
+          elapsed_seconds: Math.round((Date.now() - startEpoch) / 1000),
+          thread_id: result.threadId,
+          attempts: attempt,
+          cached: false,
+          usage: result.usage,
+          tool_calls: result.toolCalls,
+        };
+      } catch (e) {
+        lastErr = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
+        await log.warn("attempt.failed", {
+          attempt,
+          kind: lastErr.kind,
+          retryable: lastErr.retryable,
+          error: lastErr.message,
+        });
+        if (!lastErr.retryable || attempt > opts.retries) break;
+        const wait = opts.retryDelayMs * Math.pow(2, attempt - 1);
+        await log.info("retry.wait", { wait_ms: wait, next_attempt: attempt + 1 });
+        await delay(wait);
+      }
+    }
+  } finally {
+    await lock.release();
+  }
+
+  const err = lastErr ?? new GenError("spawn_failed", "Unknown failure");
+  err.attempts = lastAttempt;
+  throw err;
+}
+
+async function main() {
+  let opts: CliOptions;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    const err = e instanceof GenError ? e : new GenError("invalid_args", String(e), false);
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const log = new JsonLogger(opts.logFile, opts.verbose);
+  await log.info("start", { output: opts.outputPath, aspect: opts.aspect, refs: opts.refImages.length });
+
+  try {
+    const result = await generate(opts, log);
+    await log.info("done", { bytes: result.bytes, attempts: result.attempts, cached: result.cached });
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(0);
+  } catch (e) {
+    const err = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
+    await log.error("failed", { kind: err.kind, error: err.message, attempts: err.attempts ?? 0 });
+    const out: GenerateResult = {
+      status: "error",
+      path: opts.outputPath,
+      bytes: 0,
+      elapsed_seconds: 0,
+      thread_id: null,
+      attempts: err.attempts ?? 0,
+      cached: false,
+      usage: null,
+      tool_calls: [],
+      error: err.message,
+      error_kind: err.kind,
+    };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(1);
+  }
+}
+
+main();
@@ -0,0 +1,49 @@
+import { test, expect } from "bun:test";
+import { parseEventStream, hasImageGenInvocation } from "./parser.ts";
+
+const REAL_PoC_STREAM = `{"type":"thread.started","thread_id":"019e40d3-30e3-7030-874d-773bc0d6d1eb"}
+{"type":"turn.started"}
+{"type":"item.started","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","exit_code":0,"status":"completed"}}
+{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","exit_code":0,"status":"completed"}}
+{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"{\\"status\\":\\"ok\\",\\"path\\":\\"/tmp/out.png\\",\\"bytes\\":1234567}"}}
+{"type":"turn.completed","usage":{"input_tokens":100000,"cached_input_tokens":80000,"output_tokens":500,"reasoning_output_tokens":50}}`;
+
+test("parseEventStream extracts threadId, toolCalls, agentMessage, usage", () => {
+  const r = parseEventStream(REAL_PoC_STREAM);
+  expect(r.threadId).toBe("019e40d3-30e3-7030-874d-773bc0d6d1eb");
+  expect(r.toolCalls.length).toBe(3);
+  expect(r.usage).toEqual({
+    input: 100000,
+    cached_input: 80000,
+    output: 500,
+    reasoning: 50,
+  });
+  expect(r.agentMessage).toContain('"status":"ok"');
+});
+
+test("parseEventStream tolerates malformed lines", () => {
+  const stream = `not json at all
+{"type":"thread.started","thread_id":"abc"}
+{partial json
+{"type":"turn.completed","usage":{"input_tokens":1,"cached_input_tokens":0,"output_tokens":1,"reasoning_output_tokens":0}}`;
+  const r = parseEventStream(stream);
+  expect(r.threadId).toBe("abc");
+  expect(r.usage?.input).toBe(1);
+});
+
+test("hasImageGenInvocation finds shell calls touching generated_images", () => {
+  const r = parseEventStream(REAL_PoC_STREAM);
+  // image_gen itself is not an event; inferred via generated_images cp path
+  // this test only verifies parser behavior; driver logic lives in validator
+  const hasCp = r.toolCalls.some((tc) => tc.command?.includes("generated_images"));
+  expect(hasCp).toBe(true);
+});
+
+test("hasImageGenInvocation (proper) returns false when no image_gen tool", () => {
+  expect(hasImageGenInvocation([{ id: "1", tool: "shell", status: "completed" }])).toBe(false);
+  expect(
+    hasImageGenInvocation([{ id: "1", tool: "image_gen", status: "completed" }]),
+  ).toBe(true);
+});
@@ -0,0 +1,64 @@
+import type { CodexRunResult, ToolCall, TokenUsage } from "./types.ts";
+
+export function parseEventStream(raw: string): Omit<CodexRunResult, "rawLogPath" | "durationMs"> {
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  let threadId: string | null = null;
+  let agentMessage: string | null = null;
+  let usage: TokenUsage | null = null;
+  const toolCallsById = new Map<string, ToolCall>();
+
+  for (const line of lines) {
+    let event: any;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const type = event?.type;
+    if (type === "thread.started") {
+      threadId = event.thread_id ?? null;
+    } else if (type === "item.started" || type === "item.completed") {
+      const item = event.item;
+      if (!item?.id) continue;
+      const tc: ToolCall = {
+        id: item.id,
+        tool: deriveToolName(item),
+        status: item.status ?? (type === "item.completed" ? "completed" : "in_progress"),
+        command: item.command,
+      };
+      toolCallsById.set(item.id, tc);
+      if (item.type === "agent_message" && type === "item.completed") {
+        agentMessage = String(item.text ?? "");
+      }
+    } else if (type === "turn.completed") {
+      const u = event.usage;
+      if (u) {
+        usage = {
+          input: u.input_tokens ?? 0,
+          cached_input: u.cached_input_tokens ?? 0,
+          output: u.output_tokens ?? 0,
+          reasoning: u.reasoning_output_tokens ?? 0,
+        };
+      }
+    }
+  }
+
+  return {
+    threadId,
+    toolCalls: Array.from(toolCallsById.values()),
+    agentMessage,
+    usage,
+  };
+}
+
+function deriveToolName(item: any): string {
+  if (item.type === "command_execution") return "shell";
+  if (item.type === "agent_message") return "agent_message";
+  if (item.type === "image_gen" || item.type === "image_generation") return "image_gen";
+  if (typeof item.tool === "string") return item.tool;
+  return item.type ?? "unknown";
+}
+
+export function hasImageGenInvocation(toolCalls: ToolCall[]): boolean {
+  return toolCalls.some((tc) => tc.tool === "image_gen");
+}
@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { writeFile, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { GenError, type CodexRunResult } from "./types.ts";
+import { parseEventStream } from "./parser.ts";
+
+export interface SpawnInput {
+  instruction: string;
+  timeoutMs: number;
+  refImages?: string[];
+}
+
+export async function runCodexExec(input: SpawnInput): Promise<CodexRunResult> {
+  const start = Date.now();
+  const logDir = await mkdtemp(path.join(tmpdir(), "codex-imggen-"));
+  const rawLogPath = path.join(logDir, "stream.jsonl");
+
+  // --skip-git-repo-check: lets the wrapper run from non-git cwds
+  //   (e.g. /tmp, or a skill installed under ~/.claude/plugins/...).
+  //   Without it, codex refuses with "Not inside a trusted directory".
+  const args = [
+    "exec",
+    "--json",
+    "--sandbox",
+    "danger-full-access",
+    "--skip-git-repo-check",
+  ];
+  for (const img of input.refImages ?? []) {
+    args.push("--image", img);
+  }
+  args.push("-");
+
+  let timedOut = false;
+  const child = spawn("codex", args, { stdio: ["pipe", "pipe", "pipe"] });
+
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+
+  child.stdin.write(input.instruction);
+  child.stdin.end();
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    setTimeout(() => child.kill("SIGKILL"), 2000);
+  }, input.timeoutMs);
+
+  const exit = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+    child.on("close", (code, signal) => resolve({ code, signal }));
+  });
+  clearTimeout(timer);
+
+  await writeFile(rawLogPath, stdout + (stderr ? `\n--- stderr ---\n${stderr}` : ""));
+
+  if (timedOut) {
+    throw new GenError("timeout", `codex exec exceeded ${input.timeoutMs}ms (log: ${rawLogPath})`);
+  }
+  if (exit.code !== 0) {
+    if (stderr.includes("command not found") || stderr.includes("not found: codex")) {
+      throw new GenError("codex_not_installed", "codex CLI not installed", false);
+    }
+    throw new GenError(
+      "spawn_failed",
+      `codex exec exited ${exit.code} signal=${exit.signal} (log: ${rawLogPath})`,
+    );
+  }
+
+  const parsed = parseEventStream(stdout);
+  return {
+    ...parsed,
+    rawLogPath,
+    durationMs: Date.now() - start,
+  };
+}
@@ -0,0 +1,79 @@
+export interface CliOptions {
+  prompt: string;
+  promptFile: string | null;
+  outputPath: string;
+  aspect: string;
+  refImages: string[];
+  timeoutMs: number;
+  retries: number;
+  retryDelayMs: number;
+  cacheDir: string | null;
+  logFile: string | null;
+  verbose: boolean;
+}
+
+export interface ToolCall {
+  id: string;
+  tool: string;
+  status: string;
+  command?: string;
+}
+
+export interface TokenUsage {
+  input: number;
+  cached_input: number;
+  output: number;
+  reasoning: number;
+}
+
+export interface CodexRunResult {
+  threadId: string | null;
+  toolCalls: ToolCall[];
+  agentMessage: string | null;
+  usage: TokenUsage | null;
+  rawLogPath: string;
+  durationMs: number;
+}
+
+export interface GenerateResult {
+  status: "ok" | "error";
+  path: string;
+  bytes: number;
+  elapsed_seconds: number;
+  thread_id: string | null;
+  attempts: number;
+  cached: boolean;
+  usage: TokenUsage | null;
+  tool_calls: { tool: string; status: string }[];
+  error?: string;
+  error_kind?: ErrorKind;
+}
+
+export type ErrorKind =
+  | "codex_not_installed"
+  | "invalid_args"
+  | "prompt_file_missing"
+  | "spawn_failed"
+  | "timeout"
+  | "no_image_gen_tool_use"
+  | "output_missing"
+  | "invalid_png"
+  | "agent_refused"
+  | "lock_busy";
+
+export const RETRYABLE: ReadonlySet<ErrorKind> = new Set([
+  "spawn_failed",
+  "timeout",
+  "no_image_gen_tool_use",
+  "output_missing",
+  "invalid_png",
+  "agent_refused",
+]);
+
+export class GenError extends Error {
+  attempts?: number;
+  constructor(public kind: ErrorKind, message: string, public retryable?: boolean) {
+    super(message);
+    this.retryable = retryable ?? RETRYABLE.has(kind);
+  }
+}
@@ -0,0 +1,98 @@
+import { test, expect } from "bun:test";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { verifyOutput, verifyImageGenWasInvoked, findCpToTarget } from "./validator.ts";
+import { GenError } from "./types.ts";
+
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+test("verifyOutput passes for valid PNG", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "good.png");
+    await writeFile(p, Buffer.concat([PNG_HEADER, Buffer.alloc(5000)]));
+    const r = await verifyOutput(p);
+    expect(r.bytes).toBeGreaterThan(1000);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects missing file", async () => {
+  await expect(verifyOutput("/no/such/file.png")).rejects.toBeInstanceOf(GenError);
+});
+
+test("verifyOutput rejects tiny file", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "tiny.png");
+    await writeFile(p, "tiny");
+    await expect(verifyOutput(p)).rejects.toThrow(/too small/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects non-PNG magic", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "fake.png");
+    await writeFile(p, Buffer.concat([Buffer.from("GIF89a"), Buffer.alloc(5000)]));
+    await expect(verifyOutput(p)).rejects.toThrow(/not a valid PNG/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked false when no thread directory", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const r = await verifyImageGenWasInvoked("no-such-thread");
+    expect(r.ok).toBe(false);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked true when PNG exists in thread dir", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const threadDir = path.join(tempHome, "generated_images", "thread-xyz");
+    await mkdir(threadDir, { recursive: true });
+    await writeFile(path.join(threadDir, "ig_abc.png"), Buffer.alloc(100));
+    const r = await verifyImageGenWasInvoked("thread-xyz");
+    expect(r.ok).toBe(true);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});
+
+test("findCpToTarget detects cp from generated_images", () => {
+  expect(
+    findCpToTarget(
+      [
+        {
+          id: "1",
+          tool: "shell",
+          status: "completed",
+          command: "cp ~/.codex/generated_images/thread/ig_x.png /tmp/out.png",
+        },
+      ],
+      "/tmp/out.png",
+    ),
+  ).toBe(true);
+
+  expect(
+    findCpToTarget(
+      [{ id: "1", tool: "shell", status: "completed", command: "ls /tmp" }],
+      "/tmp/out.png",
+    ),
+  ).toBe(false);
+});
@@ -0,0 +1,55 @@
+import { stat, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { GenError } from "./types.ts";
+import type { ToolCall } from "./types.ts";
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function codexHome(): string {
+  return process.env.CODEX_HOME ?? path.join(homedir(), ".codex");
+}
+
+export async function verifyImageGenWasInvoked(threadId: string | null): Promise<{ ok: boolean; reason?: string }> {
+  if (!threadId) return { ok: false, reason: "no thread id" };
+  const dir = path.join(codexHome(), "generated_images", threadId);
+  try {
+    const entries = await readdir(dir);
+    const pngs = entries.filter((e) => e.toLowerCase().endsWith(".png"));
+    if (pngs.length === 0) return { ok: false, reason: `no PNG in ${dir}` };
+    return { ok: true };
+  } catch (e: any) {
+    return { ok: false, reason: `cannot read ${dir}: ${e?.code ?? e?.message}` };
+  }
+}
+
+export function findCpToTarget(toolCalls: ToolCall[], target: string): boolean {
+  return toolCalls.some(
+    (tc) =>
+      tc.tool === "shell" &&
+      typeof tc.command === "string" &&
+      (tc.command.includes(target) || tc.command.includes(path.basename(target))) &&
+      /\b(cp|mv|cat)\b/.test(tc.command) &&
+      tc.command.includes("generated_images"),
+  );
+}
+
+export async function verifyOutput(outputPath: string): Promise<{ bytes: number }> {
+  let s;
+  try {
+    s = await stat(outputPath);
+  } catch {
+    throw new GenError("output_missing", `Output file not created: ${outputPath}`);
+  }
+  if (s.size < 1000) {
+    throw new GenError("invalid_png", `Output file too small (${s.size} bytes)`);
+  }
+  const file = Bun.file(outputPath);
+  const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
+  for (let i = 0; i < PNG_MAGIC.length; i++) {
+    if (head[i] !== PNG_MAGIC[i]) {
+      throw new GenError("invalid_png", `Output is not a valid PNG (magic mismatch)`);
+    }
+  }
+  return { bytes: s.size };
+}
@@ -1,7 +1,7 @@
 ---
 name: baoyu-article-illustrator
 description: Analyzes article structure, identifies positions requiring visual aids, generates illustrations with Type × Style × Palette three-dimension approach. Use when user asks to "illustrate article", "add images", "generate images for article", or "为文章配图".
-version: 1.59.0
+version: 1.117.3
 metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator
@@ -28,9 +28,9 @@ When this skill needs to render an image, resolve the backend in this order:
 1. **Current-request override** — if the user names a specific backend in the current message, use it.
 2. **Saved preference** — if `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
 3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
-   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
+   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-image-gen`) unless the user has explicitly pinned a different `preferred_image_backend`.
   - **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
-   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
+   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-image-gen`), use it.
   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
 4. **If none are available**, tell the user and ask how to proceed.

@@ -42,7 +42,7 @@ Setting `preferred_image_backend: ask` forces the step-3 prompt every run regard

 **Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) above are examples — substitute the local equivalents under the same rule.

 ## Batch Generation Policy

@@ -73,7 +73,7 @@ Default behavior: **confirm before generation**.

 Users may supply reference images via `--ref <files...>` or by providing file paths / pasting images in conversation. Refs guide style, palette, composition, or subject for specific illustrations.

-Full detection, storage, and processing rules are in [references/workflow.md](references/workflow.md) (Step 1.0 saves to `references/NN-ref-{slug}.{ext}`; Step 5.3 processes per-illustration usage `direct | style | palette`). When the chosen backend supports batch input, `direct`-usage entries in each prompt file's `references:` frontmatter should be propagated into its batch payload so backends can pass them through (e.g. `baoyu-imagine` accepts `ref` per task).
+Full detection, storage, and processing rules are in [references/workflow.md](references/workflow.md) (Step 1.0 saves to `references/NN-ref-{slug}.{ext}`; Step 5.3 processes per-illustration usage `direct | style | palette`). When the chosen backend supports batch input, `direct`-usage entries in each prompt file's `references:` frontmatter should be propagated into its batch payload so backends can pass them through (e.g. `baoyu-image-gen` accepts `ref` per task).

 ## Three Dimensions

@@ -261,7 +261,7 @@ EXTEND.md lives at the first matching path listed in Step 1.5. Three ways to cha
 - **Common one-line edits**:
  - `preferred_image_backend: auto` — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
  - `preferred_image_backend: codex-imagegen` — pin to Codex's built-in.
-  - `preferred_image_backend: baoyu-imagine` — pin to the baoyu-imagine skill.
+  - `preferred_image_backend: baoyu-image-gen` — pin to the baoyu-image-gen skill.
  - `preferred_image_backend: ask` — confirm backend every run.
  - `generation_batch_size: 4` — default number of images to render concurrently when the runtime supports parallel generation calls.
  - `preferred_type: infographic`, `preferred_style: notion`, `preferred_palette: macaron`, `language: zh`.
@@ -56,7 +56,7 @@ custom_styles:
 | `preferred_palette` | string | null | Palette override (macaron, warm, neon, or null) |
 | `language` | string | null | Output language (null = auto-detect) |
 | `default_output_dir` | enum | null | Output directory preference (null = ask each time) |
-| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
+| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-image-gen`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
 | `generation_batch_size` | int | 4 | Number of images to dispatch per batch when the backend has native batch support or the runtime can issue parallel generation calls. Clamp invalid values to 1-8. Current user request overrides this value. |
 | `custom_styles` | array | [] | User-defined styles |

@@ -381,7 +381,7 @@ Follow the `## Image Generation Tools` rule at the top of `SKILL.md`. Concretely

 | Skill Supports `--ref` | Action |
 |------------------------|--------|
-| Yes (e.g., baoyu-imagine with Google) | Pass reference images via `--ref` |
+| Yes (e.g., baoyu-image-gen with Google) | Pass reference images via `--ref` |
 | No | Convert to text description, append to prompt |

 **Verification**: Before generating, confirm reference processing:
@@ -1,7 +1,7 @@
 ---
 name: baoyu-comic
 description: Knowledge comic creator supporting multiple art styles and tones. Creates original educational comics with detailed panel layouts and batch-capable image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial comic", or "Logicomix-style comic".
-version: 1.57.0
+version: 1.117.3
 metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-comic
@@ -32,9 +32,9 @@ When this skill needs to render an image, resolve the backend in this order:
 1. **Current-request override** — if the user names a specific backend in the current message, use it.
 2. **Saved preference** — if `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
 3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
-   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
+   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-image-gen`) unless the user has explicitly pinned a different `preferred_image_backend`.
   - **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
-   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
+   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-image-gen`), use it.
   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
 4. **If none are available**, tell the user and ask how to proceed.

@@ -46,7 +46,7 @@ Setting `preferred_image_backend: ask` forces the step-3 prompt every run regard

 **Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) above are examples — substitute the local equivalents under the same rule.

 ## Batch Generation Policy

@@ -245,7 +245,7 @@ Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard →

 ### Step 7: Image Generation

-**Pick a backend once per session** using the `## Image Generation Tools` rule at the top. If the backend is a repo skill (e.g., `baoyu-imagine`), read its `SKILL.md` and use its documented interface rather than its scripts.
+**Pick a backend once per session** using the `## Image Generation Tools` rule at the top. If the backend is a repo skill (e.g., `baoyu-image-gen`), read its `SKILL.md` and use its documented interface rather than its scripts.

 **7.1 Character sheet** — generate it (to `characters/characters.png`, aspect `4:3`) when the comic is multi-page with recurring characters. Skip for simple presets (e.g., four-panel minimalist) or single-page comics. Compress to JPEG before use-as-`--ref` (`sips -s format jpeg -s formatOptions 80 …` on macOS, `pngquant --quality=65-80 …` elsewhere) to avoid payload failures. The prompt file at `characters/characters.md` must exist before invoking the backend.

@@ -342,7 +342,7 @@ EXTEND.md lives at `.baoyu-skills/baoyu-comic/EXTEND.md` (project) or `~/.baoyu-
 - **Common one-line edits**:
  - `preferred_image_backend: auto` — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
  - `preferred_image_backend: codex-imagegen` — pin to Codex's built-in.
-  - `preferred_image_backend: baoyu-imagine` — pin to the baoyu-imagine skill.
+  - `preferred_image_backend: baoyu-image-gen` — pin to the baoyu-image-gen skill.
  - `preferred_image_backend: ask` — confirm backend every run.
  - `generation_batch_size: 4` — default number of page images to render concurrently when the backend/runtime supports batch or parallel generation.
  - `watermark.enabled: true`, `preferred_art`, `preferred_tone`, `preferred_layout`, `language` — shift the auto-selection defaults and cosmetic choices.
@@ -50,7 +50,7 @@ character_presets:
 | `preferred_layout` | string | null | Layout preference or null |
 | `preferred_aspect` | string | null | Aspect ratio (3:4, 4:3, 16:9) |
 | `language` | string | null | Output language (null = auto-detect) |
-| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
+| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-image-gen`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
 | `generation_batch_size` | int | 4 | Number of page images to dispatch per batch when the backend has native batch support or the runtime can issue parallel generation calls. Clamp invalid values to 1-8. Current user request overrides this value. |
 | `character_presets` | array | [] | Preset character roles for styles like ohmsha |

@@ -448,7 +448,7 @@ Character sheet is recommended for multi-page comics with recurring characters,
 | Exists | No `--ref` support | **B**: Embed character descriptions in every prompt |
 | Skipped | — | **C**: Prompt file contains all descriptions inline |

-**Strategy A: Using `--ref` parameter** (e.g., baoyu-imagine)
+**Strategy A: Using `--ref` parameter** (e.g., baoyu-image-gen)

 - Read the chosen image generation skill's `SKILL.md`
 - Invoke that installed skill via its documented interface, not by calling its scripts directly
@@ -1,7 +1,7 @@
 ---
 name: baoyu-cover-image
 description: Generates article cover images with 5 dimensions (type, palette, rendering, text, mood) combining 11 color palettes and 7 rendering styles. Supports cinematic (2.35:1), widescreen (16:9), and square (1:1) aspects. Use when user asks to "generate cover image", "create article cover", or "make cover".
-version: 1.56.2
+version: 1.117.4
 metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-cover-image
@@ -28,9 +28,22 @@ When this skill needs to render an image, resolve the backend in this order:
 1. **Current-request override** — if the user names a specific backend in the current message, use it.
 2. **Saved preference** — if `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
 3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
-   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
+   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-image-gen`) unless the user has explicitly pinned a different `preferred_image_backend`.
+   - **Codex via `codex exec` (`codex-imagegen`)** — if the current runtime does NOT expose a native `imagegen` skill but the `codex` CLI is on `PATH` and `codex login` is active (e.g., Claude Code with Codex CLI installed), invoke the `codex-imagegen` wrapper. **Path resolution**: `scripts/codex-imagegen.sh` lives at the plugin/repo root, NOT relative to your shell cwd. From this `SKILL.md`'s base directory, the wrapper is at `../../scripts/codex-imagegen.sh` — resolve to an absolute path before invoking. Command shape:
+     ```bash
+     <ABSOLUTE_PLUGIN_ROOT>/scripts/codex-imagegen.sh \
+       --image <absolute_output_path> \
+       --prompt-file <absolute_path_to_prompts/NN-cover-[slug].md> \
+       --aspect <ratio> \
+       [--ref <absolute_file>]... \
+       [--timeout <ms>] \
+       [--cache-dir ~/.cache/baoyu-codex-imagegen] \
+       [--log-file <absolute_jsonl_log_path>]
+     ```
+     `--timeout` defaults to 300000 (5 min) per codex exec attempt; raise it (e.g. `--timeout 600000` for 10 min) on slow networks or large prompts.
+     All input paths to the wrapper are auto-resolved against the wrapper's `process.cwd()` if you pass relative ones, but agents should pass absolute paths to be robust against cwd drift. Parse the single-line JSON on stdout. On `{"status":"ok",...}` proceed to Step 5. On `{"status":"error","error_kind":...}` report the `error_kind` to the user and (if retryable) ask whether to retry or fall back to another backend. The wrapper uses the user's Codex subscription — no `OPENAI_API_KEY` needed.
   - **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
-   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
+   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-image-gen`), use it.
   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
 4. **If none are available**, tell the user and ask how to proceed.

@@ -42,7 +55,7 @@ Setting `preferred_image_backend: ask` forces the step-3 prompt every run regard

 **Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-image-gen`) above are examples — substitute the local equivalents under the same rule.

 ## Confirmation Policy

@@ -214,7 +227,9 @@ Save to `prompts/cover.md`. Template: [references/workflow/prompt-template.md](r
 4. **Process references** from prompt frontmatter:
   - `direct` usage → pass via `--ref` (use ref-capable backend)
   - `style`/`palette` → extract traits, append to prompt
-5. **Generate**: Call the chosen backend with the prompt file, output path, aspect ratio
+5. **Generate**: Call the chosen backend with the prompt file, output path, aspect ratio.
+   - **`codex-imagegen`**: invoke `<ABSOLUTE_PLUGIN_ROOT>/scripts/codex-imagegen.sh` (NOT a cwd-relative `./scripts/...` — resolve the absolute path from this skill's base directory: `../../scripts/codex-imagegen.sh`) with `--image <ABSOLUTE_output>` `--prompt-file <ABSOLUTE_prompts/01-cover-[slug].md>` `--aspect <ratio>` (add `--ref <ABSOLUTE_file>` per reference, `--cache-dir ~/.cache/baoyu-codex-imagegen` to enable the idempotency cache, `--timeout <ms>` to override the default 300000 / 5-min per-attempt limit on slow networks). All input paths to the wrapper are auto-resolved against its `process.cwd()` if relative, but passing absolutes is more robust. Read the stdout JSON; act on `status` and `error_kind`.
+   - **Codex `imagegen` (native)** or other runtime-native tools / `baoyu-image-gen` skill: per the rule in `## Image Generation Tools` above.
 6. On failure: auto-retry once

 ### Step 5: Completion Report
@@ -265,7 +280,7 @@ EXTEND.md lives at the path noted in **Step 0**. Three ways to change it:
 - **Common one-line edits**:
  - `preferred_image_backend: auto` — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
  - `preferred_image_backend: codex-imagegen` — pin to Codex's built-in.
-  - `preferred_image_backend: baoyu-imagine` — pin to the baoyu-imagine skill.
+  - `preferred_image_backend: baoyu-image-gen` — pin to the baoyu-image-gen skill.
  - `preferred_image_backend: ask` — confirm backend every run.
  - `watermark.enabled: true`, `preferred_type`, `preferred_palette`, `preferred_rendering`, `default_aspect`, `quick_mode: true`, `language` — shift the auto-selection defaults and confirmation flow.

@@ -62,7 +62,7 @@ custom_palettes:
 | `default_aspect` | string | "2.35:1" | Default aspect ratio |
 | `quick_mode` | bool | false | Skip confirmation step |
 | `language` | string | null | Output language (null = auto-detect) |
-| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
+| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-image-gen`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
 | `custom_palettes` | array | [] | User-defined palettes |

 ## Type Options
@@ -0,0 +1,140 @@
+---
+name: baoyu-electron-extract
+description: Extracts resources and JavaScript from any installed Electron app (`.asar` bundle), restoring original sources from `.js.map` files when available or formatting minified code with Prettier otherwise. Use when user wants to "extract Electron app", "decompile Electron", "get the source code of <app>", "inspect app.asar", "看 Electron 应用源码", "提取 .asar", or asks how a desktop Electron app is built. Skips `node_modules` and supports both macOS and Windows.
+version: 1.119.0
+metadata:
+  openclaw:
+    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-electron-extract
+    requires:
+      anyBins:
+        - bun
+        - npx
+---
+
+# Electron App Extract
+
+Extracts resources and code from an installed Electron app's `app.asar`. When a `.js.map` is present, restores the original source files from the embedded `sourcesContent`; otherwise formats the minified code with Prettier. Source-map paths are resolved relative to the `.js.map` file first, so bundled paths like `../../src/main.ts` restore to readable paths such as `restored/src/main.ts` instead of hashed placeholders. Always skips `node_modules`. Works on macOS and Windows.
+
+## User Input Tools
+
+When this skill prompts the user, follow this tool-selection rule (priority order):
+
+1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
+2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
+3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
+
+Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
+
+## Script Directory
+
+Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.
+
+| Script            | Purpose                                                                        |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `scripts/main.ts` | App discovery + asar extraction + source-map restoration + Prettier formatting |
+
+## When to use
+
+Use this skill whenever the user wants to look inside an installed Electron application or inspect its bundled code. Trigger phrases include:
+
+- "extract Electron app", "decompile this Electron app", "unpack app.asar"
+- "show me the source of <app>", "look inside <app>", "how is <app> built"
+- "get the source code of Codex / Cursor / Discord / Slack / VS Code / Notion / Obsidian / ChatGPT desktop"
+- "提取 Electron 应用", "看 <app> 的源码", "反编译 Electron", "解包 app.asar", "还原 source map"
+
+Both **app name** (e.g., `Codex`) and **absolute path** (e.g., `/Applications/Codex.app`, a `.asar` file, or a Windows install dir) are accepted. The script handles discovery for both platforms.
+
+## Workflow
+
+**1. Determine the input.** Ask the user for the app name or path if they haven't given one. If they want a custom output directory, ask for that too.
+
+**2. Run the script.**
+
+```bash
+${BUN_X} {baseDir}/scripts/main.ts "<app>" [--output <dir>] [--asar <path>] [--force]
+```
+
+Start with `--dry-run` first if you're unsure whether discovery will find the right bundle — it prints the resolved paths and exits without touching the filesystem.
+
+**3. Handle the result.**
+
+- **Success** → report the output paths and the counts (extracted / restored / formatted).
+- **Multiple matches** → the script lists candidates and exits non-zero. Show the user the candidates, ask which one to use (via `AskUserQuestion` or the runtime equivalent), then re-run with the chosen absolute path.
+- **Existing non-empty output dir** → the script refuses without `--force`. Ask the user whether to overwrite (`--force`) or pick a new `--output` path.
+- **Unsupported platform / no match** → suggest passing `--asar /full/path/to/app.asar` if the user knows where the bundle lives.
+
+**4. Point the user at the result.** The default output dir is `~/Downloads/<AppName>-electron-extract/`. The most interesting subdirectory depends on what was found:
+
+- `restored/` exists → the original source tree was reconstructed from `.js.map` files; this is what to read first.
+- Only `extracted/` exists (no maps) → the JS/CSS in `extracted/` was Prettier-formatted in place; read from there.
+
+## Source-map path restoration
+
+The script should preserve original source names and directory structure as much as the source map allows:
+
+- Resolve each `sources[]` entry with `sourceRoot` when present, then relative to the `.js.map` file's directory inside `extracted/`.
+- Collapse normal bundler-relative paths into the restored project tree. For example, `.vite/main/index.js.map` + `../../src/main.ts` becomes `restored/src/main.ts`.
+- If a source path climbs above `extracted/`, keep the readable remaining path under `restored/` instead of hashing it. For example, `.vite/main/index.js.map` + `../../../shared/src/lib/foo.ts` becomes `restored/shared/src/lib/foo.ts`.
+- Strip URL/query decorations from source names, including common `webpack://`, `file://`, and `?loader` suffixes.
+- Use `restored/__unknown/<hash>.<ext>` only when the source name is empty or cannot be reduced to a safe file path.
+- Continue skipping `node_modules` and `webpack/runtime/*` entries; these are bundler/runtime noise, not app sources.
+
+## Usage
+
+```bash
+# Extract by app name (default output: ~/Downloads/Codex-electron-extract/)
+${BUN_X} {baseDir}/scripts/main.ts Codex
+
+# Extract by absolute path (works for .app bundles, install dirs, or .asar files)
+${BUN_X} {baseDir}/scripts/main.ts "/Applications/Visual Studio Code.app"
+${BUN_X} {baseDir}/scripts/main.ts "C:\Users\you\AppData\Local\Programs\codex"
+${BUN_X} {baseDir}/scripts/main.ts --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
+
+# Custom output
+${BUN_X} {baseDir}/scripts/main.ts Codex --output ~/work/codex-source
+
+# Preview discovery without writing anything
+${BUN_X} {baseDir}/scripts/main.ts Codex --dry-run
+
+# Overwrite an existing output dir
+${BUN_X} {baseDir}/scripts/main.ts Codex --force
+
+# Machine-readable result (one JSON line on stdout)
+${BUN_X} {baseDir}/scripts/main.ts Codex --json
+```
+
+## Options
+
+| Option           | Short | Description                                                     | Default                                  |
+| ---------------- | ----- | --------------------------------------------------------------- | ---------------------------------------- |
+| `<app>`          |       | App name or absolute path. Required unless `--asar` is given.   | —                                        |
+| `--output`       | `-o`  | Output directory                                                | `~/Downloads/<AppName>-electron-extract` |
+| `--asar`         |       | Override the resolved `.asar` path                              | auto-discovered                          |
+| `--force`        | `-f`  | Allow writing into a non-empty existing output dir              | false                                    |
+| `--skip-format`  |       | Skip Prettier formatting                                        | false                                    |
+| `--skip-restore` |       | Skip source-map restoration                                     | false                                    |
+| `--no-unpacked`  |       | Don't copy `app.asar.unpacked/` alongside                       | false                                    |
+| `--dry-run`      |       | Print resolved paths and exit without writing                   | false                                    |
+| `--json`         |       | Emit one JSON-line summary on stdout (suppresses normal output) | false                                    |
+
+## Output layout
+
+```
+~/Downloads/<AppName>-electron-extract/
+├── extract-report.json          # JSON summary: counts, warnings, resolved paths
+├── extracted/                   # raw asar contents (JS/CSS Prettier-formatted when no map)
+│   └── ...                      # node_modules left untouched (skipped from format)
+├── extracted.unpacked/          # copied from <asar>.unpacked/ if present
+│   └── ...                      # native modules (.node), large assets
+└── restored/                    # only present if at least one .js.map was usable
+    └── <original/source/tree>   # rebuilt from sourcesContent in each .js.map
+```
+
+## Notes
+
+- **node_modules** is always skipped — both for source-map restoration and Prettier formatting — because vendored dependencies are noise when inspecting an app.
+- **Source-map restoration** only works when the `.js.map` embeds `sourcesContent`. This is the common case for modern bundlers (webpack, esbuild, Vite, rollup). If a map references external `.ts`/`.js` files without embedding them, that map is skipped and the corresponding `.js` is Prettier-formatted instead. Skipped maps are listed in `extract-report.json` under `warnings`.
+- **Readable paths over hashes** — don't treat `../` segments in source-map paths as automatically unsafe. First resolve them from the map location and then sanitize the final output path so it still stays under `restored/`. Hash fallback is only for unusable source names.
+- **App discovery** searches `/Applications` + `~/Applications` on macOS, and `%LOCALAPPDATA%\Programs`, `%PROGRAMFILES%`, `%PROGRAMFILES(X86)%`, `%APPDATA%` on Windows. If discovery finds multiple matches, the script exits and lists them — re-run with an absolute path. On Linux or other platforms, pass `--asar /path/to/app.asar` explicitly.
+- **Safety** — the script refuses to write to `/`, the user home directly, or the current working directory, and refuses to populate an existing non-empty output dir without `--force`.
+- **No global installs** — `@electron/asar` and `prettier` are resolved on-the-fly via `npx -y`. First run will be slower while npx caches them.
@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { normalizeSourcePath, restoreFromMap } from "./main.ts";
+
+test("normalizes Vite source map paths into readable project paths", () => {
+  const extractedRoot = path.join(os.tmpdir(), "app", "extracted");
+  const mapPath = path.join(extractedRoot, ".vite", "main", "index.js.map");
+
+  assert.equal(
+    normalizeSourcePath(
+      "../../src/main/agent/claude-agent.ts",
+      mapPath,
+      extractedRoot,
+      undefined
+    ),
+    "src/main/agent/claude-agent.ts"
+  );
+
+  assert.equal(
+    normalizeSourcePath(
+      "../../../shared/src/lib/prompt-classification.ts",
+      mapPath,
+      extractedRoot,
+      undefined
+    ),
+    "shared/src/lib/prompt-classification.ts"
+  );
+
+  assert.equal(
+    normalizeSourcePath(
+      "./src/renderer/app.tsx",
+      mapPath,
+      extractedRoot,
+      "webpack://moss/"
+    ),
+    "moss/src/renderer/app.tsx"
+  );
+});
+
+test("restores source map sources without hashing usable relative paths", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "baoyu-electron-extract-"));
+  try {
+    const extractedRoot = path.join(root, "extracted");
+    const restoredRoot = path.join(root, "restored");
+    const mapDir = path.join(extractedRoot, ".vite", "main");
+    const mapPath = path.join(mapDir, "index.js.map");
+    await mkdir(mapDir, { recursive: true });
+    await writeFile(
+      mapPath,
+      JSON.stringify({
+        version: 3,
+        file: "index.js",
+        sources: [
+          "../../src/main.ts",
+          "../../src/common/ipcChannels.ts",
+          "../../../shared/src/lib/prompt-classification.ts",
+          "webpack://moss/./src/renderer/app.tsx",
+          "../../../../node_modules/pkg/index.js",
+          "..\\..\\node_modules\\windows-pkg\\index.js",
+          "webpack/runtime/chunk loading",
+        ],
+        sourcesContent: [
+          "export const main = true;\n",
+          "export const ipc = true;\n",
+          "export const shared = true;\n",
+          "export const renderer = true;\n",
+          "module.exports = {};\n",
+          "module.exports = {};\n",
+          "runtime();\n",
+        ],
+      }),
+      "utf8"
+    );
+
+    const warnings: string[] = [];
+    const restored = restoreFromMap(
+      mapPath,
+      extractedRoot,
+      restoredRoot,
+      warnings
+    );
+
+    assert.equal(restored, 4);
+    assert.deepEqual(warnings, []);
+    assert.equal(
+      await readFile(path.join(restoredRoot, "src", "main.ts"), "utf8"),
+      "export const main = true;\n"
+    );
+    assert.equal(
+      await readFile(
+        path.join(restoredRoot, "src", "common", "ipcChannels.ts"),
+        "utf8"
+      ),
+      "export const ipc = true;\n"
+    );
+    assert.equal(
+      await readFile(
+        path.join(
+          restoredRoot,
+          "shared",
+          "src",
+          "lib",
+          "prompt-classification.ts"
+        ),
+        "utf8"
+      ),
+      "export const shared = true;\n"
+    );
+    assert.equal(
+      await readFile(
+        path.join(restoredRoot, "moss", "src", "renderer", "app.tsx"),
+        "utf8"
+      ),
+      "export const renderer = true;\n"
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
@@ -0,0 +1,928 @@
+#!/usr/bin/env bun
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  posix as posixPath,
+  relative,
+  resolve,
+  sep,
+} from "path";
+import { createHash } from "crypto";
+import { spawn, spawnSync } from "child_process";
+import { homedir } from "os";
+import { pathToFileURL } from "url";
+
+interface Options {
+  app: string;
+  output?: string;
+  asar?: string;
+  force: boolean;
+  skipFormat: boolean;
+  skipRestore: boolean;
+  noUnpacked: boolean;
+  dryRun: boolean;
+  json: boolean;
+}
+
+interface ResolvedApp {
+  appName: string;
+  asarPath: string;
+  unpackedDir: string | null;
+  installRoot: string | null;
+}
+
+interface Counts {
+  extractedFiles: number;
+  restoredFiles: number;
+  formattedFiles: number;
+  skippedNodeModules: number;
+  unpackedFiles: number;
+}
+
+interface Report {
+  appName: string;
+  source: {
+    input: string;
+    asar: string;
+    platform: string;
+    installRoot: string | null;
+  };
+  output: {
+    root: string;
+    extracted: string;
+    unpacked: string | null;
+    restored: string | null;
+  };
+  counts: Counts;
+  warnings: string[];
+  durationMs: number;
+}
+
+function usage(): string {
+  return `Usage: main.ts <app> [options]
+
+Extract resources & JavaScript from an installed Electron app.
+
+Arguments:
+  <app>              App name (e.g. "Codex", "Visual Studio Code") or absolute
+                     path to a .app bundle, install directory, or .asar file.
+
+Options:
+  -o, --output PATH  Output directory (default: ~/Downloads/<App>-electron-extract)
+      --asar PATH    Override the resolved .asar path
+  -f, --force        Allow writing into a non-empty existing output dir
+      --skip-format  Skip Prettier formatting (extract only)
+      --skip-restore Skip source-map restoration
+      --no-unpacked  Don't copy app.asar.unpacked/ alongside
+      --dry-run      Print resolved paths and exit without writing
+      --json         Emit a single JSON line summary to stdout
+  -h, --help         Show this help
+`;
+}
+
+function fail(message: string, json: boolean): never {
+  if (json) {
+    process.stdout.write(
+      JSON.stringify({ status: "error", error: message }) + "\n"
+    );
+  } else {
+    process.stderr.write(`Error: ${message}\n`);
+  }
+  process.exit(1);
+}
+
+function parseArgs(argv: string[]): Options {
+  const opts: Options = {
+    app: "",
+    force: false,
+    skipFormat: false,
+    skipRestore: false,
+    noUnpacked: false,
+    dryRun: false,
+    json: false,
+  };
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      process.stdout.write(usage());
+      process.exit(0);
+    } else if (a === "-o" || a === "--output") {
+      opts.output = argv[++i];
+    } else if (a === "--asar") {
+      opts.asar = argv[++i];
+    } else if (a === "-f" || a === "--force") {
+      opts.force = true;
+    } else if (a === "--skip-format") {
+      opts.skipFormat = true;
+    } else if (a === "--skip-restore") {
+      opts.skipRestore = true;
+    } else if (a === "--no-unpacked") {
+      opts.noUnpacked = true;
+    } else if (a === "--dry-run") {
+      opts.dryRun = true;
+    } else if (a === "--json") {
+      opts.json = true;
+    } else if (a.startsWith("-")) {
+      throw new Error(`unknown option: ${a}\n\n${usage()}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length === 0 && !opts.asar) {
+    throw new Error(
+      `missing <app> argument (or pass --asar PATH)\n\n${usage()}`
+    );
+  }
+  if (positional.length > 1) {
+    throw new Error(
+      `too many positional arguments: ${positional.join(", ")}\n\n${usage()}`
+    );
+  }
+  opts.app = positional[0] ?? "";
+  return opts;
+}
+
+function sanitizeAppName(name: string): string {
+  return name.replace(/[\\/:*?"<>|]/g, "_").replace(/\s+/g, "-");
+}
+
+function appNameFromPath(p: string): string {
+  const parts = resolve(p).split(sep);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (parts[i].endsWith(".app")) return parts[i].slice(0, -4);
+  }
+  const n = basename(p);
+  if (n === "app.asar") {
+    if (
+      parts.length >= 3 &&
+      parts[parts.length - 2].toLowerCase() === "resources"
+    ) {
+      return parts[parts.length - 3];
+    }
+    if (parts.length >= 2) return parts[parts.length - 2];
+  }
+  if (n.endsWith(".asar")) return n.slice(0, -5);
+  if (n.endsWith(".app")) return n.slice(0, -4);
+  return n;
+}
+
+function existsAsFile(p: string): boolean {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function existsAsDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findAsarUnderDir(dir: string): string | null {
+  const candidates = [
+    join(dir, "resources", "app.asar"),
+    join(dir, "Resources", "app.asar"),
+    join(dir, "app.asar"),
+  ];
+  for (const c of candidates) {
+    if (existsAsFile(c)) return c;
+  }
+  if (!existsAsDir(dir)) return null;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const nested = join(dir, entry.name, "resources", "app.asar");
+    if (existsAsFile(nested)) return nested;
+  }
+  return null;
+}
+
+function resolveByPath(input: string): ResolvedApp | null {
+  if (!existsSync(input)) return null;
+  const st = statSync(input);
+  if (st.isFile() && input.endsWith(".asar")) {
+    return {
+      appName: appNameFromPath(input),
+      asarPath: input,
+      unpackedDir: existsAsDir(input + ".unpacked")
+        ? input + ".unpacked"
+        : null,
+      installRoot: dirname(input),
+    };
+  }
+  if (st.isDirectory()) {
+    if (input.endsWith(".app")) {
+      const asar = join(input, "Contents", "Resources", "app.asar");
+      if (existsAsFile(asar)) {
+        return {
+          appName: appNameFromPath(input),
+          asarPath: asar,
+          unpackedDir: existsAsDir(asar + ".unpacked")
+            ? asar + ".unpacked"
+            : null,
+          installRoot: input,
+        };
+      }
+      return null;
+    }
+    const asar = findAsarUnderDir(input);
+    if (asar) {
+      return {
+        appName: appNameFromPath(input),
+        asarPath: asar,
+        unpackedDir: existsAsDir(asar + ".unpacked")
+          ? asar + ".unpacked"
+          : null,
+        installRoot: input,
+      };
+    }
+  }
+  return null;
+}
+
+function listAppCandidates(name: string): string[] {
+  const lower = name.toLowerCase();
+  const stripped = lower.endsWith(".app") ? lower.slice(0, -4) : lower;
+  const matches: string[] = [];
+
+  if (process.platform === "darwin") {
+    const roots = ["/Applications", join(homedir(), "Applications")];
+    for (const root of roots) {
+      if (!existsAsDir(root)) continue;
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const en = entry.name.toLowerCase();
+        const enStripped = en.endsWith(".app") ? en.slice(0, -4) : en;
+        if (
+          en === lower ||
+          en === `${stripped}.app` ||
+          enStripped === stripped
+        ) {
+          matches.push(join(root, entry.name));
+        }
+      }
+    }
+  } else if (process.platform === "win32") {
+    const roots = [
+      process.env.LOCALAPPDATA
+        ? join(process.env.LOCALAPPDATA, "Programs")
+        : null,
+      process.env.PROGRAMFILES || null,
+      process.env["PROGRAMFILES(X86)"] || null,
+      process.env.APPDATA || null,
+    ].filter((x): x is string => Boolean(x));
+    for (const root of roots) {
+      if (!existsAsDir(root)) continue;
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.toLowerCase() === stripped) {
+          matches.push(join(root, entry.name));
+        }
+      }
+    }
+  }
+  return matches;
+}
+
+function resolveApp(input: string): ResolvedApp {
+  if (isAbsolute(input)) {
+    const r = resolveByPath(input);
+    if (r) return r;
+    throw new Error(`path exists but no app.asar found at or under: ${input}`);
+  }
+
+  if (process.platform !== "darwin" && process.platform !== "win32") {
+    throw new Error(
+      `platform ${process.platform} is not auto-supported. Pass --asar /path/to/app.asar to override.`
+    );
+  }
+
+  const candidates = listAppCandidates(input);
+  if (candidates.length === 0) {
+    throw new Error(
+      `could not find an installed app matching "${input}". Try passing an absolute path or --asar.`
+    );
+  }
+
+  const resolved = candidates
+    .map((c) => resolveByPath(c))
+    .filter((r): r is ResolvedApp => r !== null);
+
+  if (resolved.length === 0) {
+    throw new Error(
+      `found app directories for "${input}" but none contained app.asar:\n  ${candidates.join(
+        "\n  "
+      )}`
+    );
+  }
+  if (resolved.length > 1) {
+    throw new Error(
+      `multiple apps match "${input}". Re-run with an absolute path:\n  ${resolved
+        .map((r) => r.installRoot ?? r.asarPath)
+        .join("\n  ")}`
+    );
+  }
+  return resolved[0];
+}
+
+function downloadsDir(): string {
+  return join(homedir(), "Downloads");
+}
+
+function assertSafeOutputDir(outputDir: string, appName: string): void {
+  const root =
+    process.platform === "win32" ? outputDir.split(sep)[0] + sep : "/";
+  const home = resolve(homedir());
+  const cwd = resolve(process.cwd());
+  const forbidden = [root, home, cwd];
+  if (forbidden.includes(outputDir)) {
+    throw new Error(`output directory is unsafe to write into: ${outputDir}`);
+  }
+  const base = basename(outputDir).toLowerCase();
+  const tag = sanitizeAppName(appName).toLowerCase();
+  if (!base.includes(tag.toLowerCase()) && !base.includes("electron-extract")) {
+    throw new Error(
+      `output directory basename must contain the app name (or "electron-extract"): ${outputDir}`
+    );
+  }
+}
+
+function dirIsNonEmpty(p: string): boolean {
+  try {
+    return readdirSync(p).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function runQuiet(
+  cmd: string,
+  args: string[]
+): { code: number; stderr: string; stdout: string } {
+  const r = spawnSync(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  if (r.error) return { code: 1, stderr: r.error.message, stdout: "" };
+  return {
+    code: r.status ?? 1,
+    stderr: r.stderr ?? "",
+    stdout: r.stdout ?? "",
+  };
+}
+
+function runForwarded(cmd: string, args: string[]): Promise<number> {
+  return new Promise((res) => {
+    const proc = spawn(cmd, args, { stdio: ["ignore", "inherit", "inherit"] });
+    proc.on("close", (code) => res(code ?? 1));
+    proc.on("error", () => res(1));
+  });
+}
+
+async function extractAsar(
+  asarPath: string,
+  dest: string,
+  json: boolean
+): Promise<void> {
+  mkdirSync(dest, { recursive: true });
+  const args = ["-y", "@electron/asar", "extract", asarPath, dest];
+  const code = json
+    ? await new Promise<number>((res) => {
+        const p = spawn("npx", args, { stdio: ["ignore", "ignore", "pipe"] });
+        let err = "";
+        p.stderr?.on("data", (d) => (err += d.toString()));
+        p.on("close", (c) => {
+          if ((c ?? 1) !== 0) process.stderr.write(err);
+          res(c ?? 1);
+        });
+        p.on("error", (e) => {
+          process.stderr.write(e.message);
+          res(1);
+        });
+      })
+    : await runForwarded("npx", args);
+  if (code !== 0)
+    throw new Error(`@electron/asar extract failed (code ${code})`);
+}
+
+type FileKind = "js" | "css" | "other";
+
+function classifyExt(p: string): FileKind {
+  const e = extname(p).toLowerCase();
+  if (e === ".js" || e === ".mjs" || e === ".cjs") return "js";
+  if (e === ".css") return "css";
+  return "other";
+}
+
+function walk(
+  root: string,
+  out: { jsFiles: string[]; cssFiles: string[] },
+  counts: Counts
+): void {
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === "node_modules") {
+      counts.skippedNodeModules += 1;
+      continue;
+    }
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, out, counts);
+    } else if (entry.isFile()) {
+      counts.extractedFiles += 1;
+      const k = classifyExt(full);
+      if (k === "js") out.jsFiles.push(full);
+      else if (k === "css") out.cssFiles.push(full);
+    }
+  }
+}
+
+function countFiles(dir: string): number {
+  let total = 0;
+  if (!existsAsDir(dir)) return 0;
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop()!;
+    for (const entry of readdirSync(cur, { withFileTypes: true })) {
+      const full = join(cur, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) total += 1;
+    }
+  }
+  return total;
+}
+
+function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+function sourcePathExt(src: string): string {
+  return extname(src.split(/[?#]/)[0]) || ".txt";
+}
+
+function stripSourceDecorations(src: string): {
+  path: string;
+  hadProtocol: boolean;
+} {
+  let s = src.trim();
+  let hadProtocol = false;
+  if (/^webpack:\/\/\/?/.test(s)) {
+    hadProtocol = true;
+    s = s.replace(/^webpack:\/\/\/?/, "");
+  } else if (/^file:\/\//.test(s)) {
+    hadProtocol = true;
+    s = s.replace(/^file:\/\//, "");
+  } else if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s)) {
+    hadProtocol = true;
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+  }
+  return { path: s.split(/[?#]/)[0].replace(/\\/g, "/"), hadProtocol };
+}
+
+function isSafeRelativePath(p: string): boolean {
+  return (
+    p !== "" &&
+    p !== "." &&
+    p !== ".." &&
+    !p.startsWith("../") &&
+    !p.includes("/../")
+  );
+}
+
+function fallbackUnknownPath(src: string): string {
+  const h = createHash("sha1").update(src).digest("hex").slice(0, 10);
+  return posixPath.join("__unknown", `${h}${sourcePathExt(src)}`);
+}
+
+function normalizeForOutputPath(p: string): string {
+  let s = p.replace(/\\/g, "/").replace(/^[a-zA-Z]:\//, "");
+  if (s.startsWith("/")) s = s.replace(/^\/+/, "");
+  return posixPath.normalize(s);
+}
+
+function sanitizeEscapedSourcePath(
+  normalized: string,
+  original: string
+): string {
+  let s = normalized
+    .replace(/\\/g, "/")
+    .replace(/^[a-zA-Z]:\//, "")
+    .replace(/^\/+/, "");
+  while (s.startsWith("../")) s = s.slice(3);
+  s = posixPath.normalize(s);
+  if (!isSafeRelativePath(s)) return fallbackUnknownPath(original);
+  return s;
+}
+
+function shouldSkipRestoredSource(src: string): boolean {
+  const s = src.replace(/\\/g, "/");
+  return s.includes("node_modules/") || s.startsWith("webpack/runtime/");
+}
+
+function sourceWithRoot(
+  src: string,
+  sourceRoot: unknown
+): { path: string; hadProtocol: boolean } {
+  const source = stripSourceDecorations(src);
+  if (typeof sourceRoot !== "string" || sourceRoot.trim() === "") return source;
+
+  const root = stripSourceDecorations(sourceRoot);
+  const sourceIsAbsolute =
+    source.path.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(source.path);
+  if (!root.path || source.hadProtocol || sourceIsAbsolute) {
+    return {
+      path: source.path,
+      hadProtocol: source.hadProtocol || root.hadProtocol,
+    };
+  }
+  return {
+    path: posixPath.join(root.path.replace(/\\/g, "/"), source.path),
+    hadProtocol: source.hadProtocol || root.hadProtocol,
+  };
+}
+
+export function normalizeSourcePath(
+  src: string,
+  mapPath: string,
+  extractedRoot: string,
+  sourceRoot: unknown
+): string {
+  const source = sourceWithRoot(src, sourceRoot);
+  if (!source.path) return "";
+
+  if (
+    !source.hadProtocol &&
+    (source.path.startsWith("./") || source.path.startsWith("../"))
+  ) {
+    const mapRelDir = toPosix(relative(extractedRoot, dirname(mapPath))) || ".";
+    const relativeToExtracted = posixPath.normalize(
+      posixPath.join(mapRelDir, source.path)
+    );
+    if (isSafeRelativePath(relativeToExtracted)) return relativeToExtracted;
+    return sanitizeEscapedSourcePath(relativeToExtracted, src);
+  }
+
+  const normalized = normalizeForOutputPath(source.path);
+  if (isSafeRelativePath(normalized)) return normalized;
+  return sanitizeEscapedSourcePath(normalized, src);
+}
+
+function restoredTargetPath(
+  restoredRoot: string,
+  sourcePath: string
+): string | null {
+  const target = resolve(restoredRoot, ...sourcePath.split("/"));
+  const rel = relative(restoredRoot, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  return target;
+}
+
+interface MapData {
+  sources?: unknown;
+  sourcesContent?: unknown;
+  sourceRoot?: unknown;
+}
+
+export function restoreFromMap(
+  mapPath: string,
+  extractedRoot: string,
+  restoredRoot: string,
+  warnings: string[]
+): number {
+  let raw: string;
+  try {
+    raw = readFileSync(mapPath, "utf8");
+  } catch (e: any) {
+    warnings.push(`read ${mapPath}: ${e.message}`);
+    return 0;
+  }
+  let data: MapData;
+  try {
+    data = JSON.parse(raw);
+  } catch (e: any) {
+    warnings.push(`parse ${mapPath}: ${e.message}`);
+    return 0;
+  }
+  const sources = Array.isArray(data.sources)
+    ? (data.sources as unknown[])
+    : null;
+  const contents = Array.isArray(data.sourcesContent)
+    ? (data.sourcesContent as unknown[])
+    : null;
+  if (!sources || !contents) return 0;
+  if (sources.length !== contents.length) {
+    warnings.push(`${mapPath}: sources/sourcesContent length mismatch`);
+  }
+  const n = Math.min(sources.length, contents.length);
+  let written = 0;
+  for (let i = 0; i < n; i++) {
+    const src = sources[i];
+    const content = contents[i];
+    if (typeof src !== "string" || typeof content !== "string") continue;
+    if (shouldSkipRestoredSource(src)) continue;
+    const restoredPath = normalizeSourcePath(
+      src,
+      mapPath,
+      extractedRoot,
+      data.sourceRoot
+    );
+    if (!restoredPath) continue;
+    const target = restoredTargetPath(restoredRoot, restoredPath);
+    if (!target) {
+      warnings.push(`${mapPath}: unsafe restored path for source ${src}`);
+      continue;
+    }
+    try {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content);
+      written += 1;
+    } catch (e: any) {
+      warnings.push(`write ${target}: ${e.message}`);
+    }
+  }
+  return written;
+}
+
+function formatBatches(files: string[], json: boolean): Promise<void> {
+  const maxArgLen = 50_000;
+  let batch: string[] = [];
+  let len = 0;
+  const flush = async () => {
+    if (batch.length === 0) return;
+    const args = ["-y", "prettier", "--write", ...batch];
+    const code = json
+      ? await new Promise<number>((res) => {
+          const p = spawn("npx", args, { stdio: ["ignore", "ignore", "pipe"] });
+          let err = "";
+          p.stderr?.on("data", (d) => (err += d.toString()));
+          p.on("close", (c) => {
+            if ((c ?? 1) !== 0) process.stderr.write(err);
+            res(c ?? 1);
+          });
+          p.on("error", (e) => {
+            process.stderr.write(e.message);
+            res(1);
+          });
+        })
+      : await runForwarded("npx", args);
+    if (code !== 0) {
+      process.stderr.write(
+        `prettier batch exited with code ${code} (continuing)\n`
+      );
+    }
+    batch = [];
+    len = 0;
+  };
+
+  return (async () => {
+    for (const f of files) {
+      batch.push(f);
+      len += f.length + 1;
+      if (len >= maxArgLen) await flush();
+    }
+    await flush();
+  })();
+}
+
+async function main(): Promise<void> {
+  const started = Date.now();
+  let opts: Options;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e: any) {
+    process.stderr.write(`Error: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  let resolved: ResolvedApp;
+  try {
+    if (opts.asar) {
+      const r = resolveByPath(opts.asar);
+      if (!r) throw new Error(`--asar path not found: ${opts.asar}`);
+      const appName =
+        opts.app && !isAbsolute(opts.app)
+          ? opts.app
+          : appNameFromPath(opts.asar);
+      resolved = { ...r, appName };
+    } else {
+      resolved = resolveApp(opts.app);
+    }
+  } catch (e: any) {
+    fail(e.message, opts.json);
+  }
+
+  const outputDir = resolve(
+    opts.output ??
+      join(
+        downloadsDir(),
+        `${sanitizeAppName(resolved.appName)}-electron-extract`
+      )
+  );
+  try {
+    assertSafeOutputDir(outputDir, resolved.appName);
+  } catch (e: any) {
+    fail(e.message, opts.json);
+  }
+
+  const extractedDir = join(outputDir, "extracted");
+  const unpackedOut = join(outputDir, "extracted.unpacked");
+  const restoredDir = join(outputDir, "restored");
+
+  if (opts.dryRun) {
+    const summary = {
+      status: "dry-run",
+      appName: resolved.appName,
+      asar: resolved.asarPath,
+      unpacked: resolved.unpackedDir,
+      output: outputDir,
+      extracted: extractedDir,
+      extractedUnpacked: opts.noUnpacked
+        ? null
+        : resolved.unpackedDir
+        ? unpackedOut
+        : null,
+      restored: opts.skipRestore ? null : restoredDir,
+    };
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(summary) + "\n");
+    } else {
+      process.stdout.write(
+        `[dry-run] App:        ${resolved.appName}\n` +
+          `[dry-run] Asar:       ${resolved.asarPath}\n` +
+          `[dry-run] Unpacked:   ${resolved.unpackedDir ?? "(none)"}\n` +
+          `[dry-run] Output:     ${outputDir}\n` +
+          `[dry-run]  extracted: ${extractedDir}\n` +
+          `[dry-run]  unpacked:  ${
+            opts.noUnpacked
+              ? "(skipped)"
+              : resolved.unpackedDir
+              ? unpackedOut
+              : "(none)"
+          }\n` +
+          `[dry-run]  restored:  ${
+            opts.skipRestore ? "(skipped)" : restoredDir
+          }\n`
+      );
+    }
+    return;
+  }
+
+  if (existsSync(outputDir) && dirIsNonEmpty(outputDir) && !opts.force) {
+    fail(
+      `output directory exists and is not empty: ${outputDir}\n  Pass --force to allow writing into it, or choose another --output.`,
+      opts.json
+    );
+  }
+  mkdirSync(outputDir, { recursive: true });
+
+  if (!opts.json) {
+    process.stdout.write(`App:    ${resolved.appName}\n`);
+    process.stdout.write(`Asar:   ${resolved.asarPath}\n`);
+    process.stdout.write(`Output: ${outputDir}\n`);
+    process.stdout.write(`Extracting asar...\n`);
+  }
+
+  try {
+    await extractAsar(resolved.asarPath, extractedDir, opts.json);
+  } catch (e: any) {
+    fail(e.message, opts.json);
+  }
+
+  const counts: Counts = {
+    extractedFiles: 0,
+    restoredFiles: 0,
+    formattedFiles: 0,
+    skippedNodeModules: 0,
+    unpackedFiles: 0,
+  };
+  const warnings: string[] = [];
+
+  let unpackedFinal: string | null = null;
+  if (
+    !opts.noUnpacked &&
+    resolved.unpackedDir &&
+    existsAsDir(resolved.unpackedDir)
+  ) {
+    if (!opts.json) process.stdout.write(`Copying app.asar.unpacked...\n`);
+    try {
+      cpSync(resolved.unpackedDir, unpackedOut, { recursive: true });
+      counts.unpackedFiles = countFiles(unpackedOut);
+      unpackedFinal = unpackedOut;
+    } catch (e: any) {
+      warnings.push(`copy unpacked: ${e.message}`);
+    }
+  }
+
+  const walked = { jsFiles: [] as string[], cssFiles: [] as string[] };
+  walk(extractedDir, walked, counts);
+
+  const toFormat: string[] = [];
+  const restoredMapFiles = new Set<string>();
+  const skipFormatSet = new Set<string>();
+
+  if (!opts.skipRestore) {
+    for (const js of walked.jsFiles) {
+      const mapPath = js + ".map";
+      if (!existsAsFile(mapPath)) continue;
+      const w = restoreFromMap(mapPath, extractedDir, restoredDir, warnings);
+      if (w > 0) {
+        counts.restoredFiles += w;
+        restoredMapFiles.add(mapPath);
+        skipFormatSet.add(js);
+        const license = js + ".LICENSE.txt";
+        if (existsAsFile(license)) skipFormatSet.add(license);
+      }
+    }
+  }
+
+  if (!opts.skipFormat) {
+    for (const js of walked.jsFiles)
+      if (!skipFormatSet.has(js)) toFormat.push(js);
+    for (const css of walked.cssFiles) toFormat.push(css);
+    if (toFormat.length > 0) {
+      if (!opts.json)
+        process.stdout.write(
+          `Formatting ${toFormat.length} file(s) with prettier...\n`
+        );
+      await formatBatches(toFormat, opts.json);
+      counts.formattedFiles = toFormat.length;
+    }
+  }
+
+  const report: Report = {
+    appName: resolved.appName,
+    source: {
+      input: opts.app,
+      asar: resolved.asarPath,
+      platform: process.platform,
+      installRoot: resolved.installRoot,
+    },
+    output: {
+      root: outputDir,
+      extracted: extractedDir,
+      unpacked: unpackedFinal,
+      restored: counts.restoredFiles > 0 ? restoredDir : null,
+    },
+    counts,
+    warnings,
+    durationMs: Date.now() - started,
+  };
+
+  try {
+    writeFileSync(
+      join(outputDir, "extract-report.json"),
+      JSON.stringify(report, null, 2)
+    );
+  } catch (e: any) {
+    warnings.push(`write extract-report.json: ${e.message}`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ status: "ok", ...report }) + "\n");
+  } else {
+    process.stdout.write(
+      `\nDone in ${(report.durationMs / 1000).toFixed(1)}s\n` +
+        `  Extracted:        ${counts.extractedFiles} file(s) into ${extractedDir}\n` +
+        (counts.unpackedFiles > 0
+          ? `  Unpacked copied:  ${counts.unpackedFiles} file(s) into ${unpackedOut}\n`
+          : "") +
+        `  Restored:         ${counts.restoredFiles} file(s)` +
+        (counts.restoredFiles > 0 ? ` into ${restoredDir}\n` : `\n`) +
+        `  Formatted:        ${counts.formattedFiles} file(s)\n` +
+        `  node_modules dirs skipped: ${counts.skippedNodeModules}\n` +
+        (warnings.length > 0
+          ? `  Warnings:         ${warnings.length} (see extract-report.json)\n`
+          : "")
+    );
+  }
+}
+
+function isDirectRun(): boolean {
+  if (import.meta.main) return true;
+  const scriptPath = process.argv[1];
+  return Boolean(
+    scriptPath && pathToFileURL(resolve(scriptPath)).href === import.meta.url
+  );
+}
+
+if (isDirectRun()) {
+  main().catch((e) => {
+    process.stderr.write(`Unexpected error: ${e?.stack ?? e}\n`);
+    process.exit(1);
+  });
+}
@@ -1,480 +0,0 @@
---
-name: baoyu-image-cards
-description: Generates infographic image card series with 12 visual styles, 8 layouts, and 3 color palettes. Breaks content into 1-10 cartoon-style image cards optimized for social media engagement. Use when user mentions "小红书图片", "小红书种草", "小绿书", "微信图文", "微信贴图", "image cards", "图片卡片", or wants social media infographic series.
-version: 1.57.0
-metadata:
-  openclaw:
-    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-image-cards
---
-
-# Image Card Series Generator
-
-Break down complex content into eye-catching image card series with multiple style options.
-
-## User Input Tools
-
-When this skill prompts the user, follow this tool-selection rule (priority order):
-
-1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
-2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
-3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
-
-Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
-
-## Image Generation Tools
-
-When this skill needs to render an image, resolve the backend in this order:
-
-1. **Current-request override** — if the user names a specific backend in the current message, use it.
-2. **Saved preference** — if `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
-3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
-   - **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
-   - **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
-   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
-   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
-4. **If none are available**, tell the user and ask how to proceed.
-
-**⛔ Never substitute SVG, HTML, canvas, or other code-based rendering for raster image generation.** Codex `imagegen`'s own description says it should be used "when the output should be a bitmap asset rather than repo-native code or vector." If you cannot resolve a raster backend via step 3, fall through to step 4 and ask the user — do **not** silently emit SVG, write inline `<svg>` markup, or produce HTML/CSS art as a substitute. This applies even if the article/section seems "diagram-like": the consumer skill calling this rule has already decided that a raster image is what it needs.
-
-**⛔ Never repair rendered text by painting over a generated bitmap.** Do not use ImageMagick, Pillow, Canvas, SVG, HTML/CSS, OCR scripts, or any other programmatic overlay to cover, rewrite, erase, stroke, or replace titles, body copy, tags, or any other text inside an already generated image card. If text is wrong or unclear, regenerate from a corrected prompt, switch to a layout with less on-card text, or ask the user which imperfect candidate to keep.
-
-Setting `preferred_image_backend: ask` forces the step-3 prompt every run regardless of available backends. Users change the pinned backend via the `## Changing Preferences` section below.
-
-**Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The file is the reproducibility record and lets you switch backends without regenerating prompts.
-
-Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
-
-## Batch Generation Policy
-
-After every prompt file for the current generation group has been saved and verified, generate images in batches by default.
-
-Priority order:
-
-1. Use the chosen backend's native batch / multi-task interface if it exists. Each task must keep its own prompt file, output path, aspect ratio, session ID, and direct reference images.
-2. If no native batch interface exists but the runtime can issue parallel tool calls, dispatch up to `generation_batch_size` images at a time. Default: `4`. An explicit user request in the current message, such as `--batch-size 4` or "并行4张一起生成", overrides EXTEND.md.
-3. If neither native batch nor parallel tool calls are available, generate sequentially.
-
-Rules:
-
- Honor the image-1 anchor chain: generate image 1 first, then batch images 2+ using image 1 as the reference.
- Never start a batch until every selected prompt file for that batch exists on disk.
- Retry failed items once without regenerating successful items.
- Do not use subagents merely to parallelize image rendering. Use subagents only for separate prompt iteration or creative exploration.
-
-## Confirmation Policy
-
-Default behavior: **confirm before generation**.
-
- Treat explicit skill invocation, a file path, matched signals/presets, and `EXTEND.md` defaults as **recommendation inputs only**. None of them authorizes skipping confirmation.
- Do **not** start Step 3 until the user completes Step 2.
- Skip confirmation only when the current request explicitly says to do so, for example: `--yes`, "直接生成", "不用确认", "跳过确认", "按默认出图", or equivalent wording.
- If confirmation is skipped explicitly, state the assumed strategy / style / layout / palette / count / backend in the next user-facing update before generating.
-
-## Language
-
-Respond in the user's language across questions, progress, errors, and completion summary. Keep technical tokens (style names, file paths, code) in English.
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--style <name>` | Visual style (see Styles below) |
-| `--layout <name>` | Information layout (see Layouts below) |
-| `--palette <name>` | Color override: macaron / warm / neon |
-| `--preset <name>` | Style + layout + optional palette shorthand (see Presets below; per-preset prompt fragments in `references/style-presets.md`) |
-| `--ref <files...>` | Reference images applied to image 1 as the series anchor |
-| `--batch-size <n>` | Temporary generation batch size for this run. Default: `generation_batch_size` from EXTEND.md, otherwise 4. Clamp to 1-8. |
-| `--yes` | Non-interactive: skip all confirmations, use EXTEND.md or built-in defaults, auto-confirm recommended plan (Path A) |
-
-## Dimensions
-
-Three independent knobs combine freely:
-
-| Dimension | Controls | Options |
-|-----------|----------|---------|
-| **Style** | Visual aesthetics (lines, decorations, rendering) | 12 styles (see Styles below) |
-| **Layout** | Information structure (density, arrangement) | 8 layouts (see Layouts below) |
-| **Palette** (optional) | Color override, replaces the style's default colors | macaron / warm / neon (see Palettes below) |
-
-Example: `--style notion --layout dense` makes an intellectual knowledge card; add `--palette macaron` to soften the colors without changing notion's rendering rules. A `--preset` is a shorthand for style + layout (+ optional palette).
-
-**Palette behavior**: no `--palette` → style's built-in colors; `--palette <name>` → overrides colors only, rendering rules unchanged. Some styles declare a `default_palette` (e.g., sketch-notes defaults to macaron).
-
-## Styles (12)
-
-| Style | Description |
-|-------|-------------|
-| `cute` (Default) | Sweet, adorable, girly aesthetic |
-| `fresh` | Clean, refreshing, natural |
-| `warm` | Cozy, friendly, approachable |
-| `bold` | High impact, attention-grabbing |
-| `minimal` | Ultra-clean, sophisticated |
-| `retro` | Vintage, nostalgic, trendy |
-| `pop` | Vibrant, energetic, eye-catching |
-| `notion` | Minimalist hand-drawn line art, intellectual |
-| `chalkboard` | Colorful chalk on black board, educational |
-| `study-notes` | Realistic handwritten photo style, blue pen + red annotations + yellow highlighter |
-| `screen-print` | Bold poster art, halftone textures, limited colors, symbolic storytelling |
-| `sketch-notes` | Hand-drawn educational infographic, macaron pastels on warm cream, wobble lines |
-
-Per-style specifications: `references/presets/<style>.md`.
-
-## Layouts (8)
-
-| Layout | Description |
-|--------|-------------|
-| `sparse` (Default) | 1-2 points, maximum impact |
-| `balanced` | 3-4 points, standard |
-| `dense` | 5-8 points, knowledge-card style |
-| `list` | Enumeration / ranking (4-7 items) |
-| `comparison` | Side-by-side contrast |
-| `flow` | Process / timeline (3-6 steps) |
-| `mindmap` | Center-radial (4-8 branches) |
-| `quadrant` | Four-quadrant / circular sections |
-
-Layout specs: `references/elements/canvas.md`.
-
-## Palettes (optional override)
-
-Replaces the style's colors while keeping rendering rules (line treatment, textures) intact.
-
-| Palette | Background | Zone Colors | Accent | Feel |
-|---------|------------|-------------|--------|------|
-| `macaron` | Warm cream #F5F0E8 | Blue #A8D8EA, Lavender #D5C6E0, Mint #B5E5CF, Peach #F8D5C4 | Coral #E8655A | Soft, educational |
-| `warm` | Soft peach #FFECD2 | Orange #ED8936, Terracotta #C05621, Golden #F6AD55, Rose #D4A09A | Sienna #A0522D | Earth tones, cozy |
-| `neon` | Dark purple #1A1025 | Cyan #00F5FF, Magenta #FF00FF, Green #39FF14, Pink #FF6EC7 | Yellow #FFFF00 | High-energy, futuristic |
-
-Palette specs: `references/palettes/<palette>.md`.
-
-## Presets (style + layout shortcuts)
-
-Quick-start combos, grouped by scenario. Use `--preset <name>` or recommend during Step 2.
-
-**Knowledge & Learning**:
-
-| Preset | Style | Layout | Best For |
-|--------|-------|--------|----------|
-| `knowledge-card` | notion | dense | 干货知识卡、概念科普 |
-| `checklist` | notion | list | 清单、排行榜 |
-| `concept-map` | notion | mindmap | 概念图、知识脉络 |
-| `swot` | notion | quadrant | SWOT 分析、四象限 |
-| `tutorial` | chalkboard | flow | 教程步骤、操作流程 |
-| `classroom` | chalkboard | balanced | 课堂笔记、知识讲解 |
-| `study-guide` | study-notes | dense | 学习笔记、考试重点 |
-| `hand-drawn-edu` | sketch-notes | flow | 手绘教程、流程图解 |
-| `sketch-card` | sketch-notes | dense | 手绘知识卡 |
-| `sketch-summary` | sketch-notes | balanced | 手绘总结、图文笔记 |
-
-**Lifestyle & Sharing**:
-
-| Preset | Style | Layout | Best For |
-|--------|-------|--------|----------|
-| `cute-share` | cute | balanced | 少女风分享、日常种草 |
-| `girly` | cute | sparse | 甜美封面、氛围感 |
-| `cozy-story` | warm | balanced | 生活故事、情感分享 |
-| `product-review` | fresh | comparison | 产品对比、测评 |
-| `nature-flow` | fresh | flow | 健康流程、自然主题 |
-
-**Impact & Opinion**:
-
-| Preset | Style | Layout | Best For |
-|--------|-------|--------|----------|
-| `warning` | bold | list | 避坑指南、重要提醒 |
-| `versus` | bold | comparison | 正反对比 |
-| `clean-quote` | minimal | sparse | 金句、极简封面 |
-| `pro-summary` | minimal | balanced | 专业总结、商务内容 |
-
-**Trend & Entertainment**:
-
-| Preset | Style | Layout | Best For |
-|--------|-------|--------|----------|
-| `retro-ranking` | retro | list | 复古排行、经典盘点 |
-| `throwback` | retro | balanced | 怀旧分享 |
-| `pop-facts` | pop | list | 趣味冷知识 |
-| `hype` | pop | sparse | 炸裂封面、惊叹分享 |
-
-**Poster & Editorial**:
-
-| Preset | Style | Layout | Best For |
-|--------|-------|--------|----------|
-| `poster` | screen-print | sparse | 海报风封面、影评书评 |
-| `editorial` | screen-print | balanced | 观点文章、文化评论 |
-| `cinematic` | screen-print | comparison | 电影对比、戏剧张力 |
-
-Full prompt-fragment definitions: `references/style-presets.md`.
-
-## Auto-Selection
-
-Match content signals to the best combo. First row whose keywords appear wins; fall back to `cute-share` if nothing matches.
-
-| Signals in source | Style | Layout | Recommended preset |
-|-------------------|-------|--------|--------------------|
-| beauty, fashion, cute, girl, pink | `cute` | sparse/balanced | `cute-share`, `girly` |
-| health, nature, fresh, organic | `fresh` | balanced/flow | `product-review`, `nature-flow` |
-| life, story, emotion, warm | `warm` | balanced | `cozy-story` |
-| warning, important, must, critical | `bold` | list/comparison | `warning`, `versus` |
-| professional, business, elegant | `minimal` | sparse/balanced | `clean-quote`, `pro-summary` |
-| classic, vintage, traditional | `retro` | balanced | `throwback`, `retro-ranking` |
-| fun, exciting, wow, amazing | `pop` | sparse/list | `hype`, `pop-facts` |
-| knowledge, concept, productivity, SaaS | `notion` | dense/list | `knowledge-card`, `checklist` |
-| education, tutorial, learning, classroom | `chalkboard` | balanced/dense | `tutorial`, `classroom` |
-| notes, handwritten, study guide, realistic | `study-notes` | dense/list/mindmap | `study-guide` |
-| movie, poster, opinion, editorial, cinematic | `screen-print` | sparse/comparison | `poster`, `editorial`, `cinematic` |
-| hand-drawn, infographic, workflow, 手绘, 图解 | `sketch-notes` | flow/balanced/dense | `hand-drawn-edu`, `sketch-card`, `sketch-summary` |
-
-## Style × Layout Matrix
-
-Compatibility scores (✓✓ highly recommended, ✓ works well, ✗ avoid). Use when the user picks a non-default combo and you want to flag a poor match.
-
-|              | sparse | balanced | dense | list | comparison | flow | mindmap | quadrant |
-|--------------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| cute         | ✓✓ | ✓✓ | ✓  | ✓✓ | ✓  | ✓  | ✓  | ✓  |
-| fresh        | ✓✓ | ✓✓ | ✓  | ✓  | ✓  | ✓✓ | ✓  | ✓  |
-| warm         | ✓✓ | ✓✓ | ✓  | ✓  | ✓✓ | ✓  | ✓  | ✓  |
-| bold         | ✓✓ | ✓  | ✓  | ✓✓ | ✓✓ | ✓  | ✓  | ✓✓ |
-| minimal      | ✓✓ | ✓✓ | ✓✓ | ✓  | ✓  | ✓  | ✓  | ✓  |
-| retro        | ✓✓ | ✓✓ | ✓  | ✓✓ | ✓  | ✓  | ✓  | ✓  |
-| pop          | ✓✓ | ✓✓ | ✓  | ✓✓ | ✓✓ | ✓  | ✓  | ✓  |
-| notion       | ✓✓ | ✓✓ | ✓✓ | ✓✓ | ✓✓ | ✓✓ | ✓✓ | ✓✓ |
-| chalkboard   | ✓✓ | ✓✓ | ✓✓ | ✓✓ | ✓  | ✓✓ | ✓✓ | ✓  |
-| study-notes  | ✗  | ✓  | ✓✓ | ✓✓ | ✓  | ✓  | ✓✓ | ✓  |
-| screen-print | ✓✓ | ✓✓ | ✗  | ✓  | ✓✓ | ✓  | ✗  | ✓✓ |
-| sketch-notes | ✓  | ✓✓ | ✓✓ | ✓✓ | ✓  | ✓✓ | ✓✓ | ✓  |
-
-## Outline Strategies
-
-Three differentiated approaches — each produces a structurally different outline. The workflow recommends one; Path C generates all three and lets the user choose.
-
-| Strategy | Concept | Best for | Structure |
-|----------|---------|----------|-----------|
-| **A — Story-Driven** | Personal experience as the thread, emotional resonance first | Reviews, personal shares, transformation | Hook → Problem → Discovery → Experience → Conclusion |
-| **B — Information-Dense** | Value-first, efficient information delivery | Tutorials, comparisons, checklists | Core conclusion → Info card → Pros/Cons → Recommendation |
-| **C — Visual-First** | Visual impact as core, minimal text | High-aesthetic products, lifestyle, mood content | Hero image → Detail shots → Lifestyle scene → CTA |
-
-## Reference Images
-
-User-supplied refs are **separate from** the internal "image-1 as anchor" chain (Step 3) — they layer on top of it.
-
-**Intake**: via `--ref <files...>` or paths pasted in conversation.
- File path → copy to `refs/NN-ref-{slug}.{ext}`
- Pasted with no path → ask for the path, or extract style traits as a text fallback
-
-**Usage modes** (per reference):
-
-| Usage | Effect |
-|-------|--------|
-| `direct` | Pass the file to the backend (typically on image 1 only, so the anchor propagates through the chain) |
-| `style` | Extract style traits and append to every card's prompt body |
-| `palette` | Extract hex colors and append to every card's prompt body |
-
-Record refs in each affected card's prompt frontmatter:
-
-```yaml
-references:
-  - ref_id: 01
-    filename: 01-ref-brand.png
-    usage: direct
-```
-
-At generation time: verify files exist. Image 1 with `usage: direct` + backend that accepts refs → pass via the backend's ref parameter (becomes the chain anchor). Images 2+ keep using image-1 as `--ref` per Step 3 — do NOT re-stack user refs on top (avoids conflicting signals). For `style`/`palette`, embed extracted traits in every prompt.
-
-## File Layout
-
-```
-image-cards/{topic-slug}/
-├── source-{slug}.{ext}
-├── analysis.md
-├── outline-strategy-{a,b,c}.md    # Path C only
-├── outline.md
-├── prompts/NN-{type}-{slug}.md
-├── NN-{type}-{slug}.png
-└── refs/                          # only if --ref used
-```
-
-**Slug**: 2-4 words, kebab-case. "AI 工具推荐" → `ai-tools-recommend`. On collision, append `-YYYYMMDD-HHMMSS`.
-
-**Backup rule** (applies throughout): before overwriting any file — source, outline, prompt, image — rename the existing one to `<name>-backup-YYYYMMDD-HHMMSS.<ext>`. This protects user edits.
-
-## Workflow
-
-```
- [ ] Step 0: Load EXTEND.md ⛔ BLOCKING (interactive only)
- [ ] Step 1: Analyze content → analysis.md
- [ ] Step 2: Smart Confirm ⚠️ REQUIRED (Path A / B / C)
- [ ] Step 3: Generate images
- [ ] Step 4: Completion report
-```
-
-### Step 0: Load EXTEND.md ⛔ BLOCKING
-
-Check these paths in order; first hit wins:
-
-| Path | Scope |
-|------|-------|
-| `.baoyu-skills/baoyu-image-cards/EXTEND.md` | Project |
-| `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-cards/EXTEND.md` | XDG |
-| `$HOME/.baoyu-skills/baoyu-image-cards/EXTEND.md` | User home |
-
- **Found** → read, parse, print a summary (style / layout / watermark / language), continue.
- **Not found + interactive** → run first-time setup (see `references/config/first-time-setup.md`) and save before anything else. Do NOT analyze content or ask style questions until preferences exist — this keeps first-run behavior predictable.
- **Not found + `--yes`** → skip setup, use built-in defaults (no watermark, style/layout auto-selected, language from content). Do not prompt, do not create EXTEND.md.
-
-**EXTEND.md keys**: watermark, preferred style/layout, custom style definitions, language preference, preferred image backend, generation batch size. Schema: `references/config/preferences-schema.md`.
-
-### Step 1: Analyze Content → `analysis.md`
-
-1. Save the source (backup rule applies if `source.md` exists).
-2. Run the deep analysis in `references/workflows/analysis-framework.md`: content type, hook potential, audience, engagement signals, visual opportunity map, swipe flow.
-3. Detect source language, pick recommended image count (2-10).
-4. Auto-recommend strategy + style + layout + palette using the **Auto-Selection** table above.
-5. Write everything to `analysis.md`.
-
-### Step 2: Smart Confirm ⚠️ REQUIRED
-
-**Hard gate**: this step is mandatory per the [Confirmation Policy](#confirmation-policy) — Step 3 cannot start until the user confirms here (or explicitly opts out with `--yes` / equivalent wording in the current request).
-
-Goal: present the auto-recommended plan and let the user confirm or adjust. Skip this step entirely under `--yes` — proceed with Path A using the analysis and any CLI overrides.
-
-**Display summary** before asking:
-
-```
-📋 内容分析
-  主题：[topic] | 类型：[content_type]
-  要点：[key points]
-  受众：[audience]
-
-🎨 推荐方案（自动匹配）
-  策略：[A/B/C] [name]（[reason]）
-  风格：[style] · 布局：[layout] · 配色：[palette or 默认] · 预设：[preset]
-  图片：[N]张（封面+[N-2]内容+结尾）
-  元素：[background] / [decorations] / [emphasis]
-```
-
-Then ask one question — three paths. Verbatim option copy: `references/confirmation.md`.
-
-**Path A — Quick confirm** (trust auto-recommendation): generate a single outline using the recommended strategy + style → save to `outline.md` → Step 3.
-
-**Path B — Customize**: ask five questions (strategy/style, layout, palette, count, optional notes) with the recommendation pre-filled — blanks keep the recommendation. Generate one outline with the user's choices → `outline.md` → Step 3. See `references/confirmation.md`.
-
-**Path C — Detailed mode**: two sub-confirmations.
-
- *Step 2a — Content understanding*: ask selling points (multi-select), audience, style preference (authentic / professional / aesthetic / auto), optional context. Update `analysis.md`.
- *Step 2b — Three outline variants*: generate `outline-strategy-a.md`, `outline-strategy-b.md`, `outline-strategy-c.md`. Each MUST have a different structure AND a different recommended style — include `style_reason` in the frontmatter. Page-count heuristic: A ~4-6, B ~3-5, C ~3-4. Template: `references/workflows/outline-template.md`; frontmatter example in `references/confirmation.md`.
- *Step 2c — Selection*: ask three questions (outline A/B/C/Combined, style, visual elements). Save selected/merged outline to `outline.md` → Step 3.
-
-### Step 3: Generate Images
-
-With confirmed outline + style + layout + palette:
-
-**Visual consistency — image-1 anchor chain**: character / mascot / color rendering drifts between calls unless you anchor them. Generate image 1 (cover) first WITHOUT `--ref`, then pass image 1 as `--ref` to every subsequent image. This is the single most important consistency trick for this skill — don't skip it even if the backend also supports a session ID.
-
-Generation flow:
-
-1. Write the full prompt for every image to `prompts/NN-{type}-{slug}.md` in the user's preferred language (backup rule applies), then verify all selected prompt files exist.
-2. Generate **image 1** first without `--ref`; backup rule applies to the PNG file. This establishes the anchor.
-3. Build a task list for **images 2+** using image 1 as `--ref <path-to-image-01.png>`.
-4. Dispatch images 2+ in batches per the `## Batch Generation Policy`: backend native batch first, runtime parallel tool calls second, sequential only as fallback.
-5. Report progress after each completed image. On failure, retry only the failed item once from the same saved prompt file.
-
-**Watermark** (if enabled in EXTEND.md): append to the generation prompt:
-
-```
-Include a subtle watermark "[content]" positioned at [position].
-The watermark should be legible but not distracting.
-```
-
-See `references/config/watermark-guide.md`.
-
-**Backend selection**: per the Image Generation Tools rule at the top — use whatever is available, ask once if multiple, before any generation. Under `--yes`, use the EXTEND.md preference and fall back to the first available backend. Prompt files MUST exist before invoking any backend.
-
-**Session ID** (if the backend supports `--sessionId`): use `cards-{topic-slug}-{timestamp}` for every image; combined with the ref chain this gives maximum consistency.
-
-### Step 4: Completion Report
-
-```
-Image Card Series Complete!
-
-Topic: [topic]
-Mode: [Quick / Custom / Detailed]
-Strategy: [A/B/C/Combined]
-Style: [name]
-Palette: [name or "default"]
-Layout: [name or "varies"]
-Location: [directory]
-Images: N total
-
-✓ analysis.md
-✓ outline.md
-✓ outline-strategy-a/b/c.md (detailed mode only)
-
- 01-cover-[slug].png ✓ Cover (sparse)
- 02-content-[slug].png ✓ Content (balanced)
- ...
- NN-ending-[slug].png ✓ Ending (sparse)
-```
-
-## Content Breakdown Principles
-
-| Position | Purpose | Typical layout |
-|----------|---------|----------------|
-| Cover (image 1) | Hook + visual impact | `sparse` |
-| Content (middle) | Core value per image | `balanced` / `dense` / `list` / `comparison` / `flow` |
-| Ending (last) | CTA / summary | `sparse` or `balanced` |
-
-For the style × layout compatibility matrix, see the **Style × Layout Matrix** above.
-
-## Image Modification
-
-| Action | How |
-|--------|-----|
-| Edit | Update `prompts/NN-{type}-{slug}.md` **first**, then regenerate with the same session ID |
-| Add | Specify position, create prompt, generate, renumber subsequent files `NN+1`, update outline |
-| Delete | Remove files, renumber subsequent `NN-1`, update outline |
-
-Always update the prompt file before regenerating — it's the source of truth and makes changes reproducible.
-
-Text correction policy:
-
- If a card's title, body copy, tags, or any other rendered text is misspelled, garbled, hard to read, or visually weak, do not patch the bitmap with code.
- For text-correction regenerations, write a new prompt file and a new output path so the flawed candidate is preserved for comparison.
- Post-processing is limited to crop, resize, compression, or format conversion that does not alter text or the main composition.
-
-## References
-
-| File | Content |
-|------|---------|
-| `references/confirmation.md` | Verbatim AskUserQuestion copy for every confirmation path |
-| `references/style-presets.md` | Full preset shortcut definitions |
-| `references/presets/<style>.md` | Per-style element definitions |
-| `references/palettes/<name>.md` | Per-palette color definitions |
-| `references/elements/canvas.md` | Aspect ratios, safe zones, grid layouts |
-| `references/elements/image-effects.md` | Cutout, stroke, filters |
-| `references/elements/typography.md` | Decorated text, tags, text direction |
-| `references/elements/decorations.md` | Emphasis marks, backgrounds, doodles, frames |
-| `references/workflows/analysis-framework.md` | Content analysis framework |
-| `references/workflows/outline-template.md` | Outline template with layout guide |
-| `references/workflows/prompt-assembly.md` | Prompt assembly guide |
-| `references/config/preferences-schema.md` | EXTEND.md schema |
-| `references/config/first-time-setup.md` | First-time setup flow |
-| `references/config/watermark-guide.md` | Watermark configuration |
-
-## Notes
-
- Auto-retry once on generation failure before reporting an error.
- For sensitive public figures, use stylized cartoon alternatives.
- Smart Confirm (Step 2) is required; Detailed mode adds a second confirmation (2a + 2c).
-
-## Changing Preferences
-
-EXTEND.md lives at the first matching path listed in Step 0. Three ways to change it:
-
- **Edit directly** — open EXTEND.md and change fields. Full schema: `references/config/preferences-schema.md`.
- **Reconfigure interactively** — delete EXTEND.md (or ask "reconfigure baoyu-image-cards preferences" / "重新配置"). The next run re-triggers first-time setup.
- **Common one-line edits**:
-  - `preferred_image_backend: auto` — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
-  - `preferred_image_backend: codex-imagegen` — pin to Codex's built-in.
-  - `preferred_image_backend: baoyu-imagine` — pin to the baoyu-imagine skill.
-  - `preferred_image_backend: ask` — confirm backend every run.
-  - `generation_batch_size: 4` — default number of images to render concurrently when the backend/runtime supports batch or parallel generation.
-  - `preferred_style: notion`, `preferred_layout: dense`, `preferred_palette: macaron`, `language: zh`.
-  - `watermark.enabled: true` + `watermark.content: "@handle"` — add a watermark.
@@ -1,125 +0,0 @@
---
-name: first-time-setup
-description: First-time setup flow for baoyu-xhs-images preferences
---
-
-# First-Time Setup
-
-## Overview
-
-When no EXTEND.md is found, guide user through preference setup.
-
-**⛔ BLOCKING OPERATION**: This setup MUST complete before ANY other workflow steps. Do NOT:
- Ask about content/article
- Ask about style or layout
- Ask about target audience
- Proceed to content analysis
-
-ONLY ask the questions in this setup flow, save EXTEND.md, then continue.
-
-## Setup Flow
-
-```
-No EXTEND.md found
-        │
-        ▼
-┌─────────────────────┐
-│ AskUserQuestion     │
-│ (all questions)     │
-└─────────────────────┘
-        │
-        ▼
-┌─────────────────────┐
-│ Create EXTEND.md    │
-└─────────────────────┘
-        │
-        ▼
-    Continue to Step 1
-```
-
-## Questions
-
-**Language**: Use user's input language or saved language preference.
-
-Use single AskUserQuestion with multiple questions (AskUserQuestion auto-adds "Other" option):
-
-### Question 1: Watermark
-
-```
-header: "Watermark"
-question: "Watermark text for generated images? Type your watermark content (e.g., name, @handle)"
-options:
-  - label: "No watermark (Recommended)"
-    description: "No watermark, can enable later in EXTEND.md"
-```
-
-Position defaults to bottom-right.
-
-### Question 2: Preferred Style
-
-```
-header: "Style"
-question: "Default visual style preference? Or type another style name or your custom style"
-options:
-  - label: "None (Recommended)"
-    description: "Auto-select based on content analysis"
-  - label: "cute"
-    description: "Sweet, adorable - classic XHS aesthetic"
-  - label: "notion"
-    description: "Minimalist hand-drawn, intellectual"
-```
-
-### Question 3: Save Location
-
-```
-header: "Save"
-question: "Where to save preferences?"
-options:
-  - label: "Project"
-    description: ".baoyu-skills/ (this project only)"
-  - label: "User"
-    description: "~/.baoyu-skills/ (all projects)"
-```
-
-## Save Locations
-
-| Choice | Path | Scope |
-|--------|------|-------|
-| Project | `.baoyu-skills/baoyu-xhs-images/EXTEND.md` | Current project |
-| User | `~/.baoyu-skills/baoyu-xhs-images/EXTEND.md` | All projects |
-
-## After Setup
-
-1. Create directory if needed
-2. Write EXTEND.md with frontmatter
-3. Confirm: "Preferences saved to [path]"
-4. Continue to Step 1
-
-## EXTEND.md Template
-
-```yaml
---
-version: 1
-watermark:
-  enabled: [true/false]
-  content: "[user input or empty]"
-  position: bottom-right
-  opacity: 0.7
-preferred_style:
-  name: [selected style or null]
-  description: ""
-preferred_layout: null
-language: null
-preferred_image_backend: auto
-generation_batch_size: 4
-custom_styles: []
---
-```
-
-`preferred_image_backend: auto` is the baked-in default — first-time setup does not ask about it. The `## Image Generation Tools` rule in SKILL.md then picks the runtime-native tool (Codex `imagegen`, Hermes `image_generate`, etc.) when available, and falls back to installed backends.
-
-`generation_batch_size: 4` is the baked-in default for batch rendering. The current user request may override it for one run.
-
-## Modifying Preferences Later
-
-See the `## Changing Preferences` section in `SKILL.md` for the canonical list of common edits (pin backend, change defaults, retrigger setup). Full schema: `preferences-schema.md`.
@@ -1,128 +0,0 @@
---
-name: preferences-schema
-description: EXTEND.md YAML schema for baoyu-xhs-images user preferences
---
-
-# Preferences Schema
-
-## Full Schema
-
-```yaml
---
-version: 1
-
-watermark:
-  enabled: false
-  content: ""
-  position: bottom-right  # bottom-right|bottom-left|bottom-center|top-right
-
-preferred_style:
-  name: null              # Built-in or custom style name
-  description: ""         # Override/notes
-
-preferred_layout: null    # sparse|balanced|dense|list|comparison|flow
-
-language: null            # zh|en|ja|ko|auto
-
-preferred_image_backend: auto  # auto|ask|<backend-id>
-
-generation_batch_size: 4       # 1-8, used when backend/runtime supports batch or parallel generation
-
-custom_styles:
-  - name: my-style
-    description: "Style description"
-    color_palette:
-      primary: ["#FED7E2", "#FEEBC8"]
-      background: "#FFFAF0"
-      accents: ["#FF69B4", "#FF6B6B"]
-    visual_elements: "Hearts, stars, sparkles"
-    typography: "Rounded, bubbly hand lettering"
-    best_for: "Lifestyle, beauty"
---
-```
-
-## Field Reference
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `version` | int | 1 | Schema version |
-| `watermark.enabled` | bool | false | Enable watermark |
-| `watermark.content` | string | "" | Watermark text (@username or custom) |
-| `watermark.position` | enum | bottom-right | Position on image |
-| `preferred_style.name` | string | null | Style name or null |
-| `preferred_style.description` | string | "" | Custom notes/override |
-| `preferred_layout` | string | null | Layout preference or null |
-| `language` | string | null | Output language (null = auto-detect) |
-| `preferred_image_backend` | string | `auto` | Image backend selection. `auto` = prefer runtime-native tool, fall back to the only installed backend, ask if multiple non-native are present. `ask` = always confirm on every run. `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) = pin this backend when available; fall back to `auto` when it isn't. Absent = `auto`. Resolution logic is documented in `SKILL.md`'s `## Image Generation Tools` section. |
-| `generation_batch_size` | int | 4 | Number of images to dispatch per batch when the backend has native batch support or the runtime can issue parallel generation calls. Clamp invalid values to 1-8. Current user request overrides this value. |
-| `custom_styles` | array | [] | User-defined styles |
-
-## Position Options
-
-| Value | Description |
-|-------|-------------|
-| `bottom-right` | Lower right corner (default, most common) |
-| `bottom-left` | Lower left corner |
-| `bottom-center` | Bottom center |
-| `top-right` | Upper right corner |
-
-## Custom Style Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Unique style identifier (kebab-case) |
-| `description` | Yes | What the style conveys |
-| `color_palette.primary` | No | Main colors (array) |
-| `color_palette.background` | No | Background color |
-| `color_palette.accents` | No | Accent colors (array) |
-| `visual_elements` | No | Decorative elements |
-| `typography` | No | Font/lettering style |
-| `best_for` | No | Recommended content types |
-
-## Example: Minimal Preferences
-
-```yaml
---
-version: 1
-watermark:
-  enabled: true
-  content: "@myusername"
-preferred_style:
-  name: notion
---
-```
-
-## Example: Full Preferences
-
-```yaml
---
-version: 1
-watermark:
-  enabled: true
-  content: "@myxhsaccount"
-  position: bottom-right
-
-preferred_style:
-  name: notion
-  description: "Clean knowledge cards for tech content"
-
-preferred_layout: dense
-
-language: zh
-
-preferred_image_backend: codex-imagegen
-
-generation_batch_size: 4
-
-custom_styles:
-  - name: corporate
-    description: "Professional B2B style"
-    color_palette:
-      primary: ["#1E3A5F", "#4A90D9"]
-      background: "#F5F7FA"
-      accents: ["#00B4D8", "#48CAE4"]
-    visual_elements: "Clean lines, subtle gradients, geometric shapes"
-    typography: "Modern sans-serif, professional"
-    best_for: "Business, SaaS, enterprise"
---
-```
@@ -1,62 +0,0 @@
---
-name: watermark-guide
-description: Watermark configuration guide for baoyu-xhs-images
---
-
-# Watermark Guide
-
-## Position Diagram
-
-```
-┌─────────────────────────────┐
-│                  [top-right]│
-│                             │
-│                             │
-│         IMAGE CONTENT       │
-│                             │
-│                             │
-│[bottom-left][bottom-center][bottom-right]│
-└─────────────────────────────┘
-```
-
-## Position Recommendations
-
-| Position | Best For | Avoid When |
-|----------|----------|------------|
-| `bottom-right` | Default choice, most common | Key info in bottom-right |
-| `bottom-left` | Right-heavy layouts | Key info in bottom-left |
-| `bottom-center` | Centered designs | Text-heavy bottom area |
-| `top-right` | Bottom-heavy content | Title/header in top-right |
-
-## Content Format
-
-| Format | Example | Style |
-|--------|---------|-------|
-| Handle | `@username` | Most common for XHS |
-| Text | `MyBrand` | Simple branding |
-| Chinese | `小红书:用户名` | Platform specific |
-| URL | `myblog.com` | Cross-platform |
-
-## Best Practices
-
-1. **Consistency**: Use same watermark across all images in series
-2. **Legibility**: Ensure watermark readable on both light/dark areas
-3. **Size**: Keep subtle - should not distract from content
-
-## Prompt Integration
-
-When watermark is enabled, add to image generation prompt:
-
-```
-Include a subtle watermark "[content]" positioned at [position].
-The watermark should be legible but not distracting from the main content.
-```
-
-## Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| Watermark invisible | Adjust position or check contrast |
-| Watermark too prominent | Change position or reduce size |
-| Watermark overlaps content | Change position |
-| Inconsistent across images | Use session ID for consistency |
@@ -1,156 +0,0 @@
-# Confirmation Questions
-
-Concrete option copy for Step 2 Smart Confirm. SKILL.md states which question to ask and when — this file supplies the verbatim options used in Claude Code. Other runtimes should adapt the wording to their native user-input tool while preserving intent.
-
-## Step 2 — Smart Confirm Entry
-
-Single-question confirmation presented right after the auto-recommended plan.
-
-```yaml
-header: Mode
-question: How to proceed with the recommended plan?
-options:
-  - label: 1. ✅ 确认，直接生成（推荐）
-    description: Trust auto-recommendation and proceed immediately
-  - label: 2. 🎛️ 自定义调整
-    description: Modify strategy/style/layout/count in one step
-  - label: 3. 📋 详细模式
-    description: Generate 3 outline variants, then choose (two confirmations)
-```
-
-## Path B — Customize (Option 2)
-
-Batch these five questions. Leaving a field blank keeps the recommended value.
-
-```yaml
-header: Style/Strategy
-question: "Strategy + style. Current: {strategy} + {style}"
-hint: |
-  Strategies: A Story-Driven (warm) | B Information-Dense (notion) | C Visual-First (screen-print)
-  Styles: cute / fresh / warm / bold / minimal / retro / pop / notion / chalkboard / study-notes / screen-print / sketch-notes
-  Presets: knowledge-card / checklist / tutorial / poster / hand-drawn-edu / ...
-```
-
-```yaml
-header: Layout
-question: "Layout. Current: {layout}"
-options: [sparse, balanced, dense, list, comparison, flow, mindmap, quadrant]
-```
-
-```yaml
-header: Palette
-question: "Palette. Current: {palette or 默认}"
-options: [默认, macaron, warm, neon]
-```
-
-```yaml
-header: Count
-question: "Image count. Current: {N}"
-hint: Range 2-10
-```
-
-```yaml
-header: Notes
-question: Optional notes (selling-point emphasis, audience adjustment, color preference)
-optional: true
-```
-
-## Path C — Detailed Mode
-
-### Step 2a: Content Understanding
-
-Batch these questions.
-
-```yaml
-header: SellingPoints
-question: Core selling points (pick all that apply)
-multiSelect: true
-```
-
-```yaml
-header: Audience
-question: Target audience
-```
-
-```yaml
-header: Tone
-question: Style preference
-options:
-  - label: Authentic sharing
-  - label: Professional review
-  - label: Aesthetic mood
-  - label: Auto
-```
-
-```yaml
-header: Context
-question: Additional context (optional)
-optional: true
-```
-
-### Step 2c: Outline & Style Selection
-
-Batch these three questions.
-
-```yaml
-header: Strategy
-question: Which outline strategy?
-options:
-  - label: A — Story-Driven
-  - label: B — Information-Dense
-  - label: C — Visual-First
-  - label: Combine (specify pages from each)
-```
-
-```yaml
-header: Style
-question: Visual style?
-options:
-  - label: Use recommended
-  - label: Select preset
-  - label: Select style directly
-  - label: Custom description
-```
-
-```yaml
-header: Elements
-question: Visual elements?
-options:
-  - label: Use defaults (Recommended)
-  - label: Adjust background
-  - label: Adjust decorations
-  - label: Custom
-```
-
-## Outline Variant Frontmatter
-
-Used by Path C when writing the three `outline-strategy-{a,b,c}.md` files. Each variant MUST have a different structure AND a different recommended style — include `style_reason` explaining why the style fits the strategy.
-
-```yaml
---
-strategy: a  # a | b | c
-name: Story-Driven
-style: warm  # recommended style for this strategy
-palette: ~   # optional: macaron | warm | neon | ~ (style default)
-style_reason: "Warm tones enhance emotional storytelling and personal connection"
-elements:
-  background: solid-pastel
-  decorations: [clouds, stars-sparkles]
-  emphasis: star-burst
-  typography: highlight
-layout: balanced
-image_count: 5
---
-
-## P1 Cover
-**Type**: cover
-**Hook**: "入冬后脸不干了🥹终于找到对的面霜"
-**Visual**: Product hero shot with cozy winter atmosphere
-**Layout**: sparse
-
-## P2 Problem
-**Type**: pain-point
-...
-```
-
-Page-count heuristic: strategy A typically 4-6 pages, B typically 3-5, C typically 3-4.
@@ -1,122 +0,0 @@
-# Canvas & Layout
-
-Core canvas specifications and layout grids for Xiaohongshu infographics.
-
-## Aspect Ratios
-
-| Name | Ratio | Pixels | Note |
-|------|-------|--------|------|
-| portrait-3-4 | 3:4 | 1242×1660 | Highest traffic on XHS (recommended) |
-| square | 1:1 | 1242×1242 | Second recommended |
-| portrait-2-3 | 2:3 | 1242×1863 | Taller format |
-
-**Default**: portrait-3-4 for maximum engagement.
-
-## Safe Zones
-
-Avoid placing critical content in these areas:
-
-| Zone | Position | Reason |
-|------|----------|--------|
-| bottom-overlay | Bottom 10% | Title bar overlay on mobile |
-| top-right | Top-right corner | Like/share button overlay |
-| bottom-right | Bottom-right corner | Watermark position |
-
-```
-┌─────────────────────────────┐
-│                 [like/share]│  ← top-right: avoid
-│                             │
-│                             │
-│      ✓ SAFE CONTENT AREA    │
-│                             │
-│                             │
-│  [title bar overlay area]   │  ← bottom 10%: avoid key info
-└─────────────────────────────┘
-```
-
-## Grid Layouts
-
-### Density-Based Layouts
-
-| Layout | Info Density | Whitespace | Points/Image | Best For |
-|--------|--------------|------------|--------------|----------|
-| sparse | Low | 60-70% | 1-2 | Covers, quotes, impactful statements |
-| balanced | Medium | 40-50% | 3-4 | Standard content, tutorials |
-| dense | High | 20-30% | 5-8 | Knowledge cards, cheat sheets |
-
-### Structure-Based Layouts
-
-| Layout | Structure | Items | Best For |
-|--------|-----------|-------|----------|
-| list | Vertical enumeration | 4-7 | Rankings, checklists, step guides |
-| comparison | Left vs Right | 2 sections | Before/after, pros/cons |
-| flow | Connected nodes | 3-6 steps | Processes, timelines, workflows |
-| mindmap | Center radial | 4-8 branches | Concept maps, brainstorming, topic overview |
-| quadrant | 4-section grid | 4 sections | SWOT analysis, priority matrix, classification |
-
-## Layout by Position
-
-| Position | Recommended Layout | Why |
-|----------|-------------------|-----|
-| Cover | sparse | Maximum visual impact, clear title |
-| Setup | balanced | Context without overwhelming |
-| Core | balanced/dense/list | Based on content density |
-| Payoff | balanced/list | Clear takeaways |
-| Ending | sparse | Clean CTA, memorable close |
-
-## Grid Cells
-
-For multi-element compositions:
-
-| Name | Cells | Use Case |
-|------|-------|----------|
-| single | 1 | Hero image, maximum impact |
-| dual | 2 | Before/after, comparison |
-| triptych | 3 | Steps, process flow |
-| quad | 4 | Product showcase |
-| six-grid | 6 | Checklist, collection |
-| nine-grid | 9 | Multi-image gallery |
-
-## Visual Balance
-
-### Sparse Layout
- Single focal point centered
- Breathing room on all sides
- Symmetrical composition
-
-### Balanced Layout
- Top-weighted title
- Evenly distributed content below
- Clear visual hierarchy
-
-### Dense Layout
- Organized grid structure
- Clear section boundaries
- Compact but readable spacing
-
-### List Layout
- Left-aligned items
- Clear number/bullet hierarchy
- Consistent item format
-
-### Comparison Layout
- Symmetrical left/right
- Clear visual contrast
- Divider between sections
-
-### Flow Layout
- Directional flow (top→bottom or left→right)
- Connected nodes with arrows
- Clear progression indicators
-
-### Mindmap Layout
- Central topic node
- Radial branches outward
- Hierarchical sub-branches
- Organic curved connections
-
-### Quadrant Layout
- 4-section grid (2×2)
- Clear axis labels
- Each quadrant with distinct content
- Optional circular variant for cycles
@@ -1,152 +0,0 @@
-# Decorative Assets
-
-Visual embellishments and decorative elements for Xiaohongshu infographics.
-
-## Emphasis Marks (强调标记)
-
-Elements to draw attention to specific content.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| red-arrow | Red arrow pointing to target | Product features, key points |
-| circle-mark | Circle highlight annotation | Highlighting details |
-| underline | Straight or wavy underline | Text emphasis |
-| star-burst | Starburst explosion effect | Special offers, wow factor |
-| checkmark | Checkmark/tick symbol | Completed items, pros |
-| cross-mark | X mark symbol | Cons, things to avoid |
-| exclamation | Exclamation point decoration | Important warnings |
-| question | Question mark decoration | FAQ, curiosity |
-| numbering | Circled numbers | Steps, rankings |
-| bracket | Bracket highlighting | Grouping, emphasis |
-
-## Backgrounds (背景)
-
-Base layer treatments.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| solid-saturated | High-saturation solid color | Bold, energetic |
-| solid-pastel | Soft pastel solid color | Cute, gentle |
-| gradient-linear | Linear color gradient | Modern, dynamic |
-| gradient-radial | Radial color gradient | Spotlight effect |
-| frosted-glass | Frosted glass blur effect | Layered compositions |
-| paper-texture | Paper or craft texture | Handmade aesthetic |
-| fabric-texture | Fabric/cloth texture | Cozy, tactile |
-| chalkboard | Blackboard texture | Educational content |
-| grid | Subtle grid pattern | Structured, organized |
-| dots | Polka dot pattern | Playful, retro |
-
-## Doodles & Emoji (涂鸦)
-
-Hand-drawn decorative elements.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| hand-drawn-lines | Sketchy hand-drawn lines | Connections, borders |
-| stars-sparkles | Stars and sparkle effects | Magic, excellence |
-| flowers | Floral decorations | Beauty, feminine |
-| hearts | Heart symbols | Love, favorites |
-| clouds | Cloud shapes | Dreamy, thoughts |
-| arrows-curvy | Curved directional arrows | Flow, direction |
-| squiggles | Wavy squiggle lines | Energy, movement |
-| confetti | Scattered confetti | Celebration |
-| leaves | Leaf decorations | Nature, fresh |
-| bubbles | Circular bubble shapes | Playful, light |
-
-## Emoji Integration
-
-| Category | Examples | Use Case |
-|----------|----------|----------|
-| Reactions | 🥹 😍 🤯 | Emotional emphasis |
-| Objects | ✨ 💡 🎯 | Visual markers |
-| Actions | 👇 👆 ➡️ | Directional cues |
-| Nature | 🌸 🌿 ☀️ | Thematic decoration |
-
-## Frames (边框)
-
-Container and border treatments.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| polaroid | Instant photo frame | Photo showcase |
-| film-strip | Film negative border | Cinematic, retro |
-| phone-screenshot | Mobile device mockup | App/screen content |
-| torn-paper | Torn paper edge effect | Scrapbook aesthetic |
-| rounded-rect | Rounded rectangle border | Clean containers |
-| decorative | Ornate decorative border | Premium, elegant |
-| tape-corners | Washi tape corners | Crafty, casual |
-| stamp-border | Stamp perforated edge | Vintage, postal |
-
-## Dividers (分隔线)
-
-Section separators.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| line-simple | Simple horizontal line | Clean separation |
-| line-dashed | Dashed line | Subtle division |
-| line-wavy | Wavy line | Playful separation |
-| dots-row | Row of dots | Decorative division |
-| ornamental | Decorative flourish | Elegant separation |
-
-## Stickers (贴纸)
-
-Pre-composed decorative elements.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| badge-new | "NEW" badge | New products |
-| badge-hot | "HOT" badge | Trending items |
-| badge-sale | Sale/discount badge | Promotions |
-| seal-quality | Quality seal | Recommendations |
-| ribbon-award | Award ribbon | Best picks |
-| tag-price | Price tag shape | Pricing info |
-
-## Style-Specific Decorations
-
-### Cute Style
- Hearts, stars, sparkles
- Ribbon decorations, sticker-style
- Cute character elements
-
-### Notion Style
- Simple line doodles
- Geometric shapes, stick figures
- Maximum whitespace, minimal decoration
-
-### Warm Style
- Sun rays, coffee cups, cozy items
- Warm lighting effects
- Friendly, inviting decorations
-
-### Fresh Style
- Plant leaves, clouds, water drops
- Simple geometric shapes
- Open, breathing composition
-
-### Bold Style
- Exclamation marks, arrows
- Warning icons, strong shapes
- High contrast elements
-
-### Pop Style
- Bold shapes, speech bubbles
- Comic-style effects, starburst
- Dynamic, energetic decorations
-
-### Retro Style
- Halftone dots, vintage badges
- Classic icons, tape effects
- Aged texture overlays
-
-### Chalkboard Style
- Chalk dust effects
- Hand-drawn doodles
- Mathematical formulas, simple icons
-
-### Screen-Print Style
- Bold silhouettes, geometric shapes
- Halftone dot patterns, print grain
- No doodles — negative space does the work
- Stencil-cut edges, color block boundaries
- Vintage poster border treatments
@@ -1,92 +0,0 @@
-# Image Processing Layer
-
-Visual effects applied to image elements in Xiaohongshu infographics.
-
-## AI Cutout (抠图)
-
-Subject extraction styles for product/figure isolation.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| clean | Sharp edges, precise boundaries | Product photography, tech items |
-| soft | Soft transition, feathered edges | Portrait cutout, organic subjects |
-| stylized | Hand-drawn edge treatment | Artistic compositions |
-
-## Stroke Effects (描边)
-
-Border treatments for cutout elements.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| white-solid | White solid line border | Classic sticker feel, high contrast |
-| colored-solid | Colored solid line border | Playful vibe, brand colors |
-| dashed | Dashed/dotted border | Handmade aesthetic, casual |
-| double | Double-layer stroke | Emphasis effect, premium feel |
-| glow | Soft outer glow | Dreamy, soft aesthetic |
-| shadow | Drop shadow effect | Depth, floating element |
-
-**Stroke Width Guidelines**:
- Thin: 2-4px - Subtle, elegant
- Medium: 5-8px - Standard visibility
- Thick: 10-15px - Bold emphasis
-
-## Filters (滤镜)
-
-Color grading and mood presets popular on XHS.
-
-| Name | Chinese | Description | Mood |
-|------|---------|-------------|------|
-| clear-glow | 清透感 | Transparent, radiant, luminous | Fresh, youthful |
-| film-grain | 胶片感 | Vintage film aesthetic, grain texture | Nostalgic, artistic |
-| cream-skin | 奶油肌 | Smooth, creamy complexion tones | Soft, flattering |
-| japanese-magazine | 日杂感 | Lifestyle magazine aesthetic | Curated, aspirational |
-| high-saturation | 高饱和 | Vibrant, punchy colors | Energetic, eye-catching |
-| muted-tones | 莫兰迪 | Morandi-style desaturated palette | Sophisticated, calm |
-| warm-tone | 暖色调 | Golden hour warmth | Cozy, inviting |
-| cool-tone | 冷色调 | Blue-shifted coolness | Modern, clean |
-
-## Texture Overlays
-
-Additional texture effects.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| paper | Paper or fabric texture | Handmade feel |
-| noise | Fine grain noise | Analog aesthetic |
-| halftone | Dot pattern | Retro print style |
-| scratch | Light scratch marks | Vintage wear |
-
-## Blending Modes
-
-For layered compositions.
-
-| Mode | Effect | Use Case |
-|------|--------|----------|
-| multiply | Darken, merge | Shadow effects |
-| screen | Lighten, glow | Light effects |
-| overlay | Contrast boost | Vibrant compositions |
-| soft-light | Subtle blending | Natural layering |
-
-## Effect Combinations
-
-Common effect stacks for different styles:
-
-### Cute Style
- Filter: clear-glow or cream-skin
- Stroke: white-solid (medium)
- Texture: none
-
-### Notion Style
- Filter: none or muted-tones
- Stroke: white-solid (thin) or none
- Texture: paper (subtle)
-
-### Retro Style
- Filter: film-grain
- Stroke: double or dashed
- Texture: halftone, scratch
-
-### Bold Style
- Filter: high-saturation
- Stroke: colored-solid (thick)
- Texture: none
@@ -1,96 +0,0 @@
-# Typography System
-
-Text styling elements for Xiaohongshu infographics.
-
-## Decorated Text (花字)
-
-Stylized text treatments for emphasis and visual appeal.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| gradient | Gradient color fill | Title emphasis, modern feel |
-| stroke-text | Outlined text with stroke | Cover headlines, high visibility |
-| shadow-3d | 3D shadow/extrusion effect | Key terms, depth |
-| highlight | Highlighter marker effect | Critical information, key points |
-| neon | Neon glow effect | Tech content, night aesthetic |
-| handwritten | Authentic handwritten style | Personal touch, casual |
-| bubble | Rounded, inflated letterforms | Cute, playful content |
-| brush | Brush stroke texture | Artistic, dynamic |
-
-## Tags & Labels (标签)
-
-Structured text containers.
-
-| Name | Description | Use Case |
-|------|-------------|----------|
-| black-white | Black background, white text | Brand names, prices, categories |
-| white-black | White background, black text | Clean labels, minimal style |
-| bubble | Speech bubble style | Dialogue, annotations, callouts |
-| pointer | Arrow pointer with label | Product callouts, pointing to features |
-| ribbon | Ribbon/banner shape | Special offers, highlights |
-| stamp | Stamp/seal style | Authenticity, recommendations |
-| pill | Rounded pill shape | Tags, categories, keywords |
-
-## Text Hierarchy
-
-Recommended text sizing for visual hierarchy.
-
-| Level | Role | Relative Size | Style |
-|-------|------|---------------|-------|
-| H1 | Main title | 100% | Bold, decorated |
-| H2 | Section header | 70-80% | Semi-bold |
-| H3 | Subsection | 50-60% | Medium weight |
-| Body | Content text | 40-50% | Regular |
-| Caption | Small notes | 30-35% | Light |
-
-## Text Direction
-
-| Direction | Description | Use Case |
-|-----------|-------------|----------|
-| horizontal | Standard left-to-right | Default for most content |
-| vertical | Top-to-bottom columns | Magazine style, traditional Chinese |
-| curved | Text following a curve | Decorative, around shapes |
-| diagonal | Angled text | Dynamic compositions |
-
-## Text Effects
-
-| Effect | Description | Use Case |
-|--------|-------------|----------|
-| shadow | Drop shadow behind text | Readability on busy backgrounds |
-| outline | Outline around letterforms | High contrast visibility |
-| glow | Soft glow around text | Dreamy, emphasis |
-| underline-wavy | Wavy underline decoration | Playful emphasis |
-| strikethrough | Crossed out text | Before/after, corrections |
-
-## Language Considerations
-
-### Chinese Text (中文)
- Punctuation: 「」（）、。！？
- Spacing: No spaces between characters
- Line height: 1.5-1.8x for readability
-
-### Mixed Text
- English in Chinese context: Maintain consistent baseline
- Numbers: Use consistent number style (lining vs old-style)
-
-## Style-Specific Typography
-
-### Cute Style
- Rounded, bubbly hand lettering
- Soft shadows, playful decorations
- Pink/pastel color accents
-
-### Notion Style
- Clean hand-drawn lettering
- Simple sans-serif labels
- Minimal decoration
-
-### Bold Style
- Impactful hand lettering with shadows
- High contrast colors
- Strong outlines
-
-### Chalkboard Style
- Chalk texture on all text
- Visible imperfections
- Multi-color chalk variety
@@ -1,33 +0,0 @@
-# Macaron Palette
-
-Soft pastel color blocks on warm cream background. Gentle, approachable, educational feel.
-
-## Background
-
- Color: Warm cream (#F5F0E8)
- Texture: Subtle paper grain, warm tone
-
-## Colors
-
-| Role | Color | Hex | Usage |
-|------|-------|-----|-------|
-| Background | Warm Cream | #F5F0E8 | Primary background |
-| Text | Deep Charcoal | #2C3E50 | Titles, main content |
-| Secondary Text | Warm Gray | #6B6B6B | Annotations, labels |
-| Block Color | Macaron Blue | #A8D8EA | Content block fill |
-| Block Color | Macaron Lavender | #D5C6E0 | Content block fill |
-| Block Color | Macaron Mint | #B5E5CF | Content block fill |
-| Block Color | Macaron Peach | #F8D5C4 | Content block fill |
-| Accent | Coral Red | #E8655A | Emphasis, highlights |
-
-## Semantic Constraint
-
-Soft pastel macaron color palette. Use block colors as rounded card backgrounds for distinct information sections. Accent coral red sparingly for emphasis on key terms only. All colors should feel gentle and approachable — no saturated or neon tones. Do NOT render color names or role labels as visible text in the image.
-
-## Best Paired With
-
- `sketch-notes` — natural pairing for hand-drawn educational content
- `notion` — macaron accents soften the monochrome aesthetic
- `chalkboard` — pastel chalk tones replace standard chalk colors
- `warm` — reinforces the cozy, friendly feel
- `fresh` — complements the clean, natural aesthetic
@@ -1,32 +0,0 @@
-# Neon Palette
-
-Vibrant neon colors on dark background. High-energy, futuristic, eye-catching.
-
-## Background
-
- Color: Dark Purple (#1A1025)
- Texture: Smooth, deep
-
-## Colors
-
-| Role | Color | Hex | Usage |
-|------|-------|-----|-------|
-| Background | Dark Purple | #1A1025 | Primary background |
-| Text | Bright White | #F0F0F0 | Titles, main content |
-| Secondary Text | Light Lavender | #B8B8D4 | Annotations, labels |
-| Block Color | Neon Cyan | #00F5FF | Content block fill |
-| Block Color | Neon Magenta | #FF00FF | Content block fill |
-| Block Color | Neon Green | #39FF14 | Content block fill |
-| Block Color | Neon Pink | #FF6EC7 | Content block fill |
-| Accent | Electric Yellow | #FFFF00 | Emphasis, highlights |
-
-## Semantic Constraint
-
-Vibrant neon color palette on dark background. Colors should glow against the dark base. High contrast, futuristic feel. Use neon sparingly — too many glowing elements become chaotic. Let dark background breathe. Do NOT render color names, hex codes, or role labels as visible text in the image.
-
-## Best Paired With
-
- `bold` — amplifies high-impact energy
- `pop` — neon takes the vibrancy further
- `minimal` — neon accents on dark create striking contrast
- `notion` — futuristic knowledge card aesthetic
@@ -1,32 +0,0 @@
-# Warm Palette
-
-Warm earth tones on soft peach background. Cozy, inviting, no cool colors.
-
-## Background
-
- Color: Soft Peach (#FFECD2)
- Texture: Warm, slightly textured
-
-## Colors
-
-| Role | Color | Hex | Usage |
-|------|-------|-----|-------|
-| Background | Soft Peach | #FFECD2 | Primary background |
-| Text | Deep Brown | #744210 | Titles, main content |
-| Secondary Text | Warm Brown | #9C6644 | Annotations, labels |
-| Block Color | Warm Orange | #ED8936 | Content block fill |
-| Block Color | Terracotta | #C05621 | Content block fill |
-| Block Color | Golden Yellow | #F6AD55 | Content block fill |
-| Block Color | Dusty Rose | #D4A09A | Content block fill |
-| Accent | Burnt Sienna | #A0522D | Emphasis, highlights |
-
-## Semantic Constraint
-
-Warm-only color palette, no cool colors (no blue, green, purple). Earth tones throughout. Evokes comfort, warmth, and trust. All colors should feel like autumn sunlight. Do NOT render color names, hex codes, or role labels as visible text in the image.
-
-## Best Paired With
-
- `warm` — natural pairing, amplifies cozy feel
- `cute` — warm pastels enhance the sweet aesthetic
- `retro` — earth tones complement vintage style
- `sketch-notes` — warm educational feel
@@ -1,72 +0,0 @@
---
-name: bold
-category: impact
---
-
-# Bold Style
-
-High impact, attention-grabbing aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: clean
-  stroke: colored-solid | double
-  filter: high-saturation
-
-typography:
-  decorated: shadow-3d | stroke-text
-  tags: black-white | ribbon
-  direction: horizontal | diagonal
-
-decorations:
-  emphasis: exclamation | star-burst | red-arrow
-  background: solid-saturated | gradient-linear
-  doodles: arrows-curvy | squiggles
-  frames: none
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Vibrant red, orange, yellow | #E53E3E, #DD6B20, #F6E05E |
-| Background | Deep black, dark charcoal | #000000, #1A1A1A |
-| Accents | White, neon yellow | #FFFFFF, #F7FF00 |
-
-## Visual Elements
-
- Exclamation marks, arrows, warning icons
- Strong shapes, high contrast elements
- Dramatic compositions
- Bold geometric forms
-
-## Typography
-
- Bold, impactful hand lettering with shadows
- High contrast text treatments
- Large, commanding headlines
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Impactful statements |
-| balanced | ✓ | Warning content |
-| dense | ✓ | Critical information cards |
-| list | ✓✓ | Must-know lists, rankings |
-| comparison | ✓✓ | Dramatic contrasts |
-| flow | ✓ | Critical process steps |
-
-## Best For
-
- Important tips and warnings
- Must-know content
- Critical announcements
- Rankings and comparisons
- Attention-grabbing hooks
@@ -1,97 +0,0 @@
---
-name: chalkboard
-category: educational
---
-
-# Chalkboard Style
-
-Black chalkboard background with colorful chalk drawing aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual | triptych
-
-image_effects:
-  cutout: stylized
-  stroke: none
-  filter: none
-
-typography:
-  decorated: handwritten
-  tags: none
-  direction: horizontal | vertical
-
-decorations:
-  emphasis: underline | circle-mark | arrows-curvy
-  background: chalkboard
-  doodles: hand-drawn-lines | stars-sparkles
-  frames: none
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Background | Chalkboard black, green-black | #1A1A1A, #1C2B1C |
-| Primary Text | Chalk white | #F5F5F5 |
-| Accent 1 | Chalk yellow | #FFE566 |
-| Accent 2 | Chalk pink | #FF9999 |
-| Accent 3 | Chalk blue | #66B3FF |
-| Accent 4 | Chalk green | #90EE90 |
-| Accent 5 | Chalk orange | #FFB366 |
-
-## Visual Elements
-
- Hand-drawn chalk illustrations with sketchy, imperfect lines
- Chalk dust effects around text and key elements
- Doodles: stars, arrows, underlines, circles, checkmarks
- Mathematical formulas and simple diagrams
- Eraser smudges and chalk residue textures
- Stick figures and simple icons
- Connection lines with hand-drawn feel
-
-## Typography
-
- Hand-drawn chalk lettering style
- Visible chalk texture on all text
- Imperfect baseline adds authenticity
- White or bright colored chalk for emphasis
-
-## Style Rules
-
-### Do
- Maintain authentic chalk texture on all elements
- Use imperfect, hand-drawn quality throughout
- Add subtle chalk dust and smudge effects
- Create visual hierarchy with color variety
- Include playful doodles and annotations
-
-### Don't
- Use perfect geometric shapes
- Create clean digital-looking lines
- Add photorealistic elements
- Use gradients or glossy effects
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Educational covers |
-| balanced | ✓✓ | Standard lessons |
-| dense | ✓✓ | Detailed tutorials |
-| list | ✓✓ | Learning checklists |
-| comparison | ✓ | Concept comparisons |
-| flow | ✓✓ | Process explanations |
-
-## Best For
-
- Educational content
- Tutorials and how-to's
- Classroom themes
- Teaching materials
- Workshops
- Informal learning sessions
- Knowledge sharing
@@ -1,72 +0,0 @@
---
-name: cute
-category: sweet
---
-
-# Cute Style
-
-Sweet, adorable, girly - classic Xiaohongshu aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual | quad
-
-image_effects:
-  cutout: soft
-  stroke: white-solid | colored-solid
-  filter: clear-glow | cream-skin
-
-typography:
-  decorated: bubble | highlight
-  tags: pill | bubble
-  direction: horizontal
-
-decorations:
-  emphasis: star-burst | hearts
-  background: solid-pastel | gradient-linear
-  doodles: hearts | stars-sparkles | flowers
-  frames: polaroid | tape-corners
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Pink, peach, mint, lavender | #FED7E2, #FEEBC8, #C6F6D5, #E9D8FD |
-| Background | Cream, soft pink | #FFFAF0, #FFF5F7 |
-| Accents | Hot pink, coral | #FF69B4, #FF6B6B |
-
-## Visual Elements
-
- Hearts, stars, sparkles, cute faces
- Ribbon decorations, sticker-style
- Cute stickers, emoji icons
- Soft, rounded shapes
-
-## Typography
-
- Rounded, bubbly hand lettering
- Soft shadows, playful decorations
- Pink/pastel color accents on text
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Covers, emotional impact |
-| balanced | ✓✓ | Standard cute content |
-| dense | ✓ | Cute knowledge cards |
-| list | ✓✓ | Checklists, cute rankings |
-| comparison | ✓ | Before/after transformations |
-| flow | ✓ | Cute step guides |
-
-## Best For
-
- Lifestyle content
- Beauty and skincare
- Fashion and style
- Daily tips and hacks
- Personal shares
@@ -1,72 +0,0 @@
---
-name: fresh
-category: natural
---
-
-# Fresh Style
-
-Clean, refreshing, natural aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | triptych
-
-image_effects:
-  cutout: soft
-  stroke: white-solid | none
-  filter: clear-glow | cool-tone
-
-typography:
-  decorated: none | highlight
-  tags: pill | white-black
-  direction: horizontal
-
-decorations:
-  emphasis: checkmark | circle-mark
-  background: solid-white | solid-pastel
-  doodles: leaves | clouds | bubbles
-  frames: rounded-rect | none
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Mint green, sky blue, light yellow | #9AE6B4, #90CDF4, #FAF089 |
-| Background | Pure white, soft mint | #FFFFFF, #F0FFF4 |
-| Accents | Leaf green, water blue | #48BB78, #4299E1 |
-
-## Visual Elements
-
- Plant leaves, clouds, water drops
- Simple geometric shapes
- Breathing room, open composition
- Natural, organic elements
-
-## Typography
-
- Clean, light hand lettering with breathing room
- Airy spacing
- Fresh color accents
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Clean covers |
-| balanced | ✓✓ | Standard fresh content |
-| dense | ✓ | Organized information |
-| list | ✓ | Wellness tips |
-| comparison | ✓ | Before/after health |
-| flow | ✓✓ | Organic processes |
-
-## Best For
-
- Health and wellness
- Minimalist lifestyle
- Self-care content
- Nature-related topics
- Clean living tips
@@ -1,72 +0,0 @@
---
-name: minimal
-category: elegant
---
-
-# Minimal Style
-
-Ultra-clean, sophisticated aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single
-
-image_effects:
-  cutout: clean
-  stroke: none | white-solid
-  filter: none | muted-tones
-
-typography:
-  decorated: none
-  tags: white-black | pill
-  direction: horizontal
-
-decorations:
-  emphasis: underline | circle-mark
-  background: solid-white | solid-pastel
-  doodles: hand-drawn-lines
-  frames: none | rounded-rect
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Black, white | #000000, #FFFFFF |
-| Background | Off-white, pure white | #FAFAFA, #FFFFFF |
-| Accents | Single color (content-derived) | Blue, green, or coral |
-
-## Visual Elements
-
- Single focal point, thin lines
- Maximum whitespace
- Simple, clean decorations
- Restrained visual elements
-
-## Typography
-
- Clean, simple hand lettering
- Minimal weight variations
- Elegant spacing
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Elegant statements |
-| balanced | ✓✓ | Professional content |
-| dense | ✓✓ | Clean knowledge cards |
-| list | ✓ | Simple lists |
-| comparison | ✓ | Clean comparisons |
-| flow | ✓ | Elegant processes |
-
-## Best For
-
- Professional content
- Serious topics
- Elegant presentations
- High-end products
- Business content
@@ -1,73 +0,0 @@
---
-name: notion
-category: minimal
---
-
-# Notion Style
-
-Minimalist hand-drawn line art, intellectual aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: clean
-  stroke: none | white-solid
-  filter: none | muted-tones
-
-typography:
-  decorated: none | handwritten
-  tags: black-white | pill
-  direction: horizontal
-
-decorations:
-  emphasis: circle-mark | underline
-  background: solid-white | paper-texture
-  doodles: hand-drawn-lines | arrows-curvy
-  frames: none | rounded-rect
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Black, dark gray | #1A1A1A, #4A4A4A |
-| Background | Pure white, off-white | #FFFFFF, #FAFAFA |
-| Accents | Pastel blue, pastel yellow, pastel pink | #A8D4F0, #F9E79F, #FADBD8 |
-
-## Visual Elements
-
- Simple line doodles, hand-drawn wobble effect
- Geometric shapes, stick figures
- Maximum whitespace, single-weight ink lines
- Clean, uncluttered compositions
-
-## Typography
-
- Clean hand-drawn lettering
- Simple sans-serif labels
- Minimal decoration on text
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Concept covers |
-| balanced | ✓✓ | Standard explanations |
-| dense | ✓✓ | Knowledge cards, cheat sheets |
-| list | ✓✓ | Productivity tips, tool lists |
-| comparison | ✓✓ | Data comparisons |
-| flow | ✓✓ | Process diagrams |
-
-## Best For
-
- Knowledge sharing
- Concept explanations
- SaaS content
- Productivity tips
- Tech tutorials
- Professional content
@@ -1,72 +0,0 @@
---
-name: pop
-category: energetic
---
-
-# Pop Style
-
-Vibrant, energetic, eye-catching aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | quad
-
-image_effects:
-  cutout: stylized
-  stroke: colored-solid | double
-  filter: high-saturation
-
-typography:
-  decorated: stroke-text | shadow-3d
-  tags: bubble | ribbon
-  direction: horizontal | curved
-
-decorations:
-  emphasis: star-burst | exclamation
-  background: solid-saturated | dots
-  doodles: stars-sparkles | confetti | squiggles
-  frames: none
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Bright red, yellow, blue, green | #F56565, #ECC94B, #4299E1, #48BB78 |
-| Background | White, light gray | #FFFFFF, #F7FAFC |
-| Accents | Neon pink, electric purple | #FF69B4, #9F7AEA |
-
-## Visual Elements
-
- Bold shapes, speech bubbles
- Comic-style effects, starburst
- Dynamic, energetic compositions
- High-energy decorations
-
-## Typography
-
- Dynamic, energetic hand lettering with outlines
- Bold color combinations
- Playful, expressive forms
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Exciting announcements |
-| balanced | ✓✓ | Fun tutorials |
-| dense | ✓ | Packed information |
-| list | ✓✓ | Fun facts lists |
-| comparison | ✓✓ | Dynamic comparisons |
-| flow | ✓ | Energetic processes |
-
-## Best For
-
- Exciting announcements
- Fun facts
- Engaging tutorials
- Entertainment content
- Youth-oriented content
@@ -1,72 +0,0 @@
---
-name: retro
-category: vintage
---
-
-# Retro Style
-
-Vintage, nostalgic, trendy aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: stylized
-  stroke: dashed | double
-  filter: film-grain | muted-tones
-
-typography:
-  decorated: brush | handwritten
-  tags: stamp | ribbon
-  direction: horizontal
-
-decorations:
-  emphasis: star-burst | numbering
-  background: paper-texture | dots
-  doodles: stars-sparkles | squiggles
-  frames: polaroid | film-strip | stamp-border
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Muted orange, dusty pink, faded teal | #E07A4D, #D4A5A5, #6B9999 |
-| Background | Aged paper, sepia tones | #F5E6D3, #E8DCC8 |
-| Accents | Faded red, vintage gold | #C55A5A, #B8860B |
-
-## Visual Elements
-
- Halftone dots, vintage badges
- Classic icons, tape effects
- Aged texture overlays
- Nostalgic decorative elements
-
-## Typography
-
- Vintage-style hand lettering
- Classic feel with imperfections
- Aged texture on text
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Vintage covers |
-| balanced | ✓✓ | Classic content |
-| dense | ✓ | Vintage knowledge cards |
-| list | ✓✓ | Classic rankings |
-| comparison | ✓ | Then vs now |
-| flow | ✓ | Historical timelines |
-
-## Best For
-
- Throwback content
- Classic tips
- Timeless advice
- Vintage aesthetics
- Nostalgic shares
@@ -1,92 +0,0 @@
---
-name: screen-print
-category: poster
---
-
-# Screen-Print Style
-
-Bold poster art with halftone textures, limited colors, and symbolic storytelling.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: silhouette
-  stroke: none
-  filter: halftone | print-grain
-
-typography:
-  decorated: stroke-text | shadow-3d
-  tags: none
-  direction: horizontal
-
-decorations:
-  emphasis: star-burst | numbering
-  background: solid-saturated | paper-texture
-  doodles: none
-  frames: none
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Burnt Orange, Deep Teal | #E8751A, #0A6E6E |
-| Background | Off-Black, Warm Cream | #121212, #F5E6D0 |
-| Accents | Crimson, Amber | #C0392B, #F4A623 |
-
-**Duotone Pairs** (choose ONE based on content mood):
-
-| Pair | Color A | Color B | Feel |
-|------|---------|---------|------|
-| Orange + Teal | #E8751A | #0A6E6E | Cinematic, action |
-| Red + Cream | #C0392B | #F5E6D0 | Bold, classic |
-| Blue + Gold | #1A3A5C | #D4A843 | Premium, prestigious |
-| Crimson + Navy | #DC143C | #0D1B2A | Dramatic, noir |
-| Magenta + Cyan | #C2185B | #00BCD4 | Vibrant, pop |
-
-**Rule**: Use 2-5 colors maximum. Fewer colors = stronger impact.
-
-## Visual Elements
-
- Bold silhouettes and symbolic shapes
- Halftone dot patterns within color fills
- Slight color layer misregistration (print offset effect)
- Geometric framing (circles, arches, triangles)
- Figure-ground inversion (negative space tells secondary story)
- Stencil-cut edges, no outlines — shapes defined by color boundaries
- Typography integrated as design element, not overlay
- Vintage poster border treatments
-
-## Typography
-
- Bold condensed sans-serif or hand-drawn lettering
- Art Deco influences, vintage poster typography
- Typography as integral part of composition (not separate layer)
- High contrast with background for readability
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Iconic poster covers, dramatic statements |
-| balanced | ✓✓ | Editorial compositions, opinion pieces |
-| dense | ✗ | Too much info clashes with minimal poster aesthetic |
-| list | ✓ | Bold rankings, top picks |
-| comparison | ✓✓ | Duotone split compositions, before/after |
-| flow | ✓ | Cinematic progression, timelines |
-| mindmap | ✗ | Too complex for geometric poster style |
-| quadrant | ✓✓ | Strong geometric division, classification |
-
-## Best For
-
- Opinion pieces, cultural commentary
- Movie/music/book recommendations
- Dramatic announcements
- Before/after transformations
- Bold editorial content
- Event promotions
@@ -1,100 +0,0 @@
---
-name: sketch-notes
-category: educational
-default_palette: macaron
---
-
-# Sketch Notes Style
-
-Hand-drawn educational infographic with slight line wobble, like a high-quality presentation visual summary.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: stylized
-  stroke: none
-  filter: none
-
-typography:
-  decorated: handwritten
-  tags: rounded-badge
-  direction: horizontal
-
-decorations:
-  emphasis: underline | circle-mark | arrows-curvy | star-burst
-  background: paper-texture
-  doodles: hand-drawn-lines | stars-sparkles | arrows-curvy | squiggles
-  frames: rounded-rect
-```
-
-## Color Palette
-
-Default: **macaron** palette (see `palettes/macaron.md`)
-
-When no `--palette` is specified, uses macaron colors: warm cream background (#F5F0E8), macaron blue/lavender/mint/peach zone blocks, coral red accent.
-
-## Visual Elements
-
- Hand-drawn wobble on all lines and shapes
- Simple stick-figure characters at desks, working, thinking
- Rounded cards with pastel color blocks as information sections
- Color fills do NOT completely fill outlines (hand-painted feel)
- Doodle decorations: small stars, underlines, checkmarks, lock icons, clipboard icons
- Wavy hand-drawn arrows connecting zones with small text labels
- Thought bubbles and speech bubbles with sketchy outlines
- Simple conceptual icons (documents, lightbulbs, gears, arrows)
- Generous whitespace between zones for clean composition
-
-## Typography
-
- Bold hand-drawn lettering for titles (large, prominent)
- Bold keywords within content zones
- Smaller annotations in secondary text color
- Hand-drawn quality on ALL text, no computer-generated fonts
- Clear information hierarchy: title > zone labels > body text > annotations
-
-## Style Rules
-
-### Do
- Maintain slight wobble on every line, shape, and border
- Use palette block colors as distinct section backgrounds
- Leave color fills intentionally incomplete at edges
- Include simple doodle icons relevant to content
- Keep generous whitespace between zones
- Use accent color sparingly for emphasis on key terms
- Draw connecting arrows with hand-drawn wavy feel
-
-### Don't
- Use perfect geometric shapes or straight lines
- Create photorealistic elements
- Fill colors completely to edges (maintain hand-painted gap)
- Use dark or saturated backgrounds
- Overcrowd with too many decorative elements
- Use gradient fills or glossy effects
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓ | Simple covers with single zone |
-| balanced | ✓✓ | Standard educational summaries |
-| dense | ✓✓ | Knowledge cards, concept maps |
-| list | ✓✓ | Step-by-step guides, checklists |
-| comparison | ✓ | Side-by-side concept contrast |
-| flow | ✓✓ | Process diagrams, workflows, tutorials |
-| mindmap | ✓✓ | Concept maps, radial knowledge maps |
-| quadrant | ✓ | Classification matrices |
-
-## Best For
-
- Educational content, tutorials, how-to guides
- Process and workflow explanations
- Knowledge summaries, concept diagrams
- Technical explanations made approachable
- Visual summaries of articles or talks
- Onboarding materials, friendly guides
@@ -1,115 +0,0 @@
---
-name: study-notes
-category: realistic
---
-
-# Study Notes Style
-
-Realistic handwritten photo aesthetic - student notes style, dense and messy but readable.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single
-
-image_effects:
-  cutout: none
-  stroke: none
-  filter: natural-photo
-
-typography:
-  decorated: none
-  tags: none
-  direction: horizontal
-
-decorations:
-  emphasis: circle-mark | underline | checkmark | cross | star-simple
-  background: lined-paper-white
-  doodles: arrows-simple | margin-notes | corrections | explanatory-diagrams
-  frames: none
-```
-
-## Color Palette (Three-Color Annotation System)
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Blue ballpoint, Black ink | #1E3A5F, #1A1A1A |
-| Highlights | Yellow highlighter | #FFFF00 (50% opacity) |
-| Accents | Red pen (circles, underlines) | #CC0000 |
-| Background | White lined paper | #FFFFFF |
-
-## Visual Elements
-
- Realistic photo perspective: top-down view of study desk
- Hand holding blue ballpoint pen, actively underlining
- Extremely dense handwritten content, filling entire page
- Red pen annotations: circles, underlines, stars, boxes
- Yellow highlighter marking key terms
- Correction marks, cramped notes squeezed into margins
- Simple hand-drawn symbols: → * ✓ ✗ !
- Varying pen pressure creating lighter and darker strokes
-
-## Typography
-
- Authentic student handwriting
- Messy but readable, clear structure maintained
- Varying font sizes (large titles, small body, tiny margin notes)
- CJK optimized
-
-## Content Structure
-
-Three-section layout:
-
-### Top Section
- Core topic (circled multiple times in red)
- First section title + 3-4 key points
- Arrow connections, red underlines
-
-### Middle Section
- Second section title (red pen box)
- Numbered steps ①②③
- Specific methods and supplementary notes
-
-### Bottom Section
- Third section title (red star)
- Time points / key metrics
- Key quotes / core tips (tiny corner notes)
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✗ | Not suitable - style requires dense content |
-| balanced | ✓ | When content is lighter |
-| dense | ✓✓ | Best fit - knowledge notes, summaries |
-| list | ✓✓ | Step checklists, rankings |
-| comparison | ✓ | Comparative analysis |
-| flow | ✓ | Process flows |
-| mindmap | ✓✓ | Mind map notes |
-| quadrant | ✓ | Quadrant analysis |
-
-## Best For
-
- Study guides, exam notes
- Knowledge organization, framework summaries
- Tutorial summaries, quick notes
- "Top student notes" style content
- Knowledge sharing requiring authentic feel
-
-## Style Rules
-
-### DO ✓
- Keep content extremely dense
- Use simple symbols (→ * ✓ ✗ !)
- Annotate key points with red pen
- Include correction marks
- Squeeze tiny notes into margins
-
-### DON'T ✗
- Use complex emojis
- Leave too much whitespace
- Make neat, tidy layouts
- Add colorful decorations
- Include cartoon elements
@@ -1,72 +0,0 @@
---
-name: warm
-category: cozy
---
-
-# Warm Style
-
-Cozy, friendly, approachable aesthetic.
-
-## Element Combination
-
-```yaml
-canvas:
-  ratio: portrait-3-4
-  grid: single | dual
-
-image_effects:
-  cutout: soft
-  stroke: white-solid | glow
-  filter: warm-tone | cream-skin
-
-typography:
-  decorated: highlight | handwritten
-  tags: ribbon | bubble
-  direction: horizontal
-
-decorations:
-  emphasis: star-burst | hearts
-  background: solid-pastel | gradient-radial
-  doodles: clouds | stars-sparkles
-  frames: polaroid | tape-corners
-```
-
-## Color Palette
-
-| Role | Colors | Hex |
-|------|--------|-----|
-| Primary | Warm orange, golden yellow, terracotta | #ED8936, #F6AD55, #C05621 |
-| Background | Cream, soft peach | #FFFAF0, #FED7AA |
-| Accents | Deep brown, soft red | #744210, #E57373 |
-
-## Visual Elements
-
- Sun rays, coffee cups, cozy items
- Warm lighting effects
- Friendly, inviting decorations
- Soft, comfortable shapes
-
-## Typography
-
- Friendly, rounded hand lettering
- Warm color accents
- Comfortable, approachable feel
-
-## Best Layout Pairings
-
-| Layout | Compatibility | Use Case |
-|--------|---------------|----------|
-| sparse | ✓✓ | Emotional covers |
-| balanced | ✓✓ | Personal stories |
-| dense | ✓ | Detailed experiences |
-| list | ✓ | Life lessons |
-| comparison | ✓✓ | Before/after stories |
-| flow | ✓ | Journey narratives |
-
-## Best For
-
- Personal stories
- Life lessons
- Emotional content
- Comfort and lifestyle
- Heartfelt shares
@@ -1,43 +0,0 @@
-# Style Presets
-
-`--preset X` expands to a style + layout + optional palette combination. Users can override any dimension.
-
-| --preset | Style | Layout | Palette |
-|----------|-------|--------|---------|
-| `knowledge-card` | `notion` | `dense` | |
-| `checklist` | `notion` | `list` | |
-| `concept-map` | `notion` | `mindmap` | |
-| `swot` | `notion` | `quadrant` | |
-| `tutorial` | `chalkboard` | `flow` | |
-| `classroom` | `chalkboard` | `balanced` | |
-| `study-guide` | `study-notes` | `dense` | |
-| `cute-share` | `cute` | `balanced` | |
-| `girly` | `cute` | `sparse` | |
-| `cozy-story` | `warm` | `balanced` | |
-| `product-review` | `fresh` | `comparison` | |
-| `nature-flow` | `fresh` | `flow` | |
-| `warning` | `bold` | `list` | |
-| `versus` | `bold` | `comparison` | |
-| `clean-quote` | `minimal` | `sparse` | |
-| `pro-summary` | `minimal` | `balanced` | |
-| `retro-ranking` | `retro` | `list` | |
-| `throwback` | `retro` | `balanced` | |
-| `pop-facts` | `pop` | `list` | |
-| `hype` | `pop` | `sparse` | |
-| `poster` | `screen-print` | `sparse` | |
-| `editorial` | `screen-print` | `balanced` | |
-| `cinematic` | `screen-print` | `comparison` | |
-| `hand-drawn-edu` | `sketch-notes` | `flow` | `macaron` |
-| `sketch-card` | `sketch-notes` | `dense` | `macaron` |
-| `sketch-summary` | `sketch-notes` | `balanced` | `macaron` |
-
-Empty Palette = use style's built-in colors (or style's `default_palette` if defined in frontmatter).
-
-## Override Examples
-
- `--preset knowledge-card --style chalkboard` = chalkboard style with dense layout
- `--preset poster --layout quadrant` = screen-print style with quadrant layout
- `--preset hand-drawn-edu --palette warm` = sketch-notes style with flow layout, warm palette instead of macaron
- `--style notion --palette macaron` = notion rendering rules with macaron colors
-
-Explicit `--style`/`--layout`/`--palette` flags always override preset values.
@@ -1,198 +0,0 @@
-# Xiaohongshu Content Analysis Framework
-
-Deep analysis framework tailored for Xiaohongshu's unique engagement patterns.
-
-## Purpose
-
-Before creating infographics, thoroughly analyze the source material to:
- Maximize hook power and swipe motivation
- Identify save-worthy and share-worthy elements
- Plan the visual narrative arc
- Match content to optimal style/layout
-
-## Platform Characteristics
-
-Unlike other platforms, Xiaohongshu content must prioritize:
- **Hook Power**: First image decides 90% of engagement
- **Swipe Motivation**: Each image must compel users to continue
- **Save Value**: Content worth bookmarking for later
- **Share Triggers**: Emotional resonance that drives sharing
-
-## Analysis Dimensions
-
-### 1. Content Type Classification
-
-| Type | Characteristics | Best Style | Best Layout |
-|------|----------------|------------|-------------|
-| 种草/安利 | Product recommendation, benefits focus | cute/fresh | balanced/list |
-| 干货分享 | Knowledge, tips, how-to | notion | dense/list |
-| 个人故事 | Personal experience, emotional | warm | balanced |
-| 测评对比 | Review, comparison, pros/cons | bold/notion | comparison |
-| 教程步骤 | Step-by-step guide | fresh/notion | flow/list |
-| 避坑指南 | Warnings, mistakes to avoid | bold | list/comparison |
-| 清单合集 | Collections, recommendations | cute/minimal | list/dense |
-
-### 2. Hook Analysis (爆款标题潜力)
-
-Evaluate title/hook potential using these patterns:
-
-**Hook Types**:
- **数字钩子**: "5个方法", "3分钟学会", "99%的人不知道"
- **痛点钩子**: "踩过的坑", "后悔没早知道", "别再..."
- **好奇钩子**: "原来...", "竟然...", "没想到..."
- **利益钩子**: "省钱", "变美", "效率翻倍"
- **身份钩子**: "打工人必看", "学生党", "新手妈妈"
-
-**Rating Scale**:
- ⭐⭐⭐⭐⭐ (5/5): Multiple strong hooks combined
- ⭐⭐⭐⭐ (4/5): Clear hook with room for enhancement
- ⭐⭐⭐ (3/5): Basic hook, needs strengthening
- ⭐⭐ (2/5): Weak hook, requires significant improvement
- ⭐ (1/5): No clear hook
-
-### 3. Target Audience (用户画像)
-
-| Audience | Interests | Preferred Style | Content Focus |
-|----------|-----------|-----------------|---------------|
-| 学生党 | 省钱、学习、校园 | cute/fresh | 平价、教程、学习方法 |
-| 打工人 | 效率、职场、减压 | minimal/notion | 工具、技巧、摸鱼 |
-| 宝妈 | 育儿、家居、省心 | warm/fresh | 实用、安全、经验 |
-| 精致女孩 | 美妆、穿搭、仪式感 | cute/retro | 好看、氛围、品质 |
-| 技术宅 | 工具、效率、极客 | notion/chalkboard | 深度、专业、新奇 |
-| 美食爱好者 | 探店、食谱、测评 | warm/pop | 好吃、简单、颜值 |
-| 旅行达人 | 攻略、打卡、小众 | fresh/retro | 省钱、避坑、拍照 |
-
-### 4. Engagement Potential
-
-**Save Value (收藏价值)**:
- Is it reference material? ✓ High save potential
- Is it a checklist or list? ✓ High save potential
- Is it a tutorial? ✓ High save potential
- Is it time-sensitive news? ✗ Low save potential
-
-**Share Triggers (分享冲动)**:
- "我朋友也需要看这个" → High share potential
- "这说的就是我" → Identity resonance
- "太有用了必须分享" → Utility sharing
- "笑死，给朋友看看" → Entertainment sharing
-
-**Comment Inducement (评论诱导)**:
- Open-ended questions: "你是哪种类型？"
- Experience sharing: "评论区说说你的经历"
- Debate triggers: "你觉得呢？"
- Help requests: "有更好的推荐吗？"
-
-**Interaction Design (互动设计)**:
- Polls: "A还是B？"
- Challenges: "你能做到几个？"
- Tags: "@你那个需要的朋友"
-
-### 5. Visual Opportunity Map
-
-| Content Element | Visual Treatment | Example |
-|-----------------|------------------|---------|
-| 数据/统计 | Highlighted numbers, simple charts | "节省80%时间" 大字突出 |
-| 对比 | Before/after, side-by-side | 左右分屏对比图 |
-| 步骤 | Numbered flow, arrows | 1→2→3 流程图 |
-| 清单 | Checklist with icons | ✓/✗ 列表配图标 |
-| 情感 | Character expressions, scenes | 卡通人物表情包 |
-| 产品 | Product showcase, lifestyle | 产品实拍+使用场景 |
-| 引用 | Quote cards, speech bubbles | 金句卡片设计 |
-
-### 6. Swipe Flow Design
-
-Plan the narrative arc across images:
-
-| Position | Purpose | Hook Strategy |
-|----------|---------|---------------|
-| **Cover (封面)** | Stop scrolling | 最强视觉冲击 + 核心标题 |
-| **Setup (铺垫)** | Build context | 痛点共鸣 / 好奇心 |
-| **Core (核心)** | Deliver value | 干货内容，每页1-2个要点 |
-| **Payoff (收获)** | Practical takeaway | 可执行的行动建议 |
-| **Ending (结尾)** | Drive action | CTA + 互动引导 |
-
-**Swipe Motivation Between Images**:
- End each image with a hook for the next
- Use "下一页更精彩" type transitions
- Create information gaps that require swiping
- Build anticipation through numbering ("第3个最重要")
-
-## Output Format
-
-Analysis results should be saved to `analysis.md` with:
-
-```yaml
---
-title: "5个让你效率翻倍的AI工具"
-topic: 干货分享
-content_type: 工具推荐
-source_language: zh
-user_language: zh
-recommended_image_count: 6
---
-
-## Target Audience
-
- **Primary**: 打工人、自由职业者 - 追求效率提升
- **Secondary**: 学生党 - 写论文、做作业需要
- **Tertiary**: 内容创作者 - 需要AI辅助
-
-## Hook Analysis
-
-**标题钩子评分**: ⭐⭐⭐⭐ (4/5)
- ✓ 数字钩子: "5个"
- ✓ 利益钩子: "效率翻倍"
- △ 可增强: 加入身份标签 "打工人必看"
-
-**建议优化**:
- 原标题: "5个让你效率翻倍的AI工具"
- 优化: "打工人必看！5个让我效率翻倍的AI神器"
-
-## Value Proposition
-
-**为什么用户要看？**
-1. **实用价值**: 直接可用的工具推荐
-2. **省时省力**: 不用自己筛选，直接抄作业
-3. **FOMO**: 别人都在用，我不能落后
-
-**收藏理由**: 工具清单，需要时可以回来查
-
-## Engagement Design
-
- **互动点**: 结尾问"你最常用哪个？"
- **评论诱导**: "还有什么好用的工具评论区分享"
- **分享触发**: 打工人会转发给同事
-
-## Content Signals
-
- "AI工具" → notion + dense
- "效率" → notion + list
- "干货" → minimal + dense
-
-## Swipe Flow
-
-| Image | Position | Purpose | Hook |
-|-------|----------|---------|------|
-| 1 | Cover | 吸引停留 | 标题+视觉冲击 |
-| 2 | Setup | 建立共鸣 | 为什么需要AI工具 |
-| 3-5 | Core | 核心价值 | 每页1-2个工具详解 |
-| 6 | Ending | 行动引导 | 总结+互动引导 |
-
-## Recommended Approaches
-
-1. **Notion + Dense** - 知识卡片风格，适合干货分享 (recommended)
-2. **Notion + List** - 清爽知识卡片风格
-3. **Minimal + Balanced** - 简约高端，适合职场人群
-```
-
-## Analysis Checklist
-
-Before proceeding to outline generation:
-
- [ ] Can I identify the content type?
- [ ] Is the hook strong enough? (≥3 stars)
- [ ] Do I know the primary audience?
- [ ] Have I identified save/share triggers?
- [ ] Are there clear visual opportunities?
- [ ] Is the swipe flow planned?
- [ ] Have I identified the best style+layout recommendation?
@@ -1,247 +0,0 @@
-# Xiaohongshu Outline Template
-
-Template for generating infographic series outlines with layout specifications.
-
-## File Naming
-
-Outline files use strategy identifier in the name:
- `outline-strategy-a.md` - Story-driven variant
- `outline-strategy-b.md` - Information-dense variant
- `outline-strategy-c.md` - Visual-first variant
- `outline.md` - Final selected (copied from chosen variant)
-
-## Image File Naming
-
-Images use meaningful slugs for readability:
-```
-NN-{type}-[slug].png
-NN-{type}-[slug].md (in prompts/)
-```
-
-| Type | Usage |
-|------|-------|
-| `cover` | First image (cover) |
-| `content` | Middle content images |
-| `ending` | Last image |
-
-**Examples**:
- `01-cover-ai-tools.png`
- `02-content-why-ai.png`
- `03-content-chatgpt.png`
- `04-content-midjourney.png`
- `05-content-notion-ai.png`
- `06-ending-summary.png`
-
-**Slug rules**:
- Derived from image content (kebab-case)
- Must be unique within the series
- Keep short but descriptive (2-4 words)
-
-## Layout Selection Guide
-
-### Density-Based Layouts
-
-| Layout | When to Use | Info Points | Whitespace |
-|--------|-------------|-------------|------------|
-| sparse | Covers, quotes, impact statements | 1-2 | 60-70% |
-| balanced | Standard content, tutorials | 3-4 | 40-50% |
-| dense | Knowledge cards, cheat sheets | 5-8 | 20-30% |
-
-### Structure-Based Layouts
-
-| Layout | When to Use | Structure |
-|--------|-------------|-----------|
-| list | Rankings, checklists, steps | Numbered/bulleted vertical |
-| comparison | Before/after, pros/cons | Left vs right split |
-| flow | Processes, timelines | Connected nodes with arrows |
-
-### Position-Based Recommendations
-
-| Position | Recommended | Reasoning |
-|----------|-------------|-----------|
-| Cover | sparse | Maximum impact, clear title |
-| Setup | balanced | Context without overwhelming |
-| Core | balanced/dense/list | Match content density |
-| Payoff | balanced/list | Clear takeaways |
-| Ending | sparse | Clean CTA, memorable |
-
-## Outline Format
-
-```markdown
-# Xiaohongshu Infographic Series Outline
-
---
-strategy: a  # a, b, or c
-name: Story-Driven
-style: notion
-default_layout: dense
-image_count: 6
-generated: YYYY-MM-DD HH:mm
---
-
-## Image 1 of 6
-
-**Position**: Cover
-**Layout**: sparse
-**Hook**: 打工人必看！
-**Slug**: ai-tools
-**Filename**: 01-cover-ai-tools.png
-
-**Text Content**:
- Title: 「5个AI神器让你效率翻倍」
- Subtitle: 亲测好用，建议收藏
-
-**Visual Concept**:
-科技感背景，多个AI工具图标环绕，中心大标题，
-霓虹蓝+深色背景，未来感十足
-
-**Swipe Hook**: 第一个就很强大👇
-
---
-
-## Image 2 of 6
-
-**Position**: Content
-**Layout**: balanced
-**Core Message**: 为什么你需要AI工具
-**Slug**: why-ai
-**Filename**: 02-content-why-ai.png
-
-**Text Content**:
- Title: 「为什么要用AI？」
- Points:
-  - 重复工作自动化
-  - 创意辅助不卡壳
-  - 效率提升10倍
-
-**Visual Concept**:
-对比图：左边疲惫打工人，右边轻松使用AI的人
-科技线条装饰，简洁有力
-
-**Swipe Hook**: 接下来是具体工具推荐👇
-
---
-
-## Image 3 of 6
-
-**Position**: Content
-**Layout**: dense
-**Core Message**: ChatGPT使用技巧
-**Slug**: chatgpt
-**Filename**: 03-content-chatgpt.png
-
-**Text Content**:
- Title: 「ChatGPT」
- Subtitle: 最强AI助手
- Points:
-  - 写文案：给出框架，秒出初稿
-  - 改文章：润色、翻译、总结
-  - 编程：写代码、找bug
-  - 学习：解释概念、出题练习
-
-**Visual Concept**:
-ChatGPT logo居中，四周放射状展示功能点
-深色科技背景，霓虹绿点缀
-
-**Swipe Hook**: 下一个更适合创意工作者👇
-
---
-
-## Image 4 of 6
-
-**Position**: Content
-**Layout**: dense
-**Core Message**: Midjourney绘图
-**Slug**: midjourney
-**Filename**: 04-content-midjourney.png
-
-**Text Content**:
- Title: 「Midjourney」
- Subtitle: AI绘画神器
- Points:
-  - 输入描述，秒出图片
-  - 风格多样：写实/插画/3D
-  - 做封面、做头像、做素材
-  - 不会画画也能当设计师
-
-**Visual Concept**:
-展示几张MJ生成的不同风格图片
-画框/画布元素装饰
-
-**Swipe Hook**: 还有一个效率神器👇
-
---
-
-## Image 5 of 6
-
-**Position**: Content
-**Layout**: balanced
-**Core Message**: Notion AI笔记
-**Slug**: notion-ai
-**Filename**: 05-content-notion-ai.png
-
-**Text Content**:
- Title: 「Notion AI」
- Subtitle: 智能笔记助手
- Points:
-  - 自动总结长文
-  - 头脑风暴出点子
-  - 整理会议记录
-
-**Visual Concept**:
-Notion界面风格，简洁黑白配色
-展示笔记整理前后对比
-
-**Swipe Hook**: 最后总结一下👇
-
---
-
-## Image 6 of 6
-
-**Position**: Ending
-**Layout**: sparse
-**Core Message**: 总结与互动
-**Slug**: summary
-**Filename**: 06-ending-summary.png
-
-**Text Content**:
- Title: 「工具只是工具」
- Subtitle: 关键是用起来！
- CTA: 收藏备用 | 转发给需要的朋友
- Interaction: 你最常用哪个？评论区见👇
-
-**Visual Concept**:
-简洁背景，大字标题
-底部互动引导文字
-收藏/分享图标
-
---
-```
-
-## Swipe Hook Strategies
-
-Each image should end with a hook for the next:
-
-| Strategy | Example |
-|----------|---------|
-| Teaser | "第一个就很强大👇" |
-| Numbering | "接下来是第2个👇" |
-| Superlative | "下一个更厉害👇" |
-| Question | "猜猜下一个是什么？👇" |
-| Promise | "最后一个最实用👇" |
-| Urgency | "最重要的来了👇" |
-
-## Strategy Differentiation
-
-Three strategies should differ meaningfully:
-
-| Strategy | Focus | Structure | Page Count |
-|----------|-------|-----------|------------|
-| A: Story-Driven | Emotional, personal | Hook→Problem→Discovery→Experience→Conclusion | 4-6 |
-| B: Information-Dense | Factual, structured | Core→Info Cards→Comparison→Recommendation | 3-5 |
-| C: Visual-First | Atmospheric, minimal text | Hero→Details→Lifestyle→CTA | 3-4 |
-
-**Example for "AI工具推荐"**:
- `outline-strategy-a.md`: Warm + Balanced - Personal journey with AI
- `outline-strategy-b.md`: Notion + Dense - Knowledge card style
- `outline-strategy-c.md`: Minimal + Sparse - Sleek tech aesthetic
@@ -1,378 +0,0 @@
-# Prompt Assembly Guide
-
-Guide for assembling image generation prompts from elements, presets, and outline content.
-
-## Base Prompt Structure
-
-Every XHS infographic prompt follows this structure:
-
-```
-Create a Xiaohongshu (Little Red Book) style infographic following these guidelines:
-
-## Image Specifications
-
- **Type**: Infographic
- **Orientation**: Portrait (vertical)
- **Aspect Ratio**: 3:4
- **Style**: Hand-drawn illustration
-
-## Core Principles
-
- Hand-drawn quality throughout - NO realistic or photographic elements
- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
- Keep information concise, highlight keywords and core concepts
- Use ample whitespace for easy visual scanning
- Maintain clear visual hierarchy
-
-## Text Style (CRITICAL)
-
- **ALL text MUST be hand-drawn style**
- Main titles should be prominent and eye-catching
- Key text should be bold and enlarged
- Use highlighter effects to emphasize keywords
- **DO NOT use realistic or computer-generated fonts**
-
-## Language
-
- Use the same language as the content provided below
- Match punctuation style to the content language (Chinese: ""，。！)
-
---
-
-{STYLE_SECTION}
-
---
-
-{LAYOUT_SECTION}
-
---
-
-{CONTENT_SECTION}
-
---
-
-{WATERMARK_SECTION}
-
---
-
-Please use nano banana pro to generate the infographic based on the specifications above.
-```
-
-## Style Section Assembly
-
-Load from `presets/{style}.md` and extract key elements:
-
-```markdown
-## Style: {style_name}
-
-**Color Palette**:
- Primary: {colors}
- Background: {colors}
- Accents: {colors}
-
-**Visual Elements**:
-{visual_elements}
-
-**Typography**:
-{typography_style}
-```
-
-### Screen-Print Style Override
-
-When `style: screen-print`, replace the standard Core Principles and Text Style sections with:
-
-```
-## Core Principles
-
- Screen print / silkscreen poster art — flat color blocks, NO gradients
- Bold silhouettes and symbolic shapes over detailed rendering
- Negative space as active storytelling element
- If content involves sensitive or copyrighted figures, create stylistically similar silhouettes
- One iconic focal point per image — conceptual, not literal
-
-## Color Rules (CRITICAL)
-
- **2-5 FLAT COLORS MAXIMUM** — fewer colors = stronger impact
- Choose ONE duotone pair from preset as dominant palette
- Halftone dot patterns for tonal variation (NOT gradients)
- Slight color layer misregistration for print authenticity
-
-## Text Style (CRITICAL)
-
- Bold condensed sans-serif or Art Deco influenced lettering
- Typography INTEGRATED into composition as design element
- High contrast with background, stencil-cut quality
- **DO NOT use delicate, thin, or handwritten fonts**
-
-## Composition
-
- Geometric framing: circles, arches, triangles
- Figure-ground inversion where possible (negative space forms secondary image)
- Stencil-cut edges between color blocks, no outlines
- Paper grain texture beneath all colors
-```
-
-## Palette Override
-
-When `--palette` is specified (or style has `default_palette` in frontmatter and no explicit `--palette`), palette colors **replace** the style's Color Palette in the prompt. Style rendering rules (Visual Elements, Typography, Style Rules) remain unchanged.
-
-Load from `palettes/{palette}.md` and override:
-
-```markdown
-## Palette Override: {palette_name}
-
-**Background**: {palette background color and hex}
-
-**Colors**:
- Text: {text color and hex}
- Secondary: {secondary text color and hex}
- Zone 1: {zone color and hex}
- Zone 2: {zone color and hex}
- Zone 3: {zone color and hex}
- Zone 4: {zone color and hex}
- Accent: {accent color and hex}
-
-**Constraint**: {semantic constraint from palette}
-```
-
-**Override rules**:
-1. Palette Background **replaces** style's background color (keep style's texture description)
-2. Palette Colors **replace** style's Color Palette section entirely
-3. Palette Semantic Constraint is appended to the style section
-4. If no `--palette` and style has `default_palette` → load that palette
-5. If no `--palette` and no `default_palette` → use style's built-in colors (no override)
-6. Explicit `--palette` always overrides style's `default_palette`
-
-## Layout Section Assembly
-
-Load from `elements/canvas.md` and extract relevant layout:
-
-```markdown
-## Layout: {layout_name}
-
-**Information Density**: {density}
-**Whitespace**: {percentage}
-
-**Structure**:
-{structure_description}
-
-**Visual Balance**:
-{balance_description}
-```
-
-## Content Section Assembly
-
-From outline entry:
-
-```markdown
-## Content
-
-**Position**: {Cover/Content/Ending}
-**Core Message**: {message}
-
-**Text Content**:
-{text_list}
-
-**Visual Concept**:
-{visual_description}
-```
-
-## Watermark Section (if enabled)
-
-```markdown
-## Watermark
-
-Include a subtle watermark "{content}" positioned at {position}. The watermark should
-be legible but not distracting from the main content.
-```
-
-## Assembly Process
-
-### Step 0: Resolve Style Preset (if `--preset` used)
-
-If user specified `--preset`, resolve to style + layout + palette from `references/style-presets.md`:
-
-```python
-# e.g., --preset hand-drawn-edu → style=sketch-notes, layout=flow, palette=macaron
-style, layout, palette = resolve_preset(preset_name)
-```
-
-Explicit `--style`/`--layout`/`--palette` flags override preset values.
-
-### Step 1: Load Style Definition
-
-```python
-preset = load_preset(style_name)  # e.g., "sketch-notes"
-```
-
-Extract:
- Color palette (may be overridden by palette)
- Visual elements
- Typography style
- Best practices (do/don't)
- `default_palette` from frontmatter (if present)
-
-### Step 1.5: Apply Palette Override (if applicable)
-
-```python
-# Priority: explicit --palette > preset palette > style default_palette > none
-palette = resolve_palette(cli_palette, preset_palette, style_default_palette)
-if palette:
-    palette_def = load_palette(palette)  # e.g., "macaron"
-    # Replace style colors with palette colors
-    # Keep style rendering rules (visual elements, typography, style rules)
-```
-
-### Step 2: Load Layout
-
-```python
-layout = get_layout_from_canvas(layout_name)  # e.g., "dense"
-```
-
-Extract:
- Information density guidelines
- Whitespace percentage
- Structure description
- Visual balance rules
-
-### Step 3: Format Content
-
-From outline entry, format:
- Position context (Cover/Content/Ending)
- Text content with hierarchy
- Visual concept description
- Swipe hook (for context, not in prompt)
-
-### Step 4: Add Watermark (if applicable)
-
-If preferences include watermark:
- Add watermark section with content, position, opacity
-
-### Step 5: Visual Consistency — Reference Image Chain
-
-When generating multiple images in a series:
-
-1. **Image 1 (cover)**: Generate without `--ref` — this establishes the visual anchor
-2. **Images 2+**: Always pass image 1 as `--ref` to the installed image generation skill.
-   Read that skill's `SKILL.md` and use its documented interface rather than calling its scripts directly.
-   For each later image, use the assembled prompt file as input, set the output image path, keep aspect ratio `3:4`, use quality `2k`, and pass image 1 as the reference.
-   This ensures the AI maintains the same character design, illustration style, and color rendering across the series.
-
-### Step 6: Combine
-
-Assemble all sections into final prompt following base structure.
-
-## Example: Assembled Prompt
-
-```markdown
-Create a Xiaohongshu (Little Red Book) style infographic following these guidelines:
-
-## Image Specifications
-
- **Type**: Infographic
- **Orientation**: Portrait (vertical)
- **Aspect Ratio**: 3:4
- **Style**: Hand-drawn illustration
-
-## Core Principles
-
- Hand-drawn quality throughout - NO realistic or photographic elements
- If content involves sensitive or copyrighted figures, create stylistically similar alternatives
- Keep information concise, highlight keywords and core concepts
- Use ample whitespace for easy visual scanning
- Maintain clear visual hierarchy
-
-## Text Style (CRITICAL)
-
- **ALL text MUST be hand-drawn style**
- Main titles should be prominent and eye-catching
- Key text should be bold and enlarged
- Use highlighter effects to emphasize keywords
- **DO NOT use realistic or computer-generated fonts**
-
-## Language
-
- Use the same language as the content provided below
- Match punctuation style to the content language (Chinese: ""，。！)
-
---
-
-## Style: Notion
-
-**Color Palette**:
- Primary: Black (#1A1A1A), dark gray (#4A4A4A)
- Background: Pure white (#FFFFFF), off-white (#FAFAFA)
- Accents: Pastel blue (#A8D4F0), pastel yellow (#F9E79F), pastel pink (#FADBD8)
-
-**Visual Elements**:
- Simple line doodles, hand-drawn wobble effect
- Geometric shapes, stick figures
- Maximum whitespace, single-weight ink lines
- Clean, uncluttered compositions
-
-**Typography**:
- Clean hand-drawn lettering
- Simple sans-serif labels
- Minimal decoration on text
-
---
-
-## Layout: Dense
-
-**Information Density**: High (5-8 key points)
-**Whitespace**: 20-30% of canvas
-
-**Structure**:
- Multiple sections, structured grid
- More text, compact but organized
- Title + multiple sections with headers + numerous points
-
-**Visual Balance**:
- Organized grid structure
- Clear section boundaries
- Compact but readable spacing
-
---
-
-## Content
-
-**Position**: Content (Page 3 of 6)
-**Core Message**: ChatGPT 使用技巧
-
-**Text Content**:
- Title: 「ChatGPT」
- Subtitle: 最强 AI 助手
- Points:
-  - 写文案：给出框架，秒出初稿
-  - 改文章：润色、翻译、总结
-  - 编程：写代码、找 bug
-  - 学习：解释概念、出题练习
-
-**Visual Concept**:
-ChatGPT logo 居中，四周放射状展示功能点
-深色科技背景，霓虹绿点缀
-
---
-
-## Watermark
-
-Include a subtle watermark "@myxhsaccount" positioned at bottom-right
-with approximately 50% visibility. The watermark should
-be legible but not distracting from the main content.
-
---
-
-Please use nano banana pro to generate the infographic based on the specifications above.
-```
-
-## Prompt Checklist
-
-Before generating, verify:
-
- [ ] Style section loaded from correct preset
- [ ] Palette override applied (if `--palette` specified or style has `default_palette`)
- [ ] Layout section matches outline specification
- [ ] Content accurately reflects outline entry
- [ ] Language matches source content
- [ ] Watermark included (if enabled in preferences)
- [ ] No conflicting instructions
@@ -1,7 +1,7 @@
 ---
 name: baoyu-image-gen
-description: "[Deprecated: use baoyu-imagine] AI image generation with OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, Z.AI GLM-Image, MiniMax, Jimeng, Seedream and Replicate APIs. Supports text-to-image, reference images, aspect ratios, and batch generation from saved prompt files. Sequential by default; use batch parallel generation when the user already has multiple prompts or wants stable multi-image throughput. Use when user asks to generate, create, or draw images."
-version: 1.56.4
+description: AI image generation with OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope, Z.AI GLM-Image, MiniMax, Jimeng, Seedream and Replicate APIs. Supports text-to-image, reference images, aspect ratios, and batch generation from saved prompt files. Sequential by default; use batch parallel generation when the user already has multiple prompts or wants stable multi-image throughput. Use when user asks to generate, create, or draw images.
+version: 2.0.0
 metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-image-gen
@@ -11,10 +11,9 @@ metadata:
        - npx
 ---

-
 # Image Generation (AI SDK)

-Official API-based image generation. Supports OpenAI, Azure OpenAI, Google, OpenRouter, DashScope (阿里通义万象), Z.AI GLM-Image, MiniMax, Jimeng (即梦), Seedream (豆包) and Replicate.
+Official API-based image generation. Supports OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope (阿里通义万象), Z.AI GLM-Image, MiniMax, Jimeng (即梦), Seedream (豆包) and Replicate.

 ## User Input Tools

@@ -45,12 +44,24 @@ Check these paths in order; first hit wins:
 - **Found** → load, parse, apply. If `default_model.[provider]` is null → ask model only.
 - **Not found** → run first-time setup (`references/config/first-time-setup.md`) using AskUserQuestion to collect provider + model + quality + save location. Save EXTEND.md, then continue. Do not generate images before this completes.

+Legacy compatibility: if `.baoyu-skills/baoyu-imagine/EXTEND.md` exists and the new path doesn't, the runtime renames it to `baoyu-image-gen`. If both exist, the runtime leaves them alone and uses the new path.
+
 **EXTEND.md keys**: default provider, default quality, default aspect ratio, default image size, OpenAI image API dialect, default models, batch worker cap, provider-specific batch limits. Schema: `references/config/preferences-schema.md`.

 ## Usage

 Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode.

+### Identity-preserving reference prompts
+
+When the user wants a real person/character/object preserved from reference images, do **not** replace the reference with a long generic description. Prefer short, hard identity-preservation language:
+
+- "Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject."
+- "Only change scene, clothing, pose, lighting, rendering style, and composition. Keep the face/proportions/hair/key accessories/overall identity from the references."
+- If using multiple references, state that they are the same subject and should jointly define identity.
+
+Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person.
+
 ```bash
 # Basic
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png
@@ -67,10 +78,23 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref so
 # Specific provider
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider dashscope --model qwen-image-2.0-pro

+# OpenAI GPT Image 2
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --model gpt-image-2
+
 # Batch mode
 ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
 ```

+## Reference-Image Identity Preservation
+
+When the user wants a person/object preserved from reference images:
+
+- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers.
+- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person.
+- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift.
+- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing).
+- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity.
+
 ## Options

 | Option | Description |
@@ -83,11 +107,11 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
 | `--provider google\|openai\|azure\|openrouter\|dashscope\|zai\|minimax\|jimeng\|seedream\|replicate` | Force provider (default: auto-detect) |
 | `--model <id>`, `-m` | Model ID — see provider references for defaults and allowed values |
 | `--ar <ratio>` | Aspect ratio (`16:9`, `1:1`, `4:3`, …) |
-| `--size <WxH>` | Explicit size (e.g., `1024x1024`) |
+| `--size <WxH>` | Explicit size (e.g., `1024x1024`; for `gpt-image-2`, width/height must be multiples of 16, max edge 3840px, ratio no wider than 3:1) |
 | `--quality normal\|2k` | Quality preset (default: `2k`) |
 | `--imageSize 1K\|2K\|4K` | Image size for Google/OpenRouter (default: from quality) |
 | `--imageApiDialect openai-native\|ratio-metadata` | OpenAI-compatible endpoint dialect — use `ratio-metadata` for gateways that expect aspect-ratio `size` plus `metadata.resolution` |
-| `--ref <files...>` | Reference images. Supported by Google multimodal, OpenAI GPT Image edits, Azure OpenAI edits (PNG/JPG only), OpenRouter multimodal models, Replicate supported families, MiniMax subject-reference, Seedream 5.0/4.5/4.0. Not supported by Jimeng, Seedream 3.0, SeedEdit 3.0 |
+| `--ref <files...>` | Reference images. Supported by Google multimodal, OpenAI GPT Image edits, Azure OpenAI edits (PNG/JPG only), OpenRouter multimodal models, Replicate supported families, MiniMax subject-reference, Seedream 5.0/4.5/4.0, DashScope `wan2.7-image-pro`/`wan2.7-image`. Not supported by Jimeng, Seedream 3.0, SeedEdit 3.0, or any DashScope model outside the `wan2.7-image*` family |
 | `--n <count>` | Number of images. Replicate requires `--n 1` (single-output save semantics) |
 | `--json` | JSON output |

@@ -118,6 +142,18 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

 **Load priority**: CLI args > EXTEND.md > env vars > `<cwd>/.baoyu-skills/.env` > `~/.baoyu-skills/.env`

+### Codex/ChatGPT OAuth is not an OpenAI API key
+
+`--provider openai --model gpt-image-2` uses the standard OpenAI Images API (`/v1/images/generations` or `/v1/images/edits`) and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend.
+
+If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider:
+
+- In Codex runtime: use the native `imagegen` skill/tool.
+- In non-Codex runtimes with `codex` CLI installed and logged in: use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it (for example `baoyu-cover-image`). Resolve it from the plugin/repo root and pass absolute prompt/output/reference paths.
+- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits.
+
+Do not modify the existing `openai` provider to silently consume Codex OAuth. If first-class Codex OAuth support is added to `baoyu-image-gen`, implement it as a distinct provider (for example `openai-codex`) with its own auth, route, request shape, docs, and tests. See `references/codex-oauth-vs-openai-api-key.md`.
+
 ## Model Resolution

 Priority (highest → lowest) applies to every provider:
@@ -127,7 +163,9 @@ Priority (highest → lowest) applies to every provider:
 3. Env var `<PROVIDER>_IMAGE_MODEL`
 4. Built-in default

-For Azure, `--model` / `default_model.azure` is the Azure deployment name. `AZURE_OPENAI_DEPLOYMENT` is the preferred env var; `AZURE_OPENAI_IMAGE_MODEL` is kept as a backward-compatible alias.
+For OpenAI, the built-in default is `gpt-image-2`. `gpt-image-1.5`, `gpt-image-1`, and GPT Image snapshots remain selectable with `--model` or `OPENAI_IMAGE_MODEL`.
+
+For Azure, `--model` / `default_model.azure` is the Azure deployment name. `AZURE_OPENAI_DEPLOYMENT` is the preferred env var; `AZURE_OPENAI_IMAGE_MODEL` is kept as a backward-compatible alias. If your Azure deployment is named after the underlying model, use `gpt-image-2`; otherwise use the exact custom deployment name.

 EXTEND.md overrides env vars: if EXTEND.md sets `default_model.google: "gemini-3-pro-image-preview"` and the env var sets `GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview`, EXTEND.md wins.

@@ -168,17 +206,19 @@ Each provider has its own quirks (model families, size rules, ref support, limit

 | Preset | Google imageSize | OpenAI size | OpenRouter size | Replicate resolution | Use case |
 |--------|------------------|-------------|-----------------|----------------------|----------|
-| `normal` | 1K | 1024px | 1K | 1K | Quick previews |
-| `2k` (default) | 2K | 2048px | 2K | 2K | Covers, illustrations, infographics |
+| `normal` | 1K | 1024px target | 1K | 1K | Quick previews |
+| `2k` (default) | 2K | 2048px target | 2K | 2K | Covers, illustrations, infographics |

 Google/OpenRouter `imageSize` can be overridden with `--imageSize 1K|2K|4K`.

+For OpenAI native `gpt-image-2`, `normal` maps to `quality=medium` and a low-latency valid size near the requested aspect ratio; `2k` maps to `quality=high` and 2048px-class sizes such as `2048x2048`, `2048x1152`, or `1152x2048`. Use explicit `--size` for valid custom or 4K outputs, e.g. `3840x2160`.
+
 ## Aspect Ratios

 Supported: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2.35:1`.

 - Google multimodal: `imageConfig.aspectRatio`
- OpenAI: closest supported size
+- OpenAI: `gpt-image-2` uses the closest valid custom size for the requested ratio; older GPT Image and DALL·E models use their closest supported fixed size
 - OpenRouter: `imageGenerationOptions.aspect_ratio`; if only `--size <WxH>` is given, the ratio is inferred
 - Replicate: behavior is model-specific — `google/nano-banana*` uses `aspect_ratio`, `bytedance/seedream-*` uses documented Replicate ratios, Wan 2.7 maps `--ar` to a concrete `size`
 - MiniMax: official `aspect_ratio` values; if `--size <WxH>` is given without `--ar`, sends `width`/`height` for `image-01`
@@ -211,11 +251,17 @@ Rule of thumb: once prompt files are saved and the task is "generate all of thes
 - Invalid aspect ratio → warning, proceed with default
 - Reference images with unsupported provider/model → error with fix hint

+### Codex image2 fallback
+
+If `--provider openai --model gpt-image-2` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`.
+
 ## References

 | File | Content |
 |------|---------|
 | `references/usage-examples.md` | Extended CLI examples across providers and batch mode |
+| `references/codex-oauth-vs-openai-api-key.md` | Why Codex/ChatGPT OAuth image2 entitlement is not usable through baoyu-image-gen's standard OpenAI API-key provider |
+| `references/codex-image2-fallback.md` | Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available |
 | `references/providers/dashscope.md` | DashScope families, sizes, limits |
 | `references/providers/zai.md` | Z.AI GLM-image / cogview-4 |
 | `references/providers/minimax.md` | MiniMax image-01 + subject reference |
@@ -0,0 +1,35 @@
+---
+name: codex-image2-fallback
+description: Fallback behavior when baoyu-image-gen lacks OpenAI API credentials but Codex/native image generation is available
+---
+
+# Codex Image2 Fallback
+
+When using `baoyu-image-gen` with `--provider openai --model gpt-image-2`, the CLI can fail with:
+
+```text
+OPENAI_API_KEY is required. Codex/ChatGPT desktop login does not automatically grant OpenAI Images API access to this script.
+```
+
+This is expected. The `openai` provider uses the public OpenAI Images API and needs `OPENAI_API_KEY`. Codex / ChatGPT image2 entitlement is a separate runtime-native path.
+
+## Practical fallback pattern
+
+1. Try `baoyu-image-gen` when provider credentials are available.
+2. If it fails only because `OPENAI_API_KEY` is missing, do not leave the user waiting.
+3. Prefer a Codex/native raster backend in this order:
+   - Codex runtime native `imagegen` skill/tool, if available.
+   - Repo-level `scripts/codex-imagegen.sh`, if `codex` CLI is installed/logged in and the calling skill supports the wrapper.
+   - Hermes native `image_generate`, if available.
+4. Be transparent about reference-image behavior:
+   - If the fallback backend accepts references, pass the reference images.
+   - If it does not, derive a concise identity-preserving prompt from the references and state that it is a text-description fallback, not strict reference-image editing.
+5. Return the generated media path or structured backend error promptly.
+
+## User-facing wording
+
+Use concise wording such as:
+
+> The OpenAI API path needs `OPENAI_API_KEY`; Codex login is a separate image2 backend. I used the available Codex/native image backend instead. Reference images were [passed directly / reconstructed from visual traits].
+
+Avoid implying that `baoyu-image-gen --provider openai` can use Codex OAuth without a dedicated provider implementation.
@@ -0,0 +1,18 @@
+# Codex OAuth vs OpenAI API key for baoyu-image-gen
+
+`baoyu-image-gen --provider openai` uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. It calls OpenAI-compatible image endpoints such as `/images/generations` and `/images/edits`.
+
+Codex / ChatGPT login is different. Codex image generation is driven by Codex OAuth and the Codex runtime's `image_gen` capability, not by the public OpenAI Images API key path. A Codex OAuth token is not a drop-in replacement for `OPENAI_API_KEY`, and setting `OPENAI_BASE_URL` to a Codex backend will not make baoyu-image-gen's existing `openai` provider work because the auth, route, and payload shape differ.
+
+## What to use instead
+
+- If running inside Codex and the native `imagegen` skill/tool is available, use it directly.
+- If running outside Codex but the `codex` CLI is installed and logged in, use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it. The wrapper invokes `codex exec` and the Codex `image_gen` tool; no `OPENAI_API_KEY` is required.
+- If running inside Hermes and a native `image_generate` tool is available, use that as a runtime-native fallback. Be explicit about whether reference images are passed directly or only reconstructed from extracted traits.
+- If the user wants `baoyu-image-gen` itself to support Codex OAuth, add a distinct provider such as `openai-codex` rather than modifying the existing `openai` provider.
+
+## Reference-image prompting note
+
+When using actual reference images for identity preservation, avoid long generic descriptions of the subject. Long descriptions can cause the model to synthesize a new similar-looking person/object. Prefer direct wording:
+
+> Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject. Only change scene, clothing, pose, lighting, rendering style, and composition.
@@ -46,19 +46,19 @@ options:
  - label: "Google (Recommended)"
    description: "Gemini multimodal - high quality, reference images, flexible sizes"
  - label: "OpenAI"
-    description: "GPT Image - consistent quality, reliable output"
+    description: "GPT Image 2 - latest OpenAI image model, reference-image workflows"
  - label: "Azure OpenAI"
    description: "Azure-hosted GPT Image deployments with resource-specific routing"
  - label: "OpenRouter"
    description: "Router for Gemini/FLUX/OpenAI-compatible image models"
  - label: "DashScope"
    description: "Alibaba Cloud - Qwen-Image, strong Chinese/English text rendering"
+  - label: "Z.AI"
+    description: "GLM-image, strong poster and text-heavy image generation"
  - label: "MiniMax"
    description: "MiniMax image generation with subject-reference character workflows"
  - label: "Replicate"
-    description: "Community models - nano-banana-pro, flexible model selection"
-  - label: "Z.AI"
-    description: "GLM-Image - text-to-image with recommended aspect sizes"
+    description: "Curated Replicate image families - nano-banana-2, Seedream, and Wan image models"
 ```

 ### Question 2: Default Google Model
@@ -101,10 +101,12 @@ Only show if user selected Azure OpenAI.
 header: "Azure Deploy"
 question: "Default Azure image deployment name?"
 options:
-  - label: "gpt-image-1.5 (Recommended)"
-    description: "Best default if your Azure deployment uses the same name"
-  - label: "gpt-image-1"
+  - label: "gpt-image-2 (Recommended)"
+    description: "Use if your Azure deployment uses the GPT Image 2 model name"
+  - label: "gpt-image-1.5"
    description: "Previous GPT Image deployment name"
+  - label: "gpt-image-1"
+    description: "Earlier GPT Image deployment name"
 ```

 ### Question 2d: Default MiniMax Model
@@ -130,11 +132,9 @@ header: "Z.AI Model"
 question: "Default Z.AI image generation model?"
 options:
  - label: "glm-image (Recommended)"
-    description: "Latest GLM-Image, best aspect-ratio coverage and text rendering"
+    description: "Best default for posters, diagrams, and text-heavy images"
  - label: "cogview-4-250304"
-    description: "Legacy CogView-4 model with 16-pixel size stepping"
-  - label: "cogview-4"
-    description: "Previous CogView-4 snapshot for compatibility"
+    description: "Legacy Z.AI image model on the same endpoint"
 ```

 ### Question 3: Default Quality
@@ -177,18 +177,21 @@ default_provider: [selected provider or null]
 default_quality: [selected quality]
 default_aspect_ratio: null
 default_image_size: null
+default_image_api_dialect: null
 default_model:
  google: [selected google model or null]
  openai: null
  azure: [selected azure deployment or null]
  openrouter: [selected openrouter model or null]
  dashscope: null
+  zai: [selected Z.AI model or null]
  minimax: [selected minimax model or null]
  replicate: null
-  zai: [selected zai model or null]
 ---
 ```

+If the user selects `OpenAI` but says their endpoint is only OpenAI-compatible and fronts another image model family, save `default_image_api_dialect: ratio-metadata` when they explicitly confirm the gateway expects aspect-ratio `size` plus metadata-based resolution. Otherwise leave it `null` / `openai-native`.
+
 ## Flow 2: EXTEND.md Exists, Model Null

 When EXTEND.md exists but `default_model.[current_provider]` is null, ask ONLY the model question for the current provider.
@@ -213,10 +216,12 @@ options:
 header: "OpenAI Model"
 question: "Choose a default OpenAI image generation model?"
 options:
-  - label: "gpt-image-1.5 (Recommended)"
-    description: "Latest GPT Image model, high quality"
+  - label: "gpt-image-2 (Recommended)"
+    description: "Latest GPT Image model, flexible sizes up to 4K, high-fidelity image inputs"
+  - label: "gpt-image-1.5"
+    description: "Previous GPT Image model"
  - label: "gpt-image-1"
-    description: "Previous generation GPT Image model"
+    description: "Earlier GPT Image model"
 ```

 ### Azure Deployment Selection
@@ -225,8 +230,10 @@ options:
 header: "Azure Deploy"
 question: "Choose a default Azure image deployment name?"
 options:
-  - label: "gpt-image-1.5 (Recommended)"
-    description: "Use when your Azure deployment name matches the GPT-image-1.5 model"
+  - label: "gpt-image-2 (Recommended)"
+    description: "Use when your Azure deployment name matches the GPT Image 2 model"
+  - label: "gpt-image-1.5"
+    description: "Use when your Azure deployment name matches the GPT Image 1.5 model"
  - label: "gpt-image-1"
    description: "Use when your Azure deployment name matches GPT-image-1"
 ```
@@ -264,6 +271,10 @@ options:
    description: "Legacy Qwen model with five fixed output sizes"
  - label: "qwen-image-plus"
    description: "Legacy Qwen model, same current capability as qwen-image"
+  - label: "wan2.7-image-pro"
+    description: "Wan 2.7 Pro — supports up to 4K text-to-image and reference-image editing"
+  - label: "wan2.7-image"
+    description: "Wan 2.7 base — faster generation, up to 2K, supports reference-image editing"
  - label: "z-image-turbo"
    description: "Legacy DashScope model for compatibility"
  - label: "z-image-ultra"
@@ -274,18 +285,41 @@ Notes for DashScope setup:

 - Prefer `qwen-image-2.0-pro` when the user needs custom `--size`, uncommon ratios like `21:9`, or strong Chinese/English text rendering.
 - `qwen-image-max` / `qwen-image-plus` / `qwen-image` only support five fixed sizes: `1664*928`, `1472*1104`, `1328*1328`, `1104*1472`, `928*1664`.
+- `wan2.7-image-pro` and `wan2.7-image` are the only DashScope models that accept `--ref`. Pick one of these when the user wants reference-image editing or multi-image fusion via DashScope.
 - In `baoyu-image-gen`, `quality` is a compatibility preset. It is not a native DashScope parameter.

+### Z.AI Model Selection
+
+```yaml
+header: "Z.AI Model"
+question: "Choose a default Z.AI image generation model?"
+options:
+  - label: "glm-image (Recommended)"
+    description: "Current flagship image model with better text rendering and poster layouts"
+  - label: "cogview-4-250304"
+    description: "Legacy model on the sync image endpoint"
+```
+
+Notes for Z.AI setup:
+
+- Prefer `glm-image` for posters, diagrams, and Chinese/English text-heavy layouts.
+- In `baoyu-image-gen`, Z.AI currently exposes text-to-image only; reference images are not wired for this provider.
+- The sync Z.AI image API returns a downloadable image URL, which the runtime saves locally after download.
+
 ### Replicate Model Selection

 ```yaml
 header: "Replicate Model"
 question: "Choose a default Replicate image generation model?"
 options:
-  - label: "google/nano-banana-pro (Recommended)"
-    description: "Google's fast image model on Replicate"
-  - label: "google/nano-banana"
-    description: "Google's base image model on Replicate"
+  - label: "google/nano-banana-2 (Recommended)"
+    description: "Current default for general Replicate image generation in baoyu-image-gen"
+  - label: "bytedance/seedream-4.5"
+    description: "Replicate Seedream 4.5 with validated local size/ref guardrails"
+  - label: "bytedance/seedream-5-lite"
+    description: "Replicate Seedream 5 Lite with validated local size/ref guardrails"
+  - label: "wan-video/wan-2.7-image-pro"
+    description: "Replicate Wan 2.7 Image Pro with 4K text-to-image support"
 ```

 ### MiniMax Model Selection
@@ -306,27 +340,6 @@ Notes for MiniMax setup:
 - `image-01-live` is useful when the user prefers faster generation and can work with aspect-ratio-based sizing.
 - MiniMax subject reference currently uses `subject_reference[].type = character`; docs recommend front-facing portrait references in JPG/JPEG/PNG under 10MB.

-### Z.AI Model Selection
-
-```yaml
-header: "Z.AI Model"
-question: "Choose a default Z.AI image generation model?"
-options:
-  - label: "glm-image (Recommended)"
-    description: "Latest GLM-Image; pixels round to multiples of 32 and cap at 2^22"
-  - label: "cogview-4-250304"
-    description: "Legacy CogView-4 snapshot with 16-pixel size stepping"
-  - label: "cogview-4"
-    description: "Earlier CogView-4 snapshot for compatibility"
-```
-
-Notes for Z.AI setup:
-
- Set `ZAI_API_KEY` (or legacy `BIGMODEL_API_KEY`) from https://docs.z.ai/.
- `glm-image` supports recommended aspect sizes (1280x1280, 1728x960, 1568x1056, …); uncommon ratios auto-fit to the 2^22 pixel budget on multiples of 32.
- Legacy CogView models use 16-pixel stepping and cap at 2^21 pixels per image.
- Z.AI does not accept reference images or `n > 1` in `baoyu-image-gen`; use Google/OpenAI providers for those workflows.
-
 ### Update EXTEND.md

 After user selects a model:
@@ -342,9 +355,9 @@ default_model:
  azure: [value or null]
  openrouter: [value or null]
  dashscope: [value or null]
+  zai: [value or null]
  minimax: [value or null]
  replicate: [value or null]
-  zai: [value or null]
 ```

 Only set the selected provider's model; leave others as their current value or null.
@@ -11,7 +11,7 @@ description: EXTEND.md YAML schema for baoyu-image-gen user preferences
 ---
 version: 1

-default_provider: null      # google|openai|azure|openrouter|dashscope|minimax|replicate|zai|null (null = auto-detect)
+default_provider: null      # google|openai|azure|openrouter|dashscope|zai|minimax|replicate|null (null = auto-detect)

 default_quality: null       # normal|2k|null (null = use default: 2k)

@@ -19,15 +19,17 @@ default_aspect_ratio: null  # "16:9"|"1:1"|"4:3"|"3:4"|"2.35:1"|null

 default_image_size: null    # 1K|2K|4K|null (Google/OpenRouter, overrides quality)

+default_image_api_dialect: null  # openai-native|ratio-metadata|null (OpenAI-compatible gateways; null = use env/default)
+
 default_model:
  google: null              # e.g., "gemini-3-pro-image-preview", "gemini-3.1-flash-image-preview"
-  openai: null              # e.g., "gpt-image-1.5", "gpt-image-1"
-  azure: null               # Azure deployment name, e.g., "gpt-image-1.5" or "image-prod"
+  openai: null              # e.g., "gpt-image-2", "gpt-image-1.5", "gpt-image-1"
+  azure: null               # Azure deployment name, e.g., "gpt-image-2" or "image-prod"
  openrouter: null          # e.g., "google/gemini-3.1-flash-image-preview"
  dashscope: null           # e.g., "qwen-image-2.0-pro"
+  zai: null                 # e.g., "glm-image"
  minimax: null             # e.g., "image-01"
-  replicate: null           # e.g., "google/nano-banana-pro"
-  zai: null                 # e.g., "glm-image", "cogview-4-250304"
+  replicate: null           # e.g., "google/nano-banana-2"

 batch:
  max_workers: 10
@@ -50,10 +52,10 @@ batch:
    dashscope:
      concurrency: 3
      start_interval_ms: 1100
-    minimax:
+    zai:
      concurrency: 3
      start_interval_ms: 1100
-    zai:
+    minimax:
      concurrency: 3
      start_interval_ms: 1100
 ---
@@ -68,14 +70,15 @@ batch:
 | `default_quality` | string\|null | null | Default quality (null = 2k) |
 | `default_aspect_ratio` | string\|null | null | Default aspect ratio |
 | `default_image_size` | string\|null | null | Google/OpenRouter image size (overrides quality) |
+| `default_image_api_dialect` | string\|null | null | OpenAI-compatible image dialect (`openai-native` or `ratio-metadata`) |
 | `default_model.google` | string\|null | null | Google default model |
 | `default_model.openai` | string\|null | null | OpenAI default model |
 | `default_model.azure` | string\|null | null | Azure default deployment name |
 | `default_model.openrouter` | string\|null | null | OpenRouter default model |
 | `default_model.dashscope` | string\|null | null | DashScope default model |
+| `default_model.zai` | string\|null | null | Z.AI default model |
 | `default_model.minimax` | string\|null | null | MiniMax default model |
 | `default_model.replicate` | string\|null | null | Replicate default model |
-| `default_model.zai` | string\|null | null | Z.AI default model (glm-image / cogview-4-*) |
 | `batch.max_workers` | int\|null | 10 | Batch worker cap |
 | `batch.provider_limits.<provider>.concurrency` | int\|null | provider default | Max simultaneous requests per provider |
 | `batch.provider_limits.<provider>.start_interval_ms` | int\|null | provider default | Minimum gap between request starts per provider |
@@ -88,6 +91,7 @@ batch:
 version: 1
 default_provider: google
 default_quality: 2k
+default_image_api_dialect: null
 ---
 ```

@@ -99,15 +103,16 @@ default_provider: google
 default_quality: 2k
 default_aspect_ratio: "16:9"
 default_image_size: 2K
+default_image_api_dialect: null
 default_model:
  google: "gemini-3-pro-image-preview"
-  openai: "gpt-image-1.5"
-  azure: "gpt-image-1.5"
+  openai: "gpt-image-2"
+  azure: "gpt-image-2"
  openrouter: "google/gemini-3.1-flash-image-preview"
  dashscope: "qwen-image-2.0-pro"
-  minimax: "image-01"
-  replicate: "google/nano-banana-pro"
  zai: "glm-image"
+  minimax: "image-01"
+  replicate: "google/nano-banana-2"
 batch:
  max_workers: 10
  provider_limits:
@@ -117,14 +122,14 @@ batch:
    azure:
      concurrency: 3
      start_interval_ms: 1100
+    zai:
+      concurrency: 3
+      start_interval_ms: 1100
    openrouter:
      concurrency: 3
      start_interval_ms: 1100
    minimax:
      concurrency: 3
      start_interval_ms: 1100
-    zai:
-      concurrency: 3
-      start_interval_ms: 1100
 ---
 ```
@@ -17,6 +17,17 @@ Read when the user picks `--provider dashscope`, sets `default_model.dashscope`,
 - Default is `1664*928`
 - `qwen-image` currently has the same capability as `qwen-image-plus`

+**`wan2.7-image*`** — multimodal Wan 2.7 family. Members: `wan2.7-image-pro`, `wan2.7-image`.
+
+- Free-form `size` in `宽*高` format, plus aspect-ratio inference
+- `wan2.7-image-pro` text-to-image (no `--ref`): total pixels in `[768*768, 4096*4096]`, ratio in `[1:8, 8:1]`
+- `wan2.7-image-pro` with reference images and `wan2.7-image` (all scenarios): total pixels in `[768*768, 2048*2048]`, ratio in `[1:8, 8:1]`
+- Default: `1024*1024` (`--quality normal`) or `2048*2048` (`--quality 2k`); 4K requires explicit `--size`
+- Supports up to 9 reference images in `--ref` (image editing / multi-image fusion)
+- Reference images are sent inline as base64 (or passed through if the path is an `http(s)://` URL)
+- API does NOT use `prompt_extend`; the skill omits it for this family
+- The Wan 2.7 API defaults `n` to **4** in non-collage mode and bills per generated image. baoyu-image-gen forces `n: 1` and rejects `--n > 1` to avoid silently paying for and discarding extra images.
+
 **Legacy** — `z-image-turbo`, `z-image-ultra`, `wanx-v1`. Only use when the user explicitly asks for legacy behavior.

 ## Size Resolution
@@ -24,7 +35,8 @@ Read when the user picks `--provider dashscope`, sets `default_model.dashscope`,
 - `--size` wins over `--ar`
 - For `qwen-image-2.0*`: prefer explicit `--size`; otherwise infer from `--ar` using the recommended table below
 - For `qwen-image-max/plus/image`: only use the five fixed sizes; if the requested ratio doesn't fit, switch to `qwen-image-2.0-pro`
- `--quality` is a baoyu-imagine preset, not an official DashScope field. The mapping of `normal`/`2k` onto the `qwen-image-2.0*` table is an implementation choice, not an API guarantee
+- For `wan2.7-image*`: explicit `--size` is validated against the per-mode pixel/ratio limits; otherwise the size is derived from `--ar` and `--quality` (`normal` ≈ 1K, `2k` ≈ 2K). To request 4K with `wan2.7-image-pro` text-to-image, pass `--size` explicitly (e.g. `4096*4096`, `3840*2160`)
+- `--quality` is a baoyu-image-gen preset, not an official DashScope field. The mapping of `normal`/`2k` onto the `qwen-image-2.0*` and `wan2.7-image*` tables is an implementation choice, not an API guarantee

 ### Recommended `qwen-image-2.0*` sizes

@@ -39,12 +51,19 @@ Read when the user picks `--provider dashscope`, sets `default_model.dashscope`,
 | `16:9` | `1280*720` | `1920*1080` |
 | `21:9` | `1344*576` | `2048*872` |

+## Reference Images
+
+- Only `wan2.7-image-pro` and `wan2.7-image` accept `--ref`. Other DashScope models (qwen-image-2.0*, qwen-image-max/plus/image, legacy) reject `--ref` and the user is steered to a different provider/model.
+- Up to 9 reference images per request. Local files are inlined as base64 data URLs; `http(s)://` URLs are forwarded as-is.
+- Supplying any `--ref` automatically clamps the wan2.7-image-pro pixel ceiling from 4K to 2K (the API only supports 4K for pure text-to-image with no image input).
+
 ## Not Exposed

-DashScope APIs also support `negative_prompt`, `prompt_extend`, and `watermark`, but `baoyu-imagine` does not expose them as CLI flags today.
+DashScope APIs also support `negative_prompt`, `prompt_extend`, `watermark`, `thinking_mode`, `seed`, `bbox_list`, `enable_sequential`, and `color_palette`. `baoyu-image-gen` does not expose them as CLI flags today; the wan2.7 family relies on the API defaults (e.g. `thinking_mode=true`). The skill always sends `n=1` for wan2.7 — if you want grid/collage mode you currently need to call the API directly.

 ## Official References

 - [Qwen-Image API](https://help.aliyun.com/zh/model-studio/qwen-image-api)
 - [Text-to-image guide](https://help.aliyun.com/zh/model-studio/text-to-image)
 - [Qwen-Image Edit API](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api)
+- [Wan 2.7 image generation & editing API](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)
@@ -19,7 +19,7 @@ Read when the user picks `--provider minimax` or sets `default_model.minimax`. D

 - `--ref` files are sent as MiniMax `subject_reference`
 - `subject_reference[].type` is currently `character`
- Official docs say `image_file` supports public URLs or Base64 Data URLs; baoyu-imagine sends local refs as Data URLs
+- Official docs say `image_file` supports public URLs or Base64 Data URLs; baoyu-image-gen sends local refs as Data URLs
 - Recommended refs: front-facing portraits, JPG/JPEG/PNG, under 10MB

 ## Official References
@@ -1,6 +1,6 @@
 # Replicate

-Read when the user picks `--provider replicate`. Replicate support is intentionally scoped to model families baoyu-imagine can validate locally and save without dropping outputs.
+Read when the user picks `--provider replicate`. Replicate support is intentionally scoped to model families baoyu-image-gen can validate locally and save without dropping outputs.

 ## Supported Families

@@ -37,7 +37,7 @@ Read when the user picks `--provider replicate`. Replicate support is intentiona
 ## Guardrails

 - Replicate currently supports only single-output save semantics in this tool — keep `--n 1`
- If a model is outside the compatibility list above, baoyu-imagine treats it as prompt-only and rejects advanced local options instead of guessing a nano-banana-style schema
+- If a model is outside the compatibility list above, baoyu-image-gen treats it as prompt-only and rejects advanced local options instead of guessing a nano-banana-style schema

 ## Examples

@@ -6,7 +6,7 @@ Read when the user picks `--provider zai` or sets `default_model.zai`. Default m

 **`glm-image`** (recommended default)

- Text-to-image only in baoyu-imagine (no `--ref` support yet)
+- Text-to-image only in baoyu-image-gen (no `--ref` support yet)
 - Native `quality` options are `hd` and `standard`; this skill maps `2k → hd` and `normal → standard`
 - Recommended sizes: `1280x1280`, `1568x1056`, `1056x1568`, `1472x1088`, `1088x1472`, `1728x960`, `960x1728`
 - Custom `--size` requires width/height in `[1024, 2048]`, divisible by `32`, total pixels ≤ `2^22`
@@ -17,7 +17,7 @@ Read when the user picks `--provider zai` or sets `default_model.zai`. Default m

 ## Behavior Notes

- The sync API returns a temporary URL; baoyu-imagine downloads it and writes locally
+- The sync API returns a temporary URL; baoyu-image-gen downloads it and writes locally
 - `--ref` is not supported for Z.AI in this skill yet
 - The sync API returns a single image, so `--n > 1` is rejected

@@ -25,10 +25,13 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref so

 ```bash
 # OpenAI
-${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --model gpt-image-2

 # Azure OpenAI (model = deployment name)
-${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider azure --model gpt-image-1.5
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider azure --model gpt-image-2
+
+# OpenAI GPT Image 2 custom 4K size
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cinematic landscape" --image out.png --provider openai --model gpt-image-2 --size 3840x2160

 # Google with explicit model
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png
@@ -48,6 +51,12 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "为咖啡品牌设计一张 21:9
 # DashScope legacy fixed-size
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "一张电影感海报" --image out.png --provider dashscope --model qwen-image-max --size 1664x928

+# DashScope Wan 2.7 Image Pro (4K text-to-image)
+${BUN_X} {baseDir}/scripts/main.ts --prompt "一间有着精致窗户的花店" --image out.png --provider dashscope --model wan2.7-image-pro --size 4096x4096
+
+# DashScope Wan 2.7 Image with reference image (multi-image fusion)
+${BUN_X} {baseDir}/scripts/main.ts --prompt "把图2的涂鸦喷绘在图1的汽车上" --image out.png --provider dashscope --model wan2.7-image-pro --ref car.webp paint.webp
+
 # Z.AI GLM-image
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai

@@ -8,7 +8,7 @@ import test from "node:test";

 const execFileAsync = promisify(execFile);
 const repoRoot = path.resolve(import.meta.dirname, "..", "..", "..");
-const scriptPath = path.join(repoRoot, "skills", "baoyu-imagine", "scripts", "build-batch.ts");
+const scriptPath = path.join(repoRoot, "skills", "baoyu-image-gen", "scripts", "build-batch.ts");

 async function makeFixture(): Promise<{
  root: string;
@@ -16,7 +16,7 @@ async function makeFixture(): Promise<{
  promptsDir: string;
  outputPath: string;
 }> {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "baoyu-imagine-build-batch-"));
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "baoyu-image-gen-build-batch-"));
  const outlinePath = path.join(root, "outline.md");
  const promptsDir = path.join(root, "prompts");
  const outputPath = path.join(root, "batch.json");
@@ -42,7 +42,7 @@ async function runBuildBatch(args: string[]): Promise<void> {
  });
 }

-test("build-batch omits default model so baoyu-imagine can resolve env or EXTEND defaults", async () => {
+test("build-batch omits default model so baoyu-image-gen can resolve env or EXTEND defaults", async () => {
  const fixture = await makeFixture();

  await runBuildBatch([
@@ -36,8 +36,8 @@ Options:
  --output <path>      Path to output batch.json
  --images-dir <path>  Directory for generated images
  --refs-dir <path>    Directory holding reference images, relative to batch file (default: references)
-  --provider <name>    Provider for baoyu-imagine batch tasks (default: replicate)
-  --model <id>         Explicit model for baoyu-imagine batch tasks (default: resolved by baoyu-imagine config/env)
+  --provider <name>    Provider for baoyu-image-gen batch tasks (default: replicate)
+  --model <id>         Explicit model for baoyu-image-gen batch tasks (default: resolved by baoyu-image-gen config/env)
  --ar <ratio>         Aspect ratio for all tasks (default: 16:9)
  --quality <level>    Quality for all tasks (default: 2k)
  --jobs <count>       Recommended worker count metadata (optional)
@@ -13,10 +13,13 @@ import {
  getWorkerCount,
  isRetryableGenerationError,
  loadBatchTasks,
+  loadExtendConfig,
  mergeConfig,
  normalizeOutputImagePath,
  parseArgs,
+  parseOpenAIImageApiDialect,
  parseSimpleYaml,
+  validateReferenceImages,
 } from "./main.ts";

 function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
@@ -27,9 +30,12 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    provider: null,
    model: null,
    aspectRatio: null,
+    aspectRatioSource: null,
    size: null,
    quality: null,
    imageSize: null,
+    imageSizeSource: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -69,7 +75,7 @@ async function makeTempDir(prefix: string): Promise<string> {
  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
 }

-test("parseArgs parses the main image-gen CLI flags", () => {
+test("parseArgs parses the main baoyu-image-gen CLI flags", () => {
  const args = parseArgs([
    "--promptfiles",
    "prompts/system.md",
@@ -77,11 +83,13 @@ test("parseArgs parses the main image-gen CLI flags", () => {
    "--image",
    "out/hero",
    "--provider",
-    "openai",
+    "zai",
    "--quality",
    "2k",
    "--imageSize",
    "4k",
+    "--imageApiDialect",
+    "ratio-metadata",
    "--ref",
    "ref/one.png",
    "ref/two.jpg",
@@ -94,9 +102,12 @@ test("parseArgs parses the main image-gen CLI flags", () => {

  assert.deepEqual(args.promptFiles, ["prompts/system.md", "prompts/content.md"]);
  assert.equal(args.imagePath, "out/hero");
-  assert.equal(args.provider, "openai");
+  assert.equal(args.provider, "zai");
  assert.equal(args.quality, "2k");
+  assert.equal(args.aspectRatioSource, null);
  assert.equal(args.imageSize, "4K");
+  assert.equal(args.imageSizeSource, "cli");
+  assert.equal(args.imageApiDialect, "ratio-metadata");
  assert.deepEqual(args.referenceImages, ["ref/one.png", "ref/two.jpg"]);
  assert.equal(args.n, 3);
  assert.equal(args.jobs, 5);
@@ -113,6 +124,15 @@ test("parseArgs falls back to positional prompt and rejects invalid provider", (
  );
 });

+test("validateReferenceImages can skip remote URLs for providers that support them", async () => {
+  await validateReferenceImages(["https://example.com/ref.png"], { allowRemoteUrls: true });
+
+  await assert.rejects(
+    () => validateReferenceImages(["https://example.com/ref.png"]),
+    /Reference image not found/,
+  );
+});
+
 test("parseSimpleYaml parses nested defaults and provider limits", () => {
  const yaml = `
 version: 2
@@ -120,9 +140,11 @@ default_provider: openrouter
 default_quality: normal
 default_aspect_ratio: '16:9'
 default_image_size: 2K
+default_image_api_dialect: ratio-metadata
 default_model:
  google: gemini-3-pro-image-preview
-  openai: gpt-image-1.5
+  openai: gpt-image-2
+  zai: glm-image
  azure: image-prod
  minimax: image-01
 batch:
@@ -133,6 +155,9 @@ batch:
      start_interval_ms: 900
    openai:
      concurrency: 4
+    zai:
+      concurrency: 2
+      start_interval_ms: 1000
    minimax:
      concurrency: 2
      start_interval_ms: 1400
@@ -148,8 +173,10 @@ batch:
  assert.equal(config.default_quality, "normal");
  assert.equal(config.default_aspect_ratio, "16:9");
  assert.equal(config.default_image_size, "2K");
+  assert.equal(config.default_image_api_dialect, "ratio-metadata");
  assert.equal(config.default_model?.google, "gemini-3-pro-image-preview");
-  assert.equal(config.default_model?.openai, "gpt-image-1.5");
+  assert.equal(config.default_model?.openai, "gpt-image-2");
+  assert.equal(config.default_model?.zai, "glm-image");
  assert.equal(config.default_model?.azure, "image-prod");
  assert.equal(config.default_model?.minimax, "image-01");
  assert.equal(config.batch?.max_workers, 8);
@@ -160,6 +187,10 @@ batch:
  assert.deepEqual(config.batch?.provider_limits?.openai, {
    concurrency: 4,
  });
+  assert.deepEqual(config.batch?.provider_limits?.zai, {
+    concurrency: 2,
+    start_interval_ms: 1000,
+  });
  assert.deepEqual(config.batch?.provider_limits?.minimax, {
    concurrency: 2,
    start_interval_ms: 1400,
@@ -170,6 +201,61 @@ batch:
  });
 });

+test("loadExtendConfig renames legacy EXTEND.md when the new path is missing", async () => {
+  const root = await makeTempDir("baoyu-image-gen-extend-");
+  const cwd = path.join(root, "project");
+  const home = path.join(root, "home");
+  const legacyPath = path.join(cwd, ".baoyu-skills", "baoyu-imagine", "EXTEND.md");
+  const currentPath = path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md");
+
+  await fs.mkdir(path.dirname(legacyPath), { recursive: true });
+  await fs.mkdir(home, { recursive: true });
+  await fs.writeFile(legacyPath, `---
+default_provider: google
+default_quality: 2k
+---
+`);
+
+  const config = await loadExtendConfig(cwd, home);
+
+  assert.equal(config.default_provider, "google");
+  assert.equal(config.default_quality, "2k");
+  await fs.access(currentPath);
+  await assert.rejects(() => fs.access(legacyPath));
+});
+
+test("loadExtendConfig leaves legacy EXTEND.md untouched when both paths exist", async () => {
+  const root = await makeTempDir("baoyu-image-gen-extend-dual-");
+  const cwd = path.join(root, "project");
+  const home = path.join(root, "home");
+  const legacyPath = path.join(cwd, ".baoyu-skills", "baoyu-imagine", "EXTEND.md");
+  const currentPath = path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md");
+
+  await fs.mkdir(path.dirname(legacyPath), { recursive: true });
+  await fs.mkdir(path.dirname(currentPath), { recursive: true });
+  await fs.mkdir(home, { recursive: true });
+  await fs.writeFile(legacyPath, `---
+default_provider: google
+---
+`);
+  await fs.writeFile(currentPath, `---
+default_provider: openai
+---
+`);
+
+  const config = await loadExtendConfig(cwd, home);
+
+  assert.equal(config.default_provider, "openai");
+  assert.equal(await fs.readFile(legacyPath, "utf8"), `---
+default_provider: google
+---
+`);
+  assert.equal(await fs.readFile(currentPath, "utf8"), `---
+default_provider: openai
+---
+`);
+});
+
 test("mergeConfig only fills values missing from CLI args", () => {
  const merged = mergeConfig(
    makeArgs({
@@ -183,13 +269,48 @@ test("mergeConfig only fills values missing from CLI args", () => {
      default_quality: "2k",
      default_aspect_ratio: "3:2",
      default_image_size: "2K",
+      default_image_api_dialect: "ratio-metadata",
    } satisfies Partial<ExtendConfig>,
  );

  assert.equal(merged.provider, "openai");
  assert.equal(merged.quality, "2k");
  assert.equal(merged.aspectRatio, "3:2");
+  assert.equal(merged.aspectRatioSource, "config");
  assert.equal(merged.imageSize, "4K");
+  assert.equal(merged.imageSizeSource, "cli");
+  assert.equal(merged.imageApiDialect, "ratio-metadata");
+});
+
+test("mergeConfig tags inherited imageSize defaults so providers can ignore incompatible config", () => {
+  const merged = mergeConfig(
+    makeArgs(),
+    {
+      default_image_size: "2K",
+    } satisfies Partial<ExtendConfig>,
+  );
+
+  assert.equal(merged.imageSize, "2K");
+  assert.equal(merged.imageSizeSource, "config");
+});
+
+test("mergeConfig falls back to OPENAI_IMAGE_API_DIALECT when CLI and EXTEND are unset", (t) => {
+  useEnv(t, {
+    OPENAI_IMAGE_API_DIALECT: "ratio-metadata",
+  });
+
+  const merged = mergeConfig(makeArgs(), {});
+  assert.equal(merged.imageApiDialect, "ratio-metadata");
+});
+
+test("parseOpenAIImageApiDialect validates supported values", () => {
+  assert.equal(parseOpenAIImageApiDialect("openai-native"), "openai-native");
+  assert.equal(parseOpenAIImageApiDialect("ratio-metadata"), "ratio-metadata");
+  assert.equal(parseOpenAIImageApiDialect(null), null);
+  assert.throws(
+    () => parseOpenAIImageApiDialect("gateway-magic"),
+    /Invalid OpenAI image API dialect/,
+  );
 });

 test("detectProvider rejects non-ref-capable providers and prefers Google first when multiple keys exist", (t) => {
@@ -197,7 +318,7 @@ test("detectProvider rejects non-ref-capable providers and prefers Google first
    () =>
      detectProvider(
        makeArgs({
-          provider: "dashscope",
+          provider: "zai",
          referenceImages: ["ref.png"],
        }),
      ),
@@ -260,6 +381,27 @@ test("detectProvider selects Azure when only Azure credentials are configured",
  );
 });

+test("detectProvider selects Z.AI when credentials are present or the model id matches", (t) => {
+  useEnv(t, {
+    GOOGLE_API_KEY: null,
+    OPENAI_API_KEY: null,
+    AZURE_OPENAI_API_KEY: null,
+    AZURE_OPENAI_BASE_URL: null,
+    OPENROUTER_API_KEY: null,
+    DASHSCOPE_API_KEY: null,
+    ZAI_API_KEY: "zai-key",
+    BIGMODEL_API_KEY: null,
+    MINIMAX_API_KEY: null,
+    REPLICATE_API_TOKEN: null,
+    JIMENG_ACCESS_KEY_ID: null,
+    JIMENG_SECRET_ACCESS_KEY: null,
+    ARK_API_KEY: null,
+  });
+
+  assert.equal(detectProvider(makeArgs()), "zai");
+  assert.equal(detectProvider(makeArgs({ model: "glm-image" })), "zai");
+});
+
 test("detectProvider infers Seedream from model id and allows Seedream reference-image workflows", (t) => {
  useEnv(t, {
    GOOGLE_API_KEY: null,
@@ -294,6 +436,33 @@ test("detectProvider infers Seedream from model id and allows Seedream reference
  );
 });

+test("detectProvider allows DashScope reference-image workflows when explicitly chosen for wan2.7 models", (t) => {
+  useEnv(t, {
+    GOOGLE_API_KEY: null,
+    OPENAI_API_KEY: null,
+    AZURE_OPENAI_API_KEY: null,
+    AZURE_OPENAI_BASE_URL: null,
+    OPENROUTER_API_KEY: null,
+    DASHSCOPE_API_KEY: "dashscope-key",
+    MINIMAX_API_KEY: null,
+    REPLICATE_API_TOKEN: null,
+    JIMENG_ACCESS_KEY_ID: null,
+    JIMENG_SECRET_ACCESS_KEY: null,
+    ARK_API_KEY: null,
+  });
+
+  assert.equal(
+    detectProvider(
+      makeArgs({
+        provider: "dashscope",
+        model: "wan2.7-image-pro",
+        referenceImages: ["ref.png"],
+      }),
+    ),
+    "dashscope",
+  );
+});
+
 test("detectProvider selects MiniMax when only MiniMax credentials are configured or the model id matches", (t) => {
  useEnv(t, {
    GOOGLE_API_KEY: null,
@@ -319,6 +488,7 @@ test("batch worker and provider-rate-limit configuration prefer env over EXTEND
    BAOYU_IMAGE_GEN_MAX_WORKERS: "12",
    BAOYU_IMAGE_GEN_GOOGLE_CONCURRENCY: "5",
    BAOYU_IMAGE_GEN_GOOGLE_START_INTERVAL_MS: "450",
+    BAOYU_IMAGE_GEN_ZAI_CONCURRENCY: "4",
  });

  const extendConfig: Partial<ExtendConfig> = {
@@ -329,6 +499,10 @@ test("batch worker and provider-rate-limit configuration prefer env over EXTEND
          concurrency: 2,
          start_interval_ms: 900,
        },
+        zai: {
+          concurrency: 1,
+          start_interval_ms: 1200,
+        },
        minimax: {
          concurrency: 1,
          start_interval_ms: 1500,
@@ -342,6 +516,10 @@ test("batch worker and provider-rate-limit configuration prefer env over EXTEND
    concurrency: 5,
    startIntervalMs: 450,
  });
+  assert.deepEqual(getConfiguredProviderRateLimits(extendConfig).zai, {
+    concurrency: 4,
+    startIntervalMs: 1200,
+  });
  assert.deepEqual(getConfiguredProviderRateLimits(extendConfig).minimax, {
    concurrency: 1,
    startIntervalMs: 1500,
@@ -363,7 +541,7 @@ test("loadBatchTasks and createTaskArgs resolve batch-relative paths", async (t)
          id: "hero",
          promptFiles: ["prompts/hero.md"],
          image: "out/hero",
-          ref: ["refs/hero.png"],
+          ref: ["refs/hero.png", "https://example.com/ref.png"],
          ar: "16:9",
        },
      ],
@@ -379,6 +557,7 @@ test("loadBatchTasks and createTaskArgs resolve batch-relative paths", async (t)
    makeArgs({
      provider: "replicate",
      quality: "2k",
+      imageApiDialect: "ratio-metadata",
      json: true,
    }),
    loaded.tasks[0]!,
@@ -391,10 +570,12 @@ test("loadBatchTasks and createTaskArgs resolve batch-relative paths", async (t)
  assert.equal(taskArgs.imagePath, path.join(loaded.batchDir, "out/hero"));
  assert.deepEqual(taskArgs.referenceImages, [
    path.join(loaded.batchDir, "refs/hero.png"),
+    "https://example.com/ref.png",
  ]);
  assert.equal(taskArgs.provider, "replicate");
  assert.equal(taskArgs.aspectRatio, "16:9");
  assert.equal(taskArgs.quality, "2k");
+  assert.equal(taskArgs.imageApiDialect, "ratio-metadata");
  assert.equal(taskArgs.json, true);
 });

@@ -408,5 +589,35 @@ test("path normalization, worker count, and retry classification follow expected
  assert.equal(getWorkerCount(5, 0, 4), 1);

  assert.equal(isRetryableGenerationError(new Error("API error (401): denied")), false);
+  assert.equal(
+    isRetryableGenerationError(
+      new Error("Replicate returned 2 outputs, but baoyu-image-gen currently supports saving exactly one image per request."),
+    ),
+    false,
+  );
+  assert.equal(
+    isRetryableGenerationError(
+      new Error("DashScope wan2.7 image models accept at most 9 reference images. Received 10."),
+    ),
+    false,
+  );
+  assert.equal(
+    isRetryableGenerationError(
+      new Error("DashScope wan2.7 image models in baoyu-image-gen support exactly one output image per request."),
+    ),
+    false,
+  );
+  assert.equal(
+    isRetryableGenerationError(
+      new Error("DashScope wan2.7 image models support aspect ratios in [1:8, 8:1]."),
+    ),
+    false,
+  );
+  assert.equal(
+    isRetryableGenerationError(
+      new Error("DashScope wan2.7-image requires total pixels between 768*768 and 2048*2048."),
+    ),
+    false,
+  );
  assert.equal(isRetryableGenerationError(new Error("socket hang up")), true);
 });
@@ -2,12 +2,13 @@ import path from "node:path";
 import process from "node:process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import type {
  BatchFile,
  BatchTaskInput,
  CliArgs,
  ExtendConfig,
+  OpenAIImageApiDialect,
  Provider,
 } from "./types";

@@ -58,11 +59,11 @@ const DEFAULT_PROVIDER_RATE_LIMITS: Record<Provider, ProviderRateLimit> = {
  openai: { concurrency: 3, startIntervalMs: 1100 },
  openrouter: { concurrency: 3, startIntervalMs: 1100 },
  dashscope: { concurrency: 3, startIntervalMs: 1100 },
+  zai: { concurrency: 3, startIntervalMs: 1100 },
  minimax: { concurrency: 3, startIntervalMs: 1100 },
  jimeng: { concurrency: 3, startIntervalMs: 1100 },
  seedream: { concurrency: 3, startIntervalMs: 1100 },
  azure: { concurrency: 3, startIntervalMs: 1100 },
-  zai: { concurrency: 3, startIntervalMs: 1100 },
 };

 function printUsage(): void {
@@ -77,14 +78,15 @@ Options:
  --image <path>            Output image path (required in single-image mode)
  --batchfile <path>        JSON batch file for multi-image generation
  --jobs <count>            Worker count for batch mode (default: auto, max from config, built-in default 10)
-  --provider google|openai|openrouter|dashscope|minimax|replicate|jimeng|seedream|azure|zai  Force provider (auto-detect by default)
+  --provider google|openai|openrouter|dashscope|zai|minimax|replicate|jimeng|seedream|azure  Force provider (auto-detect by default)
  -m, --model <id>          Model ID
  --ar <ratio>              Aspect ratio (e.g., 16:9, 1:1, 4:3)
  --size <WxH>              Size (e.g., 1024x1024)
  --quality normal|2k       Quality preset (default: 2k)
  --imageSize 1K|2K|4K      Image size for Google/OpenRouter (default: from quality)
-  --ref <files...>          Reference images (Google, OpenAI, Azure, OpenRouter, Replicate, MiniMax, or Seedream 4.0/4.5/5.0)
-  --n <count>               Number of images for the current task (default: 1)
+  --imageApiDialect <id>    OpenAI-compatible image dialect: openai-native|ratio-metadata
+  --ref <files...>          Reference images (Google, OpenAI, Azure, OpenRouter, Replicate supported families, MiniMax, Seedream 4.0/4.5/5.0, or DashScope wan2.7-image*)
+  --n <count>               Number of images for the current task (default: 1; Replicate currently requires 1)
  --json                    JSON output
  -h, --help                Show help

@@ -97,7 +99,7 @@ Batch file format:
        "promptFiles": ["prompts/hero.md"],
        "image": "out/hero.png",
        "provider": "replicate",
-        "model": "google/nano-banana-pro",
+        "model": "google/nano-banana-2",
        "ar": "16:9"
      }
    ]
@@ -107,6 +109,7 @@ Behavior:
  - Batch mode automatically runs in parallel when pending tasks >= 2
  - Each image retries automatically up to 3 attempts
  - Batch summary reports success count, failure count, and per-image errors
+  - Replicate currently supports single-image save semantics only; --n must stay at 1

 Environment variables:
  OPENAI_API_KEY            OpenAI API key
@@ -114,30 +117,33 @@ Environment variables:
  GOOGLE_API_KEY            Google API key
  GEMINI_API_KEY            Gemini API key (alias for GOOGLE_API_KEY)
  DASHSCOPE_API_KEY         DashScope API key
+  ZAI_API_KEY               Z.AI API key
+  BIGMODEL_API_KEY          Backward-compatible alias for Z.AI API key
  MINIMAX_API_KEY           MiniMax API key
  REPLICATE_API_TOKEN       Replicate API token
  JIMENG_ACCESS_KEY_ID      Jimeng Access Key ID
  JIMENG_SECRET_ACCESS_KEY  Jimeng Secret Access Key
  ARK_API_KEY               Seedream/Ark API key
-  ZAI_API_KEY               Z.AI API key (alias: BIGMODEL_API_KEY)
-  BIGMODEL_API_KEY          Z.AI API key alias (legacy BigModel credentials)
-  OPENAI_IMAGE_MODEL        Default OpenAI model (gpt-image-1.5)
+  OPENAI_IMAGE_MODEL        Default OpenAI model (gpt-image-2)
  OPENROUTER_IMAGE_MODEL    Default OpenRouter model (google/gemini-3.1-flash-image-preview)
  GOOGLE_IMAGE_MODEL        Default Google model (gemini-3-pro-image-preview)
  DASHSCOPE_IMAGE_MODEL     Default DashScope model (qwen-image-2.0-pro)
+  ZAI_IMAGE_MODEL           Default Z.AI model (glm-image)
+  BIGMODEL_IMAGE_MODEL      Backward-compatible alias for Z.AI model (glm-image)
  MINIMAX_IMAGE_MODEL       Default MiniMax model (image-01)
-  REPLICATE_IMAGE_MODEL     Default Replicate model (google/nano-banana-pro)
+  REPLICATE_IMAGE_MODEL     Default Replicate model (google/nano-banana-2)
  JIMENG_IMAGE_MODEL        Default Jimeng model (jimeng_t2i_v40)
  SEEDREAM_IMAGE_MODEL      Default Seedream model (doubao-seedream-5-0-260128)
-  ZAI_IMAGE_MODEL           Default Z.AI model (glm-image)
-  BIGMODEL_IMAGE_MODEL      Z.AI model alias (legacy BigModel variable)
  OPENAI_BASE_URL           Custom OpenAI endpoint
+  OPENAI_IMAGE_API_DIALECT  OpenAI-compatible image dialect (openai-native|ratio-metadata)
  OPENAI_IMAGE_USE_CHAT     Use /chat/completions instead of /images/generations (true|false)
  OPENROUTER_BASE_URL       Custom OpenRouter endpoint
  OPENROUTER_HTTP_REFERER   Optional app URL for OpenRouter attribution
  OPENROUTER_TITLE          Optional app name for OpenRouter attribution
  GOOGLE_BASE_URL           Custom Google endpoint
  DASHSCOPE_BASE_URL        Custom DashScope endpoint
+  ZAI_BASE_URL              Custom Z.AI endpoint
+  BIGMODEL_BASE_URL         Backward-compatible alias for Z.AI endpoint
  MINIMAX_BASE_URL          Custom MiniMax endpoint
  REPLICATE_BASE_URL        Custom Replicate endpoint
  JIMENG_BASE_URL           Custom Jimeng endpoint
@@ -145,10 +151,8 @@ Environment variables:
  AZURE_OPENAI_BASE_URL     Azure OpenAI resource or deployment endpoint
  AZURE_OPENAI_DEPLOYMENT   Default Azure deployment name
  AZURE_API_VERSION         Azure API version (default: 2025-04-01-preview)
-  AZURE_OPENAI_IMAGE_MODEL  Backward-compatible Azure deployment/model alias (defaults to gpt-image-1.5)
+  AZURE_OPENAI_IMAGE_MODEL  Backward-compatible Azure deployment/model alias (defaults to gpt-image-2)
  SEEDREAM_BASE_URL         Custom Seedream endpoint
-  ZAI_BASE_URL              Custom Z.AI endpoint (defaults to https://api.z.ai/api/paas/v4)
-  BIGMODEL_BASE_URL         Z.AI endpoint alias (legacy BigModel variable)
  BAOYU_IMAGE_GEN_MAX_WORKERS  Override batch worker cap
  BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY  Override provider concurrency
  BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS  Override provider start gap in ms
@@ -164,9 +168,12 @@ export function parseArgs(argv: string[]): CliArgs {
    provider: null,
    model: null,
    aspectRatio: null,
+    aspectRatioSource: null,
    size: null,
    quality: null,
    imageSize: null,
+    imageSizeSource: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -246,12 +253,12 @@ export function parseArgs(argv: string[]): CliArgs {
        v !== "openai" &&
        v !== "openrouter" &&
        v !== "dashscope" &&
+        v !== "zai" &&
        v !== "minimax" &&
        v !== "replicate" &&
        v !== "jimeng" &&
        v !== "seedream" &&
-        v !== "azure" &&
-        v !== "zai"
+        v !== "azure"
      ) {
        throw new Error(`Invalid provider: ${v}`);
      }
@@ -270,6 +277,7 @@ export function parseArgs(argv: string[]): CliArgs {
      const v = argv[++i];
      if (!v) throw new Error("Missing value for --ar");
      out.aspectRatio = v;
+      out.aspectRatioSource = "cli";
      continue;
    }

@@ -291,6 +299,16 @@ export function parseArgs(argv: string[]): CliArgs {
      const v = argv[++i]?.toUpperCase();
      if (v !== "1K" && v !== "2K" && v !== "4K") throw new Error(`Invalid imageSize: ${v}`);
      out.imageSize = v;
+      out.imageSizeSource = "cli";
+      continue;
+    }
+
+    if (a === "--imageApiDialect") {
+      const v = argv[++i];
+      if (v !== "openai-native" && v !== "ratio-metadata") {
+        throw new Error(`Invalid imageApiDialect: ${v}`);
+      }
+      out.imageApiDialect = v;
      continue;
    }

@@ -397,18 +415,21 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
        config.default_aspect_ratio = cleaned === "null" ? null : cleaned;
      } else if (key === "default_image_size") {
        config.default_image_size = value === "null" ? null : value as "1K" | "2K" | "4K";
+      } else if (key === "default_image_api_dialect") {
+        config.default_image_api_dialect =
+          value === "null" ? null : parseOpenAIImageApiDialect(value);
      } else if (key === "default_model") {
        config.default_model = {
          google: null,
          openai: null,
          openrouter: null,
          dashscope: null,
+          zai: null,
          minimax: null,
          replicate: null,
          jimeng: null,
          seedream: null,
          azure: null,
-          zai: null,
        };
        currentKey = "default_model";
        currentProvider = null;
@@ -432,12 +453,12 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
          key === "openai" ||
          key === "openrouter" ||
          key === "dashscope" ||
+          key === "zai" ||
          key === "minimax" ||
          key === "replicate" ||
          key === "jimeng" ||
          key === "seedream" ||
-          key === "azure" ||
-          key === "zai"
+          key === "azure"
        )
      ) {
        config.batch ??= {};
@@ -451,12 +472,12 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
          key === "openai" ||
          key === "openrouter" ||
          key === "dashscope" ||
+          key === "zai" ||
          key === "minimax" ||
          key === "replicate" ||
          key === "jimeng" ||
          key === "seedream" ||
-          key === "azure" ||
-          key === "zai"
+          key === "azure"
        )
      ) {
        const cleaned = value.replace(/['"]/g, "");
@@ -482,14 +503,58 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
  return config;
 }

-async function loadExtendConfig(): Promise<Partial<ExtendConfig>> {
-  const home = homedir();
-  const cwd = process.cwd();
+export function parseOpenAIImageApiDialect(
+  value: string | undefined | null
+): OpenAIImageApiDialect | null {
+  if (!value) return null;
+  const normalized = value.replace(/['"]/g, "").trim();
+  if (normalized === "openai-native" || normalized === "ratio-metadata") return normalized;
+  throw new Error(`Invalid OpenAI image API dialect: ${value}`);
+}

-  const paths = [
-    path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
-    path.join(home, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
+type ExtendConfigPathPair = {
+  current: string;
+  legacy: string;
+};
+
+function getExtendConfigPathPairs(cwd: string, home: string): ExtendConfigPathPair[] {
+  return [
+    {
+      current: path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
+      legacy: path.join(cwd, ".baoyu-skills", "baoyu-imagine", "EXTEND.md"),
+    },
+    {
+      current: path.join(home, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
+      legacy: path.join(home, ".baoyu-skills", "baoyu-imagine", "EXTEND.md"),
+    },
  ];
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function migrateLegacyExtendConfig(cwd: string, home: string): Promise<void> {
+  for (const { current, legacy } of getExtendConfigPathPairs(cwd, home)) {
+    const [hasCurrent, hasLegacy] = await Promise.all([exists(current), exists(legacy)]);
+    if (hasCurrent || !hasLegacy) continue;
+    await mkdir(path.dirname(current), { recursive: true });
+    await rename(legacy, current);
+  }
+}
+
+export async function loadExtendConfig(
+  cwd = process.cwd(),
+  home = homedir(),
+): Promise<Partial<ExtendConfig>> {
+  await migrateLegacyExtendConfig(cwd, home);
+
+  const paths = getExtendConfigPathPairs(cwd, home).map(({ current }) => current);

  for (const p of paths) {
    try {
@@ -506,12 +571,25 @@ async function loadExtendConfig(): Promise<Partial<ExtendConfig>> {
 }

 export function mergeConfig(args: CliArgs, extend: Partial<ExtendConfig>): CliArgs {
+  const aspectRatio = args.aspectRatio ?? extend.default_aspect_ratio ?? null;
+  const imageSize = args.imageSize ?? extend.default_image_size ?? null;
+  const imageApiDialect =
+    args.imageApiDialect ??
+    extend.default_image_api_dialect ??
+    parseOpenAIImageApiDialect(process.env.OPENAI_IMAGE_API_DIALECT);
  return {
    ...args,
    provider: args.provider ?? extend.default_provider ?? null,
    quality: args.quality ?? extend.default_quality ?? null,
-    aspectRatio: args.aspectRatio ?? extend.default_aspect_ratio ?? null,
-    imageSize: args.imageSize ?? extend.default_image_size ?? null,
+    aspectRatio,
+    aspectRatioSource:
+      args.aspectRatioSource ??
+      (args.aspectRatio !== null ? "cli" : (aspectRatio !== null ? "config" : null)),
+    imageSize,
+    imageSizeSource:
+      args.imageSizeSource ??
+      (args.imageSize !== null ? "cli" : (imageSize !== null ? "config" : null)),
+    imageApiDialect,
  };
 }

@@ -547,14 +625,14 @@ export function getConfiguredProviderRateLimits(
    openai: { ...DEFAULT_PROVIDER_RATE_LIMITS.openai },
    openrouter: { ...DEFAULT_PROVIDER_RATE_LIMITS.openrouter },
    dashscope: { ...DEFAULT_PROVIDER_RATE_LIMITS.dashscope },
+    zai: { ...DEFAULT_PROVIDER_RATE_LIMITS.zai },
    minimax: { ...DEFAULT_PROVIDER_RATE_LIMITS.minimax },
    jimeng: { ...DEFAULT_PROVIDER_RATE_LIMITS.jimeng },
    seedream: { ...DEFAULT_PROVIDER_RATE_LIMITS.seedream },
    azure: { ...DEFAULT_PROVIDER_RATE_LIMITS.azure },
-    zai: { ...DEFAULT_PROVIDER_RATE_LIMITS.zai },
  };

-  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "minimax", "jimeng", "seedream", "azure", "zai"] as Provider[]) {
+  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "zai", "minimax", "jimeng", "seedream", "azure"] as Provider[]) {
    const envPrefix = `BAOYU_IMAGE_GEN_${provider.toUpperCase()}`;
    const extendLimit = extendConfig.batch?.provider_limits?.[provider];
    configured[provider] = {
@@ -606,6 +684,7 @@ function inferProviderFromModel(model: string | null): Provider | null {
  const normalized = model.trim();
  if (normalized.includes("seedream") || normalized.includes("seededit")) return "seedream";
  if (normalized === "image-01" || normalized === "image-01-live") return "minimax";
+  if (normalized === "glm-image" || normalized === "cogview-4-250304") return "zai";
  return null;
 }

@@ -619,10 +698,11 @@ export function detectProvider(args: CliArgs): Provider {
    args.provider !== "openrouter" &&
    args.provider !== "replicate" &&
    args.provider !== "seedream" &&
-    args.provider !== "minimax"
+    args.provider !== "minimax" &&
+    args.provider !== "dashscope"
  ) {
    throw new Error(
-      "Reference images require a ref-capable provider. Use --provider google (Gemini multimodal), --provider openai (GPT Image edits), --provider azure (Azure OpenAI), --provider openrouter (OpenRouter multimodal), --provider replicate, --provider seedream for supported Seedream models, or --provider minimax for MiniMax subject-reference workflows."
+      "Reference images require a ref-capable provider. Use --provider google (Gemini multimodal), --provider openai (GPT Image edits), --provider azure (Azure OpenAI), --provider openrouter (OpenRouter multimodal), --provider replicate, --provider dashscope with a wan2.7 image model, --provider seedream for supported Seedream models, or --provider minimax for MiniMax subject-reference workflows."
    );
  }

@@ -633,11 +713,11 @@ export function detectProvider(args: CliArgs): Provider {
  const hasOpenai = !!process.env.OPENAI_API_KEY;
  const hasOpenrouter = !!process.env.OPENROUTER_API_KEY;
  const hasDashscope = !!process.env.DASHSCOPE_API_KEY;
+  const hasZai = !!(process.env.ZAI_API_KEY || process.env.BIGMODEL_API_KEY);
  const hasMinimax = !!process.env.MINIMAX_API_KEY;
  const hasReplicate = !!process.env.REPLICATE_API_TOKEN;
  const hasJimeng = !!(process.env.JIMENG_ACCESS_KEY_ID && process.env.JIMENG_SECRET_ACCESS_KEY);
  const hasSeedream = !!process.env.ARK_API_KEY;
-  const hasZai = !!(process.env.ZAI_API_KEY || process.env.BIGMODEL_API_KEY);
  const modelProvider = inferProviderFromModel(args.model);

  if (modelProvider === "seedream") {
@@ -654,6 +734,13 @@ export function detectProvider(args: CliArgs): Provider {
    return "minimax";
  }

+  if (modelProvider === "zai") {
+    if (!hasZai) {
+      throw new Error("Model looks like a Z.AI image model, but ZAI_API_KEY is not set.");
+    }
+    return "zai";
+  }
+
  if (args.referenceImages.length > 0) {
    if (hasGoogle) return "google";
    if (hasOpenai) return "openai";
@@ -673,24 +760,40 @@ export function detectProvider(args: CliArgs): Provider {
    hasAzure && "azure",
    hasOpenrouter && "openrouter",
    hasDashscope && "dashscope",
+    hasZai && "zai",
    hasMinimax && "minimax",
    hasReplicate && "replicate",
    hasJimeng && "jimeng",
    hasSeedream && "seedream",
-    hasZai && "zai",
  ].filter(Boolean) as Provider[];

  if (available.length === 1) return available[0]!;
  if (available.length > 1) return available[0]!;

  throw new Error(
-    "No API key found. Set GOOGLE_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY+AZURE_OPENAI_BASE_URL, OPENROUTER_API_KEY, DASHSCOPE_API_KEY, MINIMAX_API_KEY, REPLICATE_API_TOKEN, JIMENG keys, ARK_API_KEY, or ZAI_API_KEY/BIGMODEL_API_KEY.\n" +
+    "No API key found. Set GOOGLE_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY+AZURE_OPENAI_BASE_URL, OPENROUTER_API_KEY, DASHSCOPE_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, REPLICATE_API_TOKEN, JIMENG keys, or ARK_API_KEY.\n" +
      "Create ~/.baoyu-skills/.env or <cwd>/.baoyu-skills/.env with your keys."
  );
 }

-export async function validateReferenceImages(referenceImages: string[]): Promise<void> {
+export type ReferenceImageValidationOptions = {
+  allowRemoteUrls?: boolean;
+};
+
+function isRemoteReferenceImage(refPath: string): boolean {
+  return /^https?:\/\//i.test(refPath);
+}
+
+function shouldAllowRemoteReferenceImages(provider: Provider | null): boolean {
+  return provider === "dashscope";
+}
+
+export async function validateReferenceImages(
+  referenceImages: string[],
+  options: ReferenceImageValidationOptions = {},
+): Promise<void> {
  for (const refPath of referenceImages) {
+    if (options.allowRemoteUrls && isRemoteReferenceImage(refPath)) continue;
    const fullPath = path.resolve(refPath);
    try {
      await access(fullPath);
@@ -716,6 +819,12 @@ export function isRetryableGenerationError(error: unknown): boolean {
    "API error (403)",
    "API error (404)",
    "temporarily disabled",
+    "supports saving exactly one image",
+    "supports only",
+    "support exactly one output image",
+    "support aspect ratios in",
+    "requires total pixels between",
+    "accept at most",
  ];
  return !nonRetryableMarkers.some((marker) => msg.includes(marker));
 }
@@ -723,13 +832,13 @@ export function isRetryableGenerationError(error: unknown): boolean {
 async function loadProviderModule(provider: Provider): Promise<ProviderModule> {
  if (provider === "google") return (await import("./providers/google")) as ProviderModule;
  if (provider === "dashscope") return (await import("./providers/dashscope")) as ProviderModule;
+  if (provider === "zai") return (await import("./providers/zai")) as ProviderModule;
  if (provider === "minimax") return (await import("./providers/minimax")) as ProviderModule;
  if (provider === "replicate") return (await import("./providers/replicate")) as ProviderModule;
  if (provider === "openrouter") return (await import("./providers/openrouter")) as ProviderModule;
  if (provider === "jimeng") return (await import("./providers/jimeng")) as ProviderModule;
  if (provider === "seedream") return (await import("./providers/seedream")) as ProviderModule;
  if (provider === "azure") return (await import("./providers/azure")) as ProviderModule;
-  if (provider === "zai") return (await import("./providers/zai")) as ProviderModule;
  return (await import("./providers/openai")) as ProviderModule;
 }

@@ -755,12 +864,12 @@ function getModelForProvider(
      return extendConfig.default_model.openrouter;
    }
    if (provider === "dashscope" && extendConfig.default_model.dashscope) return extendConfig.default_model.dashscope;
+    if (provider === "zai" && extendConfig.default_model.zai) return extendConfig.default_model.zai;
    if (provider === "minimax" && extendConfig.default_model.minimax) return extendConfig.default_model.minimax;
    if (provider === "replicate" && extendConfig.default_model.replicate) return extendConfig.default_model.replicate;
    if (provider === "jimeng" && extendConfig.default_model.jimeng) return extendConfig.default_model.jimeng;
    if (provider === "seedream" && extendConfig.default_model.seedream) return extendConfig.default_model.seedream;
    if (provider === "azure" && extendConfig.default_model.azure) return extendConfig.default_model.azure;
-    if (provider === "zai" && extendConfig.default_model.zai) return extendConfig.default_model.zai;
  }
  return providerModule.getDefaultModel();
 }
@@ -771,7 +880,11 @@ async function prepareSingleTask(args: CliArgs, extendConfig: Partial<ExtendConf
  const prompt = (await loadPromptForArgs(args)) ?? (await readPromptFromStdin());
  if (!prompt) throw new Error("Prompt is required");
  if (!args.imagePath) throw new Error("--image is required");
-  if (args.referenceImages.length > 0) await validateReferenceImages(args.referenceImages);
+  if (args.referenceImages.length > 0) {
+    await validateReferenceImages(args.referenceImages, {
+      allowRemoteUrls: shouldAllowRemoteReferenceImages(args.provider),
+    });
+  }

  const provider = detectProvider(args);
  const providerModule = await loadProviderModule(provider);
@@ -820,6 +933,10 @@ export function resolveBatchPath(batchDir: string, filePath: string): string {
  return path.isAbsolute(filePath) ? filePath : path.resolve(batchDir, filePath);
 }

+function resolveBatchReferencePath(batchDir: string, filePath: string): string {
+  return isRemoteReferenceImage(filePath) ? filePath : resolveBatchPath(batchDir, filePath);
+}
+
 export function createTaskArgs(baseArgs: CliArgs, task: BatchTaskInput, batchDir: string): CliArgs {
  return {
    ...baseArgs,
@@ -829,10 +946,13 @@ export function createTaskArgs(baseArgs: CliArgs, task: BatchTaskInput, batchDir
    provider: task.provider ?? baseArgs.provider ?? null,
    model: task.model ?? baseArgs.model ?? null,
    aspectRatio: task.ar ?? baseArgs.aspectRatio ?? null,
+    aspectRatioSource: task.ar != null ? "task" : (baseArgs.aspectRatioSource ?? null),
    size: task.size ?? baseArgs.size ?? null,
    quality: task.quality ?? baseArgs.quality ?? null,
    imageSize: task.imageSize ?? baseArgs.imageSize ?? null,
-    referenceImages: task.ref ? task.ref.map((filePath) => resolveBatchPath(batchDir, filePath)) : [],
+    imageSizeSource: task.imageSize != null ? "task" : (baseArgs.imageSizeSource ?? null),
+    imageApiDialect: task.imageApiDialect ?? baseArgs.imageApiDialect ?? null,
+    referenceImages: task.ref ? task.ref.map((filePath) => resolveBatchReferencePath(batchDir, filePath)) : [],
    n: task.n ?? baseArgs.n,
    batchFile: null,
    jobs: baseArgs.jobs,
@@ -856,7 +976,11 @@ async function prepareBatchTasks(
    const prompt = await loadPromptForArgs(taskArgs);
    if (!prompt) throw new Error(`Task ${i + 1} is missing prompt or promptFiles.`);
    if (!taskArgs.imagePath) throw new Error(`Task ${i + 1} is missing image output path.`);
-    if (taskArgs.referenceImages.length > 0) await validateReferenceImages(taskArgs.referenceImages);
+    if (taskArgs.referenceImages.length > 0) {
+      await validateReferenceImages(taskArgs.referenceImages, {
+        allowRemoteUrls: shouldAllowRemoteReferenceImages(taskArgs.provider),
+      });
+    }

    const provider = detectProvider(taskArgs);
    const providerModule = await loadProviderModule(provider);
@@ -980,7 +1104,7 @@ async function runBatchTasks(
  const acquireProvider = createProviderGate(providerRateLimits);
  const workerCount = getWorkerCount(tasks.length, jobs, maxWorkers);
  console.error(`Batch mode: ${tasks.length} tasks, ${workerCount} workers, parallel mode enabled.`);
-  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "jimeng", "seedream", "azure", "zai"] as Provider[]) {
+  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "zai", "minimax", "jimeng", "seedream", "azure"] as Provider[]) {
    const limit = providerRateLimits[provider];
    console.error(`- ${provider}: concurrency=${limit.concurrency}, startIntervalMs=${limit.startIntervalMs}`);
  }
@@ -48,6 +48,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    size: null,
    quality: null,
    imageSize: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -46,7 +46,7 @@ export function getDefaultModel(): string {
    }
  }

-  return process.env.AZURE_OPENAI_IMAGE_MODEL || "gpt-image-1.5";
+  return process.env.AZURE_OPENAI_IMAGE_MODEL || "gpt-image-2";
 }

 function getEndpoint(): AzureEndpoint {
@@ -2,15 +2,42 @@ import assert from "node:assert/strict";
 import test, { type TestContext } from "node:test";

 import {
+  generateImage,
  getDefaultModel,
  getModelFamily,
  getQwen2SizeFromAspectRatio,
  getSizeFromAspectRatio,
+  getWan27SizeFromAspectRatio,
  normalizeSize,
  parseAspectRatio,
  parseSize,
  resolveSizeForModel,
 } from "./dashscope.ts";
+import type { CliArgs } from "../types.ts";
+
+function makeCliArgs(overrides: Partial<CliArgs> = {}): CliArgs {
+  return {
+    prompt: null,
+    promptFiles: [],
+    imagePath: null,
+    provider: "dashscope",
+    model: null,
+    aspectRatio: null,
+    aspectRatioSource: null,
+    size: null,
+    quality: "2k",
+    imageSize: null,
+    imageSizeSource: null,
+    imageApiDialect: null,
+    referenceImages: [],
+    n: 1,
+    batchFile: null,
+    jobs: null,
+    json: false,
+    help: false,
+    ...overrides,
+  };
+}

 function useEnv(
  t: TestContext,
@@ -51,9 +78,11 @@ test("DashScope aspect-ratio parsing accepts numeric ratios only", () => {
  assert.equal(parseAspectRatio("-1:2"), null);
 });

-test("DashScope model family routing distinguishes qwen-2.0, fixed-size qwen, and legacy models", () => {
+test("DashScope model family routing distinguishes qwen-2.0, fixed-size qwen, wan2.7, and legacy models", () => {
  assert.equal(getModelFamily("qwen-image-2.0-pro"), "qwen2");
  assert.equal(getModelFamily("qwen-image"), "qwenFixed");
+  assert.equal(getModelFamily("wan2.7-image"), "wan27");
+  assert.equal(getModelFamily("wan2.7-image-pro"), "wan27");
  assert.equal(getModelFamily("z-image-turbo"), "legacy");
  assert.equal(getModelFamily("wanx-v1"), "legacy");
 });
@@ -146,3 +175,218 @@ test("DashScope size normalization converts WxH into provider format", () => {
  assert.equal(normalizeSize("1024x1024"), "1024*1024");
  assert.equal(normalizeSize("2048*1152"), "2048*1152");
 });
+
+test("Wan 2.7 derives sizes that match the requested ratio at the chosen pixel budget", () => {
+  const square2k = getWan27SizeFromAspectRatio(null, "2k", 2048 * 2048);
+  const parsedSquare = parseSize(square2k);
+  assert.ok(parsedSquare);
+  assert.equal(parsedSquare.width, parsedSquare.height);
+  assert.ok(parsedSquare.width * parsedSquare.height <= 2048 * 2048);
+
+  const widescreen = getWan27SizeFromAspectRatio("16:9", "2k", 2048 * 2048);
+  const parsedWide = parseSize(widescreen);
+  assert.ok(parsedWide);
+  assert.ok(Math.abs(parsedWide.width / parsedWide.height - 16 / 9) < 0.05);
+  assert.ok(parsedWide.width * parsedWide.height <= 2048 * 2048);
+
+  const pro4k = getWan27SizeFromAspectRatio("16:9", "2k", 4096 * 4096);
+  const parsed4k = parseSize(pro4k);
+  assert.ok(parsed4k);
+  assert.ok(parsed4k.width * parsed4k.height > 2048 * 2048);
+  assert.ok(parsed4k.width * parsed4k.height <= 4096 * 4096);
+});
+
+test("Wan 2.7 rejects aspect ratios outside the [1:8, 8:1] range", () => {
+  assert.throws(
+    () => getWan27SizeFromAspectRatio("9:1", "2k", 2048 * 2048),
+    /1:8, 8:1/,
+  );
+  assert.throws(
+    () => getWan27SizeFromAspectRatio("1:9", "normal", 2048 * 2048),
+    /1:8, 8:1/,
+  );
+});
+
+test("Wan 2.7 derived sizes stay inside the boundary ratio limits after rounding", () => {
+  for (const ar of ["8:1", "1:8"]) {
+    const size = getWan27SizeFromAspectRatio(ar, "2k", 2048 * 2048);
+    const parsed = parseSize(size);
+    assert.ok(parsed);
+    const ratio = parsed.width / parsed.height;
+    assert.ok(ratio >= 1 / 8);
+    assert.ok(ratio <= 8);
+    assert.ok(parsed.width * parsed.height <= 2048 * 2048);
+  }
+});
+
+test("resolveSizeForModel routes wan2.7-image to the 2K-capped derivation", () => {
+  const size = resolveSizeForModel("wan2.7-image", {
+    size: null,
+    aspectRatio: "16:9",
+    quality: "2k",
+  });
+  const parsed = parseSize(size);
+  assert.ok(parsed);
+  assert.ok(parsed.width * parsed.height <= 2048 * 2048);
+  assert.ok(Math.abs(parsed.width / parsed.height - 16 / 9) < 0.05);
+});
+
+test("resolveSizeForModel allows wan2.7-image-pro 4K only when there are no reference images", () => {
+  assert.equal(
+    resolveSizeForModel("wan2.7-image-pro", {
+      size: "4096*4096",
+      aspectRatio: null,
+      quality: "2k",
+    }),
+    "4096*4096",
+  );
+
+  assert.throws(
+    () =>
+      resolveSizeForModel("wan2.7-image-pro", {
+        size: "4096*4096",
+        aspectRatio: null,
+        quality: "2k",
+        referenceImages: ["a.png"],
+      }),
+    /total pixels between 768\*768 and 2048\*2048/,
+  );
+
+  const proWithRef = resolveSizeForModel("wan2.7-image-pro", {
+    size: null,
+    aspectRatio: "1:1",
+    quality: "2k",
+    referenceImages: ["a.png"],
+  });
+  const parsedRef = parseSize(proWithRef);
+  assert.ok(parsedRef);
+  assert.ok(parsedRef.width * parsedRef.height <= 2048 * 2048);
+});
+
+test("Wan 2.7 request body forces n=1 and omits prompt_extend / negative_prompt", async (t) => {
+  useEnv(t, { DASHSCOPE_API_KEY: "fake-key" });
+
+  const originalFetch = globalThis.fetch;
+  let capturedBody: any = null;
+  globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+    capturedBody = JSON.parse(String(init?.body));
+    return new Response(
+      JSON.stringify({
+        output: {
+          choices: [
+            {
+              message: {
+                content: [{ image: "data:image/png;base64,iVBORw0KGgo=" }],
+              },
+            },
+          ],
+        },
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    );
+  }) as typeof fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  await generateImage("hello", "wan2.7-image-pro", makeCliArgs({ aspectRatio: "1:1" }));
+
+  assert.equal(capturedBody.model, "wan2.7-image-pro");
+  assert.deepEqual(Object.keys(capturedBody.parameters).sort(), ["n", "size", "watermark"]);
+  assert.equal(capturedBody.parameters.n, 1);
+  assert.equal(capturedBody.parameters.watermark, false);
+  assert.equal(typeof capturedBody.parameters.size, "string");
+  assert.ok(!("prompt_extend" in capturedBody.parameters));
+  assert.ok(!("negative_prompt" in capturedBody.parameters));
+
+  assert.deepEqual(capturedBody.input.messages[0].content, [{ text: "hello" }]);
+});
+
+test("Wan 2.7 request body forwards remote reference image URLs", async (t) => {
+  useEnv(t, { DASHSCOPE_API_KEY: "fake-key" });
+
+  const originalFetch = globalThis.fetch;
+  let capturedBody: any = null;
+  globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+    capturedBody = JSON.parse(String(init?.body));
+    return new Response(
+      JSON.stringify({
+        output: {
+          choices: [
+            {
+              message: {
+                content: [{ image: "data:image/png;base64,iVBORw0KGgo=" }],
+              },
+            },
+          ],
+        },
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    );
+  }) as typeof fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  await generateImage(
+    "combine these",
+    "wan2.7-image-pro",
+    makeCliArgs({ referenceImages: ["https://example.com/ref.png"] }),
+  );
+
+  assert.deepEqual(capturedBody.input.messages[0].content, [
+    { image: "https://example.com/ref.png" },
+    { text: "combine these" },
+  ]);
+});
+
+test("Wan 2.7 rejects --n > 1 to prevent silent multi-image billing", async (t) => {
+  useEnv(t, { DASHSCOPE_API_KEY: "fake-key" });
+
+  await assert.rejects(
+    () => generateImage("hi", "wan2.7-image-pro", makeCliArgs({ n: 2 })),
+    /support exactly one output image/,
+  );
+});
+
+test("resolveSizeForModel validates explicit wan2.7 sizes by pixel budget and ratio", () => {
+  assert.equal(
+    resolveSizeForModel("wan2.7-image-pro", {
+      size: "3840x2160",
+      aspectRatio: null,
+      quality: "2k",
+    }),
+    "3840*2160",
+  );
+
+  assert.throws(
+    () =>
+      resolveSizeForModel("wan2.7-image-pro", {
+        size: "3840x2160",
+        aspectRatio: null,
+        quality: "2k",
+        referenceImages: ["a.png"],
+      }),
+    /total pixels between 768\*768 and 2048\*2048/,
+  );
+
+  assert.throws(
+    () =>
+      resolveSizeForModel("wan2.7-image", {
+        size: "4096x4096",
+        aspectRatio: null,
+        quality: "2k",
+      }),
+    /total pixels between 768\*768 and 2048\*2048/,
+  );
+
+  assert.throws(
+    () =>
+      resolveSizeForModel("wan2.7-image-pro", {
+        size: "3072*256",
+        aspectRatio: null,
+        quality: "2k",
+      }),
+    /1:8, 8:1/,
+  );
+});
@@ -1,6 +1,8 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
 import type { CliArgs, Quality } from "../types";

-type DashScopeModelFamily = "qwen2" | "qwenFixed" | "legacy";
+type DashScopeModelFamily = "qwen2" | "qwenFixed" | "wan27" | "legacy";

 type DashScopeModelSpec = {
  family: DashScopeModelFamily;
@@ -19,6 +21,16 @@ const QWEN_2_TARGET_PIXELS: Record<Quality, number> = {
  "2k": 1536 * 1536,
 };

+const MIN_WAN27_TOTAL_PIXELS = 768 * 768;
+const MAX_WAN27_PRO_T2I_PIXELS = 4096 * 4096;
+const MAX_WAN27_GENERAL_PIXELS = 2048 * 2048;
+const WAN27_MAX_REFERENCE_IMAGES = 9;
+
+const WAN27_TARGET_PIXELS: Record<Quality, number> = {
+  normal: 1024 * 1024,
+  "2k": 2048 * 2048,
+};
+
 const QWEN_2_RECOMMENDED: Record<string, Record<Quality, string>> = {
  "1:1": { normal: "1024*1024", "2k": "1536*1536" },
  "2:3": { normal: "768*1152", "2k": "1024*1536" },
@@ -73,6 +85,11 @@ const QWEN_FIXED_SPEC: DashScopeModelSpec = {
  defaultSize: QWEN_FIXED_SIZES_BY_RATIO["16:9"],
 };

+const WAN27_SPEC: DashScopeModelSpec = {
+  family: "wan27",
+  defaultSize: "2048*2048",
+};
+
 const LEGACY_SPEC: DashScopeModelSpec = {
  family: "legacy",
  defaultSize: "1536*1536",
@@ -88,12 +105,31 @@ const MODEL_SPEC_ALIASES: Record<string, DashScopeModelSpec> = {
  "qwen-image-plus": QWEN_FIXED_SPEC,
  "qwen-image-plus-2026-01-09": QWEN_FIXED_SPEC,
  "qwen-image": QWEN_FIXED_SPEC,
+  "wan2.7-image-pro": WAN27_SPEC,
+  "wan2.7-image": WAN27_SPEC,
 };

 export function getDefaultModel(): string {
  return process.env.DASHSCOPE_IMAGE_MODEL || DEFAULT_MODEL;
 }

+function getReferenceImageMime(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".bmp") return "image/bmp";
+  return "image/png";
+}
+
+async function loadReferenceImage(refPath: string): Promise<string> {
+  if (/^https?:\/\//i.test(refPath)) {
+    return refPath;
+  }
+  const fullPath = path.resolve(refPath);
+  const bytes = await readFile(fullPath);
+  return `data:${getReferenceImageMime(fullPath)};base64,${bytes.toString("base64")}`;
+}
+
 function getApiKey(): string | null {
  return process.env.DASHSCOPE_API_KEY || null;
 }
@@ -173,6 +209,10 @@ function roundToStep(value: number): number {
  return Math.max(SIZE_STEP, Math.round(value / SIZE_STEP) * SIZE_STEP);
 }

+function floorToStep(value: number): number {
+  return Math.max(SIZE_STEP, Math.floor(value / SIZE_STEP) * SIZE_STEP);
+}
+
 function fitToPixelBudget(
  width: number,
  height: number,
@@ -220,6 +260,21 @@ function fitToPixelBudget(
  return { width: roundedWidth, height: roundedHeight };
 }

+function clampWan27DerivedSizeToRatioBounds(
+  size: { width: number; height: number },
+): { width: number; height: number } {
+  let { width, height } = size;
+  const ratio = width / height;
+
+  if (ratio > 8) {
+    width = floorToStep(height * 8);
+  } else if (ratio < 1 / 8) {
+    height = floorToStep(width * 8);
+  }
+
+  return { width, height };
+}
+
 export function getSizeFromAspectRatio(ar: string | null, quality: CliArgs["quality"]): string {
  const normalizedQuality = normalizeQuality(quality);
  const sizes = normalizedQuality === "2k" ? LEGACY_STANDARD_SIZES_2K : LEGACY_STANDARD_SIZES;
@@ -276,6 +331,77 @@ export function getQwen2SizeFromAspectRatio(ar: string | null, quality: CliArgs[
  return formatSize(fitted.width, fitted.height);
 }

+function isWan27ProModel(model: string): boolean {
+  return model.trim().toLowerCase() === "wan2.7-image-pro";
+}
+
+function getWan27MaxPixels(model: string, hasReferenceImages: boolean): number {
+  if (isWan27ProModel(model) && !hasReferenceImages) {
+    return MAX_WAN27_PRO_T2I_PIXELS;
+  }
+  return MAX_WAN27_GENERAL_PIXELS;
+}
+
+export function getWan27SizeFromAspectRatio(
+  ar: string | null,
+  quality: CliArgs["quality"],
+  maxPixels: number,
+): string {
+  const normalizedQuality = normalizeQuality(quality);
+  const targetPixels = Math.min(WAN27_TARGET_PIXELS[normalizedQuality], maxPixels);
+
+  if (!ar) {
+    const side = roundToStep(Math.sqrt(targetPixels));
+    return formatSize(side, side);
+  }
+
+  const parsed = parseAspectRatio(ar);
+  if (!parsed) {
+    const side = roundToStep(Math.sqrt(targetPixels));
+    return formatSize(side, side);
+  }
+
+  const ratio = parsed.width / parsed.height;
+  if (ratio < 1 / 8 || ratio > 8) {
+    throw new Error(
+      `DashScope wan2.7 image models support aspect ratios in [1:8, 8:1]. Received "${ar}".`
+    );
+  }
+
+  const rawWidth = Math.sqrt(targetPixels * ratio);
+  const rawHeight = Math.sqrt(targetPixels / ratio);
+  const fitted = fitToPixelBudget(
+    rawWidth,
+    rawHeight,
+    MIN_WAN27_TOTAL_PIXELS,
+    maxPixels,
+  );
+  const bounded = clampWan27DerivedSizeToRatioBounds(fitted);
+
+  return formatSize(bounded.width, bounded.height);
+}
+
+function validateWan27Size(size: string, maxPixels: number, model: string): string {
+  const normalized = normalizeSize(size);
+  const parsed = validateSizeFormat(normalized);
+  const totalPixels = parsed.width * parsed.height;
+  if (totalPixels < MIN_WAN27_TOTAL_PIXELS || totalPixels > maxPixels) {
+    const limit = maxPixels === MAX_WAN27_PRO_T2I_PIXELS ? "4096*4096" : "2048*2048";
+    throw new Error(
+      `DashScope ${model} requires total pixels between 768*768 and ${limit} ` +
+      `for the current request. Received ${normalized} (${totalPixels} pixels).`
+    );
+  }
+  const ratio = parsed.width / parsed.height;
+  if (ratio < 1 / 8 || ratio > 8) {
+    throw new Error(
+      `DashScope wan2.7 image models support aspect ratios in [1:8, 8:1]. ` +
+      `Received ${normalized} (ratio ${ratio.toFixed(3)}).`
+    );
+  }
+  return normalized;
+}
+
 function getQwenFixedSizeFromAspectRatio(ar: string | null, quality: CliArgs["quality"]): string {
  if (quality === "normal") {
    console.warn(
@@ -331,9 +457,16 @@ function validateQwenFixedSize(size: string): string {

 export function resolveSizeForModel(
  model: string,
-  args: Pick<CliArgs, "size" | "aspectRatio" | "quality">,
+  args: Pick<CliArgs, "size" | "aspectRatio" | "quality"> & { referenceImages?: string[] },
 ): string {
  const spec = getModelSpec(model);
+  const referenceCount = args.referenceImages?.length ?? 0;
+
+  if (spec.family === "wan27") {
+    const maxPixels = getWan27MaxPixels(model, referenceCount > 0);
+    if (args.size) return validateWan27Size(args.size, maxPixels, model);
+    return getWan27SizeFromAspectRatio(args.aspectRatio, args.quality, maxPixels);
+  }

  if (args.size) {
    if (spec.family === "qwen2") return validateQwen2Size(args.size);
@@ -357,6 +490,14 @@ function buildParameters(
  family: DashScopeModelFamily,
  size: string,
 ): Record<string, unknown> {
+  if (family === "wan27") {
+    return {
+      size,
+      n: 1,
+      watermark: false,
+    };
+  }
+
  const parameters: Record<string, unknown> = {
    prompt_extend: false,
    size,
@@ -419,23 +560,44 @@ export async function generateImage(
  const apiKey = getApiKey();
  if (!apiKey) throw new Error("DASHSCOPE_API_KEY is required");

-  if (args.referenceImages.length > 0) {
+  const spec = getModelSpec(model);
+
+  if (args.referenceImages.length > 0 && spec.family !== "wan27") {
    throw new Error(
-      "Reference images are not supported with DashScope provider in baoyu-image-gen. Use --provider google with a Gemini multimodal model."
+      "Reference images are not supported with this DashScope model. Use a wan2.7 image model (--model wan2.7-image-pro or wan2.7-image), or switch to --provider google with a Gemini multimodal model."
+    );
+  }
+
+  if (args.referenceImages.length > WAN27_MAX_REFERENCE_IMAGES) {
+    throw new Error(
+      `DashScope wan2.7 image models accept at most ${WAN27_MAX_REFERENCE_IMAGES} reference images. Received ${args.referenceImages.length}.`
+    );
+  }
+
+  if (spec.family === "wan27" && args.n !== 1) {
+    throw new Error(
+      "DashScope wan2.7 image models in baoyu-image-gen support exactly one output image per request (extra images would be billed but discarded). Remove --n or use --n 1."
    );
  }

-  const spec = getModelSpec(model);
  const size = resolveSizeForModel(model, args);
  const url = `${getBaseUrl()}/api/v1/services/aigc/multimodal-generation/generation`;

+  const content: Array<Record<string, unknown>> = [];
+  if (spec.family === "wan27" && args.referenceImages.length > 0) {
+    for (const refPath of args.referenceImages) {
+      content.push({ image: await loadReferenceImage(refPath) });
+    }
+  }
+  content.push({ text: prompt });
+
  const body = {
    model,
    input: {
      messages: [
        {
          role: "user",
-          content: [{ text: prompt }],
+          content,
        },
      ],
    },
@@ -50,6 +50,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    size: null,
    quality: null,
    imageSize: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -15,6 +15,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    size: null,
    quality: null,
    imageSize: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -50,6 +50,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    size: null,
    quality: null,
    imageSize: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
@@ -1,14 +1,47 @@
 import assert from "node:assert/strict";
 import test from "node:test";

+import type { CliArgs } from "../types.ts";
 import {
+  buildOpenAIGenerationsBody,
  extractImageFromResponse,
+  getDefaultModel,
+  getOpenAIAspectRatio,
+  getOpenAIImageApiDialect,
+  getOpenAIResolution,
  getMimeType,
  getOpenAISize,
+  getOrientationFromAspectRatio,
+  inferAspectRatioFromSize,
+  inferResolutionFromSize,
  parseAspectRatio,
+  validateArgs,
 } from "./openai.ts";

+function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
+  return {
+    prompt: null,
+    promptFiles: [],
+    imagePath: null,
+    provider: null,
+    model: null,
+    aspectRatio: null,
+    size: null,
+    quality: "2k",
+    imageSize: null,
+    imageApiDialect: null,
+    referenceImages: [],
+    n: 1,
+    batchFile: null,
+    jobs: null,
+    json: false,
+    help: false,
+    ...overrides,
+  };
+}
+
 test("OpenAI aspect-ratio parsing and size selection match model families", () => {
+  assert.equal(getDefaultModel(), "gpt-image-2");
  assert.deepEqual(parseAspectRatio("16:9"), { width: 16, height: 9 });
  assert.equal(parseAspectRatio("wide"), null);
  assert.equal(parseAspectRatio("0:1"), null);
@@ -18,6 +51,96 @@ test("OpenAI aspect-ratio parsing and size selection match model families", () =
  assert.equal(getOpenAISize("dall-e-2", "16:9", "2k"), "1024x1024");
  assert.equal(getOpenAISize("gpt-image-1.5", "16:9", "2k"), "1536x1024");
  assert.equal(getOpenAISize("gpt-image-1.5", "4:3", "2k"), "1024x1024");
+  assert.equal(getOpenAISize("gpt-image-2", "16:9", "2k"), "2048x1152");
+  assert.equal(getOpenAISize("gpt-image-2", "9:16", "2k"), "1152x2048");
+  assert.equal(getOpenAISize("gpt-image-2", "4:3", "2k"), "2048x1536");
+  assert.equal(getOpenAISize("gpt-image-2", "2.35:1", "normal"), "1248x528");
+  assert.equal(inferAspectRatioFromSize("1536x1024"), "3:2");
+  assert.equal(inferResolutionFromSize("1536x1024"), "2K");
+  assert.equal(getOpenAIAspectRatio({ aspectRatio: null, size: "2048x1152" }), "16:9");
+  assert.equal(getOpenAIResolution({ imageSize: null, size: "2048x1152", quality: "normal" }), "2K");
+  assert.equal(getOrientationFromAspectRatio("16:9"), "landscape");
+  assert.equal(getOrientationFromAspectRatio("9:16"), "portrait");
+  assert.equal(getOrientationFromAspectRatio("1:1"), null);
+  assert.equal(getOpenAIImageApiDialect({ imageApiDialect: null }), "openai-native");
+});
+
+test("OpenAI generations body switches between native and ratio-metadata dialects", () => {
+  assert.deepEqual(
+    buildOpenAIGenerationsBody("Draw a skyline", "gpt-image-2", {
+      aspectRatio: "16:9",
+      size: null,
+      quality: "2k",
+      imageSize: null,
+      imageApiDialect: null,
+    }),
+    {
+      model: "gpt-image-2",
+      prompt: "Draw a skyline",
+      size: "2048x1152",
+      quality: "high",
+    },
+  );
+
+  assert.deepEqual(
+    buildOpenAIGenerationsBody("Draw a skyline", "gemini-3-pro-image-preview", {
+      aspectRatio: "16:9",
+      size: null,
+      quality: "2k",
+      imageSize: null,
+      imageApiDialect: "ratio-metadata",
+    }),
+    {
+      model: "gemini-3-pro-image-preview",
+      prompt: "Draw a skyline",
+      size: "16:9",
+      metadata: {
+        resolution: "2K",
+        orientation: "landscape",
+      },
+    },
+  );
+
+  assert.deepEqual(
+    buildOpenAIGenerationsBody("Draw a portrait", "gemini-3-pro-image-preview", {
+      aspectRatio: null,
+      size: "1152x2048",
+      quality: "normal",
+      imageSize: null,
+      imageApiDialect: "ratio-metadata",
+    }),
+    {
+      model: "gemini-3-pro-image-preview",
+      prompt: "Draw a portrait",
+      size: "9:16",
+      metadata: {
+        resolution: "2K",
+        orientation: "portrait",
+      },
+    },
+  );
+});
+
+test("OpenAI validates gpt-image-2 custom size constraints", () => {
+  assert.doesNotThrow(() =>
+    validateArgs("gpt-image-2", makeArgs({ size: "3840x2160" })),
+  );
+  assert.doesNotThrow(() =>
+    validateArgs("gpt-image-2-2026-04-21", makeArgs({ aspectRatio: "2.35:1" })),
+  );
+
+  assert.throws(
+    () => validateArgs("gpt-image-2", makeArgs({ size: "1024x576" })),
+    /total pixels/,
+  );
+  assert.throws(
+    () => validateArgs("gpt-image-2", makeArgs({ size: "1025x1024" })),
+    /multiples of 16px/,
+  );
+  assert.throws(
+    () => validateArgs("gpt-image-2", makeArgs({ aspectRatio: "4:1" })),
+    /must not exceed 3:1/,
+  );
 });

 test("OpenAI mime-type detection covers supported reference image extensions", () => {
@@ -1,9 +1,9 @@
 import path from "node:path";
 import { readFile } from "node:fs/promises";
-import type { CliArgs } from "../types";
+import type { CliArgs, OpenAIImageApiDialect } from "../types";

 export function getDefaultModel(): string {
-  return process.env.OPENAI_IMAGE_MODEL || "gpt-image-1.5";
+  return process.env.OPENAI_IMAGE_MODEL || "gpt-image-2";
 }

 type OpenAIImageResponse = { data: Array<{ url?: string; b64_json?: string }> };
@@ -23,6 +23,57 @@ type SizeMapping = {
  portrait: string;
 };

+type OpenAIGenerationsBody = Record<string, unknown>;
+
+function isGptImageModel(model: string): boolean {
+  return model.includes("gpt-image");
+}
+
+function isGptImage2Model(model: string): boolean {
+  return model.includes("gpt-image-2");
+}
+
+function roundToMultiple(value: number, multiple: number): number {
+  return Math.max(multiple, Math.round(value / multiple) * multiple);
+}
+
+function buildGptImage2SizeFromAspectRatio(
+  ar: string | null,
+  quality: CliArgs["quality"],
+): string {
+  const parsed = ar ? parseAspectRatio(ar) : null;
+  const ratio = parsed ? parsed.width / parsed.height : 1;
+
+  if (!parsed || Math.abs(ratio - 1) < 0.1) {
+    const edge = quality === "2k" ? 2048 : 1024;
+    return `${edge}x${edge}`;
+  }
+
+  const targetLongEdge = quality === "2k" ? 2048 : 1024;
+  let width: number;
+  let height: number;
+
+  if (ratio > 1) {
+    width = targetLongEdge;
+    height = roundToMultiple(width / ratio, 16);
+  } else {
+    height = targetLongEdge;
+    width = roundToMultiple(height * ratio, 16);
+  }
+
+  while (width * height < 655_360) {
+    if (ratio > 1) {
+      width += 16;
+      height = roundToMultiple(width / ratio, 16);
+    } else {
+      height += 16;
+      width = roundToMultiple(height * ratio, 16);
+    }
+  }
+
+  return `${width}x${height}`;
+}
+
 export function getOpenAISize(
  model: string,
  ar: string | null,
@@ -35,6 +86,10 @@ export function getOpenAISize(
    return "1024x1024";
  }

+  if (isGptImage2Model(model)) {
+    return buildGptImage2SizeFromAspectRatio(ar, quality);
+  }
+
  const sizes: SizeMapping = isDalle3
    ? {
        square: "1024x1024",
@@ -60,6 +115,166 @@ export function getOpenAISize(
  return sizes.square;
 }

+function parsePixelSize(value: string): { width: number; height: number } | null {
+  const match = value.match(/^(\d+)\s*[xX]\s*(\d+)$/);
+  if (!match) return null;
+
+  const width = parseInt(match[1]!, 10);
+  const height = parseInt(match[2]!, 10);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return null;
+  }
+
+  return { width, height };
+}
+
+function gcd(a: number, b: number): number {
+  let x = Math.abs(a);
+  let y = Math.abs(b);
+  while (y !== 0) {
+    const next = x % y;
+    x = y;
+    y = next;
+  }
+  return x || 1;
+}
+
+export function getOpenAIImageApiDialect(args: Pick<CliArgs, "imageApiDialect">): OpenAIImageApiDialect {
+  return args.imageApiDialect ?? "openai-native";
+}
+
+export function inferAspectRatioFromSize(size: string | null): string | null {
+  if (!size) return null;
+  const parsed = parsePixelSize(size);
+  if (!parsed) return null;
+
+  const divisor = gcd(parsed.width, parsed.height);
+  return `${parsed.width / divisor}:${parsed.height / divisor}`;
+}
+
+export function inferResolutionFromSize(size: string | null): "1K" | "2K" | "4K" | null {
+  if (!size) return null;
+  const parsed = parsePixelSize(size);
+  if (!parsed) return null;
+
+  const longestEdge = Math.max(parsed.width, parsed.height);
+  if (longestEdge <= 1024) return "1K";
+  if (longestEdge <= 2048) return "2K";
+  return "4K";
+}
+
+export function getOpenAIAspectRatio(args: Pick<CliArgs, "aspectRatio" | "size">): string {
+  return args.aspectRatio ?? inferAspectRatioFromSize(args.size) ?? "1:1";
+}
+
+export function getOpenAIResolution(
+  args: Pick<CliArgs, "imageSize" | "size" | "quality">
+): "1K" | "2K" | "4K" {
+  if (args.imageSize === "1K" || args.imageSize === "2K" || args.imageSize === "4K") {
+    return args.imageSize;
+  }
+
+  const inferred = inferResolutionFromSize(args.size);
+  if (inferred) return inferred;
+
+  return args.quality === "normal" ? "1K" : "2K";
+}
+
+function getOpenAIQuality(model: string, quality: CliArgs["quality"]): "standard" | "hd" | "medium" | "high" | null {
+  if (model.includes("dall-e-3")) {
+    return quality === "2k" ? "hd" : "standard";
+  }
+
+  if (isGptImageModel(model)) {
+    return quality === "2k" ? "high" : "medium";
+  }
+
+  return null;
+}
+
+export function getOrientationFromAspectRatio(ar: string): "landscape" | "portrait" | null {
+  const parsed = parseAspectRatio(ar);
+  if (!parsed) return null;
+
+  const ratio = parsed.width / parsed.height;
+  if (Math.abs(ratio - 1) < 0.1) return null;
+  return ratio > 1 ? "landscape" : "portrait";
+}
+
+export function buildOpenAIGenerationsBody(
+  prompt: string,
+  model: string,
+  args: Pick<CliArgs, "aspectRatio" | "size" | "quality" | "imageSize" | "imageApiDialect">
+): OpenAIGenerationsBody {
+  if (getOpenAIImageApiDialect(args) === "ratio-metadata") {
+    const aspectRatio = getOpenAIAspectRatio(args);
+    const metadata: Record<string, string> = {
+      resolution: getOpenAIResolution(args),
+    };
+    const orientation = getOrientationFromAspectRatio(aspectRatio);
+    if (orientation) metadata.orientation = orientation;
+
+    return {
+      model,
+      prompt,
+      size: aspectRatio,
+      metadata,
+    };
+  }
+
+  const body: OpenAIGenerationsBody = {
+    model,
+    prompt,
+    size: args.size || getOpenAISize(model, args.aspectRatio, args.quality),
+  };
+
+  const quality = getOpenAIQuality(model, args.quality);
+  if (quality) {
+    body.quality = quality;
+  }
+
+  return body;
+}
+
+export function validateArgs(model: string, args: CliArgs): void {
+  if (!isGptImage2Model(model)) return;
+
+  if (args.aspectRatio && !args.size) {
+    const parsed = parseAspectRatio(args.aspectRatio);
+    if (!parsed) {
+      throw new Error(`Invalid gpt-image-2 aspect ratio: ${args.aspectRatio}`);
+    }
+    const ratio = parsed.width / parsed.height;
+    if (Math.max(ratio, 1 / ratio) > 3) {
+      throw new Error("gpt-image-2 aspect ratio must not exceed 3:1.");
+    }
+  }
+
+  if (!args.size) return;
+
+  const parsedSize = parsePixelSize(args.size);
+  if (!parsedSize) {
+    throw new Error(`Invalid gpt-image-2 --size: ${args.size}. Expected <width>x<height>.`);
+  }
+
+  const { width, height } = parsedSize;
+  const totalPixels = width * height;
+  const ratio = Math.max(width, height) / Math.min(width, height);
+
+  if (Math.max(width, height) > 3840) {
+    throw new Error("gpt-image-2 --size maximum edge length must be 3840px or less.");
+  }
+  if (width % 16 !== 0 || height % 16 !== 0) {
+    throw new Error("gpt-image-2 --size width and height must both be multiples of 16px.");
+  }
+  if (ratio > 3) {
+    throw new Error("gpt-image-2 --size long edge to short edge ratio must not exceed 3:1.");
+  }
+  if (totalPixels < 655_360 || totalPixels > 8_294_400) {
+    throw new Error("gpt-image-2 --size total pixels must be between 655,360 and 8,294,400.");
+  }
+}
+
 export async function generateImage(
  prompt: string,
  model: string,
@@ -78,18 +293,28 @@ export async function generateImage(
    return generateWithChatCompletions(baseURL, apiKey, prompt, model);
  }

-  const size = args.size || getOpenAISize(model, args.aspectRatio, args.quality);
+  const imageApiDialect = getOpenAIImageApiDialect(args);

  if (args.referenceImages.length > 0) {
-    if (model.includes("dall-e-2") || model.includes("dall-e-3")) {
+    if (imageApiDialect !== "openai-native") {
      throw new Error(
-        "Reference images with OpenAI in this skill require GPT Image models. Use --model gpt-image-1.5 (or another gpt-image model)."
+        "Reference images are not supported with the ratio-metadata OpenAI dialect yet. Use openai-native, Google, Azure, OpenRouter, MiniMax, Seedream, or Replicate for image-edit workflows."
      );
    }
+    if (model.includes("dall-e-2") || model.includes("dall-e-3")) {
+      throw new Error(
+        "Reference images with OpenAI in this skill require GPT Image models. Use --model gpt-image-2 (or another gpt-image model)."
+      );
+    }
+    const size = args.size || getOpenAISize(model, args.aspectRatio, args.quality);
    return generateWithOpenAIEdits(baseURL, apiKey, prompt, model, size, args.referenceImages, args.quality);
  }

-  return generateWithOpenAIGenerations(baseURL, apiKey, prompt, model, size, args.quality);
+  return generateWithOpenAIGenerations(
+    baseURL,
+    apiKey,
+    buildOpenAIGenerationsBody(prompt, model, args)
+  );
 }

 async function generateWithChatCompletions(
@@ -129,17 +354,8 @@ async function generateWithChatCompletions(
 async function generateWithOpenAIGenerations(
  baseURL: string,
  apiKey: string,
-  prompt: string,
-  model: string,
-  size: string,
-  quality: CliArgs["quality"]
+  body: OpenAIGenerationsBody
 ): Promise<Uint8Array> {
-  const body: Record<string, any> = { model, prompt, size };
-
-  if (model.includes("dall-e-3")) {
-    body.quality = quality === "2k" ? "hd" : "standard";
-  }
-
  const res = await fetch(`${baseURL}/images/generations`, {
    method: "POST",
    headers: {
@@ -172,8 +388,9 @@ async function generateWithOpenAIEdits(
  form.append("prompt", prompt);
  form.append("size", size);

-  if (model.includes("gpt-image")) {
-    form.append("quality", quality === "2k" ? "high" : "medium");
+  const openAIQuality = getOpenAIQuality(model, quality);
+  if (openAIQuality && openAIQuality !== "standard" && openAIQuality !== "hd") {
+    form.append("quality", openAIQuality);
  }

  for (const refPath of referenceImages) {
@@ -28,6 +28,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
    size: null,
    quality: null,
    imageSize: null,
+    imageApiDialect: null,
    referenceImages: [],
    n: 1,
    batchFile: null,
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jim Liu 宝玉	66160abb9f	chore: release v2.1.0	2026-05-24 21:27:57 -05:00
Jim Liu 宝玉	b34e19daad	feat(baoyu-post-to-wechat,baoyu-post-to-weibo,baoyu-post-to-x): cascade Mermaid PNG preprocessing into publishing pipelines	2026-05-24 21:27:53 -05:00
Jim Liu 宝玉	cda76e20fd	feat(baoyu-markdown-to-html): render Mermaid code blocks to PNG via headless Chrome	2026-05-24 21:27:43 -05:00
Jim Liu 宝玉	8d2fd7aae0	feat(baoyu-md): add Mermaid preprocessing and utility modules	2026-05-24 21:27:38 -05:00
Jim Liu 宝玉	f60702cc8e	feat(baoyu-chrome-cdp): add Mermaid-to-PNG rendering via CDP	2026-05-24 21:27:33 -05:00
Jim Liu 宝玉	613bee6bb8	feat(build): support multi-entry output in shared package build script	2026-05-24 21:27:28 -05:00
Jim Liu 宝玉	e63e21786d	chore: release v2.0.1	2026-05-24 18:59:16 -05:00
Jim Liu 宝玉	b3a3b632c8	fix(baoyu-post-to-wechat): repair htmlToPlainText syntax error and entity decoding Follow-up to the previous newspic conversion commit: - `“` / `”` mapped to `"""` (three straight double-quotes), producing an unterminated string literal that prevented wechat-api.ts from parsing. Replaced with the intended curly Unicode characters. - `‘` / `’` similarly mapped to straight `'`; switched to the curly singles to match the entity meaning. - Numeric entities used `String.fromCharCode`, which mangles code points above 0xFFFF (e.g. emoji like `😀` → empty string). Switched to `String.fromCodePoint`. - Added hexadecimal numeric entity support (`😀` etc.); the previous regex only matched decimal forms. - Anchored the entity sub-patterns with `^...$` so the callback cannot accidentally re-match a substring of the captured entity.	2026-05-24 18:57:01 -05:00
Go1dFinger	3aafe60463	fix(baoyu-post-to-wechat): improve newspic plain text conversion for WeChat API The previous fix used a simple regex to strip HTML tags for newspic content, but it had several issues: 1. HTML entities ( , <, >, &, etc.) were not decoded 2. Block-level tags (</p>, </div>, </h1> etc.) did not produce line breaks 3. Multiple consecutive whitespace characters were not collapsed This commit introduces a dedicated htmlToPlainText() function that: - Converts <br> and block-level closing tags to line breaks - Strips all remaining HTML tags - Decodes common HTML entities (including numeric entities) - Collapses consecutive whitespace into single spaces - Trims whitespace from each line This ensures the content field for newspic articles is properly formatted plain text that complies with WeChat API requirements, preventing error 45166 (invalid content) especially when publishing with multiple images. Closes #163 Merges #164	2026-05-24 18:55:59 -05:00
Jim Liu 宝玉	246e90bf28	chore: align baoyu-{article-illustrator,comic,infographic,slide-deck} SKILL.md versions with ClawHub	2026-05-24 18:36:45 -05:00
Jim Liu 宝玉	c3cbce9ce3	feat\!: rename baoyu-imagine→baoyu-image-gen, baoyu-image-cards→baoyu-xhs-images (v2.0.0) BREAKING CHANGE: removed `baoyu-imagine` and `baoyu-image-cards`. All functionality now lives under `baoyu-image-gen` and `baoyu-xhs-images` respectively. Cross-skill `## Image Generation Tools` examples updated across baoyu-article-illustrator, baoyu-comic, baoyu-cover-image, baoyu-infographic, and baoyu-slide-deck. Migration: existing `~/.baoyu-skills/baoyu-imagine/EXTEND.md` configs are auto-renamed to `…/baoyu-image-gen/EXTEND.md` on first run via the legacy-path resolver in `scripts/main.ts`.	2026-05-24 18:35:05 -05:00
Jim Liu 宝玉	bc303345f4	chore(baoyu-imagine): align SKILL.md version with ClawHub	2026-05-24 17:14:11 -05:00
Jim Liu 宝玉	17d7d6105c	chore(baoyu-cover-image): align SKILL.md version with ClawHub	2026-05-24 17:14:11 -05:00
Jim Liu 宝玉	50c6c72944	docs(readme): warn users to install only the skills they need The marketplace bundles 20+ skills into one plugin, and bulk-installing all of them adds context overhead to the AI agent on every run. Add a short tip at the top of the Installation section so users browse the available list and pick what they actually need.	2026-05-24 17:05:49 -05:00
Jim Liu 宝玉	ad1755fa23	chore: release v1.119.0	2026-05-24 17:00:39 -05:00
Jim Liu 宝玉	3cc1225b18	feat(baoyu-electron-extract): add new skill to extract Electron app sources Extracts resources and JavaScript from any installed Electron app's app.asar. When .js.map files embed sourcesContent, restores the original source tree (TypeScript/JSX included); otherwise formats minified JS/CSS with Prettier in place. Always skips node_modules and webpack/runtime/* entries. Source-map paths are resolved relative to each .js.map file first, so bundler-relative entries like ../../src/main.ts restore to readable paths under restored/ instead of hashed placeholders. Auto-discovers apps on macOS (/Applications, ~/Applications) and Windows (%LOCALAPPDATA%\Programs, %PROGRAMFILES%, %PROGRAMFILES(X86)%, %APPDATA%). On other platforms pass --asar <path> explicitly. Safety: refuses to write to /, the user home, or the current working directory, and refuses non-empty existing output dirs without --force.	2026-05-24 17:00:31 -05:00
Jim Liu 宝玉	460bd087c6	Merge pull request #161 from xiaoyaner0201/docs/baoyu-imagine-codex-image2-notes docs(baoyu-imagine): clarify Codex image2 fallback	2026-05-23 11:23:19 -05:00
千乘妍 (Xiaoyaner)	daf0fb7bec	docs(baoyu-imagine): clarify Codex image2 fallback	2026-05-22 16:45:30 +08:00
Jim Liu 宝玉	adbfa3036b	chore: release v1.118.0	2026-05-21 16:56:17 -05:00
Jim Liu 宝玉	6026b619f0	Merge pull request #158 from yelban/feat/codex-imagegen-backend feat: add codex-imagegen backend for non-Codex runtimes	2026-05-21 16:45:22 -05:00
Yelban	df16bd5d1a	feat(codex-imagegen): cwd-drift immunity (path resolve + skip-git-repo-check) Two improvements so the wrapper works the same regardless of caller cwd or whether cwd is a git repo: 1. main.ts: resolve all filesystem path args (--prompt-file, --ref, --cache-dir, --log-file) to absolute paths up front. Previously only --image was resolved. Agents passing relative paths from arbitrary working directories (e.g. when SKILL.md is interpreted from a plugin install dir) now produce correct file lookups. 2. spawn.ts: pass --skip-git-repo-check to 'codex exec'. Without it, codex refuses to run outside a trusted directory: 'Not inside a trusted directory and --skip-git-repo-check was not specified.' This made the wrapper fail when invoked from /tmp or from a non-git project tree. 3. baoyu-cover-image/SKILL.md: explicit path resolution note — scripts/codex-imagegen.sh lives at plugin/repo root (not shell cwd-relative). From the skill base directory it is at '../../scripts/codex-imagegen.sh'. Agents should resolve to an absolute path before invoking. Verified: - 16 unit tests pass - e2e from /tmp (non-git, relative-path args) → 45s, 1.6MB PNG, status:ok Composes with the existing cover-image wiring (commit e3932e4).	2026-05-21 16:26:03 +08:00
Yelban	9596d39e7b	feat(baoyu-cover-image): wire SKILL.md to call codex-imagegen wrapper Per review feedback on #158: a backend wrapper alone is not enough — skills need explicit invocation guidance so the agent can find and call it. Updates skills/baoyu-cover-image/SKILL.md in two places: 1. ## Image Generation Tools — new bullet under the backend resolution list: 'Codex via codex exec (codex-imagegen)' with the exact command shape (--image / --prompt-file / --aspect / --ref / --cache-dir / --log-file), JSON output handling, and prerequisites. 2. ### Step 4: Generate Image, step 5 — added a concrete example command for the codex-imagegen branch alongside the existing generic instruction. End-to-end verified: with EXTEND.md set to preferred_image_backend: codex-imagegen, calling the command shape written in SKILL.md produces a 1672x941 PNG in 83s (status: ok, attempts: 1, cached: false). Output: /tmp/cover-e2e/cover.png. Structured log: /tmp/cover-e2e/run.jsonl. baoyu-cover-image is the validation skill; if reviewers want the same guidance in baoyu-article-illustrator / baoyu-comic / baoyu-image-cards / baoyu-infographic / baoyu-slide-deck, happy to mirror the change.	2026-05-21 15:23:42 +08:00
Yelban	e98fa33bc2	feat: add codex-imagegen backend for non-Codex runtimes Implements the preferred_image_backend: codex-imagegen config key already referenced in several SKILL.md files but with no corresponding backend. Bridges non-Codex runtimes (Claude Code, etc.) to Codex CLI's built-in image_gen tool via 'codex exec'. Uses the user's Codex subscription — no OPENAI_API_KEY required. Reliability: - Retry with exponential backoff (default 2 retries, configurable) - 9 classified error kinds (retryable vs non-retryable) - Node child_process timeout with SIGTERM→SIGKILL ladder Correctness: - Verifies image_gen was actually invoked (not bypassed) by checking $CODEX_HOME/generated_images/{thread_id}/ for a PNG - PNG magic byte validation - Output file size sanity check Observability: - Structured JSONL logging with --log-file - Verbose stderr mode with --verbose - Returns thread_id, tool_calls, token usage in result JSON - Raw codex event stream preserved per attempt for debugging Efficiency: - Idempotency cache via --cache-dir (sha256 of prompt+aspect+refs) - Cache hit returns in <0.3s vs 50-90s cold Features: - --ref reference images (repeatable, passed through to codex exec --image) - --retries, --retry-delay, --timeout all configurable - File lock serializes concurrent invocations Testing: - 16 Bun unit tests across parser, cache, validator - Path-filtered CI workflow at .github/workflows/codex-imagegen-tests.yml - Composes with existing test.yml without conflicts Architecture: - scripts/codex-imagegen.sh: thin bash entrypoint (bun → npx -y bun fallback) - scripts/codex-imagegen/: TypeScript module - main.ts (orchestrator), types.ts (CliOptions/GenerateResult/GenError), spawn.ts (child_process), parser.ts (JSONL events), validator.ts (image_gen check + PNG magic), cache.ts (sha256 cache + FileLock), logger.ts (JSONL structured logger) Trade-offs documented in docs/codex-imagegen-backend.md: - 5-10x slower than direct OpenAI API (or near-free on cache hit) - ToS gray area: image_gen is documented for interactive use; non- interactive invocation via codex exec is not explicitly addressed. Suitable for personal low-volume use; users are responsible for ensuring their usage complies with applicable terms of service.	2026-05-20 00:50:24 +08:00