chore: release v1.87.0

chore(baoyu-image-gen): remove deprecated skill from plugin manifest
chore(baoyu-image-gen): remove deprecated redirect skill
2026-07-12 22:09:48 +08:00 · 2026-03-26 09:44:06 -05:00 · 2026-03-26 09:43:05 -05:00 · 2026-03-26 09:41:04 -05:00 · 2026-03-25 20:09:44 -05:00 · 2026-03-25 20:09:30 -05:00
65 changed files with 4081 additions and 965 deletions
@@ -6,7 +6,7 @@
  },
  "metadata": {
    "description": "Skills shared by Baoyu for improving daily work efficiency",
-    "version": "1.79.1"
+    "version": "1.87.0"
  },
  "plugins": [
    {
@@ -22,7 +22,7 @@
        "./skills/baoyu-danger-gemini-web",
        "./skills/baoyu-danger-x-to-markdown",
        "./skills/baoyu-format-markdown",
-        "./skills/baoyu-image-gen",
+        "./skills/baoyu-imagine",
        "./skills/baoyu-infographic",
        "./skills/baoyu-markdown-to-html",
        "./skills/baoyu-post-to-weibo",
@@ -2,6 +2,74 @@

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

+## 1.87.0 - 2026-03-26
+
+### Maintenance
+- Remove deprecated `baoyu-image-gen` redirect skill and plugin manifest entry — migration to `baoyu-imagine` is complete
+
+## 1.86.0 - 2026-03-25
+
+### Features
+- `baoyu-translate`: enrich translation prompt with full analysis context — source voice assessment, structured figurative language mapping, comprehension challenge reasoning, structural/creative challenges, and chunk position context for subagents
+
+## 1.85.0 - 2026-03-25
+
+### Features
+- `baoyu-imagine`: auto-migrate legacy `baoyu-image-gen` EXTEND.md config path at runtime
+- Add `baoyu-image-gen` deprecation redirect skill to guide users to install `baoyu-imagine` and remove the old skill
+
+## 1.84.0 - 2026-03-25
+
+### Features
+- Rename `baoyu-image-gen` skill to `baoyu-imagine` — shorter command name, all references updated across docs, configs, and dependent skills
+
+## 1.83.0 - 2026-03-25
+
+### Features
+- `baoyu-image-gen`: add MiniMax provider (`image-01` / `image-01-live`) with subject_reference for character/portrait consistency, custom sizes, and aspect ratio support
+
+## 1.82.0 - 2026-03-24
+
+### Features
+- `baoyu-url-to-markdown`: add browser fallback strategy — headless first, automatic retry in visible Chrome on technical failure; new `--browser auto|headless|headed` flag with `--headless`/`--headed` shortcuts
+- `baoyu-url-to-markdown`: add content cleaner module for HTML preprocessing before extraction (remove ads, base64 images, scripts, styles)
+- `baoyu-url-to-markdown`: support base64 data URI images in media localizer alongside remote URLs
+- `baoyu-url-to-markdown`: capture final URL from browser to track redirects for output path generation
+- `baoyu-url-to-markdown`: add agent quality gate documentation for post-capture content validation
+
+### Dependencies
+- `baoyu-url-to-markdown`: upgrade defuddle ^0.12.0 → ^0.14.0
+
+### Tests
+- `baoyu-url-to-markdown`: add unit tests for content-cleaner, html-to-markdown, legacy-converter, media-localizer
+
+## 1.81.0 - 2026-03-24
+
+### Features
+- `baoyu-youtube-transcript`: add yt-dlp fallback when YouTube blocks direct InnerTube API, with alternate client identity retry and cookie support via `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` env var
+
+### Refactor
+- `baoyu-youtube-transcript`: split monolithic script into typed modules (youtube, transcript, storage, shared, types) and add unit tests
+
+## 1.80.1 - 2026-03-24
+
+### Fixes
+- `baoyu-image-gen`: use correct `prompt` field name for Jimeng API request
+
+## 1.80.0 - 2026-03-24
+
+### Features
+- `baoyu-image-gen`: add Azure OpenAI as independent image generation provider with flexible endpoint parsing, deployment-name resolution, quality mapping, and reference image validation
+
+## 1.79.2 - 2026-03-23
+
+### Fixes
+- `baoyu-cover-image`: simplify reference image handling — use `--ref` when model supports it, only create description files for models without reference image support
+- `baoyu-post-to-weibo`: add no-theme rule for article markdown-to-HTML conversion
+
+### Tests
+- Fix Node-compatible parser tests and add parser test dependencies
+
 ## 1.79.1 - 2026-03-23

 ### Fixes
@@ -2,6 +2,74 @@

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

+## 1.87.0 - 2026-03-26
+
+### 维护
+- 移除已废弃的 `baoyu-image-gen` 重定向技能及插件清单条目 — 向 `baoyu-imagine` 的迁移已完成
+
+## 1.86.0 - 2026-03-25
+
+### 新功能
+- `baoyu-translate`：丰富翻译提示词的分析上下文 — 加入原文语气评估、结构化比喻映射表、理解难点推理、结构性/创造性翻译挑战，以及分块翻译的位置上下文
+
+## 1.85.0 - 2026-03-25
+
+### 新功能
+- `baoyu-imagine`：运行时自动迁移旧版 `baoyu-image-gen` 的 EXTEND.md 配置路径
+- 新增 `baoyu-image-gen` 废弃重定向技能，引导用户安装 `baoyu-imagine` 并移除旧技能
+
+## 1.84.0 - 2026-03-25
+
+### 新功能
+- 将 `baoyu-image-gen` 技能重命名为 `baoyu-imagine` — 更简短的命令名，所有文档、配置和依赖技能中的引用已同步更新
+
+## 1.83.0 - 2026-03-25
+
+### 新功能
+- `baoyu-image-gen`：新增 MiniMax 服务商（`image-01` / `image-01-live`），支持 subject_reference 角色/肖像一致性、自定义尺寸和宽高比
+
+## 1.82.0 - 2026-03-24
+
+### 新功能
+- `baoyu-url-to-markdown`：新增浏览器回退策略 — 默认无头模式优先，技术故障时自动重试有头 Chrome；新增 `--browser auto|headless|headed` 参数及 `--headless`/`--headed` 快捷方式
+- `baoyu-url-to-markdown`：新增内容清理模块，提取前预处理 HTML（移除广告、base64 图片、脚本、样式）
+- `baoyu-url-to-markdown`：媒体本地化支持 base64 data URI 图片
+- `baoyu-url-to-markdown`：从浏览器捕获最终 URL 以跟踪重定向，用于输出路径生成
+- `baoyu-url-to-markdown`：新增 Agent 质量门控文档，规范捕获后的内容验证流程
+
+### 依赖
+- `baoyu-url-to-markdown`：升级 defuddle ^0.12.0 → ^0.14.0
+
+### 测试
+- `baoyu-url-to-markdown`：新增 content-cleaner、html-to-markdown、legacy-converter、media-localizer 单元测试
+
+## 1.81.0 - 2026-03-24
+
+### 新功能
+- `baoyu-youtube-transcript`：YouTube 封锁直连 InnerTube API 时自动回退到 yt-dlp，支持备用客户端身份重试及通过 `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` 环境变量传递浏览器 Cookie
+
+### 重构
+- `baoyu-youtube-transcript`：将单体脚本拆分为类型化模块（youtube、transcript、storage、shared、types）并添加单元测试
+
+## 1.80.1 - 2026-03-24
+
+### 修复
+- `baoyu-image-gen`：修正即梦 API 请求中的 `prompt` 字段名
+
+## 1.80.0 - 2026-03-24
+
+### 新功能
+- `baoyu-image-gen`：新增 Azure OpenAI 作为独立图像生成服务商，支持灵活的端点解析、部署名称推断、质量映射及参考图片格式校验
+
+## 1.79.2 - 2026-03-23
+
+### 修复
+- `baoyu-cover-image`：简化参考图片处理流程 — 模型支持 `--ref` 时直接传递，仅在模型不支持参考图时创建描述文件
+- `baoyu-post-to-weibo`：文章 Markdown 转 HTML 时不传递 --theme 参数
+
+### 测试
+- 修复 Node 兼容的解析器测试，添加解析器测试依赖
+
 ## 1.79.1 - 2026-03-23

 ### 修复
@@ -1,6 +1,6 @@
 # CLAUDE.md

-Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.79.1**.
+Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.87.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-image-gen` requires API key (OpenAI, Google, OpenRouter, DashScope, or Replicate) configured in EXTEND.md
+- **Image generation APIs**: `baoyu-imagine` 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
@@ -46,7 +46,7 @@ Execute: `${BUN_X} skills/<skill>/scripts/main.ts [options]`
 | Rule | Description |
 |------|-------------|
 | **Load project skills first** | Project skills override system/user-level skills with same name |
-| **Default image generation** | Use `skills/baoyu-image-gen/SKILL.md` unless user specifies otherwise |
+| **Default image generation** | Use `skills/baoyu-imagine/SKILL.md` unless user specifies otherwise |

 Priority: project `skills/` → `$HOME/.baoyu-skills/` → system-level.

@@ -32,7 +32,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-image-gen
+clawhub install baoyu-imagine
 clawhub install baoyu-markdown-to-html
 ```

@@ -661,40 +661,58 @@ Post content to Weibo (微博). Supports regular posts with text, images, and vi

 AI-powered generation backends.

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

-AI SDK-based image generation using OpenAI, Google, OpenRouter, DashScope (Aliyun Tongyi Wanxiang), Jimeng (即梦), Seedream (豆包), and Replicate APIs. Supports text-to-image, reference images, aspect ratios, and quality presets.
+AI SDK-based image generation using OpenAI, 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-image-gen --prompt "A cute cat" --image cat.png
+/baoyu-imagine --prompt "A cute cat" --image cat.png

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

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

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

 # OpenRouter
-/baoyu-image-gen --prompt "A cat" --image cat.png --provider openrouter
+/baoyu-imagine --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

 # DashScope (Aliyun Tongyi Wanxiang)
-/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-imagine --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
+
+# MiniMax
+/baoyu-imagine --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

 # Replicate
-/baoyu-image-gen --prompt "A cat" --image cat.png --provider replicate
+/baoyu-imagine --prompt "A cat" --image cat.png --provider replicate

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

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

-# With reference images (Google, OpenAI, OpenRouter, Replicate, or Seedream 5.0/4.5/4.0)
-/baoyu-image-gen --prompt "Make it blue" --image out.png --ref source.png
+# 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
+
+# Batch mode
+/baoyu-imagine --batchfile batch.json --jobs 4 --json
 ```

 **Options**:
@@ -703,44 +721,73 @@ AI SDK-based image generation using OpenAI, Google, OpenRouter, DashScope (Aliyu
 | `--prompt`, `-p` | Prompt text |
 | `--promptfiles` | Read prompt from files (concatenated) |
 | `--image` | Output image path (required) |
-| `--provider` | `google`, `openai`, `openrouter`, `dashscope`, `jimeng`, `seedream` or `replicate` (default: auto-detect; prefers google) |
-| `--model`, `-m` | Model ID |
+| `--batchfile` | JSON batch file for multi-image generation |
+| `--jobs` | Worker count for batch mode |
+| `--provider` | `google`, `openai`, `azure`, `openrouter`, `dashscope`, `minimax`, `jimeng`, `seedream`, or `replicate` |
+| `--model`, `-m` | Model ID or deployment name. Azure uses deployment name; OpenRouter uses full model IDs; MiniMax uses `image-01` / `image-01-live` |
 | `--ar` | Aspect ratio (e.g., `16:9`, `1:1`, `4:3`) |
 | `--size` | Size (e.g., `1024x1024`) |
 | `--quality` | `normal` or `2k` (default: `2k`) |
-| `--ref` | Reference images (Google, OpenAI, OpenRouter, Replicate, or Seedream 5.0/4.5/4.0) |
+| `--imageSize` | `1K`, `2K`, or `4K` for Google/OpenRouter |
+| `--ref` | Reference images (Google, OpenAI, Azure OpenAI, OpenRouter, Replicate, MiniMax, or Seedream 5.0/4.5/4.0) |
+| `--n` | Number of images per request |
+| `--json` | JSON output |

 **Environment Variables** (see [Environment Configuration](#environment-configuration) for setup):
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `OPENAI_API_KEY` | OpenAI API key | - |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key | - |
 | `OPENROUTER_API_KEY` | OpenRouter API key | - |
 | `GOOGLE_API_KEY` | Google API key | - |
+| `GEMINI_API_KEY` | Alias for `GOOGLE_API_KEY` | - |
 | `DASHSCOPE_API_KEY` | DashScope API key (Aliyun) | - |
+| `MINIMAX_API_KEY` | MiniMax API key | - |
 | `REPLICATE_API_TOKEN` | Replicate API token | - |
 | `JIMENG_ACCESS_KEY_ID` | Jimeng Volcengine access key | - |
 | `JIMENG_SECRET_ACCESS_KEY` | Jimeng Volcengine secret key | - |
 | `ARK_API_KEY` | Seedream Volcengine ARK API key | - |
 | `OPENAI_IMAGE_MODEL` | OpenAI model | `gpt-image-1.5` |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure default deployment name | - |
+| `AZURE_OPENAI_IMAGE_MODEL` | Backward-compatible Azure deployment/model alias | `gpt-image-1.5` |
 | `OPENROUTER_IMAGE_MODEL` | OpenRouter model | `google/gemini-3.1-flash-image-preview` |
 | `GOOGLE_IMAGE_MODEL` | Google model | `gemini-3-pro-image-preview` |
 | `DASHSCOPE_IMAGE_MODEL` | DashScope model | `qwen-image-2.0-pro` |
+| `MINIMAX_IMAGE_MODEL` | MiniMax model | `image-01` |
 | `REPLICATE_IMAGE_MODEL` | Replicate model | `google/nano-banana-pro` |
 | `JIMENG_IMAGE_MODEL` | Jimeng model | `jimeng_t2i_v40` |
 | `SEEDREAM_IMAGE_MODEL` | Seedream model | `doubao-seedream-5-0-260128` |
 | `OPENAI_BASE_URL` | Custom OpenAI endpoint | - |
+| `OPENAI_IMAGE_USE_CHAT` | Use `/chat/completions` for OpenAI image generation | `false` |
+| `AZURE_OPENAI_BASE_URL` | Azure resource or deployment endpoint | - |
+| `AZURE_API_VERSION` | Azure image API version | `2025-04-01-preview` |
 | `OPENROUTER_BASE_URL` | Custom OpenRouter endpoint | `https://openrouter.ai/api/v1` |
+| `OPENROUTER_HTTP_REFERER` | Optional app/site URL for OpenRouter attribution | - |
+| `OPENROUTER_TITLE` | Optional app name for OpenRouter attribution | - |
 | `GOOGLE_BASE_URL` | Custom Google endpoint | - |
 | `DASHSCOPE_BASE_URL` | Custom DashScope endpoint | - |
+| `MINIMAX_BASE_URL` | Custom MiniMax endpoint | `https://api.minimax.io` |
 | `REPLICATE_BASE_URL` | Custom Replicate endpoint | - |
 | `JIMENG_BASE_URL` | Custom Jimeng endpoint | `https://visual.volcengineapi.com` |
 | `JIMENG_REGION` | Jimeng region | `cn-north-1` |
 | `SEEDREAM_BASE_URL` | Custom Seedream endpoint | `https://ark.cn-beijing.volces.com/api/v3` |
+| `BAOYU_IMAGE_GEN_MAX_WORKERS` | Override batch worker cap | `10` |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY` | Override provider concurrency | provider-specific |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS` | Override provider request start gap | provider-specific |
+
+**Provider Notes**:
+- Azure OpenAI: `--model` means Azure deployment name, not the underlying model family.
+- DashScope: `qwen-image-2.0-pro` is the recommended default for custom `--size`, `21:9`, and strong Chinese/English text rendering.
+- MiniMax: `image-01` supports documented custom `width` / `height`; `image-01-live` is lower latency and works best with `--ar`.
+- 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.

 **Provider Auto-Selection**:
-1. If `--provider` specified → use it
-2. If only one API key available → use that provider
-3. If multiple available → default to Google
+1. If `--provider` is specified → use it
+2. If `--ref` is provided and no provider is specified → try Google, then OpenAI, Azure, OpenRouter, Replicate, Seedream, and finally MiniMax
+3. If only one API key is available → use that provider
+4. If multiple providers are available → default to Google

 #### baoyu-danger-gemini-web

@@ -998,7 +1045,7 @@ Custom style descriptions are also accepted, e.g., `--style "poetic and lyrical"
 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-image-gen ...`)
+1. CLI environment variables (e.g., `OPENAI_API_KEY=xxx /baoyu-imagine ...`)
 2. `process.env` (system environment)
 3. `<cwd>/.baoyu-skills/.env` (project-level)
 4. `~/.baoyu-skills/.env` (user-level)
@@ -1015,11 +1062,20 @@ cat > ~/.baoyu-skills/.env << 'EOF'
 OPENAI_API_KEY=sk-xxx
 OPENAI_IMAGE_MODEL=gpt-image-1.5
 # OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_IMAGE_USE_CHAT=false
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=xxx
+AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-image-1.5
+# AZURE_API_VERSION=2025-04-01-preview

 # OpenRouter
 OPENROUTER_API_KEY=sk-or-xxx
 OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
 # OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# OPENROUTER_HTTP_REFERER=https://your-app.example.com
+# OPENROUTER_TITLE=Your App Name

 # Google
 GOOGLE_API_KEY=xxx
@@ -1031,6 +1087,11 @@ DASHSCOPE_API_KEY=sk-xxx
 DASHSCOPE_IMAGE_MODEL=qwen-image-2.0-pro
 # DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1

+# MiniMax
+MINIMAX_API_KEY=xxx
+MINIMAX_IMAGE_MODEL=image-01
+# MINIMAX_BASE_URL=https://api.minimax.io
+
 # Replicate
 REPLICATE_API_TOKEN=r8_xxx
 REPLICATE_IMAGE_MODEL=google/nano-banana-pro
@@ -32,7 +32,7 @@ npx skills add jimliu/baoyu-skills
 ClawHub 按“单个 skill”安装，不是把整个 marketplace 一次性装进去。发布后，用户可以按需安装：

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

@@ -661,40 +661,58 @@ accounts:

 AI 驱动的生成后端。

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

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

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

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

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

 # 指定服务商
-/baoyu-image-gen --prompt "一只猫" --image cat.png --provider openai
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider openai
+
+# Azure OpenAI（model 为部署名称）
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider azure --model gpt-image-1.5

 # OpenRouter
-/baoyu-image-gen --prompt "一只猫" --image cat.png --provider openrouter
+/baoyu-imagine --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

 # DashScope（阿里通义万相）
-/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-imagine --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
+
+# MiniMax
+/baoyu-imagine --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

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

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

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

-# 带参考图（Google、OpenAI、OpenRouter、Replicate 或 Seedream 5.0/4.5/4.0）
-/baoyu-image-gen --prompt "把它变成蓝色" --image out.png --ref source.png
+# 带参考图（Google、OpenAI、Azure OpenAI、OpenRouter、Replicate、MiniMax 或 Seedream 5.0/4.5/4.0）
+/baoyu-imagine --prompt "把它变成蓝色" --image out.png --ref source.png
+
+# 批量模式
+/baoyu-imagine --batchfile batch.json --jobs 4 --json
 ```

 **选项**：
@@ -703,44 +721,73 @@ AI 驱动的生成后端。
 | `--prompt`, `-p` | 提示词文本 |
 | `--promptfiles` | 从文件读取提示词（多文件拼接） |
 | `--image` | 输出图片路径（必需） |
-| `--provider` | `google`、`openai`、`openrouter`、`dashscope`、`jimeng`、`seedream` 或 `replicate`（默认：自动检测，优先 google） |
-| `--model`, `-m` | 模型 ID |
+| `--batchfile` | 多图批量生成的 JSON 文件 |
+| `--jobs` | 批量模式的并发 worker 数 |
+| `--provider` | `google`、`openai`、`azure`、`openrouter`、`dashscope`、`minimax`、`jimeng`、`seedream` 或 `replicate` |
+| `--model`, `-m` | 模型 ID 或部署名。Azure 使用部署名；OpenRouter 使用完整模型 ID；MiniMax 使用 `image-01` / `image-01-live` |
 | `--ar` | 宽高比（如 `16:9`、`1:1`、`4:3`） |
 | `--size` | 尺寸（如 `1024x1024`） |
 | `--quality` | `normal` 或 `2k`（默认：`2k`） |
-| `--ref` | 参考图片（Google、OpenAI、OpenRouter、Replicate 或 Seedream 5.0/4.5/4.0） |
+| `--imageSize` | Google/OpenRouter 使用的 `1K`、`2K`、`4K` |
+| `--ref` | 参考图片（Google、OpenAI、Azure OpenAI、OpenRouter、Replicate、MiniMax 或 Seedream 5.0/4.5/4.0） |
+| `--n` | 单次请求生成图片数量 |
+| `--json` | 输出 JSON 结果 |

 **环境变量**（配置方法见[环境配置](#环境配置)）：
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `OPENAI_API_KEY` | OpenAI API 密钥 | - |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API 密钥 | - |
 | `OPENROUTER_API_KEY` | OpenRouter API 密钥 | - |
 | `GOOGLE_API_KEY` | Google API 密钥 | - |
+| `GEMINI_API_KEY` | `GOOGLE_API_KEY` 的别名 | - |
 | `DASHSCOPE_API_KEY` | DashScope API 密钥（阿里云） | - |
+| `MINIMAX_API_KEY` | MiniMax API 密钥 | - |
 | `REPLICATE_API_TOKEN` | Replicate API Token | - |
 | `JIMENG_ACCESS_KEY_ID` | 即梦火山引擎 Access Key | - |
 | `JIMENG_SECRET_ACCESS_KEY` | 即梦火山引擎 Secret Key | - |
 | `ARK_API_KEY` | 豆包火山引擎 ARK API 密钥 | - |
 | `OPENAI_IMAGE_MODEL` | OpenAI 模型 | `gpt-image-1.5` |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure 默认部署名 | - |
+| `AZURE_OPENAI_IMAGE_MODEL` | 兼容旧配置的 Azure 部署/模型别名 | `gpt-image-1.5` |
 | `OPENROUTER_IMAGE_MODEL` | OpenRouter 模型 | `google/gemini-3.1-flash-image-preview` |
 | `GOOGLE_IMAGE_MODEL` | Google 模型 | `gemini-3-pro-image-preview` |
 | `DASHSCOPE_IMAGE_MODEL` | DashScope 模型 | `qwen-image-2.0-pro` |
+| `MINIMAX_IMAGE_MODEL` | MiniMax 模型 | `image-01` |
 | `REPLICATE_IMAGE_MODEL` | Replicate 模型 | `google/nano-banana-pro` |
 | `JIMENG_IMAGE_MODEL` | 即梦模型 | `jimeng_t2i_v40` |
 | `SEEDREAM_IMAGE_MODEL` | 豆包模型 | `doubao-seedream-5-0-260128` |
 | `OPENAI_BASE_URL` | 自定义 OpenAI 端点 | - |
+| `OPENAI_IMAGE_USE_CHAT` | OpenAI 改走 `/chat/completions` | `false` |
+| `AZURE_OPENAI_BASE_URL` | Azure 资源或部署端点 | - |
+| `AZURE_API_VERSION` | Azure 图像 API 版本 | `2025-04-01-preview` |
 | `OPENROUTER_BASE_URL` | 自定义 OpenRouter 端点 | `https://openrouter.ai/api/v1` |
+| `OPENROUTER_HTTP_REFERER` | OpenRouter 归因用站点 URL | - |
+| `OPENROUTER_TITLE` | OpenRouter 归因用应用名 | - |
 | `GOOGLE_BASE_URL` | 自定义 Google 端点 | - |
 | `DASHSCOPE_BASE_URL` | 自定义 DashScope 端点 | - |
+| `MINIMAX_BASE_URL` | 自定义 MiniMax 端点 | `https://api.minimax.io` |
 | `REPLICATE_BASE_URL` | 自定义 Replicate 端点 | - |
 | `JIMENG_BASE_URL` | 自定义即梦端点 | `https://visual.volcengineapi.com` |
 | `JIMENG_REGION` | 即梦区域 | `cn-north-1` |
 | `SEEDREAM_BASE_URL` | 自定义豆包端点 | `https://ark.cn-beijing.volces.com/api/v3` |
+| `BAOYU_IMAGE_GEN_MAX_WORKERS` | 批量模式最大 worker 数 | `10` |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY` | 覆盖 provider 并发数 | provider 默认值 |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS` | 覆盖 provider 请求启动间隔 | provider 默认值 |
+
+**Provider 说明**：
+- Azure OpenAI：`--model` 表示 Azure deployment name，不是底层模型家族名。
+- DashScope：`qwen-image-2.0-pro` 是自定义 `--size`、`21:9` 和中英文排版的推荐默认模型。
+- MiniMax：`image-01` 支持官方文档里的自定义 `width` / `height`；`image-01-live` 更偏低延迟，适合配合 `--ar` 使用。
+- MiniMax 参考图会走 `subject_reference`，当前能力更偏角色 / 人像一致性。
+- 即梦不支持参考图。
+- 豆包参考图能力仅适用于 Seedream 5.0 / 4.5 / 4.0，不适用于 Seedream 3.0。

 **服务商自动选择**：
 1. 如果指定了 `--provider` → 使用指定的
-2. 如果只有一个 API 密钥 → 使用对应服务商
-3. 如果多个可用 → 默认使用 Google
+2. 如果传了 `--ref` 且未指定 provider → 依次尝试 Google、OpenAI、Azure、OpenRouter、Replicate、Seedream，最后是 MiniMax
+3. 如果只有一个 API 密钥 → 使用对应服务商
+4. 如果多个可用 → 默认使用 Google

 #### baoyu-danger-gemini-web

@@ -998,7 +1045,7 @@ AI 驱动的生成后端。
 部分技能需要 API 密钥或自定义配置。环境变量可以在 `.env` 文件中设置：

 **加载优先级**（高优先级覆盖低优先级）：
-1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-image-gen ...`）
+1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-imagine ...`）
 2. `process.env`（系统环境变量）
 3. `<cwd>/.baoyu-skills/.env`（项目级）
 4. `~/.baoyu-skills/.env`（用户级）
@@ -1015,11 +1062,20 @@ cat > ~/.baoyu-skills/.env << 'EOF'
 OPENAI_API_KEY=sk-xxx
 OPENAI_IMAGE_MODEL=gpt-image-1.5
 # OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_IMAGE_USE_CHAT=false
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=xxx
+AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-image-1.5
+# AZURE_API_VERSION=2025-04-01-preview

 # OpenRouter
 OPENROUTER_API_KEY=sk-or-xxx
 OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
 # OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# OPENROUTER_HTTP_REFERER=https://your-app.example.com
+# OPENROUTER_TITLE=你的应用名

 # Google
 GOOGLE_API_KEY=xxx
@@ -1031,6 +1087,11 @@ DASHSCOPE_API_KEY=sk-xxx
 DASHSCOPE_IMAGE_MODEL=qwen-image-2.0-pro
 # DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1

+# MiniMax
+MINIMAX_API_KEY=xxx
+MINIMAX_IMAGE_MODEL=image-01
+# MINIMAX_BASE_URL=https://api.minimax.io
+
 # Replicate
 REPLICATE_API_TOKEN=r8_xxx
 REPLICATE_IMAGE_MODEL=google/nano-banana-pro
@@ -4,7 +4,7 @@ Skills that require image generation MUST delegate to available image generation

 ## Skill Selection

-**Default**: `skills/baoyu-image-gen/SKILL.md` (unless user specifies otherwise).
+**Default**: `skills/baoyu-imagine/SKILL.md` (unless user specifies otherwise).

 1. Read skill's SKILL.md for parameters and capabilities
 2. If user requests different skill, check `skills/` for alternatives
@@ -16,7 +16,7 @@ Skills that require image generation MUST delegate to available image generation
 ### Step N: Generate Images

 **Skill Selection**:
-1. Check available skills (`baoyu-image-gen` default, or `baoyu-danger-gemini-web`)
+1. Check available skills (`baoyu-imagine` default, or `baoyu-danger-gemini-web`)
 2. Read selected skill's SKILL.md for parameters
 3. If multiple skills available, ask user to choose

@@ -27,7 +27,7 @@ Skills that require image generation MUST delegate to available image generation
 4. On failure, auto-retry once before reporting error
 ```

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

 ## Output Path Convention

@@ -9,7 +9,11 @@
        "packages/*"
      ],
      "devDependencies": {
-        "tsx": "^4.20.5"
+        "@mozilla/readability": "^0.6.0",
+        "linkedom": "^0.18.12",
+        "tsx": "^4.20.5",
+        "turndown": "^7.2.2",
+        "turndown-plugin-gfm": "^1.0.2"
      }
    },
    "node_modules/@esbuild/aix-ppc64": {
@@ -454,6 +458,23 @@
        "node": ">=18"
      }
    },
+    "node_modules/@mixmark-io/domino": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@mixmark-io/domino/-/domino-2.2.0.tgz",
+      "integrity": "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==",
+      "dev": true,
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/@mozilla/readability": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/@mozilla/readability/-/readability-0.6.0.tgz",
+      "integrity": "sha512-juG5VWh4qAivzTAeMzvY9xs9HY5rAcr2E4I7tiSSCokRFi7XIZCAu92ZkSTsIj1OPceCifL3cpfteP3pDT9/QQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
    "node_modules/@types/debug": {
      "version": "4.1.12",
      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
@@ -615,6 +636,13 @@
        "url": "https://github.com/sponsors/fb55"
      }
    },
+    "node_modules/cssom": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/cssom/-/cssom-0.5.0.tgz",
+      "integrity": "sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -896,6 +924,13 @@
        "node": ">=12.0.0"
      }
    },
+    "node_modules/html-escaper": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-3.0.3.tgz",
+      "integrity": "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/htmlparser2": {
      "version": "9.1.0",
      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-9.1.0.tgz",
@@ -984,6 +1019,51 @@
        "node": ">=18.17"
      }
    },
+    "node_modules/linkedom": {
+      "version": "0.18.12",
+      "resolved": "https://registry.npmjs.org/linkedom/-/linkedom-0.18.12.tgz",
+      "integrity": "sha512-jalJsOwIKuQJSeTvsgzPe9iJzyfVaEJiEXl+25EkKevsULHvMJzpNqwvj1jOESWdmgKDiXObyjOYwlUqG7wo1Q==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "css-select": "^5.1.0",
+        "cssom": "^0.5.0",
+        "html-escaper": "^3.0.3",
+        "htmlparser2": "^10.0.0",
+        "uhyphen": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "peerDependencies": {
+        "canvas": ">= 2"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/linkedom/node_modules/htmlparser2": {
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-10.1.0.tgz",
+      "integrity": "sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/fb55/htmlparser2?sponsor=1",
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.2.2",
+        "entities": "^7.0.1"
+      }
+    },
    "node_modules/longest-streak": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz",
@@ -1768,6 +1848,30 @@
        "fsevents": "~2.3.3"
      }
    },
+    "node_modules/turndown": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/turndown/-/turndown-7.2.2.tgz",
+      "integrity": "sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@mixmark-io/domino": "^2.2.0"
+      }
+    },
+    "node_modules/turndown-plugin-gfm": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/turndown-plugin-gfm/-/turndown-plugin-gfm-1.0.2.tgz",
+      "integrity": "sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/uhyphen": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/uhyphen/-/uhyphen-0.2.0.tgz",
+      "integrity": "sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA==",
+      "dev": true,
+      "license": "ISC"
+    },
    "node_modules/undici": {
      "version": "6.24.0",
      "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.0.tgz",
@@ -10,6 +10,10 @@
    "test:coverage": "node --import tsx --experimental-test-coverage --test"
  },
  "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.12",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
    "tsx": "^4.20.5"
  }
 }
@@ -118,7 +118,7 @@ Full template: [references/workflow.md](references/workflow.md#step-4-generate-o

 ⛔ **BLOCKING: Prompt files MUST be saved before ANY image generation.**

-**Execution strategy**: When multiple illustrations have saved prompt files and the task is now plain generation, prefer `baoyu-image-gen` batch mode (`build-batch.ts` → `--batchfile`) over spawning subagents. Use subagents only when each image still needs separate prompt iteration or creative exploration.
+**Execution strategy**: When multiple illustrations have saved prompt files and the task is now plain generation, prefer `baoyu-imagine` batch mode (`build-batch.ts` → `--batchfile`) over spawning subagents. Use subagents only when each image still needs separate prompt iteration or creative exploration.

 1. For each illustration, create a prompt file per [references/prompt-construction.md](references/prompt-construction.md)
 2. Save to `prompts/NN-{type}-{slug}.md` with YAML frontmatter
@@ -316,7 +316,7 @@ Prompt Files:
 **DO NOT** pass ad-hoc inline text to `--prompt` without first saving prompt files. The generation command should either use `--promptfiles prompts/NN-{type}-{slug}.md` or read the saved file content for `--prompt`.

 **Execution choice**:
- If multiple illustrations already have saved prompt files and the task is now plain generation, prefer `baoyu-image-gen` batch mode (`build-batch.ts` -> `main.ts --batchfile`)
+- If multiple illustrations already have saved prompt files and the task is now plain generation, prefer `baoyu-imagine` batch mode (`build-batch.ts` -> `main.ts --batchfile`)
 - Use subagents only when each illustration still needs separate prompt rewriting, style exploration, or other per-image reasoning before generation

 **CRITICAL - References in Frontmatter**:
@@ -352,7 +352,7 @@ Check available skills. If multiple, ask user.

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

 **Verification**: Before generating, confirm reference processing:
@@ -29,8 +29,8 @@ Options:
  --prompts <path>     Path to prompts directory
  --output <path>      Path to output batch.json
  --images-dir <path>  Directory for generated images
-  --provider <name>    Provider for baoyu-image-gen batch tasks (default: replicate)
-  --model <id>         Model for baoyu-image-gen batch tasks (default: google/nano-banana-pro)
+  --provider <name>    Provider for baoyu-imagine batch tasks (default: replicate)
+  --model <id>         Model for baoyu-imagine batch tasks (default: google/nano-banana-pro)
  --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)
@@ -216,7 +216,7 @@ Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard →

 **7.1 Generate character sheet first**:
 - **Backup rule**: If `characters/characters.png` exists, rename to `characters/characters-backup-YYYYMMDD-HHMMSS.png`
- Invoke an installed image generation skill such as `baoyu-image-gen`
+- Invoke an installed image generation skill such as `baoyu-imagine`
 - Read that skill's `SKILL.md` and follow its documented interface rather than calling its scripts directly
 - Use `characters/characters.md` as the prompt-file input
 - Save output to `characters/characters.png`
@@ -433,7 +433,7 @@ With confirmed prompts from Step 5/6:
 | Supports `--ref` | **Strategy A** | Pass `characters/characters.png` with EVERY page |
 | Does NOT support `--ref` | **Strategy B** | Prepend character descriptions to EVERY prompt |

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

 - Read the chosen image generation skill's `SKILL.md`
 - Invoke that installed skill via its documented interface, not by calling its scripts directly
@@ -162,15 +162,14 @@ if (Test-Path "$HOME/.baoyu-skills/baoyu-cover-image/EXTEND.md") { "user" }
 5. **Detect language**: Compare source, user input, EXTEND.md preference
 6. **Determine output directory**: Per File Structure rules

-**⚠️ People in Reference Images — MUST follow all 3 rules:**
+**⚠️ People in Reference Images:**

 If reference images contain **people** who should appear in the cover:

-1. **`usage: direct`** — MUST set in refs description file. NEVER use `style` or `palette` when people need to appear
-2. **Per-character description** — MUST describe each person's distinctive features (hair, glasses, skin tone, clothing) in `refs/ref-NN-{slug}.md`. Vague descriptions like "a man" will fail
-3. **`--ref` flag** — MUST pass reference image via `--ref` in Step 4 so the model sees actual faces
+- **Model supports `--ref`** (default): Copy image to `refs/`, pass via `--ref` at generation. No description file needed — the model sees the face directly.
+- **Model does NOT support `--ref`** (Jimeng, Seedream 3.0): Create `refs/ref-NN-{slug}.md` with per-character description (hair, glasses, skin tone, clothing). Embed as MUST/REQUIRED instructions in prompt text.

-See [reference-images.md § Character Analysis](references/workflow/reference-images.md) for description format.
+See [reference-images.md](references/workflow/reference-images.md) for full decision table.

 ### Step 2: Confirm Options ⚠️

@@ -16,17 +16,24 @@ Guide for processing user-provided reference images in cover generation.

 **If user provides file path**:
 1. Copy to `refs/ref-NN-{slug}.{ext}` (NN = 01, 02, ...)
-2. Create description: `refs/ref-NN-{slug}.md`
-3. Verify files exist before proceeding
+2. **Only** create description file `refs/ref-NN-{slug}.md` when model does NOT support `--ref` (see below)
+3. Verify image file exists before proceeding

-**Description File Format**:
+**When to create description file**:
+
+| Situation | Action |
+|-----------|--------|
+| Model supports `--ref` (Google, OpenAI, OpenRouter, Replicate, Seedream 4.0+) | Copy image only. **No description file needed.** Pass via `--ref` at generation. |
+| Model does NOT support `--ref` (Jimeng, Seedream 3.0) | Copy image + create description file. Embed description in prompt text. |
+
+**Description File Format** (only when needed):
 ```yaml
 ---
 ref_id: NN
 filename: ref-NN-{slug}.{ext}
 usage: direct | style | palette
 ---
-[User's description or auto-generated description]
+[Character or style description to embed in prompt]
 ```

 | Usage | When to Use |
@@ -1,10 +1,10 @@
 ---
-name: baoyu-image-gen
-description: AI image generation with OpenAI, Google, OpenRouter, DashScope, 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.3
+name: baoyu-imagine
+description: AI image generation with OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, 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
 metadata:
  openclaw:
-    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-image-gen
+    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-imagine
    requires:
      anyBins:
        - bun
@@ -13,7 +13,7 @@ metadata:

 # Image Generation (AI SDK)

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

 ## Script Directory

@@ -30,17 +30,17 @@ Check EXTEND.md existence (priority: project → user):

 ```bash
 # macOS, Linux, WSL, Git Bash
-test -f .baoyu-skills/baoyu-image-gen/EXTEND.md && echo "project"
-test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "xdg"
-test -f "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "user"
+test -f .baoyu-skills/baoyu-imagine/EXTEND.md && echo "project"
+test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-imagine/EXTEND.md" && echo "xdg"
+test -f "$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md" && echo "user"
 ```

 ```powershell
 # PowerShell (Windows)
-if (Test-Path .baoyu-skills/baoyu-image-gen/EXTEND.md) { "project" }
+if (Test-Path .baoyu-skills/baoyu-imagine/EXTEND.md) { "project" }
 $xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
-if (Test-Path "$xdg/baoyu-skills/baoyu-image-gen/EXTEND.md") { "xdg" }
-if (Test-Path "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md") { "user" }
+if (Test-Path "$xdg/baoyu-skills/baoyu-imagine/EXTEND.md") { "xdg" }
+if (Test-Path "$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md") { "user" }
 ```

 | Result | Action |
@@ -52,8 +52,10 @@ if (Test-Path "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md") { "user" }

 | Path | Location |
 |------|----------|
-| `.baoyu-skills/baoyu-image-gen/EXTEND.md` | Project directory |
-| `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` | User home |
+| `.baoyu-skills/baoyu-imagine/EXTEND.md` | Project directory |
+| `$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md` | User home |
+
+Legacy compatibility: if `.baoyu-skills/baoyu-image-gen/EXTEND.md` exists and the new path does not, runtime renames it to `baoyu-imagine`. If both files exist, runtime leaves them unchanged and uses the new path.

 **EXTEND.md Supports**: Default provider | Default quality | Default aspect ratio | Default image size | Default models | Batch worker cap | Provider-specific batch limits

@@ -74,12 +76,15 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k
 # From prompt files
 ${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

-# With reference images (Google, OpenAI, OpenRouter, Replicate, or Seedream 4.0/4.5/5.0)
+# With reference images (Google, OpenAI, Azure OpenAI, OpenRouter, Replicate, MiniMax, or Seedream 4.0/4.5/5.0)
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

 # With reference images (explicit provider/model)
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

+# Azure OpenAI (model means deployment name)
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider azure --model gpt-image-1.5
+
 # OpenRouter (recommended default model)
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openrouter

@@ -98,6 +103,15 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "为咖啡品牌设计一张 21:9
 # DashScope legacy Qwen fixed-size model
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "一张电影感海报" --image out.png --provider dashscope --model qwen-image-max --size 1664x928

+# MiniMax
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax
+
+# MiniMax with subject reference (best for character/portrait consistency)
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9
+
+# MiniMax with custom size (documented for image-01)
+${BUN_X} {baseDir}/scripts/main.ts --prompt "A cinematic poster" --image out.jpg --provider minimax --model image-01 --size 1536x1024
+
 # Replicate (google/nano-banana-pro)
 ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

@@ -147,13 +161,13 @@ Paths in `promptFiles`, `image`, and `ref` are resolved relative to the batch fi
 | `--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\|jimeng\|seedream\|replicate` | Force provider (default: auto-detect) |
-| `--model <id>`, `-m` | Model ID (Google: `gemini-3-pro-image-preview`; OpenAI: `gpt-image-1.5`; OpenRouter: `google/gemini-3.1-flash-image-preview`; DashScope: `qwen-image-2.0-pro`) |
+| `--provider google\|openai\|azure\|openrouter\|dashscope\|minimax\|jimeng\|seedream\|replicate` | Force provider (default: auto-detect) |
+| `--model <id>`, `-m` | Model ID (Google: `gemini-3-pro-image-preview`; OpenAI: `gpt-image-1.5`; Azure: deployment name such as `gpt-image-1.5` or `image-prod`; OpenRouter: `google/gemini-3.1-flash-image-preview`; DashScope: `qwen-image-2.0-pro`; MiniMax: `image-01`) |
 | `--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. Supported by Google multimodal, OpenAI GPT Image edits, OpenRouter multimodal models, Replicate, and Seedream 5.0/4.5/4.0. Not supported by Jimeng, Seedream 3.0, or removed 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, MiniMax subject-reference, and Seedream 5.0/4.5/4.0. Not supported by Jimeng, Seedream 3.0, or removed SeedEdit 3.0 |
 | `--n <count>` | Number of images |
 | `--json` | JSON output |

@@ -162,26 +176,34 @@ Paths in `promptFiles`, `image`, and `ref` are resolved relative to the batch fi
 | Variable | Description |
 |----------|-------------|
 | `OPENAI_API_KEY` | OpenAI API key |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
 | `OPENROUTER_API_KEY` | OpenRouter API key |
 | `GOOGLE_API_KEY` | Google API key |
 | `DASHSCOPE_API_KEY` | DashScope API key (阿里云) |
+| `MINIMAX_API_KEY` | MiniMax API key |
 | `REPLICATE_API_TOKEN` | Replicate API token |
 | `JIMENG_ACCESS_KEY_ID` | Jimeng (即梦) Volcengine access key |
 | `JIMENG_SECRET_ACCESS_KEY` | Jimeng (即梦) Volcengine secret key |
 | `ARK_API_KEY` | Seedream (豆包) Volcengine ARK API key |
 | `OPENAI_IMAGE_MODEL` | OpenAI model override |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure default deployment name |
+| `AZURE_OPENAI_IMAGE_MODEL` | Backward-compatible alias for Azure default deployment/model name |
 | `OPENROUTER_IMAGE_MODEL` | OpenRouter model override (default: `google/gemini-3.1-flash-image-preview`) |
 | `GOOGLE_IMAGE_MODEL` | Google model override |
 | `DASHSCOPE_IMAGE_MODEL` | DashScope model override (default: `qwen-image-2.0-pro`) |
+| `MINIMAX_IMAGE_MODEL` | MiniMax model override (default: `image-01`) |
 | `REPLICATE_IMAGE_MODEL` | Replicate model override (default: google/nano-banana-pro) |
 | `JIMENG_IMAGE_MODEL` | Jimeng model override (default: jimeng_t2i_v40) |
 | `SEEDREAM_IMAGE_MODEL` | Seedream model override (default: doubao-seedream-5-0-260128) |
 | `OPENAI_BASE_URL` | Custom OpenAI endpoint |
+| `AZURE_OPENAI_BASE_URL` | Azure resource endpoint or deployment endpoint |
+| `AZURE_API_VERSION` | Azure image API version (default: `2025-04-01-preview`) |
 | `OPENROUTER_BASE_URL` | Custom OpenRouter endpoint (default: `https://openrouter.ai/api/v1`) |
 | `OPENROUTER_HTTP_REFERER` | Optional app/site URL for OpenRouter attribution |
 | `OPENROUTER_TITLE` | Optional app name for OpenRouter attribution |
 | `GOOGLE_BASE_URL` | Custom Google endpoint |
 | `DASHSCOPE_BASE_URL` | Custom DashScope endpoint |
+| `MINIMAX_BASE_URL` | Custom MiniMax endpoint (default: `https://api.minimax.io`) |
 | `REPLICATE_BASE_URL` | Custom Replicate endpoint |
 | `JIMENG_BASE_URL` | Custom Jimeng endpoint (default: `https://visual.volcengineapi.com`) |
 | `JIMENG_REGION` | Jimeng region (default: `cn-north-1`) |
@@ -201,6 +223,8 @@ Model priority (highest → lowest), applies to all providers:
 3. Env var: `<PROVIDER>_IMAGE_MODEL` (e.g., `GOOGLE_IMAGE_MODEL`)
 4. Built-in default

+For Azure, `--model` / `default_model.azure` should be the Azure deployment name. `AZURE_OPENAI_DEPLOYMENT` is the preferred env var, and `AZURE_OPENAI_IMAGE_MODEL` remains as a backward-compatible alias.
+
 **EXTEND.md overrides env vars**. If both EXTEND.md `default_model.google: "gemini-3-pro-image-preview"` and env var `GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview` exist, EXTEND.md wins.

 **Agent MUST display model info** before each generation:
@@ -230,7 +254,7 @@ When translating CLI args into DashScope behavior:
 - `--size` wins over `--ar`
 - For `qwen-image-2.0*`, prefer explicit `--size`; otherwise infer from `--ar` and use the official recommended resolutions below
 - For `qwen-image-max/plus/image`, only use the five official fixed sizes; if the requested ratio is not covered, switch to `qwen-image-2.0-pro`
- `--quality` is a baoyu-image-gen compatibility preset, not a native DashScope API field. Mapping `normal` / `2k` onto the `qwen-image-2.0*` table below is an implementation inference, not an official API guarantee
+- `--quality` is a baoyu-imagine compatibility preset, not a native DashScope API field. Mapping `normal` / `2k` onto the `qwen-image-2.0*` table below is an implementation inference, not an official API guarantee

 Recommended `qwen-image-2.0*` sizes for common aspect ratios:

@@ -245,7 +269,7 @@ Recommended `qwen-image-2.0*` sizes for common aspect ratios:
 | `16:9` | `1280*720` | `1920*1080` |
 | `21:9` | `1344*576` | `2048*872` |

-DashScope official APIs also expose `negative_prompt`, `prompt_extend`, and `watermark`, but `baoyu-image-gen` does not expose them as dedicated CLI flags today.
+DashScope official APIs also expose `negative_prompt`, `prompt_extend`, and `watermark`, but `baoyu-imagine` does not expose them as dedicated CLI flags today.

 Official references:

@@ -253,6 +277,34 @@ Official references:
 - [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)

+### MiniMax Models
+
+Use `--model image-01` or set `default_model.minimax` / `MINIMAX_IMAGE_MODEL` when the user wants MiniMax image generation.
+
+Official MiniMax image model options currently documented in the API reference:
+
+- `image-01` (recommended default)
+  - Supports text-to-image and subject-reference image generation
+  - Supports official `aspect_ratio` values: `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`
+  - Supports documented custom `width` / `height` output sizes when using `--size <WxH>`
+  - `width` and `height` must both be between `512` and `2048`, and both must be divisible by `8`
+- `image-01-live`
+  - Lower-latency variant
+  - Use `--ar` for sizing; MiniMax documents custom `width` / `height` as only effective for `image-01`
+
+MiniMax subject reference notes:
+
+- `--ref` files are sent as MiniMax `subject_reference`
+- MiniMax docs currently describe `subject_reference[].type` as `character`
+- Official docs say `image_file` supports public URLs or Base64 Data URLs; `baoyu-imagine` sends local refs as Data URLs
+- Official docs recommend front-facing portrait references in JPG/JPEG/PNG under 10MB
+
+Official references:
+
+- [MiniMax Image Generation Guide](https://platform.minimax.io/docs/guides/image-generation)
+- [MiniMax Text-to-Image API](https://platform.minimax.io/docs/api-reference/image-generation-t2i)
+- [MiniMax Image-to-Image API](https://platform.minimax.io/docs/api-reference/image-generation-i2i)
+
 ### OpenRouter Models

 Use full OpenRouter model IDs, e.g.:
@@ -287,8 +339,8 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider r

 ## Provider Selection

-1. `--ref` provided + no `--provider` → auto-select Google first, then OpenAI, then OpenRouter, then Replicate (Jimeng and Seedream do not support reference images)
-2. `--provider` specified → use it (if `--ref`, must be `google`, `openai`, `openrouter`, or `replicate`)
+1. `--ref` provided + no `--provider` → auto-select Google first, then OpenAI, then Azure, then OpenRouter, then Replicate, then Seedream, then MiniMax (MiniMax subject reference is more specialized toward character/portrait consistency)
+2. `--provider` specified → use it (if `--ref`, must be `google`, `openai`, `azure`, `openrouter`, `replicate`, `seedream`, or `minimax`)
 3. Only one API key available → use that provider
 4. Multiple available → default to Google

@@ -309,6 +361,7 @@ Supported: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2.35:1`
 - OpenAI: maps to closest supported size
 - OpenRouter: sends `imageGenerationOptions.aspect_ratio`; if only `--size <WxH>` is given, aspect ratio is inferred automatically
 - Replicate: passes `aspect_ratio` to model; when `--ref` is provided without `--ar`, defaults to `match_input_image`
+- MiniMax: sends official `aspect_ratio` values directly; if `--size <WxH>` is given without `--ar`, `width` / `height` are sent for `image-01`

 ## Generation Mode

@@ -1,6 +1,6 @@
 ---
 name: first-time-setup
-description: First-time setup and default model selection flow for baoyu-image-gen
+description: First-time setup and default model selection flow for baoyu-imagine
 ---

 # First-Time Setup
@@ -47,10 +47,14 @@ options:
    description: "Gemini multimodal - high quality, reference images, flexible sizes"
  - label: "OpenAI"
    description: "GPT Image - consistent quality, reliable output"
+  - 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: "MiniMax"
+    description: "MiniMax image generation with subject-reference character workflows"
  - label: "Replicate"
    description: "Community models - nano-banana-pro, flexible model selection"
 ```
@@ -87,6 +91,34 @@ options:
    description: "Strong text-to-image quality through OpenRouter"
 ```

+### Question 2c: Default Azure Deployment
+
+Only show if user selected Azure OpenAI.
+
+```yaml
+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"
+    description: "Previous GPT Image deployment name"
+```
+
+### Question 2d: Default MiniMax Model
+
+Only show if user selected MiniMax.
+
+```yaml
+header: "MiniMax Model"
+question: "Default MiniMax image generation model?"
+options:
+  - label: "image-01 (Recommended)"
+    description: "Best default, supports aspect ratios and custom width/height"
+  - label: "image-01-live"
+    description: "Faster variant, use aspect ratio instead of custom size"
+```
+
 ### Question 3: Default Quality

 ```yaml
@@ -115,8 +147,8 @@ options:

 | Choice | Path | Scope |
 |--------|------|-------|
-| Project | `.baoyu-skills/baoyu-image-gen/EXTEND.md` | Current project |
-| User | `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` | All projects |
+| Project | `.baoyu-skills/baoyu-imagine/EXTEND.md` | Current project |
+| User | `$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md` | All projects |

 ### EXTEND.md Template

@@ -130,8 +162,10 @@ default_image_size: 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
+  minimax: [selected minimax model or null]
  replicate: null
 ---
 ```
@@ -166,6 +200,23 @@ options:
    description: "Previous generation GPT Image model"
 ```

+### Azure Deployment Selection
+
+```yaml
+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-1"
+    description: "Use when your Azure deployment name matches GPT-image-1"
+```
+
+Notes for Azure setup:
+
+- In `baoyu-imagine`, Azure `--model` / `default_model.azure` should be the Azure deployment name, not just the underlying model family.
+- If the deployment name is custom, save that exact deployment name in `default_model.azure`.
+
 ### OpenRouter Model Selection

 ```yaml
@@ -204,7 +255,7 @@ 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`.
- In `baoyu-image-gen`, `quality` is a compatibility preset. It is not a native DashScope parameter.
+- In `baoyu-imagine`, `quality` is a compatibility preset. It is not a native DashScope parameter.

 ### Replicate Model Selection

@@ -218,6 +269,24 @@ options:
    description: "Google's base image model on Replicate"
 ```

+### MiniMax Model Selection
+
+```yaml
+header: "MiniMax Model"
+question: "Choose a default MiniMax image generation model?"
+options:
+  - label: "image-01 (Recommended)"
+    description: "Best general-purpose MiniMax image model with custom width/height support"
+  - label: "image-01-live"
+    description: "Lower-latency MiniMax image model using aspect ratios"
+```
+
+Notes for MiniMax setup:
+
+- `image-01` is the safest default. It supports official `aspect_ratio` values and documented custom `width` / `height` output sizes.
+- `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.
+
 ### Update EXTEND.md

 After user selects a model:
@@ -230,8 +299,10 @@ After user selects a model:
 default_model:
  google: [value or null]
  openai: [value or null]
+  azure: [value or null]
  openrouter: [value or null]
  dashscope: [value or null]
+  minimax: [value or null]
  replicate: [value or null]
 ```

@@ -1,6 +1,6 @@
 ---
 name: preferences-schema
-description: EXTEND.md YAML schema for baoyu-image-gen user preferences
+description: EXTEND.md YAML schema for baoyu-imagine user preferences
 ---

 # Preferences Schema
@@ -11,7 +11,7 @@ description: EXTEND.md YAML schema for baoyu-image-gen user preferences
 ---
 version: 1

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

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

@@ -22,8 +22,10 @@ default_image_size: null    # 1K|2K|4K|null (Google/OpenRouter, overrides qualit
 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"
  openrouter: null          # e.g., "google/gemini-3.1-flash-image-preview"
  dashscope: null           # e.g., "qwen-image-2.0-pro"
+  minimax: null             # e.g., "image-01"
  replicate: null           # e.g., "google/nano-banana-pro"

 batch:
@@ -38,12 +40,18 @@ batch:
    openai:
      concurrency: 3
      start_interval_ms: 1100
+    azure:
+      concurrency: 3
+      start_interval_ms: 1100
    openrouter:
      concurrency: 3
      start_interval_ms: 1100
    dashscope:
      concurrency: 3
      start_interval_ms: 1100
+    minimax:
+      concurrency: 3
+      start_interval_ms: 1100
 ---
 ```

@@ -58,8 +66,10 @@ batch:
 | `default_image_size` | string\|null | null | Google/OpenRouter image size (overrides quality) |
 | `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.minimax` | string\|null | null | MiniMax default model |
 | `default_model.replicate` | string\|null | null | Replicate default model |
 | `batch.max_workers` | int\|null | 10 | Batch worker cap |
 | `batch.provider_limits.<provider>.concurrency` | int\|null | provider default | Max simultaneous requests per provider |
@@ -87,8 +97,10 @@ default_image_size: 2K
 default_model:
  google: "gemini-3-pro-image-preview"
  openai: "gpt-image-1.5"
+  azure: "gpt-image-1.5"
  openrouter: "google/gemini-3.1-flash-image-preview"
  dashscope: "qwen-image-2.0-pro"
+  minimax: "image-01"
  replicate: "google/nano-banana-pro"
 batch:
  max_workers: 10
@@ -96,8 +108,14 @@ batch:
    replicate:
      concurrency: 5
      start_interval_ms: 700
+    azure:
+      concurrency: 3
+      start_interval_ms: 1100
    openrouter:
      concurrency: 3
      start_interval_ms: 1100
+    minimax:
+      concurrency: 3
+      start_interval_ms: 1100
 ---
 ```
@@ -13,6 +13,7 @@ import {
  getWorkerCount,
  isRetryableGenerationError,
  loadBatchTasks,
+  loadExtendConfig,
  mergeConfig,
  normalizeOutputImagePath,
  parseArgs,
@@ -69,7 +70,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-imagine CLI flags", () => {
  const args = parseArgs([
    "--promptfiles",
    "prompts/system.md",
@@ -123,6 +124,8 @@ default_image_size: 2K
 default_model:
  google: gemini-3-pro-image-preview
  openai: gpt-image-1.5
+  azure: image-prod
+  minimax: image-01
 batch:
  max_workers: 8
  provider_limits:
@@ -131,6 +134,12 @@ batch:
      start_interval_ms: 900
    openai:
      concurrency: 4
+    minimax:
+      concurrency: 2
+      start_interval_ms: 1400
+    azure:
+      concurrency: 1
+      start_interval_ms: 1500
 `;

  const config = parseSimpleYaml(yaml);
@@ -142,6 +151,8 @@ batch:
  assert.equal(config.default_image_size, "2K");
  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?.azure, "image-prod");
+  assert.equal(config.default_model?.minimax, "image-01");
  assert.equal(config.batch?.max_workers, 8);
  assert.deepEqual(config.batch?.provider_limits?.google, {
    concurrency: 2,
@@ -150,6 +161,69 @@ batch:
  assert.deepEqual(config.batch?.provider_limits?.openai, {
    concurrency: 4,
  });
+  assert.deepEqual(config.batch?.provider_limits?.minimax, {
+    concurrency: 2,
+    start_interval_ms: 1400,
+  });
+  assert.deepEqual(config.batch?.provider_limits?.azure, {
+    concurrency: 1,
+    start_interval_ms: 1500,
+  });
+});
+
+test("loadExtendConfig renames legacy EXTEND.md when the new path is missing", async () => {
+  const root = await makeTempDir("baoyu-imagine-extend-");
+  const cwd = path.join(root, "project");
+  const home = path.join(root, "home");
+  const legacyPath = path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md");
+  const currentPath = path.join(cwd, ".baoyu-skills", "baoyu-imagine", "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-imagine-extend-dual-");
+  const cwd = path.join(root, "project");
+  const home = path.join(root, "home");
+  const legacyPath = path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md");
+  const currentPath = path.join(cwd, ".baoyu-skills", "baoyu-imagine", "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", () => {
@@ -191,6 +265,7 @@ test("detectProvider rejects non-ref-capable providers and prefers Google first
    OPENAI_API_KEY: "openai-key",
    OPENROUTER_API_KEY: null,
    DASHSCOPE_API_KEY: null,
+    MINIMAX_API_KEY: null,
    REPLICATE_API_TOKEN: null,
    JIMENG_ACCESS_KEY_ID: null,
    JIMENG_SECRET_ACCESS_KEY: null,
@@ -203,8 +278,11 @@ test("detectProvider selects an available ref-capable provider for reference-ima
  useEnv(t, {
    GOOGLE_API_KEY: null,
    OPENAI_API_KEY: "openai-key",
+    AZURE_OPENAI_API_KEY: null,
+    AZURE_OPENAI_BASE_URL: null,
    OPENROUTER_API_KEY: null,
    DASHSCOPE_API_KEY: null,
+    MINIMAX_API_KEY: null,
    REPLICATE_API_TOKEN: null,
    JIMENG_ACCESS_KEY_ID: null,
    JIMENG_SECRET_ACCESS_KEY: null,
@@ -216,12 +294,35 @@ test("detectProvider selects an available ref-capable provider for reference-ima
  );
 });

+test("detectProvider selects Azure when only Azure credentials are configured", (t) => {
+  useEnv(t, {
+    GOOGLE_API_KEY: null,
+    OPENAI_API_KEY: null,
+    AZURE_OPENAI_API_KEY: "azure-key",
+    AZURE_OPENAI_BASE_URL: "https://example.openai.azure.com",
+    OPENROUTER_API_KEY: null,
+    DASHSCOPE_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()), "azure");
+  assert.equal(
+    detectProvider(makeArgs({ referenceImages: ["ref.png"] })),
+    "azure",
+  );
+});
+
 test("detectProvider infers Seedream from model id and allows Seedream reference-image workflows", (t) => {
  useEnv(t, {
    GOOGLE_API_KEY: null,
    OPENAI_API_KEY: null,
    OPENROUTER_API_KEY: null,
    DASHSCOPE_API_KEY: null,
+    MINIMAX_API_KEY: null,
    REPLICATE_API_TOKEN: null,
    JIMENG_ACCESS_KEY_ID: null,
    JIMENG_SECRET_ACCESS_KEY: null,
@@ -249,6 +350,26 @@ test("detectProvider infers Seedream from model id and allows Seedream reference
  );
 });

+test("detectProvider selects MiniMax when only MiniMax credentials are configured 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,
+    MINIMAX_API_KEY: "minimax-key",
+    REPLICATE_API_TOKEN: null,
+    JIMENG_ACCESS_KEY_ID: null,
+    JIMENG_SECRET_ACCESS_KEY: null,
+    ARK_API_KEY: null,
+  });
+
+  assert.equal(detectProvider(makeArgs()), "minimax");
+  assert.equal(detectProvider(makeArgs({ referenceImages: ["ref.png"] })), "minimax");
+  assert.equal(detectProvider(makeArgs({ model: "image-01-live" })), "minimax");
+});
+
 test("batch worker and provider-rate-limit configuration prefer env over EXTEND config", (t) => {
  useEnv(t, {
    BAOYU_IMAGE_GEN_MAX_WORKERS: "12",
@@ -264,6 +385,10 @@ test("batch worker and provider-rate-limit configuration prefer env over EXTEND
          concurrency: 2,
          start_interval_ms: 900,
        },
+        minimax: {
+          concurrency: 1,
+          start_interval_ms: 1500,
+        },
      },
    },
  };
@@ -273,10 +398,14 @@ test("batch worker and provider-rate-limit configuration prefer env over EXTEND
    concurrency: 5,
    startIntervalMs: 450,
  });
+  assert.deepEqual(getConfiguredProviderRateLimits(extendConfig).minimax, {
+    concurrency: 1,
+    startIntervalMs: 1500,
+  });
 });

 test("loadBatchTasks and createTaskArgs resolve batch-relative paths", async (t) => {
-  const root = await makeTempDir("baoyu-image-gen-batch-");
+  const root = await makeTempDir("baoyu-imagine-batch-");
  t.after(() => fs.rm(root, { recursive: true, force: true }));

  const batchFile = path.join(root, "jobs", "batch.json");
@@ -2,7 +2,7 @@ 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,
@@ -58,8 +58,10 @@ const DEFAULT_PROVIDER_RATE_LIMITS: Record<Provider, ProviderRateLimit> = {
  openai: { concurrency: 3, startIntervalMs: 1100 },
  openrouter: { concurrency: 3, startIntervalMs: 1100 },
  dashscope: { concurrency: 3, startIntervalMs: 1100 },
+  minimax: { concurrency: 3, startIntervalMs: 1100 },
  jimeng: { concurrency: 3, startIntervalMs: 1100 },
  seedream: { concurrency: 3, startIntervalMs: 1100 },
+  azure: { concurrency: 3, startIntervalMs: 1100 },
 };

 function printUsage(): void {
@@ -74,13 +76,13 @@ 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|replicate|jimeng|seedream  Force provider (auto-detect by default)
+  --provider google|openai|openrouter|dashscope|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, OpenRouter, Replicate, or Seedream 4.0/4.5/5.0)
+  --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)
  --json                    JSON output
  -h, --help                Show help
@@ -111,6 +113,7 @@ 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
+  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
@@ -119,6 +122,7 @@ Environment variables:
  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)
+  MINIMAX_IMAGE_MODEL       Default MiniMax model (image-01)
  REPLICATE_IMAGE_MODEL     Default Replicate model (google/nano-banana-pro)
  JIMENG_IMAGE_MODEL        Default Jimeng model (jimeng_t2i_v40)
  SEEDREAM_IMAGE_MODEL      Default Seedream model (doubao-seedream-5-0-260128)
@@ -129,8 +133,14 @@ Environment variables:
  OPENROUTER_TITLE          Optional app name for OpenRouter attribution
  GOOGLE_BASE_URL           Custom Google endpoint
  DASHSCOPE_BASE_URL        Custom DashScope endpoint
+  MINIMAX_BASE_URL          Custom MiniMax endpoint
  REPLICATE_BASE_URL        Custom Replicate endpoint
  JIMENG_BASE_URL           Custom Jimeng endpoint
+  AZURE_OPENAI_API_KEY      Azure OpenAI API key
+  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)
  SEEDREAM_BASE_URL         Custom Seedream endpoint
  BAOYU_IMAGE_GEN_MAX_WORKERS  Override batch worker cap
  BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY  Override provider concurrency
@@ -229,9 +239,11 @@ export function parseArgs(argv: string[]): CliArgs {
        v !== "openai" &&
        v !== "openrouter" &&
        v !== "dashscope" &&
+        v !== "minimax" &&
        v !== "replicate" &&
        v !== "jimeng" &&
-        v !== "seedream"
+        v !== "seedream" &&
+        v !== "azure"
      ) {
        throw new Error(`Invalid provider: ${v}`);
      }
@@ -383,9 +395,11 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
          openai: null,
          openrouter: null,
          dashscope: null,
+          minimax: null,
          replicate: null,
          jimeng: null,
          seedream: null,
+          azure: null,
        };
        currentKey = "default_model";
        currentProvider = null;
@@ -409,9 +423,11 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
          key === "openai" ||
          key === "openrouter" ||
          key === "dashscope" ||
+          key === "minimax" ||
          key === "replicate" ||
          key === "jimeng" ||
-          key === "seedream"
+          key === "seedream" ||
+          key === "azure"
        )
      ) {
        config.batch ??= {};
@@ -425,9 +441,11 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
          key === "openai" ||
          key === "openrouter" ||
          key === "dashscope" ||
+          key === "minimax" ||
          key === "replicate" ||
          key === "jimeng" ||
-          key === "seedream"
+          key === "seedream" ||
+          key === "azure"
        )
      ) {
        const cleaned = value.replace(/['"]/g, "");
@@ -453,14 +471,49 @@ export function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
  return config;
 }

-async function loadExtendConfig(): Promise<Partial<ExtendConfig>> {
-  const home = homedir();
-  const cwd = process.cwd();
+type ExtendConfigPathPair = {
+  current: string;
+  legacy: string;
+};

-  const paths = [
-    path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
-    path.join(home, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
+function getExtendConfigPathPairs(cwd: string, home: string): ExtendConfigPathPair[] {
+  return [
+    {
+      current: path.join(cwd, ".baoyu-skills", "baoyu-imagine", "EXTEND.md"),
+      legacy: path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
+    },
+    {
+      current: path.join(home, ".baoyu-skills", "baoyu-imagine", "EXTEND.md"),
+      legacy: path.join(home, ".baoyu-skills", "baoyu-image-gen", "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 {
@@ -518,11 +571,13 @@ export function getConfiguredProviderRateLimits(
    openai: { ...DEFAULT_PROVIDER_RATE_LIMITS.openai },
    openrouter: { ...DEFAULT_PROVIDER_RATE_LIMITS.openrouter },
    dashscope: { ...DEFAULT_PROVIDER_RATE_LIMITS.dashscope },
+    minimax: { ...DEFAULT_PROVIDER_RATE_LIMITS.minimax },
    jimeng: { ...DEFAULT_PROVIDER_RATE_LIMITS.jimeng },
    seedream: { ...DEFAULT_PROVIDER_RATE_LIMITS.seedream },
+    azure: { ...DEFAULT_PROVIDER_RATE_LIMITS.azure },
  };

-  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "jimeng", "seedream"] as Provider[]) {
+  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "minimax", "jimeng", "seedream", "azure"] as Provider[]) {
    const envPrefix = `BAOYU_IMAGE_GEN_${provider.toUpperCase()}`;
    const extendLimit = extendConfig.batch?.provider_limits?.[provider];
    configured[provider] = {
@@ -571,7 +626,9 @@ export function normalizeOutputImagePath(p: string, defaultExtension = ".png"):

 function inferProviderFromModel(model: string | null): Provider | null {
  if (!model) return null;
-  if (model.includes("seedream") || model.includes("seededit")) return "seedream";
+  const normalized = model.trim();
+  if (normalized.includes("seedream") || normalized.includes("seededit")) return "seedream";
+  if (normalized === "image-01" || normalized === "image-01-live") return "minimax";
  return null;
 }

@@ -581,21 +638,25 @@ export function detectProvider(args: CliArgs): Provider {
    args.provider &&
    args.provider !== "google" &&
    args.provider !== "openai" &&
+    args.provider !== "azure" &&
    args.provider !== "openrouter" &&
    args.provider !== "replicate" &&
-    args.provider !== "seedream"
+    args.provider !== "seedream" &&
+    args.provider !== "minimax"
  ) {
    throw new Error(
-      "Reference images require a ref-capable provider. Use --provider google (Gemini multimodal), --provider openai (GPT Image edits), --provider openrouter (OpenRouter multimodal), --provider replicate, or --provider seedream for supported Seedream models."
+      "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."
    );
  }

  if (args.provider) return args.provider;

  const hasGoogle = !!(process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY);
+  const hasAzure = !!(process.env.AZURE_OPENAI_API_KEY && process.env.AZURE_OPENAI_BASE_URL);
  const hasOpenai = !!process.env.OPENAI_API_KEY;
  const hasOpenrouter = !!process.env.OPENROUTER_API_KEY;
  const hasDashscope = !!process.env.DASHSCOPE_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;
@@ -608,22 +669,33 @@ export function detectProvider(args: CliArgs): Provider {
    return "seedream";
  }

+  if (modelProvider === "minimax") {
+    if (!hasMinimax) {
+      throw new Error("Model looks like a MiniMax image model, but MINIMAX_API_KEY is not set.");
+    }
+    return "minimax";
+  }
+
  if (args.referenceImages.length > 0) {
    if (hasGoogle) return "google";
    if (hasOpenai) return "openai";
+    if (hasAzure) return "azure";
    if (hasOpenrouter) return "openrouter";
    if (hasReplicate) return "replicate";
    if (hasSeedream) return "seedream";
+    if (hasMinimax) return "minimax";
    throw new Error(
-      "Reference images require Google, OpenAI, OpenRouter, Replicate, or supported Seedream models. Set GOOGLE_API_KEY/GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, REPLICATE_API_TOKEN, or ARK_API_KEY, or remove --ref."
+      "Reference images require Google, OpenAI, Azure, OpenRouter, Replicate, supported Seedream models, or MiniMax. Set GOOGLE_API_KEY/GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY+AZURE_OPENAI_BASE_URL, OPENROUTER_API_KEY, REPLICATE_API_TOKEN, ARK_API_KEY, or MINIMAX_API_KEY, or remove --ref."
    );
  }

  const available = [
    hasGoogle && "google",
    hasOpenai && "openai",
+    hasAzure && "azure",
    hasOpenrouter && "openrouter",
    hasDashscope && "dashscope",
+    hasMinimax && "minimax",
    hasReplicate && "replicate",
    hasJimeng && "jimeng",
    hasSeedream && "seedream",
@@ -633,7 +705,7 @@ export function detectProvider(args: CliArgs): Provider {
  if (available.length > 1) return available[0]!;

  throw new Error(
-    "No API key found. Set GOOGLE_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, DASHSCOPE_API_KEY, REPLICATE_API_TOKEN, JIMENG keys, or ARK_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, 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."
  );
 }
@@ -672,10 +744,12 @@ 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 === "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;
  return (await import("./providers/openai")) as ProviderModule;
 }

@@ -701,9 +775,11 @@ function getModelForProvider(
      return extendConfig.default_model.openrouter;
    }
    if (provider === "dashscope" && extendConfig.default_model.dashscope) return extendConfig.default_model.dashscope;
+    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;
  }
  return providerModule.getDefaultModel();
 }
@@ -923,7 +999,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"] as Provider[]) {
+  for (const provider of ["replicate", "google", "openai", "openrouter", "dashscope", "jimeng", "seedream", "azure"] as Provider[]) {
    const limit = providerRateLimits[provider];
    console.error(`- ${provider}: concurrency=${limit.concurrency}, startIntervalMs=${limit.startIntervalMs}`);
  }
@@ -0,0 +1,188 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test, { type TestContext } from "node:test";
+
+import type { CliArgs } from "../types.ts";
+import {
+  generateImage,
+  getDefaultModel,
+  parseAzureBaseURL,
+  validateArgs,
+} from "./azure.ts";
+
+function useEnv(
+  t: TestContext,
+  values: Record<string, string | null>,
+): void {
+  const previous = new Map<string, string | undefined>();
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, process.env[key]);
+    if (value == null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+
+  t.after(() => {
+    for (const [key, value] of previous.entries()) {
+      if (value == null) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
+  return {
+    prompt: null,
+    promptFiles: [],
+    imagePath: null,
+    provider: null,
+    model: null,
+    aspectRatio: null,
+    size: null,
+    quality: null,
+    imageSize: null,
+    referenceImages: [],
+    n: 1,
+    batchFile: null,
+    jobs: null,
+    json: false,
+    help: false,
+    ...overrides,
+  };
+}
+
+async function makeTempDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+test("Azure endpoint parsing and default deployment selection follow env precedence", (t) => {
+  assert.deepEqual(parseAzureBaseURL("https://example.openai.azure.com"), {
+    resourceBaseURL: "https://example.openai.azure.com/openai",
+    deployment: null,
+  });
+  assert.deepEqual(
+    parseAzureBaseURL("https://example.openai.azure.com/openai/deployments/from-url"),
+    {
+      resourceBaseURL: "https://example.openai.azure.com/openai",
+      deployment: "from-url",
+    },
+  );
+
+  useEnv(t, {
+    AZURE_OPENAI_BASE_URL: "https://example.openai.azure.com/openai/deployments/from-url",
+    AZURE_OPENAI_DEPLOYMENT: "explicit-deploy",
+    AZURE_OPENAI_IMAGE_MODEL: "env-fallback",
+  });
+  assert.equal(getDefaultModel(), "explicit-deploy");
+});
+
+test("Azure validateArgs rejects unsupported edit input formats before the API call", () => {
+  assert.doesNotThrow(() =>
+    validateArgs("demo-deployment", makeArgs({ referenceImages: ["hero.png", "photo.jpeg"] })),
+  );
+  assert.throws(
+    () => validateArgs("demo-deployment", makeArgs({ referenceImages: ["hero.webp"] })),
+    /PNG or JPG\/JPEG/,
+  );
+});
+
+test("Azure image generation routes model to deployment and sends mapped quality", async (t) => {
+  useEnv(t, {
+    AZURE_OPENAI_API_KEY: "azure-key",
+    AZURE_OPENAI_BASE_URL: "https://example.openai.azure.com/openai/deployments/default-deploy",
+    AZURE_API_VERSION: null,
+    AZURE_OPENAI_DEPLOYMENT: null,
+    AZURE_OPENAI_IMAGE_MODEL: null,
+  });
+
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const calls: Array<{ url: string; body: string }> = [];
+  globalThis.fetch = async (input, init) => {
+    calls.push({
+      url: String(input),
+      body: String(init?.body ?? ""),
+    });
+    return Response.json({
+      data: [{ b64_json: Buffer.from("azure-image").toString("base64") }],
+    });
+  };
+
+  const bytes = await generateImage(
+    "A calm lake at sunset",
+    "custom-deploy",
+    makeArgs({ quality: "normal" }),
+  );
+
+  assert.equal(Buffer.from(bytes).toString("utf8"), "azure-image");
+  assert.equal(
+    calls[0]?.url,
+    "https://example.openai.azure.com/openai/deployments/custom-deploy/images/generations?api-version=2025-04-01-preview",
+  );
+
+  const body = JSON.parse(calls[0]!.body) as Record<string, string>;
+  assert.equal(body.quality, "medium");
+  assert.equal(body.size, "1024x1024");
+});
+
+test("Azure image edits include quality in multipart requests", async (t) => {
+  const root = await makeTempDir("baoyu-imagine-azure-");
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+
+  const pngPath = path.join(root, "ref.png");
+  const jpgPath = path.join(root, "ref.jpg");
+  await fs.writeFile(pngPath, "png-bytes");
+  await fs.writeFile(jpgPath, "jpg-bytes");
+
+  useEnv(t, {
+    AZURE_OPENAI_API_KEY: "azure-key",
+    AZURE_OPENAI_BASE_URL: "https://example.openai.azure.com",
+    AZURE_API_VERSION: "2025-04-01-preview",
+    AZURE_OPENAI_DEPLOYMENT: null,
+    AZURE_OPENAI_IMAGE_MODEL: null,
+  });
+
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const calls: Array<{ url: string; form: FormData }> = [];
+  globalThis.fetch = async (input, init) => {
+    calls.push({
+      url: String(input),
+      form: init?.body as FormData,
+    });
+    return Response.json({
+      data: [{ b64_json: Buffer.from("edited-image").toString("base64") }],
+    });
+  };
+
+  const bytes = await generateImage(
+    "Add warm lighting",
+    "edit-deploy",
+    makeArgs({
+      quality: "2k",
+      referenceImages: [pngPath, jpgPath],
+    }),
+  );
+
+  assert.equal(Buffer.from(bytes).toString("utf8"), "edited-image");
+  assert.equal(
+    calls[0]?.url,
+    "https://example.openai.azure.com/openai/deployments/edit-deploy/images/edits?api-version=2025-04-01-preview",
+  );
+  assert.equal(calls[0]?.form.get("quality"), "high");
+  assert.equal(calls[0]?.form.get("size"), "1024x1024");
+  assert.equal(calls[0]?.form.getAll("image[]").length, 2);
+});
@@ -0,0 +1,192 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import type { CliArgs } from "../types";
+import { getOpenAISize, extractImageFromResponse } from "./openai.ts";
+
+type OpenAIImageResponse = { data: Array<{ url?: string; b64_json?: string }> };
+type AzureEndpoint = {
+  resourceBaseURL: string;
+  deployment: string | null;
+};
+
+const DEFAULT_AZURE_API_VERSION = "2025-04-01-preview";
+const AZURE_EDIT_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg"]);
+
+export function parseAzureBaseURL(url: string): AzureEndpoint {
+  const parsed = new URL(url);
+  const trimmedPath = parsed.pathname.replace(/\/+$/, "");
+  const deploymentMatch = trimmedPath.match(/^(.*?)(?:\/openai)?\/deployments\/([^/]+)$/);
+
+  if (deploymentMatch) {
+    parsed.pathname = `${deploymentMatch[1] || ""}/openai`;
+    return {
+      resourceBaseURL: parsed.toString().replace(/\/+$/, ""),
+      deployment: decodeURIComponent(deploymentMatch[2]!),
+    };
+  }
+
+  parsed.pathname = trimmedPath.endsWith("/openai") ? trimmedPath : `${trimmedPath}/openai`;
+  return {
+    resourceBaseURL: parsed.toString().replace(/\/+$/, ""),
+    deployment: null,
+  };
+}
+
+export function getDefaultModel(): string {
+  const explicitDeployment = process.env.AZURE_OPENAI_DEPLOYMENT?.trim();
+  if (explicitDeployment) return explicitDeployment;
+
+  const baseURL = process.env.AZURE_OPENAI_BASE_URL;
+  if (baseURL) {
+    try {
+      const { deployment } = parseAzureBaseURL(baseURL);
+      if (deployment) return deployment;
+    } catch {
+      // Ignore invalid URLs here so the required-env check can raise the user-facing error later.
+    }
+  }
+
+  return process.env.AZURE_OPENAI_IMAGE_MODEL || "gpt-image-1.5";
+}
+
+function getEndpoint(): AzureEndpoint {
+  const url = process.env.AZURE_OPENAI_BASE_URL;
+  if (!url) {
+    throw new Error(
+      "AZURE_OPENAI_BASE_URL is required. Set it to your Azure resource or deployment endpoint, e.g.: https://your-resource.openai.azure.com or https://your-resource.openai.azure.com/openai/deployments/your-deployment"
+    );
+  }
+  return parseAzureBaseURL(url);
+}
+
+function getApiKey(): string {
+  const key = process.env.AZURE_OPENAI_API_KEY;
+  if (!key) {
+    throw new Error(
+      "AZURE_OPENAI_API_KEY is required. Get it from Azure Portal → your OpenAI resource → Keys and Endpoint."
+    );
+  }
+  return key;
+}
+
+function getApiVersion(): string {
+  return process.env.AZURE_API_VERSION || DEFAULT_AZURE_API_VERSION;
+}
+
+function getDeployment(model: string): string {
+  const deployment = model.trim();
+  if (!deployment) {
+    throw new Error(
+      "Azure deployment name is required. Use --model <deployment>, AZURE_OPENAI_DEPLOYMENT, AZURE_OPENAI_IMAGE_MODEL, or embed the deployment in AZURE_OPENAI_BASE_URL."
+    );
+  }
+  return deployment;
+}
+
+function buildURL(deployment: string, pathSuffix: string): string {
+  const { resourceBaseURL } = getEndpoint();
+  return `${resourceBaseURL}/deployments/${encodeURIComponent(deployment)}${pathSuffix}?api-version=${getApiVersion()}`;
+}
+
+function authHeaders(): Record<string, string> {
+  return { "api-key": getApiKey() };
+}
+
+function getAzureQuality(quality: CliArgs["quality"]): "medium" | "high" {
+  return quality === "2k" ? "high" : "medium";
+}
+
+export function validateArgs(_model: string, args: CliArgs): void {
+  for (const refPath of args.referenceImages) {
+    const ext = path.extname(refPath).toLowerCase();
+    if (!AZURE_EDIT_IMAGE_EXTENSIONS.has(ext)) {
+      throw new Error(
+        `Azure OpenAI reference images must be PNG or JPG/JPEG. Unsupported file: ${refPath}`
+      );
+    }
+  }
+}
+
+export async function generateImage(
+  prompt: string,
+  model: string,
+  args: CliArgs
+): Promise<Uint8Array> {
+  const deployment = getDeployment(model);
+  const size = args.size || getOpenAISize(model, args.aspectRatio, args.quality);
+
+  if (args.referenceImages.length > 0) {
+    return generateWithAzureEdits(prompt, deployment, size, args.referenceImages, args.quality);
+  }
+
+  return generateWithAzureGenerations(prompt, deployment, size, args.quality);
+}
+
+async function generateWithAzureGenerations(
+  prompt: string,
+  deployment: string,
+  size: string,
+  quality: CliArgs["quality"]
+): Promise<Uint8Array> {
+  const body: Record<string, any> = {
+    prompt,
+    size,
+    n: 1,
+    quality: getAzureQuality(quality),
+  };
+
+  const res = await fetch(buildURL(deployment, "/images/generations"), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders(),
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Azure OpenAI API error: ${err}`);
+  }
+
+  const result = (await res.json()) as OpenAIImageResponse;
+  return extractImageFromResponse(result);
+}
+
+async function generateWithAzureEdits(
+  prompt: string,
+  deployment: string,
+  size: string,
+  referenceImages: string[],
+  quality: CliArgs["quality"]
+): Promise<Uint8Array> {
+  const form = new FormData();
+  form.append("prompt", prompt);
+  form.append("size", size);
+  form.append("n", "1");
+  form.append("quality", getAzureQuality(quality));
+
+  for (const refPath of referenceImages) {
+    const bytes = await readFile(refPath);
+    const filename = path.basename(refPath);
+    const mimeType = path.extname(filename).toLowerCase() === ".png" ? "image/png" : "image/jpeg";
+    const blob = new Blob([bytes], { type: mimeType });
+    form.append("image[]", blob, filename);
+  }
+
+  const res = await fetch(buildURL(deployment, "/images/edits"), {
+    method: "POST",
+    headers: {
+      ...authHeaders(),
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Azure OpenAI edits API error: ${err}`);
+  }
+
+  const result = (await res.json()) as OpenAIImageResponse;
+  return extractImageFromResponse(result);
+}
@@ -421,7 +421,7 @@ export async function generateImage(

  if (args.referenceImages.length > 0) {
    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 DashScope provider in baoyu-imagine. Use --provider google with a Gemini multimodal model."
    );
  }

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test, { type TestContext } from "node:test";
+
+import type { CliArgs } from "../types.ts";
+import { generateImage } from "./jimeng.ts";
+
+function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
+  return {
+    prompt: null,
+    promptFiles: [],
+    imagePath: null,
+    provider: null,
+    model: null,
+    aspectRatio: null,
+    size: null,
+    quality: null,
+    imageSize: null,
+    referenceImages: [],
+    n: 1,
+    batchFile: null,
+    jobs: null,
+    json: false,
+    help: false,
+    ...overrides,
+  };
+}
+
+function useEnv(
+  t: TestContext,
+  values: Record<string, string | null>,
+): void {
+  const previous = new Map<string, string | undefined>();
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, process.env[key]);
+    if (value == null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+
+  t.after(() => {
+    for (const [key, value] of previous.entries()) {
+      if (value == null) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+test("Jimeng submit request uses prompt field expected by current API", async (t) => {
+  useEnv(t, {
+    JIMENG_ACCESS_KEY_ID: "test-access-key",
+    JIMENG_SECRET_ACCESS_KEY: "test-secret-key",
+    JIMENG_BASE_URL: null,
+    JIMENG_REGION: null,
+  });
+
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const calls: Array<{
+    input: string;
+    init?: RequestInit;
+  }> = [];
+
+  globalThis.fetch = async (input, init) => {
+    calls.push({
+      input: String(input),
+      init,
+    });
+
+    if (calls.length === 1) {
+      return Response.json({
+        code: 10000,
+        data: {
+          task_id: "task-123",
+        },
+      });
+    }
+
+    return Response.json({
+      code: 10000,
+      data: {
+        status: "done",
+        binary_data_base64: [Buffer.from("jimeng-image").toString("base64")],
+      },
+    });
+  };
+
+  const image = await generateImage(
+    "A quiet bamboo forest",
+    "jimeng_t2i_v40",
+    makeArgs({ quality: "normal" }),
+  );
+
+  assert.equal(Buffer.from(image).toString("utf8"), "jimeng-image");
+  assert.equal(calls.length, 2);
+  assert.equal(
+    calls[0]?.input,
+    "https://visual.volcengineapi.com/?Action=CVSync2AsyncSubmitTask&Version=2022-08-31",
+  );
+
+  const submitBody = JSON.parse(String(calls[0]?.init?.body)) as Record<string, unknown>;
+  assert.equal(submitBody.req_key, "jimeng_t2i_v40");
+  assert.equal(submitBody.prompt, "A quiet bamboo forest");
+  assert.ok(!("prompt_text" in submitBody));
+  assert.equal(submitBody.width, 1024);
+  assert.equal(submitBody.height, 1024);
+});
@@ -246,7 +246,7 @@ async function submitTask(
  const [width, height] = size.split("x").map(Number);
  const bodyObj = {
    req_key: model,
-    prompt_text: prompt,
+    prompt,
    // Use separate width and height parameters instead of size string
    width: width,
    height: height,
@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test, { type TestContext } from "node:test";
+
+import type { CliArgs } from "../types.ts";
+import {
+  buildMinimaxUrl,
+  buildRequestBody,
+  buildSubjectReference,
+  extractImageFromResponse,
+  parsePixelSize,
+  validateArgs,
+} from "./minimax.ts";
+
+function useEnv(
+  t: TestContext,
+  values: Record<string, string | null>,
+): void {
+  const previous = new Map<string, string | undefined>();
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, process.env[key]);
+    if (value == null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+
+  t.after(() => {
+    for (const [key, value] of previous.entries()) {
+      if (value == null) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
+  return {
+    prompt: null,
+    promptFiles: [],
+    imagePath: null,
+    provider: null,
+    model: null,
+    aspectRatio: null,
+    size: null,
+    quality: null,
+    imageSize: null,
+    referenceImages: [],
+    n: 1,
+    batchFile: null,
+    jobs: null,
+    json: false,
+    help: false,
+    ...overrides,
+  };
+}
+
+test("MiniMax URL builder normalizes /v1 suffixes", (t) => {
+  useEnv(t, { MINIMAX_BASE_URL: "https://api.minimax.io" });
+  assert.equal(buildMinimaxUrl(), "https://api.minimax.io/v1/image_generation");
+
+  process.env.MINIMAX_BASE_URL = "https://proxy.example.com/custom/v1/";
+  assert.equal(buildMinimaxUrl(), "https://proxy.example.com/custom/v1/image_generation");
+});
+
+test("MiniMax size parsing and validation follow documented constraints", () => {
+  assert.deepEqual(parsePixelSize("1536x1024"), { width: 1536, height: 1024 });
+  assert.deepEqual(parsePixelSize("1536*1024"), { width: 1536, height: 1024 });
+  assert.equal(parsePixelSize("wide"), null);
+
+  validateArgs("image-01", makeArgs({ size: "1536x1024", n: 9 }));
+
+  assert.throws(
+    () => validateArgs("image-01-live", makeArgs({ size: "1536x1024" })),
+    /only supported with model image-01/,
+  );
+  assert.throws(
+    () => validateArgs("image-01", makeArgs({ size: "1537x1024" })),
+    /divisible by 8/,
+  );
+  assert.throws(
+    () => validateArgs("image-01", makeArgs({ aspectRatio: "2.35:1" })),
+    /aspect_ratio must be one of/,
+  );
+  assert.throws(
+    () => validateArgs("image-01", makeArgs({ n: 10 })),
+    /at most 9 images/,
+  );
+});
+
+test("MiniMax request body maps aspect ratio, size, n, and subject references", async (t) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "minimax-test-"));
+  t.after(() => fs.rm(dir, { recursive: true, force: true }));
+
+  const refPath = path.join(dir, "portrait.png");
+  await fs.writeFile(refPath, Buffer.from("portrait"));
+
+  const ratioBody = await buildRequestBody(
+    "A portrait by the window",
+    "image-01",
+    makeArgs({ aspectRatio: "16:9", n: 2, referenceImages: [refPath] }),
+  );
+  assert.equal(ratioBody.aspect_ratio, "16:9");
+  assert.equal(ratioBody.n, 2);
+  assert.equal(ratioBody.response_format, "base64");
+  assert.match(ratioBody.subject_reference?.[0]?.image_file || "", /^data:image\/png;base64,/);
+
+  const sizeBody = await buildRequestBody(
+    "A portrait by the window",
+    "image-01",
+    makeArgs({ size: "1536x1024" }),
+  );
+  assert.equal(sizeBody.width, 1536);
+  assert.equal(sizeBody.height, 1024);
+  assert.equal(sizeBody.aspect_ratio, undefined);
+});
+
+test("MiniMax subject references require supported file types", async (t) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "minimax-ref-"));
+  t.after(() => fs.rm(dir, { recursive: true, force: true }));
+
+  const good = path.join(dir, "portrait.jpg");
+  const bad = path.join(dir, "portrait.webp");
+  await fs.writeFile(good, Buffer.from("portrait"));
+  await fs.writeFile(bad, Buffer.from("portrait"));
+
+  const subjectReference = await buildSubjectReference([good]);
+  assert.equal(subjectReference?.[0]?.type, "character");
+
+  await assert.rejects(
+    () => buildSubjectReference([bad]),
+    /only supports JPG, JPEG, or PNG/,
+  );
+});
+
+test("MiniMax response extraction supports base64 and URL payloads", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const fromBase64 = await extractImageFromResponse({
+    data: {
+      image_base64: [Buffer.from("hello").toString("base64")],
+    },
+  });
+  assert.equal(Buffer.from(fromBase64).toString("utf8"), "hello");
+
+  globalThis.fetch = async () =>
+    new Response(Uint8Array.from([1, 2, 3]), {
+      status: 200,
+      headers: { "Content-Type": "image/jpeg" },
+    });
+
+  const fromUrl = await extractImageFromResponse({
+    data: {
+      image_urls: ["https://example.com/output.jpg"],
+    },
+  });
+  assert.deepEqual([...fromUrl], [1, 2, 3]);
+
+  await assert.rejects(
+    () => extractImageFromResponse({ base_resp: { status_code: 1001, status_msg: "blocked" } }),
+    /blocked/,
+  );
+});
@@ -0,0 +1,220 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+
+import type { CliArgs } from "../types";
+
+const DEFAULT_MODEL = "image-01";
+const MAX_REFERENCE_IMAGE_BYTES = 10 * 1024 * 1024;
+const SUPPORTED_ASPECT_RATIOS = new Set(["1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]);
+
+type MinimaxSubjectReference = {
+  type: "character";
+  image_file: string;
+};
+
+type MinimaxRequestBody = {
+  model: string;
+  prompt: string;
+  response_format: "base64";
+  aspect_ratio?: string;
+  width?: number;
+  height?: number;
+  n?: number;
+  subject_reference?: MinimaxSubjectReference[];
+};
+
+type MinimaxResponse = {
+  id?: string;
+  data?: {
+    image_urls?: string[];
+    image_base64?: string[];
+  };
+  base_resp?: {
+    status_code?: number;
+    status_msg?: string;
+  };
+};
+
+export function getDefaultModel(): string {
+  return process.env.MINIMAX_IMAGE_MODEL || DEFAULT_MODEL;
+}
+
+function getApiKey(): string | null {
+  return process.env.MINIMAX_API_KEY || null;
+}
+
+export function buildMinimaxUrl(): string {
+  const base = (process.env.MINIMAX_BASE_URL || "https://api.minimax.io").replace(/\/+$/g, "");
+  return base.endsWith("/v1") ? `${base}/image_generation` : `${base}/v1/image_generation`;
+}
+
+function getMimeType(filename: string): "image/jpeg" | "image/png" {
+  const ext = path.extname(filename).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".png") return "image/png";
+  throw new Error(
+    `MiniMax subject_reference only supports JPG, JPEG, or PNG files: ${filename}`
+  );
+}
+
+export function parsePixelSize(size: string): { width: number; height: number } | null {
+  const match = size.trim().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 validatePixelSize(width: number, height: number): void {
+  if (width < 512 || width > 2048 || height < 512 || height > 2048) {
+    throw new Error("MiniMax custom size must keep width and height between 512 and 2048.");
+  }
+  if (width % 8 !== 0 || height % 8 !== 0) {
+    throw new Error("MiniMax custom size requires width and height divisible by 8.");
+  }
+}
+
+export function validateArgs(model: string, args: CliArgs): void {
+  if (args.n > 9) {
+    throw new Error("MiniMax supports at most 9 images per request.");
+  }
+
+  if (args.aspectRatio && !SUPPORTED_ASPECT_RATIOS.has(args.aspectRatio)) {
+    throw new Error(
+      `MiniMax aspect_ratio must be one of: ${Array.from(SUPPORTED_ASPECT_RATIOS).join(", ")}.`
+    );
+  }
+
+  if (args.size && !args.aspectRatio) {
+    if (model !== "image-01") {
+      throw new Error("MiniMax custom --size is only supported with model image-01. Use --model image-01 or pass --ar instead.");
+    }
+    const parsed = parsePixelSize(args.size);
+    if (!parsed) {
+      throw new Error("MiniMax --size must be in WxH format, for example 1536x1024.");
+    }
+    validatePixelSize(parsed.width, parsed.height);
+  }
+}
+
+export async function buildSubjectReference(
+  referenceImages: string[],
+): Promise<MinimaxSubjectReference[] | undefined> {
+  if (referenceImages.length === 0) return undefined;
+
+  const subjectReference: MinimaxSubjectReference[] = [];
+  for (const refPath of referenceImages) {
+    const bytes = await readFile(refPath);
+    if (bytes.length > MAX_REFERENCE_IMAGE_BYTES) {
+      throw new Error(`MiniMax subject_reference images must be smaller than 10MB: ${refPath}`);
+    }
+
+    subjectReference.push({
+      type: "character",
+      image_file: `data:${getMimeType(refPath)};base64,${bytes.toString("base64")}`,
+    });
+  }
+
+  return subjectReference;
+}
+
+export async function buildRequestBody(
+  prompt: string,
+  model: string,
+  args: CliArgs,
+): Promise<MinimaxRequestBody> {
+  validateArgs(model, args);
+
+  const body: MinimaxRequestBody = {
+    model,
+    prompt,
+    response_format: "base64",
+  };
+
+  if (args.aspectRatio) {
+    body.aspect_ratio = args.aspectRatio;
+  } else if (args.size) {
+    const parsed = parsePixelSize(args.size);
+    if (!parsed) {
+      throw new Error("MiniMax --size must be in WxH format, for example 1536x1024.");
+    }
+    body.width = parsed.width;
+    body.height = parsed.height;
+  }
+
+  if (args.n > 1) {
+    body.n = args.n;
+  }
+
+  const subjectReference = await buildSubjectReference(args.referenceImages);
+  if (subjectReference) {
+    body.subject_reference = subjectReference;
+  }
+
+  return body;
+}
+
+async function downloadImage(url: string): Promise<Uint8Array> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download image from MiniMax: ${response.status}`);
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+export async function extractImageFromResponse(result: MinimaxResponse): Promise<Uint8Array> {
+  const baseResp = result.base_resp;
+  if (baseResp && baseResp.status_code !== undefined && baseResp.status_code !== 0) {
+    throw new Error(baseResp.status_msg || `MiniMax API returned status_code=${baseResp.status_code}`);
+  }
+
+  const base64Image = result.data?.image_base64?.[0];
+  if (base64Image) {
+    return Uint8Array.from(Buffer.from(base64Image, "base64"));
+  }
+
+  const url = result.data?.image_urls?.[0];
+  if (url) {
+    return downloadImage(url);
+  }
+
+  throw new Error("No image data in MiniMax response");
+}
+
+export function getDefaultOutputExtension(): ".jpg" {
+  return ".jpg";
+}
+
+export async function generateImage(
+  prompt: string,
+  model: string,
+  args: CliArgs
+): Promise<Uint8Array> {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("MINIMAX_API_KEY is required. Get one from https://platform.minimax.io/");
+  }
+
+  const body = await buildRequestBody(prompt, model, args);
+  const response = await fetch(buildMinimaxUrl(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`MiniMax API error (${response.status}): ${err}`);
+  }
+
+  const result = (await response.json()) as MinimaxResponse;
+  return extractImageFromResponse(result);
+}
@@ -1,4 +1,13 @@
-export type Provider = "google" | "openai" | "openrouter" | "dashscope" | "replicate" | "jimeng" | "seedream";
+export type Provider =
+  | "google"
+  | "openai"
+  | "openrouter"
+  | "dashscope"
+  | "minimax"
+  | "replicate"
+  | "jimeng"
+  | "seedream"
+  | "azure";
 export type Quality = "normal" | "2k";

 export type CliArgs = {
@@ -52,9 +61,11 @@ export type ExtendConfig = {
    openai: string | null;
    openrouter: string | null;
    dashscope: string | null;
+    minimax: string | null;
    replicate: string | null;
    jimeng: string | null;
    seedream: string | null;
+    azure: string | null;
  };
  batch?: {
    max_workers?: number | null;
@@ -123,6 +123,8 @@ ${BUN_X} {baseDir}/scripts/weibo-article.ts article.md --cover ./cover.jpg
 - Title: 32 characters max (truncated with warning if longer)
 - Summary/导语: 44 characters max (auto-regenerated from content if longer)

+**Markdown-to-HTML**: Do NOT pass any `--theme` parameter when converting markdown to HTML. Use the default theme (no theme argument).
+
 **Article Workflow**:
 1. Opens `https://card.weibo.com/article/v3/editor`
 2. Clicks "写文章" button, waits for editor to become editable
@@ -1,7 +1,7 @@
 ---
 name: baoyu-translate
 description: Translates articles and documents between languages with three modes - quick (direct), normal (analyze then translate), and refined (analyze, translate, review, polish). Supports custom glossaries and terminology consistency via EXTEND.md. Use when user asks to "translate", "翻译", "精翻", "translate article", "translate to Chinese/English", "改成中文", "改成英文", "convert to Chinese", "localize", "本地化", or needs any document translation. Also triggers for "refined translation", "精细翻译", "proofread translation", "快速翻译", "快翻", "这篇文章翻译一下", or when a URL or file is provided with translation intent.
-version: 1.56.1
+version: 1.57.0
 metadata:
  openclaw:
    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-translate
@@ -189,12 +189,12 @@ Before translating chunks:
   - Splits at markdown block boundaries to preserve structure
   - If a single block exceeds the threshold, falls back to line splitting, then word splitting
 4. **Assemble translation prompt**:
-   - Main agent reads `01-analysis.md` (if exists) and assembles shared context using Part 1 of [references/subagent-prompt-template.md](references/subagent-prompt-template.md) — inlining the resolved style preset (from `--style` flag, EXTEND.md `style` setting, or default `storytelling`), content background, merged glossary, and comprehension challenges
+   - Main agent reads `01-analysis.md` (if exists) and assembles shared context using Part 1 of [references/subagent-prompt-template.md](references/subagent-prompt-template.md) — inlining: target style + source voice assessment, content background, merged glossary, figurative language mapping (structured table), comprehension challenges (with reasoning), and translation challenges (structural/creative)
   - Save as `02-prompt.md` in the output directory (shared context only, no task instructions)
 5. **Draft translation via subagents** (if Agent tool available):
   - Spawn one subagent **per chunk**, all in parallel (Part 2 of the template)
-   - Each subagent reads `02-prompt.md` for shared context, translates its chunk, saves to `chunks/chunk-NN-draft.md`
-   - Terminology consistency is guaranteed by the shared `02-prompt.md` (glossary + comprehension challenges from analysis)
+   - Each subagent reads `02-prompt.md` for shared context, receives chunk position info (chunk N of M + brief context of where it sits in the argument), translates its chunk, saves to `chunks/chunk-NN-draft.md`
+   - Consistency is guaranteed by the shared `02-prompt.md` (glossary, figurative language mapping, comprehension challenges, source voice, and translation challenges from analysis)
   - If no chunks (content under threshold): spawn one subagent for the entire source file
   - If Agent tool is unavailable, translate chunks sequentially inline using `02-prompt.md`
 6. **Merge**: Once all subagents complete, combine translated chunks in order. If `chunks/frontmatter.md` exists, prepend it. Save as `03-draft.md` (refined) or `translation.md` (normal)
@@ -121,9 +121,16 @@ Implicit assumptions: [unstated premises]

 ## Step 2: Assemble Translation Prompt

-Main agent reads `01-analysis.md` and assembles a complete translation prompt using [references/subagent-prompt-template.md](subagent-prompt-template.md). Inline the resolved style preset (from `--style` flag, EXTEND.md `style` setting, or default `storytelling`), content background, merged glossary, and comprehension challenges into the prompt. Save to `02-prompt.md`.
+Main agent reads `01-analysis.md` and assembles a complete translation prompt using [references/subagent-prompt-template.md](subagent-prompt-template.md). Inline the following from analysis into the prompt:

-This prompt is used by the subagent (chunked) or by the main agent itself (non-chunked).
+- **Target style + Source voice**: Resolved style preset (from `--style` flag, EXTEND.md `style` setting, or default `storytelling`) AND the source voice assessment from analysis §1.5 (formal/conversational, humor, register, sentence rhythm)
+- **Content background**: Quick summary, core argument, author background, writing context, purpose, implicit assumptions (from §1.1–1.3)
+- **Glossary**: Merged glossary with analysis-extracted terms (from §1.4)
+- **Figurative Language Mapping**: Structured table from analysis §1.7 — each metaphor/idiom with intended meaning, approach (interpret/substitute/retain), and suggested rendering
+- **Comprehension Challenges**: Each challenge with reasoning (why it confuses readers) and proposed note (from §1.6)
+- **Translation Challenges**: Structural and creative challenges from analysis §1.8 — specific passages with suggested approaches
+
+Save to `02-prompt.md`. This prompt is used by the subagent (chunked) or by the main agent itself (non-chunked).

 ## Step 3: Initial Draft

@@ -21,13 +21,15 @@ You are a professional translator. Your task is to translate markdown content fr

 ## Translation Style

-{style description — e.g., "storytelling: engaging narrative flow, smooth transitions, vivid phrasing" or custom style from user}
+**Target style**: {style description — e.g., "storytelling: engaging narrative flow, smooth transitions, vivid phrasing" or custom style from user}

-Apply this style consistently: it determines the voice, tone, and sentence-level choices throughout the translation. Style is independent of audience — a technical audience can still get a storytelling-style translation, or a general audience can get a formal one.
+**Source voice** (from analysis, if exists): {Describe the original author's voice — e.g., "Self-deprecating, conversational tone with frequent tech-industry humor. Sarcasm used to critique trends. Short punchy sentences alternate with longer analytical passages." Include: formal/conversational, humor type, cultural register, sentence rhythm, any distinctive patterns.}
+
+Apply the target style consistently while respecting the source voice. The translator should understand what the original sounds like in order to produce a translation that captures the same feel in the target style. Style is independent of audience — a technical audience can still get a storytelling-style translation, or a general audience can get a formal one.

 ## Content Background

-{Inlined from 01-analysis.md if analysis exists: quick summary, core argument, author background, writing context, tone assessment, figurative language & metaphor mapping.}
+{Inlined from 01-analysis.md if analysis exists: quick summary, core argument, author background, writing context, purpose, implicit assumptions.}

 ## Glossary

@@ -35,23 +37,43 @@ Apply these term translations consistently throughout. First occurrence of each

 {Merged glossary — combine built-in glossary + EXTEND.md glossary + terms extracted in analysis. One per line: English → Translation}

+## Figurative Language Mapping
+
+{Inlined from 01-analysis.md section 1.7 if analysis exists. Structured table — one row per metaphor, idiom, or figurative expression identified in the source:}
+
+| Original Expression | Intended Meaning | Approach | Suggested Rendering |
+|--------------------|--------------------|----------|---------------------|
+| {source metaphor} | {what the author actually means} | {Interpret / Substitute / Retain} | {target-language rendering or guidance} |
+
+Also note any emotional connotations (words carrying subjective feeling beyond dictionary meaning) and implied meanings (sentences where surface meaning is simpler than the author's full intent) identified in the analysis — preserve these in translation.
+
 ## Comprehension Challenges

 The following terms or references may confuse target readers. Add translator's notes in parentheses where they appear: `译文（English original，通俗解释）`

-{Inlined from 01-analysis.md comprehension challenges section if analysis exists. Each entry: term → explanation to use as note.}
+{Inlined from 01-analysis.md comprehension challenges section if analysis exists. Each entry includes the reasoning so the translator can calibrate annotation depth:}
+
+- **{term/passage}**: {why this may confuse target readers} → Note: {concise explanation to use as translator's note}
+
+## Translation Challenges
+
+{Inlined from 01-analysis.md section 1.8 if analysis exists. Specific passages requiring structural or creative adaptation:}
+
+- {location/passage}: {what makes it challenging — e.g., 60-word participial chain, wordplay, pun, author's signature humor} → {suggested approach — e.g., break into 2-3 shorter sentences, adapt the joke for target culture, preserve the ambiguity}
+
+If this section is empty, omit it.

 ## Translation Principles

 - **Accuracy first**: Facts, data, and logic must match the original exactly
 - **Meaning over words**: Translate what the author means, not just what the words say. When a literal translation sounds unnatural or fails to convey the intended effect, restructure freely to express the same meaning in idiomatic {target_lang}
- **Figurative language**: Interpret metaphors, idioms, and figurative expressions by their intended meaning. When a source-language image does not carry the same connotation in {target_lang}, replace it with a natural expression that conveys the same idea and emotional effect. Refer to the Figurative Language section in Content Background (if provided) for pre-analyzed metaphor mappings
+- **Figurative language**: Interpret metaphors, idioms, and figurative expressions by their intended meaning. When a source-language image does not carry the same connotation in {target_lang}, replace it with a natural expression that conveys the same idea and emotional effect. Follow the Figurative Language Mapping table above for pre-analyzed decisions
 - **Emotional fidelity**: Preserve the emotional connotations of word choices, not just their dictionary meanings
 - **Natural flow**: Use idiomatic {target_lang} word order and sentence patterns; break or restructure sentences freely when the source structure doesn't work naturally
 - **Terminology**: Use glossary translations consistently; annotate with original term in parentheses on first occurrence
 - **Preserve format**: Keep all markdown formatting (headings, bold, italic, images, links, code blocks)
 - **Respect original**: Maintain original meaning and intent; do not add, remove, or editorialize — but sentence structure and imagery may be adapted freely to serve the meaning
- **Translator's notes**: For terms or cultural references listed in Comprehension Challenges above, add a concise explanatory note in parentheses. Only annotate where genuinely needed for the target audience.
+- **Translator's notes**: For terms or cultural references listed in Comprehension Challenges above, add a concise explanatory note in parentheses. Use the provided reasoning to judge annotation depth — explain more for genuinely obscure references, less for terms that are merely unfamiliar. Only annotate where genuinely needed for the target audience.
 ```

 ---
@@ -63,6 +85,9 @@ The following terms or references may confuse target readers. Add translator's n
 ```
 Read the translation instructions from: {output_dir}/02-prompt.md

+You are translating chunk {NN} of {total_chunks}.
+Context: {brief description of what this chunk covers and where it sits in the overall argument — e.g., "This chunk covers the author's critique of current approaches, following the introduction of the problem and leading into the proposed solution."}
+
 Translate this chunk:
 1. Read `{output_dir}/chunks/chunk-{NN}.md`
 2. Translate following the instructions in 02-prompt.md
@@ -118,6 +118,7 @@ Full reference: [references/config/first-time-setup.md](references/config/first-
 ## Features

 - Chrome CDP for full JavaScript rendering
+- Browser strategy fallback: default headless first, then visible Chrome on technical failure
 - URL-specific parser layer for sites that need custom HTML rules before generic extraction
 - Two capture modes: auto or wait-for-user
 - Save rendered HTML as a sibling `-captured.html` file
@@ -137,6 +138,12 @@ Full reference: [references/config/first-time-setup.md](references/config/first-
 # Auto mode (default) - capture when page loads
 ${BUN_X} {baseDir}/scripts/main.ts <url>

+# Force headless only
+${BUN_X} {baseDir}/scripts/main.ts <url> --browser headless
+
+# Force visible browser
+${BUN_X} {baseDir}/scripts/main.ts <url> --browser headed
+
 # Wait mode - wait for user signal before capture
 ${BUN_X} {baseDir}/scripts/main.ts <url> --wait

@@ -158,6 +165,9 @@ ${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
 | `-o <path>` | Output file path — must be a **file** path, not directory (default: auto-generated) |
 | `--output-dir <dir>` | Base output directory — auto-generates `{dir}/{domain}/{slug}.md` (default: `./url-to-markdown/`) |
 | `--wait` | Wait for user signal before capturing |
+| `--browser <mode>` | Browser strategy: `auto` (default), `headless`, or `headed` |
+| `--headless` | Shortcut for `--browser headless` |
+| `--headed` | Shortcut for `--browser headed` |
 | `--timeout <ms>` | Page load timeout (default: 30000) |
 | `--download-media` | Download image/video assets to local `imgs/` and `videos/`, and rewrite markdown links to local relative paths |

@@ -165,7 +175,7 @@ ${BUN_X} {baseDir}/scripts/main.ts <url> --download-media

 | Mode | Behavior | Use When |
 |------|----------|----------|
-| Auto (default) | Capture on network idle | Public pages, static content |
+| Auto (default) | Try headless first, then retry in visible Chrome if needed | Public pages, static content, unknown pages |
 | Wait (`--wait`) | User signals when ready | Login-required, lazy loading, paywalls |

 **Wait mode workflow**:
@@ -173,6 +183,43 @@ ${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
 2. Ask user to confirm page is ready
 3. Send newline to stdin to trigger capture

+**Default browser fallback**:
+1. Auto mode starts with headless Chrome and captures on network idle
+2. If headless capture fails technically, retry with visible Chrome
+3. If a shared Chrome session for this profile already exists, reuse it instead of launching a new browser
+4. The script does not hard-code login or paywall detection; the agent must inspect the captured markdown or HTML and decide whether to rerun with `--browser headed --wait`
+
+## Agent Quality Gate
+
+**CRITICAL**: The agent must treat headless capture as provisional. Some sites render differently in headless mode and can silently return an error shell, partially hydrated page, or low-quality extraction **without** causing the CLI to fail.
+
+After every run that used `--browser auto` or `--browser headless`, the agent **MUST** inspect the saved markdown first, and inspect the saved `-captured.html` when the markdown looks suspicious.
+
+### Quality checks the agent must perform
+
+1. Confirm the markdown title matches the target page, not a generic site shell
+2. Confirm the body contains the expected article or page content, not just navigation, footer, or a generic error
+3. Watch for obvious failure signs such as:
+   - `Application error`
+   - `This page could not be found`
+   - login, signup, subscribe, or verification shells
+   - extremely short markdown for a page that should be long-form
+   - raw framework payloads or mostly boilerplate content
+4. If the result is low quality, incomplete, or clearly wrong, do **not** accept the run as successful just because the CLI exited with code 0
+
+### Recovery workflow the agent must follow
+
+1. First run with default `auto` unless there is already a clear reason to use wait mode
+2. Review markdown quality immediately after the run
+3. If the content is low quality, rerun locally with visible Chrome:
+   - `--browser headed` for ordinary rendering issues
+   - `--browser headed --wait` when the page may need login, anti-bot interaction, cookie acceptance, or extra hydration time
+4. If `--wait` is used, tell the user exactly what to do:
+   - if login is required, ask them to sign in
+   - if the page needs time to hydrate, ask them to wait until the full content is visible
+   - once ready, ask them to press Enter so capture can continue
+5. Only fall back to hosted `defuddle.md` after the local browser strategies have failed or are clearly lower fidelity
+
 ## Output Format

 Each run saves two files side by side:
@@ -211,8 +258,9 @@ Conversion order:
 2. If no specialized parser matches, try Defuddle
 3. For rich pages such as YouTube, prefer Defuddle's extractor-specific output (including transcripts when available) instead of replacing it with the legacy pipeline
 4. If Defuddle throws, cannot load, returns obviously incomplete markdown, or captures lower-quality content than the legacy pipeline, automatically fall back to the pre-Defuddle extractor
-5. If the entire local browser capture flow fails before markdown can be produced, try the hosted `https://defuddle.md/<url>` API and save its markdown output directly
-6. The legacy fallback path uses the older Readability/selector/Next.js-data based HTML-to-Markdown implementation recovered from git history
+5. If the agent determines the captured result is a login screen, verification screen, or paywall shell, rerun locally with `--browser headed --wait` and ask the user to complete access before capture
+6. If the entire local browser capture flow still fails before markdown can be produced, try the hosted `https://defuddle.md/<url>` API and save its markdown output directly
+7. The legacy fallback path uses the older Readability/selector/Next.js-data based HTML-to-Markdown implementation recovered from git history

 CLI output will show:

@@ -6,7 +6,7 @@
      "dependencies": {
        "@mozilla/readability": "^0.6.0",
        "baoyu-chrome-cdp": "file:./vendor/baoyu-chrome-cdp",
-        "defuddle": "^0.12.0",
+        "defuddle": "^0.14.0",
        "jsdom": "^24.1.3",
        "linkedom": "^0.18.12",
        "turndown": "^7.2.2",
@@ -61,7 +61,7 @@

    "decimal.js": ["decimal.js@10.6.0", "", {}, "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg=="],

-    "defuddle": ["defuddle@0.12.0", "", { "dependencies": { "commander": "^12.1.0" }, "optionalDependencies": { "mathml-to-latex": "^1.5.0", "temml": "^0.13.1", "turndown": "^7.2.0" }, "peerDependencies": { "jsdom": "^24.0.0" }, "bin": { "defuddle": "dist/cli.js" } }, "sha512-Y/WgyGKBxwxFir+hWNth4nmWDDDb8BzQi3qASS2NWYPXsKU42Ku49/3M5yFYefnRef9prynnmasfnXjk99EWgA=="],
+    "defuddle": ["defuddle@0.14.0", "", { "dependencies": { "commander": "^12.1.0" }, "optionalDependencies": { "linkedom": "^0.18.12", "mathml-to-latex": "^1.5.0", "temml": "^0.13.1", "turndown": "^7.2.0" }, "bin": { "defuddle": "dist/cli.js" } }, "sha512-btavZGd1WgiVqrVM62WGRXMUi/aU7ckTZiq0xXWLZMHvzIqNZjwIFQEDRx8MarD7fIgsB90NXZ9xHJkKtapt2Q=="],

    "delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { cleanContent } from "./content-cleaner.js";
+
+const SAMPLE_HTML = `<!doctype html>
+<html>
+  <head>
+    <title>Example Story</title>
+    <style>.cookie-banner { position: fixed; }</style>
+    <script>window.__noise = true;</script>
+  </head>
+  <body>
+    <!-- comment that should be removed -->
+    <header>
+      <nav>
+        <a href="/home">Home</a>
+        <a href="/topics">Topics</a>
+      </nav>
+    </header>
+    <div class="cookie-banner">Accept cookies</div>
+    <aside>Sidebar links</aside>
+    <main>
+      <article class="content">
+        <h1>Actual Story Title</h1>
+        <p>
+          This is the first paragraph of the real story body, and it is intentionally long enough
+          to survive the cleaner's main-content heuristics without being mistaken for navigation.
+        </p>
+        <p>
+          This is the second paragraph with more useful detail, a
+          <a href="/read-more">supporting link</a>, and a normal image.
+        </p>
+        <img src="/images/cover.jpg" alt="Cover">
+        <img src="data:image/png;base64,AAAA" alt="Inline data">
+      </article>
+    </main>
+    <footer>Footer boilerplate</footer>
+  </body>
+</html>`;
+
+test("cleanContent keeps the article body and removes obvious boilerplate", () => {
+  const cleaned = cleanContent(SAMPLE_HTML, "https://example.com/posts/story");
+
+  assert.match(cleaned, /Actual Story Title/);
+  assert.match(cleaned, /https:\/\/example\.com\/read-more/);
+  assert.match(cleaned, /https:\/\/example\.com\/images\/cover\.jpg/);
+
+  assert.doesNotMatch(cleaned, /Accept cookies/);
+  assert.doesNotMatch(cleaned, /Sidebar links/);
+  assert.doesNotMatch(cleaned, /Footer boilerplate/);
+  assert.doesNotMatch(cleaned, /window\.__noise/);
+  assert.doesNotMatch(cleaned, /comment that should be removed/);
+  assert.doesNotMatch(cleaned, /data:image\/png;base64/);
+});
@@ -0,0 +1,432 @@
+import { parseHTML } from "linkedom";
+
+export interface CleaningOptions {
+  removeAds?: boolean;
+  removeBase64Images?: boolean;
+  onlyMainContent?: boolean;
+  includeTags?: string[];
+  excludeTags?: string[];
+}
+
+const ALWAYS_REMOVE_SELECTORS = [
+  "script",
+  "style",
+  "noscript",
+  "link[rel='stylesheet']",
+  "[hidden]",
+  "[aria-hidden='true']",
+  "[style*='display: none']",
+  "[style*='display:none']",
+  "[style*='visibility: hidden']",
+  "[style*='visibility:hidden']",
+  "svg[aria-hidden='true']",
+  "svg.icon",
+  "svg[class*='icon']",
+  "template",
+  "meta",
+  "iframe",
+  "canvas",
+  "object",
+  "embed",
+  "form",
+  "input",
+  "select",
+  "textarea",
+  "button",
+];
+
+const OVERLAY_SELECTORS = [
+  "[class*='modal']",
+  "[class*='popup']",
+  "[class*='overlay']",
+  "[class*='dialog']",
+  "[role='dialog']",
+  "[role='alertdialog']",
+  "[class*='cookie']",
+  "[class*='consent']",
+  "[class*='gdpr']",
+  "[class*='privacy-banner']",
+  "[class*='notification-bar']",
+  "[id*='cookie']",
+  "[id*='consent']",
+  "[id*='gdpr']",
+  "[style*='position: fixed']",
+  "[style*='position:fixed']",
+  "[style*='position: sticky']",
+  "[style*='position:sticky']",
+];
+
+const NAVIGATION_SELECTORS = [
+  "header",
+  "footer",
+  "nav",
+  "aside",
+  ".header",
+  ".top",
+  ".navbar",
+  "#header",
+  ".footer",
+  ".bottom",
+  "#footer",
+  ".sidebar",
+  ".side",
+  ".aside",
+  "#sidebar",
+  ".modal",
+  ".popup",
+  "#modal",
+  ".overlay",
+  ".ad",
+  ".ads",
+  ".advert",
+  "#ad",
+  ".lang-selector",
+  ".language",
+  "#language-selector",
+  ".social",
+  ".social-media",
+  ".social-links",
+  "#social",
+  ".menu",
+  ".navigation",
+  "#nav",
+  ".breadcrumbs",
+  "#breadcrumbs",
+  ".share",
+  "#share",
+  ".widget",
+  "#widget",
+  ".cookie",
+  "#cookie",
+];
+
+const FORCE_INCLUDE_SELECTORS = [
+  "#main",
+  "#content",
+  "#main-content",
+  "#article",
+  "#post",
+  "#page-content",
+  "main",
+  "article",
+  "[role='main']",
+  ".main-content",
+  ".content",
+  ".post-content",
+  ".article-content",
+  ".entry-content",
+  ".page-content",
+  ".article-body",
+  ".post-body",
+  ".story-content",
+  ".blog-content",
+];
+
+const AD_SELECTORS = [
+  "ins.adsbygoogle",
+  ".google-ad",
+  ".adsense",
+  "[data-ad]",
+  "[data-ads]",
+  "[data-ad-slot]",
+  "[data-ad-client]",
+  ".ad-container",
+  ".ad-wrapper",
+  ".advertisement",
+  ".sponsored-content",
+  "img[width='1'][height='1']",
+  "img[src*='pixel']",
+  "img[src*='tracking']",
+  "img[src*='analytics']",
+];
+
+function getLinkDensity(element: Element): number {
+  const text = element.textContent || "";
+  const textLength = text.trim().length;
+  if (textLength === 0) return 1;
+
+  let linkLength = 0;
+  element.querySelectorAll("a").forEach((link: Element) => {
+    linkLength += (link.textContent || "").trim().length;
+  });
+
+  return linkLength / textLength;
+}
+
+function getContentScore(element: Element): number {
+  let score = 0;
+  const text = element.textContent || "";
+  const textLength = text.trim().length;
+
+  score += Math.min(textLength / 100, 50);
+  score += element.querySelectorAll("p").length * 3;
+  score += element.querySelectorAll("h1, h2, h3, h4, h5, h6").length * 2;
+  score += element.querySelectorAll("img").length;
+
+  score -= element.querySelectorAll("a").length * 0.5;
+  score -= element.querySelectorAll("li").length * 0.2;
+
+  const linkDensity = getLinkDensity(element);
+  if (linkDensity > 0.5) score -= 30;
+  else if (linkDensity > 0.3) score -= 15;
+
+  const className = typeof element.className === "string" ? element.className : "";
+  const classAndId = `${className} ${element.id || ""}`;
+  if (/article|content|post|body|main|entry/i.test(classAndId)) score += 25;
+  if (/comment|sidebar|footer|nav|menu|header|widget|ad/i.test(classAndId)) score -= 25;
+
+  return score;
+}
+
+function looksLikeNavigation(element: Element): boolean {
+  const linkDensity = getLinkDensity(element);
+  if (linkDensity > 0.5) return true;
+
+  const listItems = element.querySelectorAll("li");
+  const links = element.querySelectorAll("a");
+  return listItems.length > 5 && links.length > listItems.length * 0.8;
+}
+
+function removeElements(document: Document, selectors: string[]): void {
+  for (const selector of selectors) {
+    try {
+      document.querySelectorAll(selector).forEach((element: Element) => element.remove());
+    } catch {
+      // Ignore unsupported selectors from linkedom/jsdom differences.
+    }
+  }
+}
+
+function removeWithProtection(
+  document: Document,
+  selectorsToRemove: string[],
+  protectedSelectors: string[]
+): void {
+  for (const selector of selectorsToRemove) {
+    try {
+      document.querySelectorAll(selector).forEach((element: Element) => {
+        const isProtected = protectedSelectors.some((protectedSelector) => {
+          try {
+            return element.matches(protectedSelector);
+          } catch {
+            return false;
+          }
+        });
+        if (isProtected) return;
+
+        const containsProtected = protectedSelectors.some((protectedSelector) => {
+          try {
+            return element.querySelector(protectedSelector) !== null;
+          } catch {
+            return false;
+          }
+        });
+        if (containsProtected) return;
+
+        element.remove();
+      });
+    } catch {
+      // Ignore unsupported selectors from linkedom/jsdom differences.
+    }
+  }
+}
+
+function findMainContent(document: Document): Element | null {
+  const isValidContent = (element: Element | null): element is Element => {
+    if (!element) return false;
+    const text = element.textContent || "";
+    if (text.trim().length < 100) return false;
+    return !looksLikeNavigation(element);
+  };
+
+  const main = document.querySelector("main");
+  if (isValidContent(main) && getLinkDensity(main) < 0.4) return main;
+
+  const roleMain = document.querySelector('[role="main"]');
+  if (isValidContent(roleMain) && getLinkDensity(roleMain) < 0.4) return roleMain;
+
+  const articles = document.querySelectorAll("article");
+  if (articles.length === 1 && isValidContent(articles[0] ?? null)) {
+    return articles[0] ?? null;
+  }
+
+  const contentSelectors = [
+    "#content",
+    "#main-content",
+    "#main",
+    ".content",
+    ".main-content",
+    ".post-content",
+    ".article-content",
+    ".entry-content",
+    ".page-content",
+    ".article-body",
+    ".post-body",
+    ".story-content",
+    ".blog-content",
+  ];
+
+  for (const selector of contentSelectors) {
+    try {
+      const element = document.querySelector(selector);
+      if (isValidContent(element) && getLinkDensity(element) < 0.4) {
+        return element;
+      }
+    } catch {
+      // Ignore invalid selectors.
+    }
+  }
+
+  const candidates: Array<{ element: Element; score: number }> = [];
+  const containers = document.querySelectorAll("div, section, article");
+  containers.forEach((element: Element) => {
+    const text = element.textContent || "";
+    if (text.trim().length < 200) return;
+
+    const score = getContentScore(element);
+    if (score > 0) {
+      candidates.push({ element, score });
+    }
+  });
+
+  candidates.sort((left, right) => right.score - left.score);
+  if ((candidates[0]?.score ?? 0) > 20) {
+    return candidates[0]?.element ?? null;
+  }
+
+  return null;
+}
+
+function removeBase64ImagesFromDocument(document: Document): void {
+  document.querySelectorAll("img[src^='data:']").forEach((element: Element) => {
+    element.remove();
+  });
+
+  document.querySelectorAll("[style*='data:image']").forEach((element: Element) => {
+    const style = element.getAttribute("style");
+    if (!style) return;
+
+    const cleanedStyle = style.replace(
+      /background(-image)?:\s*url\([^)]*data:image[^)]*\)[^;]*;?/gi,
+      ""
+    );
+
+    if (cleanedStyle.trim()) {
+      element.setAttribute("style", cleanedStyle);
+    } else {
+      element.removeAttribute("style");
+    }
+  });
+
+  document.querySelectorAll("source[src^='data:'], source[srcset*='data:']").forEach((element: Element) => {
+    element.remove();
+  });
+}
+
+function makeAbsoluteUrl(value: string, baseUrl: string): string | null {
+  try {
+    return new URL(value, baseUrl).toString();
+  } catch {
+    return null;
+  }
+}
+
+function convertRelativeUrls(document: Document, baseUrl: string): void {
+  document.querySelectorAll("[src]").forEach((element: Element) => {
+    const src = element.getAttribute("src");
+    if (!src || src.startsWith("http") || src.startsWith("//") || src.startsWith("data:")) return;
+
+    const absolute = makeAbsoluteUrl(src, baseUrl);
+    if (absolute) element.setAttribute("src", absolute);
+  });
+
+  document.querySelectorAll("[href]").forEach((element: Element) => {
+    const href = element.getAttribute("href");
+    if (
+      !href ||
+      href.startsWith("http") ||
+      href.startsWith("//") ||
+      href.startsWith("#") ||
+      href.startsWith("mailto:") ||
+      href.startsWith("tel:") ||
+      href.startsWith("javascript:")
+    ) {
+      return;
+    }
+
+    const absolute = makeAbsoluteUrl(href, baseUrl);
+    if (absolute) element.setAttribute("href", absolute);
+  });
+}
+
+export function cleanHtml(html: string, baseUrl: string, options: CleaningOptions = {}): string {
+  const {
+    removeAds = true,
+    removeBase64Images = true,
+    onlyMainContent = true,
+    includeTags,
+    excludeTags,
+  } = options;
+
+  const { document } = parseHTML(html);
+
+  removeElements(document, ALWAYS_REMOVE_SELECTORS);
+  removeElements(document, OVERLAY_SELECTORS);
+
+  if (removeAds) {
+    removeElements(document, AD_SELECTORS);
+  }
+
+  if (excludeTags?.length) {
+    removeElements(document, excludeTags);
+  }
+
+  if (onlyMainContent) {
+    removeWithProtection(document, NAVIGATION_SELECTORS, FORCE_INCLUDE_SELECTORS);
+
+    const mainContent = findMainContent(document);
+    if (mainContent && document.body) {
+      const clone = mainContent.cloneNode(true) as Element;
+      document.body.innerHTML = "";
+      document.body.appendChild(clone);
+    }
+  }
+
+  if (includeTags?.length && document.body) {
+    const matchedElements: Element[] = [];
+
+    for (const selector of includeTags) {
+      try {
+        document.querySelectorAll(selector).forEach((element: Element) => {
+          matchedElements.push(element.cloneNode(true) as Element);
+        });
+      } catch {
+        // Ignore invalid selectors.
+      }
+    }
+
+    if (matchedElements.length > 0) {
+      document.body.innerHTML = "";
+      matchedElements.forEach((element) => document.body?.appendChild(element));
+    }
+  }
+
+  if (removeBase64Images) {
+    removeBase64ImagesFromDocument(document);
+  }
+
+  const walker = document.createTreeWalker(document, 128);
+  const comments: Node[] = [];
+  while (walker.nextNode()) {
+    comments.push(walker.currentNode);
+  }
+  comments.forEach((comment) => comment.parentNode?.removeChild(comment));
+
+  convertRelativeUrls(document, baseUrl);
+
+  return document.documentElement?.outerHTML || html;
+}
+
+export function cleanContent(html: string, baseUrl: string, options: CleaningOptions = {}): string {
+  return cleanHtml(html, baseUrl, options);
+}
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { extractContent } from "./html-to-markdown.js";
+
+const EMBEDDED_IMAGE_HTML = `<!doctype html>
+<html>
+  <body>
+    <main>
+      <article>
+        <h1>Embedded Image Story</h1>
+        <p>
+          This paragraph is intentionally long enough to satisfy the extractor thresholds so the
+          resulting markdown keeps the main article body and the embedded image reference.
+        </p>
+        <img src="data:image/png;base64,AAAA" alt="inline">
+      </article>
+    </main>
+  </body>
+</html>`;
+
+test("extractContent preserves base64 images when requested for media download", async () => {
+  const result = await extractContent(EMBEDDED_IMAGE_HTML, "https://example.com/embedded", {
+    preserveBase64Images: true,
+  });
+
+  assert.match(result.markdown, /!\[inline\]\(data:image\/png;base64,AAAA\)/);
+});
@@ -13,10 +13,15 @@ import {
  shouldCompareWithLegacy,
 } from "./legacy-converter.js";
 import { tryUrlRuleParsers } from "./parsers/index.js";
+import { cleanContent } from "./content-cleaner.js";

 export type { ConversionResult, PageMetadata };
 export { createMarkdownDocument, formatMetadataYaml };

+export interface ExtractContentOptions {
+  preserveBase64Images?: boolean;
+}
+
 export const absolutizeUrlsScript = String.raw`
 (function() {
  const baseUrl = document.baseURI || location.href;
@@ -85,7 +90,10 @@ export const absolutizeUrlsScript = String.raw`
  absAttr(htmlClone, "video[poster]", "poster");
  absSrcset(htmlClone, "img[srcset], source[srcset]");

-  return { html: "<!doctype html>\n" + htmlClone.outerHTML };
+  return {
+    html: "<!doctype html>\n" + htmlClone.outerHTML,
+    finalUrl: location.href,
+  };
 })()
 `;

@@ -102,7 +110,11 @@ function shouldPreferDefuddle(result: ConversionResult): boolean {
  return /^##?\s+transcript\b/im.test(result.markdown);
 }

-export async function extractContent(html: string, url: string): Promise<ConversionResult> {
+export async function extractContent(
+  html: string,
+  url: string,
+  options: ExtractContentOptions = {}
+): Promise<ConversionResult> {
  const capturedAt = new Date().toISOString();
  const baseMetadata = extractMetadataFromHtml(html, url, capturedAt);

@@ -111,14 +123,23 @@ export async function extractContent(html: string, url: string): Promise<Convers
    return specializedResult;
  }

-  const defuddleResult = await tryDefuddleConversion(html, url, baseMetadata);
+  let cleanedHtml = html;
+  try {
+    cleanedHtml = cleanContent(html, url, {
+      removeBase64Images: !options.preserveBase64Images,
+    });
+  } catch {
+    cleanedHtml = html;
+  }
+
+  const defuddleResult = await tryDefuddleConversion(cleanedHtml, url, baseMetadata);
  if (defuddleResult.ok) {
    if (shouldPreferDefuddle(defuddleResult.result)) {
-      return defuddleResult.result;
+      return { ...defuddleResult.result, rawHtml: html };
    }

    if (shouldCompareWithLegacy(defuddleResult.result.markdown)) {
-      const legacyResult = convertWithLegacyExtractor(html, baseMetadata);
+      const legacyResult = convertWithLegacyExtractor(html, baseMetadata, cleanedHtml);
      const legacyScore = scoreMarkdownQuality(legacyResult.markdown);
      const defuddleScore = scoreMarkdownQuality(defuddleResult.result.markdown);

@@ -130,10 +151,10 @@ export async function extractContent(html: string, url: string): Promise<Convers
      }
    }

-    return defuddleResult.result;
+    return { ...defuddleResult.result, rawHtml: html };
  }

-  const fallbackResult = convertWithLegacyExtractor(html, baseMetadata);
+  const fallbackResult = convertWithLegacyExtractor(html, baseMetadata, cleanedHtml);
  return {
    ...fallbackResult,
    fallbackReason: defuddleResult.reason,
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { cleanContent } from "./content-cleaner.js";
+import { convertWithLegacyExtractor } from "./legacy-converter.js";
+import { extractMetadataFromHtml } from "./markdown-conversion-shared.js";
+
+const CAPTURED_AT = "2026-03-24T03:00:00.000Z";
+
+const NEXT_DATA_HTML = `<!doctype html>
+<html>
+  <head>
+    <title>Hydrated Story</title>
+  </head>
+  <body>
+    <div class="cookie-banner">Accept cookies</div>
+    <main>
+      <p>Short teaser text that should not win over the structured article payload.</p>
+    </main>
+    <script id="__NEXT_DATA__" type="application/json">
+      {
+        "props": {
+          "pageProps": {
+            "article": {
+              "title": "Hydrated Story",
+              "description": "A structured article payload from Next.js",
+              "body": "<p>The full article lives in __NEXT_DATA__ and should still be extracted even when the cleaned HTML removes scripts before the selector and readability passes run.</p><p>A second paragraph keeps the content comfortably above the minimum extraction threshold and proves the legacy extractor still has access to the original structured payload.</p>"
+            }
+          }
+        }
+      }
+    </script>
+  </body>
+</html>`;
+
+test("legacy extractor still uses original __NEXT_DATA__ after HTML cleaning", () => {
+  const url = "https://example.com/posts/hydrated-story";
+  const baseMetadata = extractMetadataFromHtml(NEXT_DATA_HTML, url, CAPTURED_AT);
+  const cleanedHtml = cleanContent(NEXT_DATA_HTML, url);
+
+  const result = convertWithLegacyExtractor(NEXT_DATA_HTML, baseMetadata, cleanedHtml);
+
+  assert.equal(result.conversionMethod, "legacy:next-data");
+  assert.match(result.markdown, /The full article lives in .*NEXT.*DATA/);
+  assert.match(result.markdown, /A second paragraph keeps the content comfortably above the minimum extraction threshold/);
+  assert.doesNotMatch(result.markdown, /Short teaser text that should not win/);
+  assert.equal(result.rawHtml, NEXT_DATA_HTML);
+});
@@ -336,29 +336,32 @@ function tryNextDataExtraction(document: Document): ExtractionCandidate | null {

 function buildReadabilityCandidate(
  article: ReturnType<Readability["parse"]>,
-  document: Document,
+  referenceDocument: Document,
  method: string
 ): ExtractionCandidate | null {
  const textContent = article?.textContent?.trim() ?? "";
  if (textContent.length < MIN_CONTENT_LENGTH) return null;

  return {
-    title: pickString(article?.title, extractTitle(document)),
+    title: pickString(article?.title, extractTitle(referenceDocument)),
    byline: pickString((article as { byline?: string } | null)?.byline),
    excerpt: pickString(article?.excerpt, generateExcerpt(null, textContent)),
-    published: pickString((article as { publishedTime?: string } | null)?.publishedTime, extractPublishedTime(document)),
+    published: pickString(
+      (article as { publishedTime?: string } | null)?.publishedTime,
+      extractPublishedTime(referenceDocument)
+    ),
    html: article?.content ? sanitizeHtml(article.content) : null,
    textContent,
    method,
  };
 }

-function tryReadability(document: Document): ExtractionCandidate | null {
+function tryReadability(document: Document, referenceDocument: Document = document): ExtractionCandidate | null {
  try {
    const strictClone = document.cloneNode(true) as Document;
    const strictResult = buildReadabilityCandidate(
      new Readability(strictClone).parse(),
-      document,
+      referenceDocument,
      "readability"
    );
    if (strictResult) return strictResult;
@@ -366,7 +369,7 @@ function tryReadability(document: Document): ExtractionCandidate | null {
    const relaxedClone = document.cloneNode(true) as Document;
    return buildReadabilityCandidate(
      new Readability(relaxedClone, { charThreshold: 120 }).parse(),
-      document,
+      referenceDocument,
      "readability-relaxed"
    );
  } catch {
@@ -471,14 +474,15 @@ function pickBestCandidate(candidates: ExtractionCandidate[]): ExtractionCandida
  return ranked[0];
 }

-function extractFromHtml(html: string): ExtractionCandidate | null {
-  const document = parseDocument(html);
+function extractFromHtml(html: string, cleanedHtml: string = html): ExtractionCandidate | null {
+  const originalDocument = parseDocument(html);
+  const cleanedDocument = parseDocument(cleanedHtml);

-  const readabilityCandidate = tryReadability(document);
-  const nextDataCandidate = tryNextDataExtraction(document);
-  const jsonLdCandidate = tryJsonLdExtraction(document);
-  const selectorCandidate = trySelectorExtraction(document);
-  const bodyCandidate = tryBodyExtraction(document);
+  const readabilityCandidate = tryReadability(cleanedDocument, originalDocument);
+  const nextDataCandidate = tryNextDataExtraction(originalDocument);
+  const jsonLdCandidate = tryJsonLdExtraction(originalDocument);
+  const selectorCandidate = trySelectorExtraction(cleanedDocument);
+  const bodyCandidate = tryBodyExtraction(cleanedDocument);

  const candidates = [
    readabilityCandidate,
@@ -493,8 +497,8 @@ function extractFromHtml(html: string): ExtractionCandidate | null {

  return {
    ...winner,
-    title: winner.title ?? extractTitle(document),
-    published: winner.published ?? extractPublishedTime(document),
+    title: winner.title ?? extractTitle(originalDocument),
+    published: winner.published ?? extractPublishedTime(originalDocument),
    excerpt: winner.excerpt ?? generateExcerpt(null, winner.textContent),
  };
 }
@@ -610,12 +614,16 @@ export function shouldCompareWithLegacy(markdown: string): boolean {
  );
 }

-export function convertWithLegacyExtractor(html: string, baseMetadata: PageMetadata): ConversionResult {
-  const extracted = extractFromHtml(html);
+export function convertWithLegacyExtractor(
+  html: string,
+  baseMetadata: PageMetadata,
+  cleanedHtml: string = html
+): ConversionResult {
+  const extracted = extractFromHtml(html, cleanedHtml);

  let markdown = extracted?.html ? convertHtmlFragmentToMarkdown(extracted.html) : "";
  if (!markdown.trim()) {
-    markdown = extracted?.textContent?.trim() || fallbackPlainText(html);
+    markdown = extracted?.textContent?.trim() || fallbackPlainText(cleanedHtml);
  }

  return {
@@ -29,10 +29,33 @@ interface Args {
  wait: boolean;
  timeout: number;
  downloadMedia: boolean;
+  browserMode: BrowserMode;
 }

+type BrowserMode = "auto" | "headless" | "headed";
+
+interface CaptureAttemptOptions {
+  headless: boolean;
+  wait: boolean;
+  existingPort?: number;
+  waitPrompt?: string;
+}
+
+interface CaptureSnapshot {
+  html: string;
+  finalUrl: string;
+}
+
+const BROWSER_MODES = new Set<BrowserMode>(["auto", "headless", "headed"]);
+
 function parseArgs(argv: string[]): Args {
-  const args: Args = { url: "", wait: false, timeout: DEFAULT_TIMEOUT_MS, downloadMedia: false };
+  const args: Args = {
+    url: "",
+    wait: false,
+    timeout: DEFAULT_TIMEOUT_MS,
+    downloadMedia: false,
+    browserMode: "auto",
+  };
  for (let i = 2; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === "--wait" || arg === "-w") {
@@ -45,6 +68,12 @@ function parseArgs(argv: string[]): Args {
      args.outputDir = argv[++i];
    } else if (arg === "--download-media") {
      args.downloadMedia = true;
+    } else if (arg === "--browser") {
+      args.browserMode = (argv[++i] as BrowserMode | undefined) ?? "auto";
+    } else if (arg === "--headless") {
+      args.browserMode = "headless";
+    } else if (arg === "--headed" || arg === "--noheadless" || arg === "--no-headless") {
+      args.browserMode = "headed";
    } else if (!arg.startsWith("-") && !args.url) {
      args.url = arg;
    }
@@ -194,21 +223,28 @@ async function generateOutputPath(url: string, title: string, outputDir?: string
  return path.join(dataDir, domain, timestampSlug, `${timestampSlug}.md`);
 }

-async function waitForUserSignal(): Promise<void> {
-  console.log("Page opened. Press Enter when ready to capture...");
+function defaultWaitPrompt(): string {
+  return "A browser window has been opened. If the page requires login or verification, complete it first, then press Enter to capture.";
+}
+
+async function waitForUserSignal(prompt: string): Promise<void> {
+  console.log(prompt);
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  await new Promise<void>((resolve) => {
    rl.once("line", () => { rl.close(); resolve(); });
  });
 }

-async function captureUrl(args: Args): Promise<ConversionResult> {
-  const existingPort = await findExistingChromePort();
-  const reusing = existingPort !== null;
-  const port = existingPort ?? await getFreePort();
-  const chrome = reusing ? null : await launchChrome(args.url, port, false);
+async function captureUrlOnce(args: Args, options: CaptureAttemptOptions): Promise<ConversionResult> {
+  const reusing = options.existingPort !== undefined;
+  const port = options.existingPort ?? await getFreePort();
+  const chrome = reusing ? null : await launchChrome(args.url, port, options.headless);

-  if (reusing) console.log(`Reusing existing Chrome on port ${port}`);
+  if (reusing) {
+    console.log(`Reusing existing Chrome on port ${port}`);
+  } else {
+    console.log(`Launching Chrome (${options.headless ? "headless" : "headed"})...`);
+  }

  let cdp: CdpConnection | null = null;
  let targetId: string | null = null;
@@ -235,8 +271,8 @@ async function captureUrl(args: Args): Promise<ConversionResult> {
      await cdp.send("Page.enable", {}, { sessionId });
    }

-    if (args.wait) {
-      await waitForUserSignal();
+    if (options.wait) {
+      await waitForUserSignal(options.waitPrompt ?? defaultWaitPrompt());
    } else {
      console.log("Waiting for page to load...");
      await Promise.race([
@@ -251,11 +287,12 @@ async function captureUrl(args: Args): Promise<ConversionResult> {
    }

    console.log("Capturing page content...");
-    const { html } = await evaluateScript<{ html: string }>(
+    const snapshot = await evaluateScript<CaptureSnapshot>(
      cdp, sessionId, absolutizeUrlsScript, args.timeout
    );
-
-    return await extractContent(html, args.url);
+    return await extractContent(snapshot.html, snapshot.finalUrl || args.url, {
+      preserveBase64Images: args.downloadMedia,
+    });
  } finally {
    if (reusing) {
      if (cdp && targetId) {
@@ -272,10 +309,67 @@ async function captureUrl(args: Args): Promise<ConversionResult> {
  }
 }

+async function runHeadedFlow(
+  args: Args,
+  options: { existingPort?: number; wait: boolean; waitPrompt?: string }
+): Promise<ConversionResult> {
+  return await captureUrlOnce(args, {
+    headless: false,
+    wait: options.wait,
+    existingPort: options.existingPort,
+    waitPrompt: options.waitPrompt,
+  });
+}
+
+async function captureUrl(args: Args): Promise<ConversionResult> {
+  const existingPort = await findExistingChromePort();
+  if (existingPort !== null) {
+    console.log("Found an existing Chrome session for this profile. Reusing it instead of launching a new browser.");
+    return await runHeadedFlow(args, {
+      existingPort,
+      wait: args.wait,
+      waitPrompt: args.wait ? defaultWaitPrompt() : undefined,
+    });
+  }
+
+  if (args.browserMode === "headless") {
+    return await captureUrlOnce(args, { headless: true, wait: false });
+  }
+
+  if (args.browserMode === "headed") {
+    return await runHeadedFlow(args, {
+      wait: args.wait,
+      waitPrompt: args.wait ? defaultWaitPrompt() : undefined,
+    });
+  }
+
+  if (args.wait) {
+    return await runHeadedFlow(args, {
+      wait: true,
+      waitPrompt: defaultWaitPrompt(),
+    });
+  }
+
+  try {
+    return await captureUrlOnce(args, { headless: true, wait: false });
+  } catch (error) {
+    const headlessMessage = error instanceof Error ? error.message : String(error);
+    console.warn(`Headless capture failed: ${headlessMessage}`);
+    console.log("Retrying with a visible browser window...");
+
+    try {
+      return await runHeadedFlow(args, { wait: false });
+    } catch (headedError) {
+      const headedMessage = headedError instanceof Error ? headedError.message : String(headedError);
+      throw new Error(`Headless capture failed (${headlessMessage}); headed retry failed (${headedMessage})`);
+    }
+  }
+}
+
 async function main(): Promise<void> {
  const args = parseArgs(process.argv);
  if (!args.url) {
-    console.error("Usage: bun main.ts <url> [-o output.md] [--output-dir dir] [--wait] [--timeout ms] [--download-media]");
+    console.error("Usage: bun main.ts <url> [-o output.md] [--output-dir dir] [--wait] [--browser auto|headless|headed] [--timeout ms] [--download-media]");
    process.exit(1);
  }

@@ -286,6 +380,16 @@ async function main(): Promise<void> {
    process.exit(1);
  }

+  if (!BROWSER_MODES.has(args.browserMode)) {
+    console.error(`Invalid --browser mode: ${args.browserMode}. Expected auto, headless, or headed.`);
+    process.exit(1);
+  }
+
+  if (args.wait && args.browserMode === "headless") {
+    console.error("Error: --wait requires a visible browser. Use --browser auto or --browser headed.");
+    process.exit(1);
+  }
+
  if (args.output) {
    const stat = await import("node:fs").then(fs => fs.statSync(args.output!, { throwIfNoEntry: false }));
    if (stat?.isDirectory()) {
@@ -296,6 +400,7 @@ async function main(): Promise<void> {

  console.log(`Fetching: ${args.url}`);
  console.log(`Mode: ${args.wait ? "wait" : "auto"}`);
+  console.log(`Browser: ${args.browserMode}`);

  let outputPath: string;
  let htmlSnapshotPath: string | null = null;
@@ -306,7 +411,7 @@ async function main(): Promise<void> {
  try {
    const result = await captureUrl(args);
    document = createMarkdownDocument(result);
-    outputPath = args.output || await generateOutputPath(args.url, result.metadata.title, args.outputDir, document);
+    outputPath = args.output || await generateOutputPath(result.metadata.url || args.url, result.metadata.title, args.outputDir, document);
    const outputDir = path.dirname(outputPath);
    htmlSnapshotPath = deriveHtmlSnapshotPath(outputPath);
    await mkdir(outputDir, { recursive: true });
@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, readdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { localizeMarkdownMedia } from "./media-localizer.js";
+
+const PNG_1X1_BASE64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7Z0ioAAAAASUVORK5CYII=";
+
+test("localizeMarkdownMedia saves embedded base64 images into imgs directory", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "url-to-markdown-media-"));
+  const dataUri = `data:image/png;base64,${PNG_1X1_BASE64}`;
+  const markdown = [
+    "---",
+    `coverImage: "${dataUri}"`,
+    "---",
+    "",
+    "# Embedded Image",
+    "",
+    `![inline](${dataUri})`,
+    "",
+  ].join("\n");
+
+  const result = await localizeMarkdownMedia(markdown, {
+    markdownPath: path.join(tempDir, "post.md"),
+  });
+
+  assert.equal(result.downloadedImages, 1);
+  assert.equal(result.downloadedVideos, 0);
+  assert.match(result.markdown, /coverImage: "imgs\/img-001\.png"/);
+  assert.match(result.markdown, /!\[inline\]\(imgs\/img-001\.png\)/);
+
+  const files = await readdir(path.join(tempDir, "imgs"));
+  assert.deepEqual(files, ["img-001.png"]);
+
+  const bytes = await readFile(path.join(tempDir, "imgs", "img-001.png"));
+  assert.equal(bytes.length, Buffer.from(PNG_1X1_BASE64, "base64").length);
+});
@@ -3,10 +3,12 @@ import { mkdir, writeFile } from "node:fs/promises";

 type MediaKind = "image" | "video";
 type MediaHint = "image" | "unknown";
+type MediaSource = "remote" | "data";

 type MarkdownLinkCandidate = {
  url: string;
  hint: MediaHint;
+  source: MediaSource;
 };

 export type LocalizeMarkdownMediaOptions = {
@@ -22,8 +24,9 @@ export type LocalizeMarkdownMediaResult = {
  videoDir: string | null;
 };

-const MARKDOWN_LINK_RE = /(!?\[[^\]\n]*\])\((<)?(https?:\/\/[^)\s>]+)(>)?\)/g;
-const FRONTMATTER_COVER_RE = /^(coverImage:\s*")(https?:\/\/[^"]+)(")/m;
+const MARKDOWN_LINK_RE =
+  /(!?\[[^\]\n]*\])\((<)?((?:https?:\/\/[^)\s>]+)|(?:data:[^)>\s]+))(>)?\)/g;
+const FRONTMATTER_COVER_RE = /^(coverImage:\s*")((?:https?:\/\/[^"]+)|(?:data:[^"]+))(")/m;

 const IMAGE_EXTENSIONS = new Set([
  "jpg",
@@ -86,6 +89,10 @@ function resolveExtensionFromUrl(rawUrl: string): string | undefined {
  return undefined;
 }

+function resolveExtensionFromContentType(contentType: string): string | undefined {
+  return normalizeExtension(MIME_EXTENSION_MAP[contentType]);
+}
+
 function resolveKindFromContentType(contentType: string): MediaKind | undefined {
  if (!contentType) return undefined;
  if (contentType.startsWith("image/")) return "image";
@@ -124,7 +131,7 @@ function resolveOutputExtension(
  extension: string | undefined,
  kind: MediaKind
 ): string {
-  const extFromMime = normalizeExtension(MIME_EXTENSION_MAP[contentType]);
+  const extFromMime = resolveExtensionFromContentType(contentType);
  if (extFromMime) return extFromMime;

  const normalizedExt = normalizeExtension(extension);
@@ -150,6 +157,10 @@ function sanitizeFileSegment(input: string): string {
 }

 function resolveFileStem(rawUrl: string, extension: string): string {
+  if (isDataUri(rawUrl)) {
+    return "";
+  }
+
  try {
    const parsed = new URL(rawUrl);
    const base = path.posix.basename(parsed.pathname);
@@ -172,6 +183,26 @@ function buildFileName(kind: MediaKind, index: number, sourceUrl: string, extens
  return `${prefix}-${serial}${suffix}.${extension}`;
 }

+function isDataUri(value: string): boolean {
+  return value.startsWith("data:");
+}
+
+function parseBase64DataUri(rawUrl: string): { contentType: string; bytes: Buffer } | null {
+  const match = rawUrl.match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s]+)$/i);
+  if (!match?.[1] || !match[2]) return null;
+
+  const contentType = normalizeContentType(match[1]);
+  if (!contentType) return null;
+
+  try {
+    const bytes = Buffer.from(match[2].replace(/\s+/g, ""), "base64");
+    if (bytes.length === 0) return null;
+    return { contentType, bytes };
+  } catch {
+    return null;
+  }
+}
+
 function collectMarkdownLinkCandidates(markdown: string): MarkdownLinkCandidate[] {
  const candidates: MarkdownLinkCandidate[] = [];
  const seen = new Set<string>();
@@ -181,7 +212,11 @@ function collectMarkdownLinkCandidates(markdown: string): MarkdownLinkCandidate[
    const coverMatch = fmMatch[1]?.match(FRONTMATTER_COVER_RE);
    if (coverMatch?.[2] && !seen.has(coverMatch[2])) {
      seen.add(coverMatch[2]);
-      candidates.push({ url: coverMatch[2], hint: "image" });
+      candidates.push({
+        url: coverMatch[2],
+        hint: "image",
+        source: isDataUri(coverMatch[2]) ? "data" : "remote",
+      });
    }
  }

@@ -195,6 +230,7 @@ function collectMarkdownLinkCandidates(markdown: string): MarkdownLinkCandidate[
    candidates.push({
      url: rawUrl,
      hint: label.startsWith("![") ? "image" : "unknown",
+      source: isDataUri(rawUrl) ? "data" : "remote",
    });
  }

@@ -244,24 +280,45 @@ export async function localizeMarkdownMedia(

  for (const candidate of candidates) {
    try {
-      const response = await fetch(candidate.url, {
-        method: "GET",
-        redirect: "follow",
-        headers: {
-          "user-agent": DOWNLOAD_USER_AGENT,
-        },
-      });
+      let sourceUrl = candidate.url;
+      let contentType = "";
+      let extension: string | undefined;
+      let kind: MediaKind | undefined;
+      let bytes: Buffer | null = null;

-      if (!response.ok) {
-        log(`[url-to-markdown] Skip media (${response.status}): ${candidate.url}`);
-        continue;
+      if (candidate.source === "data") {
+        const parsed = parseBase64DataUri(candidate.url);
+        if (!parsed) {
+          log("[url-to-markdown] Skip embedded media: unsupported or invalid data URI");
+          continue;
+        }
+
+        contentType = parsed.contentType;
+        extension = resolveExtensionFromContentType(contentType);
+        kind = resolveMediaKind(sourceUrl, contentType, extension, candidate.hint);
+        bytes = parsed.bytes;
+      } else {
+        const response = await fetch(candidate.url, {
+          method: "GET",
+          redirect: "follow",
+          headers: {
+            "user-agent": DOWNLOAD_USER_AGENT,
+          },
+        });
+
+        if (!response.ok) {
+          log(`[url-to-markdown] Skip media (${response.status}): ${candidate.url}`);
+          continue;
+        }
+
+        sourceUrl = response.url || candidate.url;
+        contentType = normalizeContentType(response.headers.get("content-type"));
+        extension = resolveExtensionFromUrl(sourceUrl) ?? resolveExtensionFromUrl(candidate.url);
+        kind = resolveMediaKind(sourceUrl, contentType, extension, candidate.hint);
+        bytes = Buffer.from(await response.arrayBuffer());
      }

-      const sourceUrl = response.url || candidate.url;
-      const contentType = normalizeContentType(response.headers.get("content-type"));
-      const extension = resolveExtensionFromUrl(sourceUrl) ?? resolveExtensionFromUrl(candidate.url);
-      const kind = resolveMediaKind(sourceUrl, contentType, extension, candidate.hint);
-      if (!kind) {
+      if (!kind || !bytes) {
        continue;
      }

@@ -274,7 +331,6 @@ export async function localizeMarkdownMedia(
      const fileName = buildFileName(kind, nextIndex, sourceUrl, outputExtension);
      const absolutePath = path.join(targetDir, fileName);
      const relativePath = path.posix.join(dirName, fileName);
-      const bytes = Buffer.from(await response.arrayBuffer());
      await writeFile(absolutePath, bytes);
      replacements.set(candidate.url, relativePath);

@@ -305,6 +361,7 @@ export function countRemoteMedia(markdown: string): { images: number; videos: nu
  let images = 0;
  let videos = 0;
  for (const c of candidates) {
+    if (c.source !== "remote") continue;
    const ext = resolveExtensionFromUrl(c.url);
    const kind = resolveKindFromExtension(ext);
    if (kind === "video") {
@@ -5,7 +5,7 @@
  "dependencies": {
    "@mozilla/readability": "^0.6.0",
    "baoyu-chrome-cdp": "file:./vendor/baoyu-chrome-cdp",
-    "defuddle": "^0.12.0",
+    "defuddle": "^0.14.0",
    "jsdom": "^24.1.3",
    "linkedom": "^0.18.12",
    "turndown": "^7.2.2",
@@ -1,4 +1,5 @@
-import { describe, expect, test } from "bun:test";
+import assert from "node:assert/strict";
+import test from "node:test";

 import {
  createMarkdownDocument,
@@ -129,73 +130,77 @@ function parse(html: string, url: string) {
  return tryUrlRuleParsers(html, url, baseMetadata);
 }

-describe("url rule parsers", () => {
-  test("parses archive.ph pages from CONTENT and restores the original URL", () => {
-    const result = parse(ARCHIVE_HTML, "https://archive.ph/SMcX5");
+test("parses archive.ph pages from CONTENT and restores the original URL", () => {
+  const result = parse(ARCHIVE_HTML, "https://archive.ph/SMcX5");

-    expect(result).not.toBeNull();
-    expect(result?.conversionMethod).toBe("parser:archive-ph");
-    expect(result?.metadata.url).toBe(
-      "https://www.newscientist.com/article/2520204-major-leap-towards-reanimation-after-death-as-mammals-brain-preserved/"
-    );
-    expect(result?.metadata.title).toBe(
-      "Major leap towards reanimation after death as mammal brain preserved"
-    );
-    expect(result?.metadata.coverImage).toBe("https://cdn.example.com/brain.jpg");
-    expect(result?.markdown).toContain("Researchers say the preserved structure");
-    expect(result?.markdown).toContain("![Brain tissue](https://cdn.example.com/brain.jpg)");
-    expect(result?.markdown).not.toContain("Archive shell text that should be ignored");
-  });
-
-  test("falls back to body when archive.ph CONTENT is missing", () => {
-    const result = parse(ARCHIVE_FALLBACK_HTML, "https://archive.ph/fallback");
-
-    expect(result).not.toBeNull();
-    expect(result?.conversionMethod).toBe("parser:archive-ph");
-    expect(result?.metadata.url).toBe("https://example.com/fallback-story");
-    expect(result?.metadata.title).toBe("Fallback body parsing still works");
-    expect(result?.markdown).toContain("When CONTENT is absent");
-  });
-
-  test("parses X article pages from HTML", () => {
-    const result = parse(
-      ARTICLE_HTML,
-      "https://x.com/dotey/article/2035141635713941927"
-    );
-
-    expect(result).not.toBeNull();
-    expect(result?.conversionMethod).toBe("parser:x-article");
-    expect(result?.metadata.title).toBe("Karpathy：\"写代码\"已经不是对的动词了");
-    expect(result?.metadata.author).toBe("宝玉 (@dotey)");
-    expect(result?.metadata.coverImage).toBe("https://pbs.twimg.com/media/article-cover.jpg");
-    expect(result?.metadata.published).toBe("2026-03-20T23:49:11.000Z");
-    expect(result?.metadata.language).toBe("zh");
-    expect(result?.markdown).toContain("## 要点速览");
-    expect(result?.markdown).toContain(
-      "[![](https://pbs.twimg.com/media/article-inline.jpg)](/dotey/article/2035141635713941927/media/2)"
-    );
-    expect(result?.markdown).toContain("写代码已经不是对的动词了。");
-
-    const document = createMarkdownDocument(result!);
-    expect(document).toContain("# Karpathy：\"写代码\"已经不是对的动词了");
-  });
-
-  test("parses X status pages from HTML without duplicating the title heading", () => {
-    const result = parse(
-      STATUS_HTML,
-      "https://x.com/dotey/status/2035590649081196710"
-    );
-
-    expect(result).not.toBeNull();
-    expect(result?.conversionMethod).toBe("parser:x-status");
-    expect(result?.metadata.author).toBe("宝玉 (@dotey)");
-    expect(result?.metadata.coverImage).toBe("https://pbs.twimg.com/media/tweet-main.jpg");
-    expect(result?.metadata.language).toBe("zh");
-    expect(result?.markdown).toContain("转译：把下面这段加到你的 Codex 自定义指令里");
-    expect(result?.markdown).toContain("> Quote from Matt Shumer (@mattshumer_)");
-    expect(result?.markdown).toContain("![");
-
-    const document = createMarkdownDocument(result!);
-    expect(document).not.toContain("\n\n# 转译：把下面这段加到你的 Codex 自定义指令里，体验会好太多：\n\n");
-  });
+  assert.ok(result);
+  assert.equal(result.conversionMethod, "parser:archive-ph");
+  assert.equal(
+    result.metadata.url,
+    "https://www.newscientist.com/article/2520204-major-leap-towards-reanimation-after-death-as-mammals-brain-preserved/"
+  );
+  assert.equal(
+    result.metadata.title,
+    "Major leap towards reanimation after death as mammal brain preserved"
+  );
+  assert.equal(result.metadata.coverImage, "https://cdn.example.com/brain.jpg");
+  assert.ok(result.markdown.includes("Researchers say the preserved structure"));
+  assert.ok(result.markdown.includes("![Brain tissue](https://cdn.example.com/brain.jpg)"));
+  assert.ok(!result.markdown.includes("Archive shell text that should be ignored"));
+});
+
+test("falls back to body when archive.ph CONTENT is missing", () => {
+  const result = parse(ARCHIVE_FALLBACK_HTML, "https://archive.ph/fallback");
+
+  assert.ok(result);
+  assert.equal(result.conversionMethod, "parser:archive-ph");
+  assert.equal(result.metadata.url, "https://example.com/fallback-story");
+  assert.equal(result.metadata.title, "Fallback body parsing still works");
+  assert.ok(result.markdown.includes("When CONTENT is absent"));
+});
+
+test("parses X article pages from HTML", () => {
+  const result = parse(
+    ARTICLE_HTML,
+    "https://x.com/dotey/article/2035141635713941927"
+  );
+
+  assert.ok(result);
+  assert.equal(result.conversionMethod, "parser:x-article");
+  assert.equal(result.metadata.title, "Karpathy：\"写代码\"已经不是对的动词了");
+  assert.equal(result.metadata.author, "宝玉 (@dotey)");
+  assert.equal(result.metadata.coverImage, "https://pbs.twimg.com/media/article-cover.jpg");
+  assert.equal(result.metadata.published, "2026-03-20T23:49:11.000Z");
+  assert.equal(result.metadata.language, "zh");
+  assert.ok(result.markdown.includes("## 要点速览"));
+  assert.ok(
+    result.markdown.includes(
+      "[![](https://pbs.twimg.com/media/article-inline.jpg)](/dotey/article/2035141635713941927/media/2)"
+    )
+  );
+  assert.ok(result.markdown.includes("写代码已经不是对的动词了。"));
+
+  const document = createMarkdownDocument(result);
+  assert.ok(document.includes("# Karpathy：\"写代码\"已经不是对的动词了"));
+});
+
+test("parses X status pages from HTML without duplicating the title heading", () => {
+  const result = parse(
+    STATUS_HTML,
+    "https://x.com/dotey/status/2035590649081196710"
+  );
+
+  assert.ok(result);
+  assert.equal(result.conversionMethod, "parser:x-status");
+  assert.equal(result.metadata.author, "宝玉 (@dotey)");
+  assert.equal(result.metadata.coverImage, "https://pbs.twimg.com/media/tweet-main.jpg");
+  assert.equal(result.metadata.language, "zh");
+  assert.ok(result.markdown.includes("转译：把下面这段加到你的 Codex 自定义指令里"));
+  assert.ok(result.markdown.includes("> Quote from Matt Shumer (@mattshumer_)"));
+  assert.ok(result.markdown.includes("!["));
+
+  const document = createMarkdownDocument(result);
+  assert.ok(
+    !document.includes("\n\n# 转译：把下面这段加到你的 Codex 自定义指令里，体验会好太多：\n\n")
+  );
 });
@@ -13,7 +13,7 @@ metadata:

 # YouTube Transcript

-Downloads transcripts (subtitles/captions) from YouTube videos. Works with both manually created and auto-generated transcripts. No API key or browser required — uses YouTube's InnerTube API directly.
+Downloads transcripts (subtitles/captions) from YouTube videos. Works with both manually created and auto-generated transcripts. No API key or browser required — uses YouTube's InnerTube API directly and automatically falls back to `yt-dlp` when YouTube blocks the direct API path.

 Fetches video metadata and cover image on first run, caches raw data for fast re-formatting.

@@ -75,6 +75,12 @@ ${BUN_X} {baseDir}/scripts/main.ts <url> --refresh
 | `-o, --output <path>` | Save to specific file path | auto-generated |
 | `--output-dir <dir>` | Base output directory | `youtube-transcript` |

+## Optional Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` | Passed to `yt-dlp --cookies-from-browser` during fallback, e.g. `chrome`, `safari`, `firefox`, or `chrome:Profile 1` |
+
 ## Input Formats

 Accepts any of these as video input:
@@ -121,6 +127,8 @@ On first fetch, the script saves:

 Subsequent runs for the same video use cached data (no network calls). Use `--refresh` to force re-fetch. If a different language is requested, the cache is automatically refreshed.

+When YouTube returns anti-bot / blocked responses on the direct InnerTube path, the script retries with alternate client identities and then falls back to `yt-dlp` if available. If fallback is needed but `yt-dlp` is unavailable, the agent should decide how to make `yt-dlp` available and continue rather than pushing the installation decision to the user.
+
 SRT output (`--format srt`) is generated from `transcript-raw.json`. Text/markdown output uses `transcript-sentences.json` for natural sentence boundaries.

 ## Workflow
@@ -175,3 +183,4 @@ When `--speakers` is used, `--chapters` is implied — the processed output alwa
 | Video unavailable | Video deleted, private, or region-locked |
 | IP blocked | Too many requests, try again later |
 | Age restricted | Video requires login for age verification |
+| bot detected | The script retries alternate clients and then `yt-dlp`; if fallback tooling is missing, the agent should resolve that itself, otherwise if it still fails try `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari` (or your browser) |
@@ -0,0 +1,125 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { findTranscript, parseTranscriptJson3, parseWebVtt } from "./transcript.ts";
+import { buildTranscriptListFromYtDlp, resolveVideoSource, selectYtDlpTrack } from "./youtube.ts";
+
+test("selectYtDlpTrack prefers json3 over xml and vtt", () => {
+  const track = selectYtDlpTrack([
+    { ext: "vtt", url: "https://example.com/subs.vtt" },
+    { ext: "srv3", url: "https://example.com/subs.srv3" },
+    { ext: "json3", url: "https://example.com/subs.json3" },
+  ]);
+
+  assert.equal(track?.ext, "json3");
+});
+
+test("buildTranscriptListFromYtDlp keeps manual and generated tracks separate", () => {
+  const transcripts = buildTranscriptListFromYtDlp({
+    subtitles: {
+      en: [
+        { ext: "json3", url: "https://example.com/en.json3", name: "English" },
+      ],
+    },
+    automatic_captions: {
+      "zh-Hans": [
+        { ext: "json3", url: "https://example.com/zh.json3", name: "Chinese (Simplified)" },
+      ],
+    },
+  });
+
+  assert.equal(transcripts.length, 2);
+  assert.equal(transcripts[0].isGenerated, false);
+  assert.equal(transcripts[1].isGenerated, true);
+  assert.equal(transcripts[0].translationLanguages[0]?.languageCode, "zh-Hans");
+
+  const translated = findTranscript(transcripts, ["zh-Hans"], false, false);
+  assert.equal(translated.languageCode, "zh-Hans");
+  assert.equal(translated.isGenerated, true);
+});
+
+test("parseTranscriptJson3 reads youtube timedtext json3 payloads", () => {
+  const snippets = parseTranscriptJson3(JSON.stringify({
+    events: [
+      {
+        tStartMs: 80,
+        dDurationMs: 3120,
+        segs: [{ utf8: "hello\nworld" }],
+      },
+      {
+        tStartMs: 4000,
+        dDurationMs: 1800,
+        segs: [{ utf8: "again" }],
+      },
+    ],
+  }));
+
+  assert.deepEqual(snippets, [
+    { text: "hello world", start: 0.08, duration: 3.12 },
+    { text: "again", start: 4, duration: 1.8 },
+  ]);
+});
+
+test("parseWebVtt strips tags and cue settings", () => {
+  const snippets = parseWebVtt(`WEBVTT
+
+00:00:00.080 --> 00:00:03.200 align:start position:0%
+<c.colorE5E5E5>Hello</c> world
+
+00:00:04.000 --> 00:00:05.800
+Again
+`);
+
+  assert.equal(snippets.length, 2);
+  assert.equal(snippets[0].text, "Hello world");
+  assert.equal(snippets[0].start, 0.08);
+  assert.equal(snippets[0].duration, 3.12);
+  assert.equal(snippets[1].text, "Again");
+  assert.equal(snippets[1].start, 4);
+  assert.equal(Number(snippets[1].duration.toFixed(1)), 1.8);
+});
+
+test("resolveVideoSource prefers primary InnerTube result before fallback", async () => {
+  let fallbackCalled = false;
+  const source = await resolveVideoSource(
+    "video12345ab",
+    async () => ({ kind: "innertube", data: { videoDetails: { title: "Primary" } }, transcripts: [] }),
+    () => {
+      fallbackCalled = true;
+      return {
+        subtitles: {
+          en: [{ ext: "json3", url: "https://example.com/en.json3", name: "English" }],
+        },
+      };
+    },
+    () => {}
+  );
+
+  assert.equal(source.kind, "innertube");
+  assert.equal(fallbackCalled, false);
+});
+
+test("resolveVideoSource falls back to yt-dlp only after fallback-eligible errors", async () => {
+  let fallbackCalled = false;
+  const source = await resolveVideoSource(
+    "video12345ab",
+    async () => {
+      const error = new Error("Request blocked for video12345ab: bot detected");
+      (error as Error & { code?: string }).code = "BOT_DETECTED";
+      throw error;
+    },
+    () => {
+      fallbackCalled = true;
+      return {
+        automatic_captions: {
+          en: [{ ext: "json3", url: "https://example.com/en.json3", name: "English (auto-generated)" }],
+        },
+      };
+    },
+    () => {}
+  );
+
+  assert.equal(source.kind, "yt-dlp");
+  assert.equal(fallbackCalled, true);
+  assert.equal(source.transcripts[0].languageCode, "en");
+});
@@ -1,659 +1,55 @@
 #!/usr/bin/env bun
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
-
-type Format = "text" | "srt";
-
-interface Options {
-  videoIds: string[];
-  languages: string[];
-  format: Format;
-  translate: string;
-  list: boolean;
-  excludeGenerated: boolean;
-  excludeManual: boolean;
-  output: string;
-  outputDir: string;
-  timestamps: boolean;
-  chapters: boolean;
-  speakers: boolean;
-  refresh: boolean;
-}
-
-interface Snippet {
-  text: string;
-  start: number;
-  duration: number;
-}
-
-interface Sentence {
-  text: string;
-  start: string;
-  end: string;
-}
-
-interface TranscriptInfo {
-  language: string;
-  languageCode: string;
-  isGenerated: boolean;
-  isTranslatable: boolean;
-  baseUrl: string;
-  translationLanguages: { language: string; languageCode: string }[];
-}
-
-interface Chapter {
-  title: string;
-  start: number;
-  end: number;
-}
-
-interface VideoMeta {
-  videoId: string;
-  title: string;
-  channel: string;
-  channelId: string;
-  description: string;
-  duration: number;
-  publishDate: string;
-  url: string;
-  coverImage: string;
-  thumbnailUrl: string;
-  language: { code: string; name: string; isGenerated: boolean };
-  chapters: Chapter[];
-}
-
-interface VideoResult {
-  videoId: string;
-  title?: string;
-  filePath?: string;
-  content?: string;
-  error?: string;
-}
-
-const WATCH_URL = "https://www.youtube.com/watch?v=";
-const INNERTUBE_URL = "https://www.youtube.com/youtubei/v1/player";
-const INNERTUBE_CTX = { client: { clientName: "ANDROID", clientVersion: "20.10.38" } };
-
-function extractVideoId(input: string): string {
-  input = input.replace(/\\/g, "").trim();
-  const patterns = [
-    /(?:youtube\.com\/watch\?.*v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/v\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/,
-    /^([a-zA-Z0-9_-]{11})$/,
-  ];
-  for (const p of patterns) {
-    const m = input.match(p);
-    if (m) return m[1];
-  }
-  return input;
-}
-
-function slugify(s: string): string {
-  return s
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "") || "untitled";
-}
-
-function htmlUnescape(s: string): string {
-  return s
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&#x27;/g, "'")
-    .replace(/&#x2F;/g, "/")
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)));
-}
-
-function stripTags(s: string): string {
-  return s.replace(/<[^>]*>/g, "");
-}
-
-function parseTranscriptXml(xml: string): Snippet[] {
-  const snippets: Snippet[] = [];
-  const re = /<text\s+start="([^"]*)"(?:\s+dur="([^"]*)")?[^>]*>([\s\S]*?)<\/text>/g;
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(xml)) !== null) {
-    const raw = m[3];
-    if (!raw) continue;
-    snippets.push({
-      text: htmlUnescape(stripTags(raw)),
-      start: parseFloat(m[1]),
-      duration: parseFloat(m[2] || "0"),
-    });
-  }
-  return snippets;
-}
-
-// --- YouTube API ---
-
-async function fetchHtml(videoId: string): Promise<string> {
-  const r = await fetch(WATCH_URL + videoId, {
-    headers: { "Accept-Language": "en-US", "User-Agent": "Mozilla/5.0" },
-  });
-  if (!r.ok) throw new Error(`HTTP ${r.status} fetching video page`);
-  let html = await r.text();
-  if (html.includes('action="https://consent.youtube.com/s"')) {
-    const cv = html.match(/name="v" value="(.*?)"/);
-    if (!cv) throw new Error("Failed to create consent cookie");
-    const r2 = await fetch(WATCH_URL + videoId, {
-      headers: {
-        "Accept-Language": "en-US",
-        "User-Agent": "Mozilla/5.0",
-        Cookie: `CONSENT=YES+${cv[1]}`,
-      },
-    });
-    if (!r2.ok) throw new Error(`HTTP ${r2.status} fetching video page (consent)`);
-    html = await r2.text();
-  }
-  return html;
-}
-
-function extractApiKey(html: string, videoId: string): string {
-  const m = html.match(/"INNERTUBE_API_KEY":\s*"([a-zA-Z0-9_-]+)"/);
-  if (!m) {
-    if (html.includes('class="g-recaptcha"')) throw new Error(`IP blocked for ${videoId} (reCAPTCHA)`);
-    throw new Error(`Cannot extract API key for ${videoId}`);
-  }
-  return m[1];
-}
-
-async function fetchInnertubeData(videoId: string, apiKey: string): Promise<any> {
-  const r = await fetch(`${INNERTUBE_URL}?key=${apiKey}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ context: INNERTUBE_CTX, videoId }),
-  });
-  if (r.status === 429) throw new Error(`IP blocked for ${videoId} (429)`);
-  if (!r.ok) throw new Error(`HTTP ${r.status} from InnerTube API`);
-  return r.json();
-}
-
-function assertPlayability(data: any, videoId: string) {
-  const ps = data?.playabilityStatus;
-  if (!ps) return;
-  const status = ps.status;
-  if (status === "OK" || !status) return;
-  const reason = ps.reason || "";
-  if (status === "LOGIN_REQUIRED") {
-    if (reason.includes("bot")) throw new Error(`Request blocked for ${videoId}: bot detected`);
-    if (reason.includes("inappropriate")) throw new Error(`Age restricted: ${videoId}`);
-  }
-  if (status === "ERROR" && reason.includes("unavailable")) {
-    if (videoId.startsWith("http")) throw new Error(`Invalid video ID: pass the ID, not the URL`);
-    throw new Error(`Video unavailable: ${videoId}`);
-  }
-  const subreasons = ps.errorScreen?.playerErrorMessageRenderer?.subreason?.runs?.map((r: any) => r.text).join("") || "";
-  throw new Error(`Video unplayable (${videoId}): ${reason} ${subreasons}`.trim());
-}
-
-function extractCaptionsJson(data: any, videoId: string): any {
-  assertPlayability(data, videoId);
-  const cj = data?.captions?.playerCaptionsTracklistRenderer;
-  if (!cj || !cj.captionTracks) throw new Error(`Transcripts disabled for ${videoId}`);
-  return cj;
-}
-
-function buildTranscriptList(captionsJson: any): TranscriptInfo[] {
-  const tlLangs = (captionsJson.translationLanguages || []).map((tl: any) => ({
-    language: tl.languageName?.runs?.[0]?.text || tl.languageName?.simpleText || "",
-    languageCode: tl.languageCode,
-  }));
-  return (captionsJson.captionTracks || []).map((t: any) => ({
-    language: t.name?.runs?.[0]?.text || t.name?.simpleText || "",
-    languageCode: t.languageCode,
-    isGenerated: t.kind === "asr",
-    isTranslatable: !!t.isTranslatable,
-    baseUrl: (t.baseUrl || "").replace(/&fmt=srv3/g, ""),
-    translationLanguages: t.isTranslatable ? tlLangs : [],
-  }));
-}
-
-function findTranscript(
-  transcripts: TranscriptInfo[],
-  languages: string[],
-  excludeGenerated: boolean,
-  excludeManual: boolean
-): TranscriptInfo {
-  let filtered = transcripts;
-  if (excludeGenerated) filtered = filtered.filter((t) => !t.isGenerated);
-  if (excludeManual) filtered = filtered.filter((t) => t.isGenerated);
-  for (const lang of languages) {
-    const found = filtered.find((t) => t.languageCode === lang);
-    if (found) return found;
-  }
-  const available = filtered.map((t) => `${t.languageCode} ("${t.language}")`).join(", ");
-  throw new Error(`No transcript found for languages [${languages.join(", ")}]. Available: ${available || "none"}`);
-}
-
-async function fetchTranscriptSnippets(info: TranscriptInfo, translateTo?: string): Promise<{ snippets: Snippet[]; language: string; languageCode: string }> {
-  let url = info.baseUrl;
-  let lang = info.language;
-  let langCode = info.languageCode;
-  if (translateTo) {
-    if (!info.isTranslatable) throw new Error(`Transcript ${info.languageCode} is not translatable`);
-    const tl = info.translationLanguages.find((t) => t.languageCode === translateTo);
-    if (!tl) throw new Error(`Translation language ${translateTo} not available`);
-    url += `&tlang=${translateTo}`;
-    lang = tl.language;
-    langCode = translateTo;
-  }
-  const r = await fetch(url, { headers: { "Accept-Language": "en-US" } });
-  if (!r.ok) throw new Error(`HTTP ${r.status} fetching transcript`);
-  return { snippets: parseTranscriptXml(await r.text()), language: lang, languageCode: langCode };
-}
-
-// --- Metadata & chapters ---
-
-function parseChapters(description: string, duration: number = 0): Chapter[] {
-  const raw: { title: string; start: number }[] = [];
-  for (const line of description.split("\n")) {
-    const m = line.trim().match(/^(?:(\d{1,2}):)?(\d{1,2}):(\d{2})\s+(.+)$/);
-    if (m) {
-      const h = m[1] ? parseInt(m[1]) : 0;
-      raw.push({ title: m[4].trim(), start: h * 3600 + parseInt(m[2]) * 60 + parseInt(m[3]) });
-    }
-  }
-  if (raw.length < 2) return [];
-  return raw.map((ch, i) => ({
-    title: ch.title,
-    start: ch.start,
-    end: i < raw.length - 1 ? raw[i + 1].start : Math.max(duration, ch.start),
-  }));
-}
-
-function getThumbnailUrls(videoId: string, data: any): string[] {
-  const urls = [
-    `https://i.ytimg.com/vi/${videoId}/maxresdefault.jpg`,
-    `https://i.ytimg.com/vi/${videoId}/hqdefault.jpg`,
-  ];
-  const thumbnails = data?.videoDetails?.thumbnail?.thumbnails ||
-    data?.microformat?.playerMicroformatRenderer?.thumbnail?.thumbnails || [];
-  if (thumbnails.length) {
-    const sorted = [...thumbnails].sort((a: any, b: any) => (b.width || 0) - (a.width || 0));
-    for (const t of sorted) if (t.url && !urls.includes(t.url)) urls.push(t.url);
-  }
-  return urls;
-}
-
-function buildVideoMeta(data: any, videoId: string, langInfo: { code: string; name: string; isGenerated: boolean }, chapters: Chapter[]): VideoMeta {
-  const vd = data?.videoDetails || {};
-  const mf = data?.microformat?.playerMicroformatRenderer || {};
-  return {
-    videoId,
-    title: vd.title || mf.title?.simpleText || "",
-    channel: vd.author || mf.ownerChannelName || "",
-    channelId: vd.channelId || mf.externalChannelId || "",
-    description: vd.shortDescription || mf.description?.simpleText || "",
-    duration: parseInt(vd.lengthSeconds || "0"),
-    publishDate: mf.publishDate || mf.uploadDate || "",
-    url: `https://www.youtube.com/watch?v=${videoId}`,
-    coverImage: "",
-    thumbnailUrl: getThumbnailUrls(videoId, data)[0],
-    language: langInfo,
-    chapters,
-  };
-}
-
-async function downloadCoverImage(urls: string[], outputPath: string): Promise<boolean> {
-  for (const u of urls) {
-    try {
-      const r = await fetch(u);
-      if (r.ok) {
-        writeFileSync(outputPath, Buffer.from(await r.arrayBuffer()));
-        return true;
-      }
-    } catch {}
-  }
-  return false;
-}
-
-function parseSrt(srt: string): Snippet[] {
-  const blocks = srt.trim().split(/\n\n+/);
-  const snippets: Snippet[] = [];
-  for (const block of blocks) {
-    const lines = block.split("\n");
-    if (lines.length < 3) continue;
-    const m = lines[1].match(/(\d{2}):(\d{2}):(\d{2}),(\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2}),(\d{3})/);
-    if (!m) continue;
-    const start = parseInt(m[1]) * 3600 + parseInt(m[2]) * 60 + parseInt(m[3]) + parseInt(m[4]) / 1000;
-    const end = parseInt(m[5]) * 3600 + parseInt(m[6]) * 60 + parseInt(m[7]) + parseInt(m[8]) / 1000;
-    snippets.push({ text: lines.slice(2).join(" "), start, duration: end - start });
-  }
-  return snippets;
-}
-
-// --- Timestamp formatting ---
-
-function ts(t: number): string {
-  const h = Math.floor(t / 3600);
-  const m = Math.floor((t % 3600) / 60);
-  const s = Math.floor(t % 60);
-  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
-}
-
-function tsMs(t: number, sep: string): string {
-  const h = Math.floor(t / 3600);
-  const m = Math.floor((t % 3600) / 60);
-  const s = Math.floor(t % 60);
-  const ms = Math.round((t - Math.floor(t)) * 1000);
-  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}${sep}${String(ms).padStart(3, "0")}`;
-}
-
-// --- Paragraph grouping ---
-
-interface Paragraph {
-  text: string;
-  start: number;
-  end: number;
-}
-
-function groupIntoParagraphs(snippets: Snippet[]): Paragraph[] {
-  if (!snippets.length) return [];
-  const paras: Paragraph[] = [];
-  let buf: Snippet[] = [];
-  for (let i = 0; i < snippets.length; i++) {
-    buf.push(snippets[i]);
-    const last = i === snippets.length - 1;
-    const gap = !last && snippets[i + 1].start - (snippets[i].start + snippets[i].duration) > 1.5;
-    if (last || gap || buf.length >= 8) {
-      const lastS = buf[buf.length - 1];
-      paras.push({ text: buf.map(s => s.text).join(" "), start: buf[0].start, end: lastS.start + lastS.duration });
-      buf = [];
-    }
-  }
-  return paras;
-}
-
-// --- Sentence segmentation ---
-
-const SENTENCE_END_RE = /[.?!…。？！⁈⁇‼‽．]/;
-
-function isCJK(ch: string): boolean {
-  const code = ch.charCodeAt(0);
-  return (code >= 0x4E00 && code <= 0x9FFF) ||
-    (code >= 0x3040 && code <= 0x309F) ||
-    (code >= 0x30A0 && code <= 0x30FF) ||
-    (code >= 0xAC00 && code <= 0xD7AF) ||
-    (code >= 0x3400 && code <= 0x4DBF) ||
-    (code >= 0xF900 && code <= 0xFAFF);
-}
-
-function splitSnippetAtPunctuation(s: Snippet): { text: string; start: number; end: number }[] {
-  const { text, start, duration } = s;
-  const end = start + duration;
-  if (!text.length) return [];
-
-  const splitPoints: number[] = [];
-  for (let i = 0; i < text.length; i++) {
-    if (SENTENCE_END_RE.test(text[i])) {
-      while (i + 1 < text.length && SENTENCE_END_RE.test(text[i + 1])) i++;
-      if (i < text.length - 1) splitPoints.push(i);
-    }
-  }
-
-  if (!splitPoints.length) return [{ text, start, end }];
-
-  const parts: { text: string; start: number; end: number }[] = [];
-  let prev = 0;
-  for (const pos of splitPoints) {
-    const partText = text.slice(prev, pos + 1).trim();
-    if (partText) {
-      parts.push({
-        text: partText,
-        start: start + (prev / text.length) * duration,
-        end: start + ((pos + 1) / text.length) * duration,
-      });
-    }
-    prev = pos + 1;
-  }
-
-  const remaining = text.slice(prev).trim();
-  if (remaining) {
-    parts.push({ text: remaining, start: start + (prev / text.length) * duration, end });
-  }
-
-  return parts;
-}
-
-function mergeTexts(texts: string[]): string {
-  if (!texts.length) return "";
-  let result = texts[0];
-  for (let i = 1; i < texts.length; i++) {
-    const next = texts[i];
-    if (!next) continue;
-    const lastChar = result[result.length - 1];
-    const firstChar = next[0];
-    if (isCJK(lastChar) || isCJK(firstChar)) {
-      result += next;
-    } else {
-      result = result.trimEnd() + " " + next.trimStart();
-    }
-  }
-  return result.replace(/ {2,}/g, " ");
-}
-
-function segmentIntoSentences(snippets: Snippet[]): Sentence[] {
-  const parts: { text: string; start: number; end: number }[] = [];
-  for (const s of snippets) parts.push(...splitSnippetAtPunctuation(s));
-
-  const sentences: Sentence[] = [];
-  let buf: { text: string; start: number; end: number }[] = [];
-
-  for (const part of parts) {
-    buf.push(part);
-    if (SENTENCE_END_RE.test(part.text[part.text.length - 1])) {
-      sentences.push({
-        text: mergeTexts(buf.map(b => b.text)),
-        start: ts(buf[0].start),
-        end: ts(buf[buf.length - 1].end),
-      });
-      buf = [];
-    }
-  }
-
-  if (buf.length) {
-    sentences.push({
-      text: mergeTexts(buf.map(b => b.text)),
-      start: ts(buf[0].start),
-      end: ts(buf[buf.length - 1].end),
-    });
-  }
-
-  return sentences;
-}
-
-function parseTs(t: string): number {
-  const [h, m, s] = t.split(":").map(Number);
-  return h * 3600 + m * 60 + s;
-}
-
-function groupSentenceParas(sentences: Sentence[]): Paragraph[] {
-  if (!sentences.length) return [];
-  const paras: Paragraph[] = [];
-  let buf: Sentence[] = [];
-  for (let i = 0; i < sentences.length; i++) {
-    buf.push(sentences[i]);
-    const last = i === sentences.length - 1;
-    const gap = !last && parseTs(sentences[i + 1].start) - parseTs(sentences[i].end) > 2;
-    if (last || gap || buf.length >= 5) {
-      paras.push({
-        text: mergeTexts(buf.map(s => s.text)),
-        start: parseTs(buf[0].start),
-        end: parseTs(buf[buf.length - 1].end),
-      });
-      buf = [];
-    }
-  }
-  return paras;
-}
-
-// --- Format functions ---
-
-function formatSrt(snippets: Snippet[]): string {
-  return snippets
-    .map((s, i) => {
-      const end = i < snippets.length - 1 && snippets[i + 1].start < s.start + s.duration
-        ? snippets[i + 1].start
-        : s.start + s.duration;
-      return `${i + 1}\n${tsMs(s.start, ",")} --> ${tsMs(end, ",")}\n${s.text}`;
-    })
-    .join("\n\n") + "\n";
-}
-
-function yamlEscape(s: string): string {
-  if (/[:"'{}\[\]#&*!|>%@`\n]/.test(s) || s.trim() !== s) return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-  return s;
-}
-
-function extractSummary(description: string): string {
-  if (!description) return "";
-  const firstPara = description.split(/\n\s*\n/)[0].trim();
-  const lines = firstPara.split("\n").filter(l => !/^\s*(https?:\/\/|#|@|\d+:\d+)/.test(l) && l.trim());
-  return lines.join(" ").slice(0, 300).trim();
-}
-
-function formatMarkdown(sentences: Sentence[], meta: VideoMeta, opts: { timestamps: boolean; chapters: boolean; speakers: boolean }, snippets?: Snippet[]): string {
-  const summary = extractSummary(meta.description);
-  let md = "---\n";
-  md += `title: ${yamlEscape(meta.title)}\n`;
-  md += `channel: ${yamlEscape(meta.channel)}\n`;
-  if (meta.publishDate) md += `date: ${meta.publishDate}\n`;
-  md += `url: ${yamlEscape(meta.url)}\n`;
-  if (meta.coverImage) md += `cover: ${meta.coverImage}\n`;
-  if (summary) md += `description: ${yamlEscape(summary)}\n`;
-  if (meta.language) md += `language: ${meta.language.code}\n`;
-  md += "---\n\n";
-
-  if (opts.speakers) {
-    md += `# ${meta.title}\n\n`;
-    if (summary) md += `${summary}\n\n`;
-    if (meta.description) md += "# Description\n\n" + meta.description.trim() + "\n\n";
-    if (meta.chapters.length) {
-      md += "# Chapters\n\n";
-      for (const ch of meta.chapters) md += `* [${ts(ch.start)}] ${ch.title}\n`;
-      md += "\n";
-    }
-    md += "# Transcript\n\n";
-    md += snippets ? formatSrt(snippets) : "";
-    return md;
-  }
-
-  md += `# ${meta.title}\n\n`;
-  if (summary) md += `${summary}\n\n`;
-
-  const chapters = opts.chapters ? meta.chapters : [];
-
-  if (chapters.length) {
-    md += "## Table of Contents\n\n";
-    for (const ch of chapters) md += opts.timestamps ? `* [${ts(ch.start)}] ${ch.title}\n` : `* ${ch.title}\n`;
-    md += "\n";
-    if (meta.coverImage) md += `\n![cover](${meta.coverImage})\n`;
-    md += "\n";
-    for (let i = 0; i < chapters.length; i++) {
-      const nextStart = i < chapters.length - 1 ? chapters[i + 1].start : Infinity;
-      const chSentences = sentences.filter(s => parseTs(s.start) >= chapters[i].start && parseTs(s.start) < nextStart);
-      const paras = groupSentenceParas(chSentences);
-      md += opts.timestamps
-        ? `## [${ts(chapters[i].start)}] ${chapters[i].title}\n\n`
-        : `## ${chapters[i].title}\n\n`;
-      for (const p of paras) md += opts.timestamps ? `${p.text} [${ts(p.start)} → ${ts(p.end)}]\n\n` : `${p.text}\n\n`;
-      md += "\n";
-    }
-  } else {
-    const paras = groupSentenceParas(sentences);
-    for (const p of paras) md += opts.timestamps ? `${p.text} [${ts(p.start)} → ${ts(p.end)}]\n\n` : `${p.text}\n\n`;
-  }
-
-  return md.trimEnd() + "\n";
-}
-
-function formatListOutput(videoId: string, title: string, transcripts: TranscriptInfo[]): string {
-  const manual = transcripts.filter((t) => !t.isGenerated);
-  const generated = transcripts.filter((t) => t.isGenerated);
-  const tlLangs = transcripts.find((t) => t.translationLanguages.length > 0)?.translationLanguages || [];
-  const fmtList = (list: TranscriptInfo[]) =>
-    list.length ? list.map((t) => ` - ${t.languageCode} ("${t.language}")${t.isTranslatable ? " [TRANSLATABLE]" : ""}`).join("\n") : "None";
-  const fmtTl = tlLangs.length
-    ? tlLangs.map((t) => ` - ${t.languageCode} ("${t.language}")`).join("\n")
-    : "None";
-  return `Transcripts for ${videoId}${title ? ` (${title})` : ""}:\n\n(MANUALLY CREATED)\n${fmtList(manual)}\n\n(GENERATED)\n${fmtList(generated)}\n\n(TRANSLATION LANGUAGES)\n${fmtTl}`;
-}
-
-// --- File helpers ---
-
-function ensureDir(p: string) {
-  const dir = dirname(p);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-}
-
-function resolveBaseDir(outputDir: string): string {
-  return resolve(outputDir || "youtube-transcript");
-}
-
-function loadIndex(baseDir: string): Record<string, string> {
-  try { return JSON.parse(readFileSync(join(baseDir, ".index.json"), "utf-8")); } catch { return {}; }
-}
-
-function saveIndex(baseDir: string, index: Record<string, string>) {
-  const p = join(baseDir, ".index.json");
-  ensureDir(p);
-  writeFileSync(p, JSON.stringify(index, null, 2));
-}
-
-function lookupVideoDir(videoId: string, baseDir: string): string | null {
-  const rel = loadIndex(baseDir)[videoId];
-  if (rel) {
-    const dir = resolve(baseDir, rel);
-    if (existsSync(dir)) return dir;
-  }
-  return null;
-}
-
-function registerVideoDir(videoId: string, channelSlug: string, titleSlug: string, baseDir: string): string {
-  const rel = join(channelSlug, titleSlug);
-  const index = loadIndex(baseDir);
-  index[videoId] = rel;
-  saveIndex(baseDir, index);
-  return resolve(baseDir, rel);
-}
-
-function hasCachedData(videoDir: string): boolean {
-  return existsSync(join(videoDir, "meta.json")) && existsSync(join(videoDir, "transcript-raw.json"));
-}
-
-function loadMeta(videoDir: string): VideoMeta {
-  return JSON.parse(readFileSync(join(videoDir, "meta.json"), "utf-8"));
-}
-
-function loadSnippets(videoDir: string): Snippet[] {
-  return JSON.parse(readFileSync(join(videoDir, "transcript-raw.json"), "utf-8"));
-}
-
-function loadSentences(videoDir: string): Sentence[] {
-  return JSON.parse(readFileSync(join(videoDir, "transcript-sentences.json"), "utf-8"));
-}
-
-// --- Main processing ---
-
-async function fetchAndCache(videoId: string, baseDir: string, opts: Options): Promise<{ meta: VideoMeta; snippets: Snippet[]; sentences: Sentence[]; videoDir: string }> {
-  const html = await fetchHtml(videoId);
-  const apiKey = extractApiKey(html, videoId);
-  const data = await fetchInnertubeData(videoId, apiKey);
-  const captionsJson = extractCaptionsJson(data, videoId);
-  const transcripts = buildTranscriptList(captionsJson);
-  const info = findTranscript(transcripts, opts.languages, opts.excludeGenerated, opts.excludeManual);
-  const result = await fetchTranscriptSnippets(info, opts.translate || undefined);
-  const description = data?.videoDetails?.shortDescription || "";
-  const duration = parseInt(data?.videoDetails?.lengthSeconds || "0");
+import { writeFileSync } from "fs";
+import { join, resolve } from "path";
+
+import { extractVideoId, slugify } from "./shared.ts";
+import {
+  ensureDir,
+  hasCachedData,
+  loadMeta,
+  loadSentences,
+  loadSnippets,
+  lookupVideoDir,
+  registerVideoDir,
+  resolveBaseDir,
+} from "./storage.ts";
+import { findTranscript, formatListOutput, formatMarkdown, formatSrt, segmentIntoSentences } from "./transcript.ts";
+import type { Options, Sentence, Snippet, VideoMeta, VideoResult } from "./types.ts";
+import {
+  buildVideoMeta,
+  buildVideoMetaFromYtDlp,
+  downloadCoverImage,
+  fetchTranscriptSnippets,
+  fetchVideoSource,
+  getThumbnailUrls,
+  getYtDlpThumbnailUrls,
+  parseChapters,
+} from "./youtube.ts";
+
+async function fetchAndCache(
+  videoId: string,
+  baseDir: string,
+  opts: Options
+): Promise<{ meta: VideoMeta; snippets: Snippet[]; sentences: Sentence[]; videoDir: string }> {
+  const source = await fetchVideoSource(videoId);
+  const requestedLanguages = source.kind === "yt-dlp" && opts.translate ? [opts.translate] : opts.languages;
+  const transcript = findTranscript(source.transcripts, requestedLanguages, opts.excludeGenerated, opts.excludeManual);
+  const result = await fetchTranscriptSnippets(transcript, source.kind === "yt-dlp" ? undefined : opts.translate || undefined);
+  const description = source.kind === "yt-dlp"
+    ? source.info.description || ""
+    : source.data?.videoDetails?.shortDescription || "";
+  const duration = source.kind === "yt-dlp"
+    ? Number(source.info.duration || 0)
+    : parseInt(source.data?.videoDetails?.lengthSeconds || "0");
  const chapters = parseChapters(description, duration);
-  const langInfo = { code: result.languageCode, name: result.language, isGenerated: info.isGenerated };
-  const meta = buildVideoMeta(data, videoId, langInfo, chapters);
+  const language = {
+    code: result.languageCode,
+    name: result.language,
+    isGenerated: transcript.isGenerated,
+  };
+  const meta = source.kind === "yt-dlp"
+    ? buildVideoMetaFromYtDlp(source.info, videoId, language, chapters)
+    : buildVideoMeta(source.data, videoId, language, chapters);

  const videoDir = registerVideoDir(videoId, slugify(meta.channel), slugify(meta.title), baseDir);
  ensureDir(join(videoDir, "meta.json"));
@@ -663,9 +59,12 @@ async function fetchAndCache(videoId: string, baseDir: string, opts: Options): P
  const sentences = segmentIntoSentences(result.snippets);
  writeFileSync(join(videoDir, "transcript-sentences.json"), JSON.stringify(sentences, null, 2));

-  const imgPath = join(videoDir, "imgs", "cover.jpg");
-  ensureDir(imgPath);
-  const downloaded = await downloadCoverImage(getThumbnailUrls(videoId, data), imgPath);
+  const imagePath = join(videoDir, "imgs", "cover.jpg");
+  ensureDir(imagePath);
+  const downloaded = await downloadCoverImage(
+    source.kind === "yt-dlp" ? getYtDlpThumbnailUrls(videoId, source.info) : getThumbnailUrls(videoId, source.data),
+    imagePath
+  );
  meta.coverImage = downloaded ? "imgs/cover.jpg" : "";

  writeFileSync(join(videoDir, "meta.json"), JSON.stringify(meta, null, 2));
@@ -676,15 +75,10 @@ async function fetchAndCache(videoId: string, baseDir: string, opts: Options): P
 async function processVideo(videoId: string, opts: Options): Promise<VideoResult> {
  const baseDir = resolveBaseDir(opts.outputDir);

-  // --list: always fetch fresh
  if (opts.list) {
-    const html = await fetchHtml(videoId);
-    const apiKey = extractApiKey(html, videoId);
-    const data = await fetchInnertubeData(videoId, apiKey);
-    const title = data?.videoDetails?.title || "";
-    const captionsJson = extractCaptionsJson(data, videoId);
-    const transcripts = buildTranscriptList(captionsJson);
-    return { videoId, title, content: formatListOutput(videoId, title, transcripts) };
+    const source = await fetchVideoSource(videoId);
+    const title = source.kind === "yt-dlp" ? source.info.title || "" : source.data?.videoDetails?.title || "";
+    return { videoId, title, content: formatListOutput(videoId, title, source.transcripts) };
  }

  let videoDir = lookupVideoDir(videoId, baseDir);
@@ -697,16 +91,17 @@ async function processVideo(videoId: string, opts: Options): Promise<VideoResult
    meta = loadMeta(videoDir);
    snippets = loadSnippets(videoDir);
    sentences = loadSentences(videoDir);
-    const wantLangs = opts.translate ? [opts.translate] : opts.languages;
-    if (!wantLangs.includes(meta.language.code)) needsFetch = true;
-    // Backfill chapter end times for caches created before this field existed
-    if (!needsFetch && meta.chapters.length > 0 && meta.chapters.some((ch: any) => ch.end === undefined)) {
+    const wantedLanguages = opts.translate ? [opts.translate] : opts.languages;
+    if (!wantedLanguages.includes(meta.language.code)) needsFetch = true;
+    if (!needsFetch && meta.chapters.length > 0 && meta.chapters.some((chapter: any) => chapter.end === undefined)) {
      for (let i = 0; i < meta.chapters.length; i++) {
        meta.chapters[i].end = i < meta.chapters.length - 1
          ? meta.chapters[i + 1].start
          : Math.max(meta.duration, meta.chapters[i].start);
      }
-      try { writeFileSync(join(videoDir, "meta.json"), JSON.stringify(meta, null, 2)); } catch {}
+      try {
+        writeFileSync(join(videoDir, "meta.json"), JSON.stringify(meta, null, 2));
+      } catch {}
    }
  }

@@ -722,21 +117,19 @@ async function processVideo(videoId: string, opts: Options): Promise<VideoResult
    sentences = sentences!;
  }

-  let content: string;
-  let ext: string;
-
-  if (opts.format === "srt") {
-    content = formatSrt(snippets);
-    ext = "srt";
-  } else {
-    content = formatMarkdown(sentences, meta, {
-      timestamps: opts.timestamps,
-      chapters: opts.chapters,
-      speakers: opts.speakers,
-    }, snippets);
-    ext = "md";
-  }
-
+  const content = opts.format === "srt"
+    ? formatSrt(snippets)
+    : formatMarkdown(
+      sentences,
+      meta,
+      {
+        timestamps: opts.timestamps,
+        chapters: opts.chapters,
+        speakers: opts.speakers,
+      },
+      snippets
+    );
+  const ext = opts.format === "srt" ? "srt" : "md";
  const filePath = opts.output ? resolve(opts.output) : join(videoDir!, `transcript.${ext}`);
  ensureDir(filePath);
  writeFileSync(filePath, content);
@@ -744,8 +137,6 @@ async function processVideo(videoId: string, opts: Options): Promise<VideoResult
  return { videoId, title: meta.title, filePath };
 }

-// --- CLI ---
-
 function printHelp() {
  console.log(`Usage: bun main.ts <video-url-or-id> [options]

@@ -789,13 +180,13 @@ function parseArgs(argv: string[]): Options | null {
      printHelp();
      process.exit(0);
    } else if (arg === "--languages") {
-      const v = argv[++i];
-      if (v) opts.languages = v.split(",").map((s) => s.trim());
+      const value = argv[++i];
+      if (value) opts.languages = value.split(",").map((entry) => entry.trim());
    } else if (arg === "--format") {
-      const v = argv[++i]?.toLowerCase();
-      if (v === "text" || v === "srt") opts.format = v;
+      const value = argv[++i]?.toLowerCase();
+      if (value === "text" || value === "srt") opts.format = value;
      else {
-        console.error(`Invalid format: ${v}. Use: text, srt`);
+        console.error(`Invalid format: ${value}. Use: text, srt`);
        return null;
      }
    } else if (arg === "--translate") {
@@ -830,6 +221,7 @@ function parseArgs(argv: string[]): Options | null {
    printHelp();
    return null;
  }
+
  return opts;
 }

@@ -844,14 +236,16 @@ async function main() {

  for (const videoId of opts.videoIds) {
    try {
-      const r = await processVideo(videoId, opts);
-      if (r.error) console.error(`Error (${r.videoId}): ${r.error}`);
-      else if (r.filePath) console.log(r.filePath);
-      else if (r.content) console.log(r.content);
-    } catch (e) {
-      console.error(`Error (${videoId}): ${(e as Error).message}`);
+      const result = await processVideo(videoId, opts);
+      if (result.error) console.error(`Error (${result.videoId}): ${result.error}`);
+      else if (result.filePath) console.log(result.filePath);
+      else if (result.content) console.log(result.content);
+    } catch (error) {
+      console.error(`Error (${videoId}): ${(error as Error).message}`);
    }
  }
 }

-main();
+if (import.meta.main) {
+  main();
+}
@@ -0,0 +1,83 @@
+import type { TranscriptError } from "./types.ts";
+
+export function extractVideoId(input: string): string {
+  input = input.replace(/\\/g, "").trim();
+  const patterns = [
+    /(?:youtube\.com\/watch\?.*v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/v\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/,
+    /^([a-zA-Z0-9_-]{11})$/,
+  ];
+  for (const pattern of patterns) {
+    const match = input.match(pattern);
+    if (match) return match[1];
+  }
+  return input;
+}
+
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "untitled";
+}
+
+export function htmlUnescape(value: string): string {
+  return value
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&#x2F;/g, "/")
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n)))
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)));
+}
+
+export function stripTags(value: string): string {
+  return value.replace(/<[^>]*>/g, "");
+}
+
+export function makeError(message: string, code?: string): Error {
+  const error = new Error(message) as TranscriptError;
+  if (code) error.code = code;
+  return error;
+}
+
+export function normalizeError(error: unknown): TranscriptError {
+  if (error instanceof Error) {
+    const known = error as TranscriptError;
+    if (known.code) return known;
+    const message = known.message || String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes("bot detected")) known.code = "BOT_DETECTED";
+    else if (lower.includes("age restricted")) known.code = "AGE_RESTRICTED";
+    else if (lower.includes("video unavailable")) known.code = "VIDEO_UNAVAILABLE";
+    else if (lower.includes("transcripts disabled")) known.code = "TRANSCRIPTS_DISABLED";
+    else if (lower.includes("no transcript found")) known.code = "NO_TRANSCRIPT";
+    else if (lower.includes("invalid video id")) known.code = "INVALID_VIDEO_ID";
+    else if (lower.includes("ip blocked") || lower.includes("recaptcha") || lower.includes("http 429")) known.code = "IP_BLOCKED";
+    else if (lower.includes("cannot extract api key")) known.code = "PAGE_FETCH_FAILED";
+    else if (lower.includes("innertube api") || lower.includes("http 403")) known.code = "INNERTUBE_REJECTED";
+    else if (lower.includes("yt-dlp fallback failed")) known.code = "YT_DLP_FAILED";
+    return known;
+  }
+  return makeError(String(error), "UNKNOWN") as TranscriptError;
+}
+
+export function shouldTryAlternateClient(error: unknown): boolean {
+  const code = normalizeError(error).code;
+  return code === "BOT_DETECTED" || code === "IP_BLOCKED" || code === "INNERTUBE_REJECTED" || code === "AGE_RESTRICTED" || code === "VIDEO_UNAVAILABLE";
+}
+
+export function shouldTryYtDlpFallback(error: unknown): boolean {
+  const code = normalizeError(error).code;
+  return code === "BOT_DETECTED" || code === "IP_BLOCKED" || code === "INNERTUBE_REJECTED" || code === "PAGE_FETCH_FAILED" || code === "AGE_RESTRICTED" || code === "VIDEO_UNAVAILABLE";
+}
+
+export function normalizePublishDate(uploadDate?: string): string {
+  if (!uploadDate || !/^\d{8}$/.test(uploadDate)) return uploadDate || "";
+  return `${uploadDate.slice(0, 4)}-${uploadDate.slice(4, 6)}-${uploadDate.slice(6, 8)}`;
+}
@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+
+import type { Sentence, Snippet, VideoMeta } from "./types.ts";
+
+export function ensureDir(path: string) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function resolveBaseDir(outputDir: string): string {
+  return resolve(outputDir || "youtube-transcript");
+}
+
+function loadIndex(baseDir: string): Record<string, string> {
+  try {
+    return JSON.parse(readFileSync(join(baseDir, ".index.json"), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveIndex(baseDir: string, index: Record<string, string>) {
+  const path = join(baseDir, ".index.json");
+  ensureDir(path);
+  writeFileSync(path, JSON.stringify(index, null, 2));
+}
+
+export function lookupVideoDir(videoId: string, baseDir: string): string | null {
+  const rel = loadIndex(baseDir)[videoId];
+  if (rel) {
+    const dir = resolve(baseDir, rel);
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+export function registerVideoDir(videoId: string, channelSlug: string, titleSlug: string, baseDir: string): string {
+  const rel = join(channelSlug, titleSlug);
+  const index = loadIndex(baseDir);
+  index[videoId] = rel;
+  saveIndex(baseDir, index);
+  return resolve(baseDir, rel);
+}
+
+export function hasCachedData(videoDir: string): boolean {
+  return existsSync(join(videoDir, "meta.json")) && existsSync(join(videoDir, "transcript-raw.json"));
+}
+
+export function loadMeta(videoDir: string): VideoMeta {
+  return JSON.parse(readFileSync(join(videoDir, "meta.json"), "utf-8"));
+}
+
+export function loadSnippets(videoDir: string): Snippet[] {
+  return JSON.parse(readFileSync(join(videoDir, "transcript-raw.json"), "utf-8"));
+}
+
+export function loadSentences(videoDir: string): Sentence[] {
+  return JSON.parse(readFileSync(join(videoDir, "transcript-sentences.json"), "utf-8"));
+}
@@ -0,0 +1,349 @@
+import { htmlUnescape, makeError, stripTags } from "./shared.ts";
+import type { Sentence, Snippet, TranscriptInfo, VideoMeta } from "./types.ts";
+
+interface Paragraph {
+  text: string;
+  start: number;
+  end: number;
+}
+
+const SENTENCE_END_RE = /[.?!…。？！⁈⁇‼‽．]/;
+
+export function parseTranscriptXml(xml: string): Snippet[] {
+  const snippets: Snippet[] = [];
+  const pattern = /<text\s+start="([^"]*)"(?:\s+dur="([^"]*)")?[^>]*>([\s\S]*?)<\/text>/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(xml)) !== null) {
+    const raw = match[3];
+    if (!raw) continue;
+    snippets.push({
+      text: htmlUnescape(stripTags(raw)),
+      start: parseFloat(match[1]),
+      duration: parseFloat(match[2] || "0"),
+    });
+  }
+  return snippets;
+}
+
+export function parseTranscriptJson3(text: string): Snippet[] {
+  const data = JSON.parse(text);
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const snippets: Snippet[] = [];
+  for (const event of events) {
+    const segs = Array.isArray(event?.segs) ? event.segs : [];
+    const textParts = segs
+      .map((seg: any) => htmlUnescape(String(seg?.utf8 || "").replace(/\n+/g, " ").trim()))
+      .filter(Boolean);
+    const merged = mergeTexts(textParts).trim();
+    if (!merged) continue;
+    snippets.push({
+      text: merged,
+      start: Number(event?.tStartMs || 0) / 1000,
+      duration: Number(event?.dDurationMs || 0) / 1000,
+    });
+  }
+  return snippets;
+}
+
+function parseSrt(srt: string): Snippet[] {
+  const blocks = srt.trim().split(/\n\n+/);
+  const snippets: Snippet[] = [];
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    if (lines.length < 3) continue;
+    const match = lines[1].match(/(\d{2}):(\d{2}):(\d{2}),(\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2}),(\d{3})/);
+    if (!match) continue;
+    const start = parseInt(match[1]) * 3600 + parseInt(match[2]) * 60 + parseInt(match[3]) + parseInt(match[4]) / 1000;
+    const end = parseInt(match[5]) * 3600 + parseInt(match[6]) * 60 + parseInt(match[7]) + parseInt(match[8]) / 1000;
+    snippets.push({ text: lines.slice(2).join(" "), start, duration: end - start });
+  }
+  return snippets;
+}
+
+export function parseWebVtt(vtt: string): Snippet[] {
+  const blocks = vtt
+    .replace(/^WEBVTT\s*/m, "")
+    .trim()
+    .split(/\n\n+/);
+  const snippets: Snippet[] = [];
+  for (const block of blocks) {
+    const lines = block.split("\n").map((line) => line.trim()).filter(Boolean);
+    const tsLine = lines.find((line) => line.includes("-->"));
+    if (!tsLine) continue;
+    const match = tsLine.match(
+      /(?:(\d{2}):)?(\d{2}):(\d{2})\.(\d{3})\s*-->\s*(?:(\d{2}):)?(\d{2}):(\d{2})\.(\d{3})/
+    );
+    if (!match) continue;
+    const start =
+      (match[1] ? parseInt(match[1]) : 0) * 3600 +
+      parseInt(match[2]) * 60 +
+      parseInt(match[3]) +
+      parseInt(match[4]) / 1000;
+    const end =
+      (match[5] ? parseInt(match[5]) : 0) * 3600 +
+      parseInt(match[6]) * 60 +
+      parseInt(match[7]) +
+      parseInt(match[8]) / 1000;
+    const text = htmlUnescape(stripTags(lines.slice(lines.indexOf(tsLine) + 1).join(" ").replace(/\s+/g, " ").trim()));
+    if (!text) continue;
+    snippets.push({ text, start, duration: end - start });
+  }
+  return snippets;
+}
+
+export function parseTranscriptPayload(payload: string, url: string): Snippet[] {
+  const normalized = payload.trimStart();
+  if (url.includes("fmt=json3") || normalized.startsWith("{")) return parseTranscriptJson3(payload);
+  if (normalized.startsWith("WEBVTT")) return parseWebVtt(payload);
+  if (/^\d+\s*\n\d{2}:\d{2}:\d{2},\d{3}\s*-->/.test(normalized)) return parseSrt(payload);
+  return parseTranscriptXml(payload);
+}
+
+function isCJK(ch: string): boolean {
+  const code = ch.charCodeAt(0);
+  return (code >= 0x4E00 && code <= 0x9FFF) ||
+    (code >= 0x3040 && code <= 0x309F) ||
+    (code >= 0x30A0 && code <= 0x30FF) ||
+    (code >= 0xAC00 && code <= 0xD7AF) ||
+    (code >= 0x3400 && code <= 0x4DBF) ||
+    (code >= 0xF900 && code <= 0xFAFF);
+}
+
+function splitSnippetAtPunctuation(snippet: Snippet): { text: string; start: number; end: number }[] {
+  const { text, start, duration } = snippet;
+  const end = start + duration;
+  if (!text.length) return [];
+
+  const splitPoints: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    if (SENTENCE_END_RE.test(text[i])) {
+      while (i + 1 < text.length && SENTENCE_END_RE.test(text[i + 1])) i++;
+      if (i < text.length - 1) splitPoints.push(i);
+    }
+  }
+
+  if (!splitPoints.length) return [{ text, start, end }];
+
+  const parts: { text: string; start: number; end: number }[] = [];
+  let prev = 0;
+  for (const pos of splitPoints) {
+    const partText = text.slice(prev, pos + 1).trim();
+    if (partText) {
+      parts.push({
+        text: partText,
+        start: start + (prev / text.length) * duration,
+        end: start + ((pos + 1) / text.length) * duration,
+      });
+    }
+    prev = pos + 1;
+  }
+
+  const remaining = text.slice(prev).trim();
+  if (remaining) parts.push({ text: remaining, start: start + (prev / text.length) * duration, end });
+
+  return parts;
+}
+
+function mergeTexts(texts: string[]): string {
+  if (!texts.length) return "";
+  let result = texts[0];
+  for (let i = 1; i < texts.length; i++) {
+    const next = texts[i];
+    if (!next) continue;
+    const lastChar = result[result.length - 1];
+    const firstChar = next[0];
+    if (isCJK(lastChar) || isCJK(firstChar)) {
+      result += next;
+    } else {
+      result = result.trimEnd() + " " + next.trimStart();
+    }
+  }
+  return result.replace(/ {2,}/g, " ");
+}
+
+export function ts(time: number): string {
+  const h = Math.floor(time / 3600);
+  const m = Math.floor((time % 3600) / 60);
+  const s = Math.floor(time % 60);
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+
+function tsMs(time: number, sep: string): string {
+  const h = Math.floor(time / 3600);
+  const m = Math.floor((time % 3600) / 60);
+  const s = Math.floor(time % 60);
+  const ms = Math.round((time - Math.floor(time)) * 1000);
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}${sep}${String(ms).padStart(3, "0")}`;
+}
+
+function parseTs(time: string): number {
+  const [h, m, s] = time.split(":").map(Number);
+  return h * 3600 + m * 60 + s;
+}
+
+export function segmentIntoSentences(snippets: Snippet[]): Sentence[] {
+  const parts: { text: string; start: number; end: number }[] = [];
+  for (const snippet of snippets) parts.push(...splitSnippetAtPunctuation(snippet));
+
+  const sentences: Sentence[] = [];
+  let buffer: { text: string; start: number; end: number }[] = [];
+
+  for (const part of parts) {
+    buffer.push(part);
+    if (SENTENCE_END_RE.test(part.text[part.text.length - 1])) {
+      sentences.push({
+        text: mergeTexts(buffer.map((entry) => entry.text)),
+        start: ts(buffer[0].start),
+        end: ts(buffer[buffer.length - 1].end),
+      });
+      buffer = [];
+    }
+  }
+
+  if (buffer.length) {
+    sentences.push({
+      text: mergeTexts(buffer.map((entry) => entry.text)),
+      start: ts(buffer[0].start),
+      end: ts(buffer[buffer.length - 1].end),
+    });
+  }
+
+  return sentences;
+}
+
+function groupSentenceParas(sentences: Sentence[]): Paragraph[] {
+  if (!sentences.length) return [];
+  const paragraphs: Paragraph[] = [];
+  let buffer: Sentence[] = [];
+  for (let i = 0; i < sentences.length; i++) {
+    buffer.push(sentences[i]);
+    const last = i === sentences.length - 1;
+    const gap = !last && parseTs(sentences[i + 1].start) - parseTs(sentences[i].end) > 2;
+    if (last || gap || buffer.length >= 5) {
+      paragraphs.push({
+        text: mergeTexts(buffer.map((sentence) => sentence.text)),
+        start: parseTs(buffer[0].start),
+        end: parseTs(buffer[buffer.length - 1].end),
+      });
+      buffer = [];
+    }
+  }
+  return paragraphs;
+}
+
+export function formatSrt(snippets: Snippet[]): string {
+  return snippets
+    .map((snippet, index) => {
+      const end = index < snippets.length - 1 && snippets[index + 1].start < snippet.start + snippet.duration
+        ? snippets[index + 1].start
+        : snippet.start + snippet.duration;
+      return `${index + 1}\n${tsMs(snippet.start, ",")} --> ${tsMs(end, ",")}\n${snippet.text}`;
+    })
+    .join("\n\n") + "\n";
+}
+
+function yamlEscape(value: string): string {
+  if (/[:"'{}\[\]#&*!|>%@`\n]/.test(value) || value.trim() !== value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function extractSummary(description: string): string {
+  if (!description) return "";
+  const firstPara = description.split(/\n\s*\n/)[0].trim();
+  const lines = firstPara.split("\n").filter((line) => !/^\s*(https?:\/\/|#|@|\d+:\d+)/.test(line) && line.trim());
+  return lines.join(" ").slice(0, 300).trim();
+}
+
+export function formatMarkdown(
+  sentences: Sentence[],
+  meta: VideoMeta,
+  opts: { timestamps: boolean; chapters: boolean; speakers: boolean },
+  snippets?: Snippet[]
+): string {
+  const summary = extractSummary(meta.description);
+  let md = "---\n";
+  md += `title: ${yamlEscape(meta.title)}\n`;
+  md += `channel: ${yamlEscape(meta.channel)}\n`;
+  if (meta.publishDate) md += `date: ${meta.publishDate}\n`;
+  md += `url: ${yamlEscape(meta.url)}\n`;
+  if (meta.coverImage) md += `cover: ${meta.coverImage}\n`;
+  if (summary) md += `description: ${yamlEscape(summary)}\n`;
+  if (meta.language) md += `language: ${meta.language.code}\n`;
+  md += "---\n\n";
+
+  if (opts.speakers) {
+    md += `# ${meta.title}\n\n`;
+    if (summary) md += `${summary}\n\n`;
+    if (meta.description) md += `# Description\n\n${meta.description.trim()}\n\n`;
+    if (meta.chapters.length) {
+      md += "# Chapters\n\n";
+      for (const chapter of meta.chapters) md += `* [${ts(chapter.start)}] ${chapter.title}\n`;
+      md += "\n";
+    }
+    md += "# Transcript\n\n";
+    md += snippets ? formatSrt(snippets) : "";
+    return md;
+  }
+
+  md += `# ${meta.title}\n\n`;
+  if (summary) md += `${summary}\n\n`;
+
+  const chapters = opts.chapters ? meta.chapters : [];
+  if (chapters.length) {
+    md += "## Table of Contents\n\n";
+    for (const chapter of chapters) md += opts.timestamps ? `* [${ts(chapter.start)}] ${chapter.title}\n` : `* ${chapter.title}\n`;
+    md += "\n";
+    if (meta.coverImage) md += `\n![cover](${meta.coverImage})\n`;
+    md += "\n";
+    for (let i = 0; i < chapters.length; i++) {
+      const nextStart = i < chapters.length - 1 ? chapters[i + 1].start : Infinity;
+      const chapterSentences = sentences.filter((sentence) => parseTs(sentence.start) >= chapters[i].start && parseTs(sentence.start) < nextStart);
+      const paragraphs = groupSentenceParas(chapterSentences);
+      md += opts.timestamps ? `## [${ts(chapters[i].start)}] ${chapters[i].title}\n\n` : `## ${chapters[i].title}\n\n`;
+      for (const paragraph of paragraphs) {
+        md += opts.timestamps ? `${paragraph.text} [${ts(paragraph.start)} → ${ts(paragraph.end)}]\n\n` : `${paragraph.text}\n\n`;
+      }
+      md += "\n";
+    }
+  } else {
+    const paragraphs = groupSentenceParas(sentences);
+    for (const paragraph of paragraphs) {
+      md += opts.timestamps ? `${paragraph.text} [${ts(paragraph.start)} → ${ts(paragraph.end)}]\n\n` : `${paragraph.text}\n\n`;
+    }
+  }
+
+  return md.trimEnd() + "\n";
+}
+
+export function formatListOutput(videoId: string, title: string, transcripts: TranscriptInfo[]): string {
+  const manual = transcripts.filter((transcript) => !transcript.isGenerated);
+  const generated = transcripts.filter((transcript) => transcript.isGenerated);
+  const translationLanguages = transcripts.find((transcript) => transcript.translationLanguages.length > 0)?.translationLanguages || [];
+  const formatList = (list: TranscriptInfo[]) =>
+    list.length
+      ? list.map((transcript) => ` - ${transcript.languageCode} ("${transcript.language}")${transcript.isTranslatable ? " [TRANSLATABLE]" : ""}`).join("\n")
+      : "None";
+  const formatTranslations = translationLanguages.length
+    ? translationLanguages.map((language) => ` - ${language.languageCode} ("${language.language}")`).join("\n")
+    : "None";
+  return `Transcripts for ${videoId}${title ? ` (${title})` : ""}:\n\n(MANUALLY CREATED)\n${formatList(manual)}\n\n(GENERATED)\n${formatList(generated)}\n\n(TRANSLATION LANGUAGES)\n${formatTranslations}`;
+}
+
+export function findTranscript(
+  transcripts: TranscriptInfo[],
+  languages: string[],
+  excludeGenerated: boolean,
+  excludeManual: boolean
+): TranscriptInfo {
+  let filtered = transcripts;
+  if (excludeGenerated) filtered = filtered.filter((transcript) => !transcript.isGenerated);
+  if (excludeManual) filtered = filtered.filter((transcript) => transcript.isGenerated);
+  for (const language of languages) {
+    const found = filtered.find((transcript) => transcript.languageCode === language);
+    if (found) return found;
+  }
+  const available = filtered.map((transcript) => `${transcript.languageCode} ("${transcript.language}")`).join(", ");
+  throw makeError(`No transcript found for languages [${languages.join(", ")}]. Available: ${available || "none"}`, "NO_TRANSCRIPT");
+}
@@ -0,0 +1,123 @@
+export type Format = "text" | "srt";
+
+export interface Options {
+  videoIds: string[];
+  languages: string[];
+  format: Format;
+  translate: string;
+  list: boolean;
+  excludeGenerated: boolean;
+  excludeManual: boolean;
+  output: string;
+  outputDir: string;
+  timestamps: boolean;
+  chapters: boolean;
+  speakers: boolean;
+  refresh: boolean;
+}
+
+export interface Snippet {
+  text: string;
+  start: number;
+  duration: number;
+}
+
+export interface Sentence {
+  text: string;
+  start: string;
+  end: string;
+}
+
+export interface TranscriptLanguage {
+  language: string;
+  languageCode: string;
+}
+
+export interface TranscriptInfo {
+  language: string;
+  languageCode: string;
+  isGenerated: boolean;
+  isTranslatable: boolean;
+  baseUrl: string;
+  translationLanguages: TranscriptLanguage[];
+}
+
+export interface Chapter {
+  title: string;
+  start: number;
+  end: number;
+}
+
+export interface LanguageMeta {
+  code: string;
+  name: string;
+  isGenerated: boolean;
+}
+
+export interface VideoMeta {
+  videoId: string;
+  title: string;
+  channel: string;
+  channelId: string;
+  description: string;
+  duration: number;
+  publishDate: string;
+  url: string;
+  coverImage: string;
+  thumbnailUrl: string;
+  language: LanguageMeta;
+  chapters: Chapter[];
+}
+
+export interface VideoResult {
+  videoId: string;
+  title?: string;
+  filePath?: string;
+  content?: string;
+  error?: string;
+}
+
+export interface InnerTubeSession {
+  apiKey: string;
+  webClientVersion: string;
+  visitorData: string;
+}
+
+export interface InnerTubeClient {
+  id: string;
+  clientName: string;
+  clientVersion?: string;
+  clientHeaderName?: string;
+  userAgent: string;
+  extraContext?: Record<string, any>;
+}
+
+export interface TranscriptError extends Error {
+  code?: string;
+}
+
+export interface YtDlpTrack {
+  ext?: string;
+  url?: string;
+  name?: string;
+}
+
+export interface YtDlpInfo {
+  title?: string;
+  channel?: string;
+  channel_id?: string;
+  uploader?: string;
+  uploader_id?: string;
+  description?: string;
+  duration?: number;
+  upload_date?: string;
+  webpage_url?: string;
+  thumbnail?: string;
+  thumbnails?: { url?: string; width?: number; height?: number }[];
+  subtitles?: Record<string, YtDlpTrack[]>;
+  automatic_captions?: Record<string, YtDlpTrack[]>;
+}
+
+export type VideoSource =
+  | { kind: "innertube"; data: any; transcripts: TranscriptInfo[] }
+  | { kind: "yt-dlp"; info: YtDlpInfo; transcripts: TranscriptInfo[] };
@@ -0,0 +1,477 @@
+import { spawnSync } from "child_process";
+import { writeFileSync } from "fs";
+
+import { makeError, normalizeError, normalizePublishDate, shouldTryAlternateClient, shouldTryYtDlpFallback } from "./shared.ts";
+import { parseTranscriptPayload } from "./transcript.ts";
+import type {
+  Chapter,
+  InnerTubeClient,
+  InnerTubeSession,
+  LanguageMeta,
+  Snippet,
+  TranscriptInfo,
+  VideoMeta,
+  VideoSource,
+  YtDlpInfo,
+  YtDlpTrack,
+} from "./types.ts";
+
+const WATCH_URL = "https://www.youtube.com/watch?v=";
+const INNERTUBE_URL = "https://www.youtube.com/youtubei/v1/player";
+const WATCH_PAGE_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36";
+const DEFAULT_WEB_CLIENT_VERSION = "2.20260320.08.00";
+const YT_DLP_MAX_BUFFER = 32 * 1024 * 1024;
+
+let cachedYtDlpCommand: { command: string; args: string[]; label: string } | null | undefined;
+
+const INNER_TUBE_CLIENTS: InnerTubeClient[] = [
+  {
+    id: "android",
+    clientName: "ANDROID",
+    clientHeaderName: "3",
+    clientVersion: "20.10.38",
+    userAgent:
+      "com.google.android.youtube/20.10.38 (Linux; U; Android 14; en_US; Pixel 8 Pro; Build/AP1A.240405.002)",
+    extraContext: {
+      clientFormFactor: "SMALL_FORM_FACTOR",
+      androidSdkVersion: 34,
+      osName: "Android",
+      osVersion: "14",
+      platform: "MOBILE",
+    },
+  },
+  {
+    id: "web",
+    clientName: "WEB",
+    clientHeaderName: "1",
+    userAgent: WATCH_PAGE_USER_AGENT,
+  },
+  {
+    id: "ios",
+    clientName: "IOS",
+    clientHeaderName: "5",
+    clientVersion: "20.10.4",
+    userAgent:
+      "com.google.ios.youtube/20.10.4 (iPhone16,2; U; CPU iOS 18_3 like Mac OS X; en_US)",
+    extraContext: {
+      deviceMake: "Apple",
+      deviceModel: "iPhone16,2",
+      osName: "iPhone",
+      osVersion: "18.3.0.22D5054f",
+      platform: "MOBILE",
+    },
+  },
+];
+
+async function fetchHtml(videoId: string): Promise<string> {
+  const watchUrl = `${WATCH_URL}${videoId}&hl=en&persist_hl=1&has_verified=1&bpctr=9999999999`;
+  const baseHeaders = {
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Cache-Control": "no-cache",
+    Pragma: "no-cache",
+    "User-Agent": WATCH_PAGE_USER_AGENT,
+  };
+  const response = await fetch(watchUrl, { headers: baseHeaders });
+  if (!response.ok) throw new Error(`HTTP ${response.status} fetching video page`);
+  let html = await response.text();
+  if (html.includes('action="https://consent.youtube.com/s"')) {
+    const consentValue = html.match(/name="v" value="(.*?)"/);
+    if (!consentValue) throw new Error("Failed to create consent cookie");
+    const consentResponse = await fetch(watchUrl, {
+      headers: {
+        ...baseHeaders,
+        Cookie: `CONSENT=YES+${consentValue[1]}`,
+      },
+    });
+    if (!consentResponse.ok) throw new Error(`HTTP ${consentResponse.status} fetching video page (consent)`);
+    html = await consentResponse.text();
+  }
+  return html;
+}
+
+function extractSession(html: string, videoId: string): InnerTubeSession {
+  const apiKey = html.match(/"INNERTUBE_API_KEY":\s*"([a-zA-Z0-9_-]+)"/)?.[1];
+  if (!apiKey) {
+    if (html.includes('class="g-recaptcha"')) throw new Error(`IP blocked for ${videoId} (reCAPTCHA)`);
+    throw new Error(`Cannot extract API key for ${videoId}`);
+  }
+  const webClientVersion =
+    html.match(/"INNERTUBE_CLIENT_VERSION":\s*"([^"]+)"/)?.[1] ||
+    html.match(/"clientVersion":"([^"]+)"/)?.[1] ||
+    DEFAULT_WEB_CLIENT_VERSION;
+  const visitorData =
+    html.match(/"VISITOR_DATA":"([^"]+)"/)?.[1] ||
+    html.match(/"visitorData":"([^"]+)"/)?.[1] ||
+    "";
+  return { apiKey, webClientVersion, visitorData };
+}
+
+function buildInnerTubeContext(client: InnerTubeClient, session: InnerTubeSession, videoId: string) {
+  return {
+    context: {
+      client: {
+        hl: "en",
+        gl: "US",
+        utcOffsetMinutes: 0,
+        visitorData: session.visitorData,
+        clientName: client.clientName,
+        clientVersion: client.clientVersion || session.webClientVersion,
+        ...client.extraContext,
+      },
+      request: { useSsl: true },
+    },
+    videoId,
+  };
+}
+
+async function fetchInnertubeData(videoId: string, session: InnerTubeSession, client: InnerTubeClient): Promise<any> {
+  const clientVersion = client.clientVersion || session.webClientVersion;
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Content-Type": "application/json",
+    Origin: "https://www.youtube.com",
+    Referer: `${WATCH_URL}${videoId}`,
+    "User-Agent": client.userAgent,
+    "X-YouTube-Client-Name": client.clientHeaderName || "1",
+    "X-YouTube-Client-Version": clientVersion,
+  };
+  if (session.visitorData) headers["X-Goog-Visitor-Id"] = session.visitorData;
+  const response = await fetch(`${INNERTUBE_URL}?key=${session.apiKey}&prettyPrint=false`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(buildInnerTubeContext(client, session, videoId)),
+  });
+  if (response.status === 429) throw new Error(`IP blocked for ${videoId} (429)`);
+  if (!response.ok) throw new Error(`HTTP ${response.status} from InnerTube API`);
+  return response.json();
+}
+
+function assertPlayability(data: any, videoId: string) {
+  const playabilityStatus = data?.playabilityStatus;
+  if (!playabilityStatus) return;
+  const status = playabilityStatus.status;
+  if (status === "OK" || !status) return;
+  const reason = playabilityStatus.reason || "";
+  const reasonLower = reason.toLowerCase();
+  if (status === "LOGIN_REQUIRED") {
+    if (reasonLower.includes("bot")) throw makeError(`Request blocked for ${videoId}: bot detected`, "BOT_DETECTED");
+    if (reasonLower.includes("inappropriate")) throw makeError(`Age restricted: ${videoId}`, "AGE_RESTRICTED");
+  }
+  if (status === "ERROR" && reasonLower.includes("unavailable")) {
+    if (videoId.startsWith("http")) throw makeError("Invalid video ID: pass the ID, not the URL", "INVALID_VIDEO_ID");
+    throw makeError(`Video unavailable: ${videoId}`, "VIDEO_UNAVAILABLE");
+  }
+  const subreasons = playabilityStatus.errorScreen?.playerErrorMessageRenderer?.subreason?.runs?.map((run: any) => run.text).join("") || "";
+  throw new Error(`Video unplayable (${videoId}): ${reason} ${subreasons}`.trim());
+}
+
+function extractCaptionsJson(data: any, videoId: string): any {
+  assertPlayability(data, videoId);
+  const captionsJson = data?.captions?.playerCaptionsTracklistRenderer;
+  if (!captionsJson || !captionsJson.captionTracks) throw makeError(`Transcripts disabled for ${videoId}`, "TRANSCRIPTS_DISABLED");
+  return captionsJson;
+}
+
+function buildTranscriptList(captionsJson: any): TranscriptInfo[] {
+  const translationLanguages = (captionsJson.translationLanguages || []).map((language: any) => ({
+    language: language.languageName?.runs?.[0]?.text || language.languageName?.simpleText || "",
+    languageCode: language.languageCode,
+  }));
+  return (captionsJson.captionTracks || []).map((track: any) => ({
+    language: track.name?.runs?.[0]?.text || track.name?.simpleText || "",
+    languageCode: track.languageCode,
+    isGenerated: track.kind === "asr",
+    isTranslatable: !!track.isTranslatable,
+    baseUrl: track.baseUrl || "",
+    translationLanguages: track.isTranslatable ? translationLanguages : [],
+  }));
+}
+
+export async function fetchTranscriptSnippets(
+  info: TranscriptInfo,
+  translateTo?: string
+): Promise<{ snippets: Snippet[]; language: string; languageCode: string }> {
+  let url = info.baseUrl;
+  let language = info.language;
+  let languageCode = info.languageCode;
+  if (translateTo) {
+    if (!info.isTranslatable) throw new Error(`Transcript ${info.languageCode} is not translatable`);
+    const translatedLanguage = info.translationLanguages.find((entry) => entry.languageCode === translateTo);
+    if (!translatedLanguage) throw new Error(`Translation language ${translateTo} not available`);
+    url += `&tlang=${translateTo}`;
+    language = translatedLanguage.language;
+    languageCode = translateTo;
+  }
+  const response = await fetch(url, {
+    headers: {
+      "Accept-Language": "en-US,en;q=0.9",
+      "User-Agent": WATCH_PAGE_USER_AGENT,
+    },
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status} fetching transcript`);
+  return {
+    snippets: parseTranscriptPayload(await response.text(), url),
+    language,
+    languageCode,
+  };
+}
+
+export function detectYtDlpCommand(): { command: string; args: string[]; label: string } | null {
+  if (cachedYtDlpCommand !== undefined) return cachedYtDlpCommand;
+  const candidates = [
+    { command: "yt-dlp", args: [], label: "yt-dlp" },
+    { command: "uvx", args: ["--from", "yt-dlp", "yt-dlp"], label: "uvx --from yt-dlp yt-dlp" },
+    { command: "python3", args: ["-m", "yt_dlp"], label: "python3 -m yt_dlp" },
+  ];
+  for (const candidate of candidates) {
+    const probe = spawnSync(candidate.command, [...candidate.args, "--version"], {
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024,
+    });
+    if (probe.status !== 0) continue;
+
+    const helpProbe = spawnSync(candidate.command, [...candidate.args, "--help"], {
+      encoding: "utf8",
+      maxBuffer: 2 * 1024 * 1024,
+    });
+    const helpText = `${helpProbe.stdout || ""}\n${helpProbe.stderr || ""}`;
+    const supportsRequiredFlags =
+      helpProbe.status === 0 &&
+      helpText.includes("--js-runtimes") &&
+      helpText.includes("--remote-components");
+
+    if (supportsRequiredFlags) {
+      cachedYtDlpCommand = candidate;
+      return candidate;
+    }
+  }
+  cachedYtDlpCommand = null;
+  return cachedYtDlpCommand;
+}
+
+export function selectYtDlpTrack(entries: YtDlpTrack[]): YtDlpTrack | null {
+  const preferredExts = ["json3", "srv3", "srv2", "srv1", "ttml", "vtt"];
+  for (const ext of preferredExts) {
+    const match = entries.find((entry) => entry.url && entry.ext === ext);
+    if (match) return match;
+  }
+  return entries.find((entry) => !!entry.url) || null;
+}
+
+export function buildTranscriptListFromYtDlp(info: YtDlpInfo): TranscriptInfo[] {
+  const translationLanguages = Object.entries(info.automatic_captions || {}).map(([languageCode, entries]) => ({
+    language: entries.find((entry) => entry.name)?.name || languageCode,
+    languageCode,
+  }));
+  const manual = Object.entries(info.subtitles || {}).flatMap(([languageCode, entries]) => {
+    const selected = selectYtDlpTrack(entries);
+    if (!selected?.url) return [];
+    return [{
+      language: selected.name || languageCode,
+      languageCode,
+      isGenerated: false,
+      isTranslatable: translationLanguages.length > 0,
+      baseUrl: selected.url,
+      translationLanguages,
+    }];
+  });
+  const generated = Object.entries(info.automatic_captions || {}).flatMap(([languageCode, entries]) => {
+    const selected = selectYtDlpTrack(entries);
+    if (!selected?.url) return [];
+    return [{
+      language: selected.name || languageCode,
+      languageCode,
+      isGenerated: true,
+      isTranslatable: translationLanguages.length > 0,
+      baseUrl: selected.url,
+      translationLanguages,
+    }];
+  });
+  return [...manual, ...generated];
+}
+
+function fetchYtDlpInfo(videoId: string): YtDlpInfo {
+  const command = detectYtDlpCommand();
+  if (!command) {
+    throw makeError(
+      `Request blocked for ${videoId}: bot detected. yt-dlp fallback unavailable (install yt-dlp or uv).`,
+      "YT_DLP_UNAVAILABLE"
+    );
+  }
+
+  const args = [
+    ...command.args,
+    "-J",
+    "--skip-download",
+    "--js-runtimes",
+    "bun",
+    "--remote-components",
+    "ejs:github",
+  ];
+  const cookiesFromBrowser = process.env.YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER?.trim();
+  if (cookiesFromBrowser) args.push("--cookies-from-browser", cookiesFromBrowser);
+  args.push(`${WATCH_URL}${videoId}`);
+
+  const result = spawnSync(command.command, args, {
+    encoding: "utf8",
+    maxBuffer: YT_DLP_MAX_BUFFER,
+  });
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").trim();
+    const stdout = (result.stdout || "").trim();
+    const detail = stderr || stdout || `exit ${result.status ?? "unknown"}`;
+    throw makeError(`yt-dlp fallback failed for ${videoId} (${command.label}): ${detail}`, "YT_DLP_FAILED");
+  }
+  return JSON.parse(result.stdout);
+}
+
+async function fetchInnertubeSource(videoId: string): Promise<VideoSource> {
+  const html = await fetchHtml(videoId);
+  const session = extractSession(html, videoId);
+  const attempts: string[] = [];
+  let lastError: Error | null = null;
+
+  for (const client of INNER_TUBE_CLIENTS) {
+    try {
+      const data = await fetchInnertubeData(videoId, session, client);
+      const captionsJson = extractCaptionsJson(data, videoId);
+      return { kind: "innertube", data, transcripts: buildTranscriptList(captionsJson) };
+    } catch (error) {
+      const normalized = normalizeError(error);
+      attempts.push(`${client.id}: ${normalized.message}`);
+      lastError = normalized;
+      if (!shouldTryAlternateClient(normalized)) break;
+    }
+  }
+
+  if (!lastError) throw makeError(`Unable to fetch transcript metadata for ${videoId}`, "UNKNOWN");
+  if (attempts.length > 1) {
+    throw makeError(`${lastError.message}. Tried clients: ${attempts.join("; ")}`, normalizeError(lastError).code);
+  }
+  throw lastError;
+}
+
+export async function resolveVideoSource(
+  videoId: string,
+  fetchPrimary: (videoId: string) => Promise<VideoSource>,
+  fetchFallback: (videoId: string) => YtDlpInfo,
+  logWarning: (message: string) => void = (message) => console.error(message)
+): Promise<VideoSource> {
+  try {
+    return await fetchPrimary(videoId);
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (!shouldTryYtDlpFallback(normalized)) throw normalized;
+    logWarning(`Warning (${videoId}): ${normalized.message}. Retrying with yt-dlp fallback.`);
+    const info = fetchFallback(videoId);
+    const transcripts = buildTranscriptListFromYtDlp(info);
+    if (!transcripts.length) throw makeError(`Transcripts disabled for ${videoId}`, "TRANSCRIPTS_DISABLED");
+    return { kind: "yt-dlp", info, transcripts };
+  }
+}
+
+export async function fetchVideoSource(videoId: string): Promise<VideoSource> {
+  return resolveVideoSource(videoId, fetchInnertubeSource, fetchYtDlpInfo);
+}
+
+export function parseChapters(description: string, duration: number = 0): Chapter[] {
+  const raw: { title: string; start: number }[] = [];
+  for (const line of description.split("\n")) {
+    const match = line.trim().match(/^(?:(\d{1,2}):)?(\d{1,2}):(\d{2})\s+(.+)$/);
+    if (match) {
+      const hours = match[1] ? parseInt(match[1]) : 0;
+      raw.push({ title: match[4].trim(), start: hours * 3600 + parseInt(match[2]) * 60 + parseInt(match[3]) });
+    }
+  }
+  if (raw.length < 2) return [];
+  return raw.map((chapter, index) => ({
+    title: chapter.title,
+    start: chapter.start,
+    end: index < raw.length - 1 ? raw[index + 1].start : Math.max(duration, chapter.start),
+  }));
+}
+
+export function getThumbnailUrls(videoId: string, data: any): string[] {
+  const urls = [
+    `https://i.ytimg.com/vi/${videoId}/maxresdefault.jpg`,
+    `https://i.ytimg.com/vi/${videoId}/hqdefault.jpg`,
+  ];
+  const thumbnails = data?.videoDetails?.thumbnail?.thumbnails ||
+    data?.microformat?.playerMicroformatRenderer?.thumbnail?.thumbnails ||
+    [];
+  if (thumbnails.length) {
+    const sorted = [...thumbnails].sort((a: any, b: any) => (b.width || 0) - (a.width || 0));
+    for (const thumbnail of sorted) {
+      if (thumbnail.url && !urls.includes(thumbnail.url)) urls.push(thumbnail.url);
+    }
+  }
+  return urls;
+}
+
+export function getYtDlpThumbnailUrls(videoId: string, info: YtDlpInfo): string[] {
+  const urls = getThumbnailUrls(videoId, null);
+  const thumbnails = Array.isArray(info.thumbnails) ? info.thumbnails : [];
+  const sorted = [...thumbnails].sort((a, b) => (b?.width || 0) - (a?.width || 0));
+  for (const thumbnail of sorted) {
+    if (thumbnail?.url && !urls.includes(thumbnail.url)) urls.push(thumbnail.url);
+  }
+  if (info.thumbnail && !urls.includes(info.thumbnail)) urls.push(info.thumbnail);
+  return urls;
+}
+
+export function buildVideoMeta(data: any, videoId: string, language: LanguageMeta, chapters: Chapter[]): VideoMeta {
+  const videoDetails = data?.videoDetails || {};
+  const microformat = data?.microformat?.playerMicroformatRenderer || {};
+  return {
+    videoId,
+    title: videoDetails.title || microformat.title?.simpleText || "",
+    channel: videoDetails.author || microformat.ownerChannelName || "",
+    channelId: videoDetails.channelId || microformat.externalChannelId || "",
+    description: videoDetails.shortDescription || microformat.description?.simpleText || "",
+    duration: parseInt(videoDetails.lengthSeconds || "0"),
+    publishDate: microformat.publishDate || microformat.uploadDate || "",
+    url: `${WATCH_URL}${videoId}`,
+    coverImage: "",
+    thumbnailUrl: getThumbnailUrls(videoId, data)[0],
+    language,
+    chapters,
+  };
+}
+
+export function buildVideoMetaFromYtDlp(
+  info: YtDlpInfo,
+  videoId: string,
+  language: LanguageMeta,
+  chapters: Chapter[]
+): VideoMeta {
+  return {
+    videoId,
+    title: info.title || "",
+    channel: info.channel || info.uploader || "",
+    channelId: info.channel_id || info.uploader_id || "",
+    description: info.description || "",
+    duration: Number(info.duration || 0),
+    publishDate: normalizePublishDate(info.upload_date),
+    url: info.webpage_url || `${WATCH_URL}${videoId}`,
+    coverImage: "",
+    thumbnailUrl: getYtDlpThumbnailUrls(videoId, info)[0] || "",
+    language,
+    chapters,
+  };
+}
+
+export async function downloadCoverImage(urls: string[], outputPath: string): Promise<boolean> {
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        writeFileSync(outputPath, Buffer.from(await response.arrayBuffer()));
+        return true;
+      }
+    } catch {}
+  }
+  return false;
+}
Author	SHA1	Message	Date
Jim Liu 宝玉	41a75584b3	chore: release v1.87.0	2026-03-26 09:44:06 -05:00
Jim Liu 宝玉	88843b0276	chore(baoyu-image-gen): remove deprecated skill from plugin manifest	2026-03-26 09:43:05 -05:00
Jim Liu 宝玉	6909c016b2	chore(baoyu-image-gen): remove deprecated redirect skill	2026-03-26 09:41:04 -05:00
Jim Liu 宝玉	bec1f1e2a1	chore: release v1.86.0	2026-03-25 20:09:44 -05:00
Jim Liu 宝玉	39a97678bb	feat(baoyu-translate): enrich translation prompt with full analysis context Restructure 02-prompt.md template to better leverage analysis results: - Add source voice assessment alongside target style preset - Extract figurative language mapping into dedicated structured table - Include reasoning in comprehension challenges for annotation depth - Add translation challenges section for structural/creative issues - Provide chunk position context in subagent spawn prompts	2026-03-25 20:09:30 -05:00
Jim Liu 宝玉	6cd709b9e7	chore: release v1.85.0	2026-03-25 17:37:18 -05:00
Jim Liu 宝玉	aaf0f188dd	feat(baoyu-image-gen): add deprecation redirect skill to guide migration to baoyu-imagine	2026-03-25 17:36:49 -05:00
Jim Liu 宝玉	b6bf8ecd06	feat(baoyu-imagine): auto-migrate legacy baoyu-image-gen EXTEND.md config path	2026-03-25 17:36:46 -05:00
Jim Liu 宝玉	7a0ffd9533	chore: release v1.84.0	2026-03-25 16:29:22 -05:00
Jim Liu 宝玉	69355b4ee1	feat(baoyu-imagine): rename baoyu-image-gen to baoyu-imagine	2026-03-25 16:28:06 -05:00
Jim Liu 宝玉	23b7487321	chore: release v1.83.0	2026-03-25 15:40:22 -05:00
Jim Liu 宝玉	ad8781c1c5	feat(baoyu-image-gen): add MiniMax provider with subject reference and custom sizes	2026-03-25 15:39:40 -05:00
Jim Liu 宝玉	86a3d6521b	chore: release v1.82.0	2026-03-24 22:40:23 -05:00
Jim Liu 宝玉	e99ce744cd	feat(baoyu-url-to-markdown): add browser fallback strategy, content cleaner, and data URI support - Browser strategy: headless first with automatic retry in visible Chrome on failure - New --browser auto\|headless\|headed flag with --headless/--headed shortcuts - Content cleaner module for HTML preprocessing (remove ads, base64 images, scripts) - Media localizer now handles base64 data URIs alongside remote URLs - Capture finalUrl from browser to track redirects for output path - Agent quality gate documentation for post-capture validation - Upgrade defuddle ^0.12.0 → ^0.14.0 - Add unit tests for content-cleaner, html-to-markdown, legacy-converter, media-localizer	2026-03-24 22:39:17 -05:00
Jim Liu 宝玉	40f9f05c22	chore: release v1.81.0	2026-03-24 20:59:56 -05:00
Jim Liu 宝玉	09ce80357f	feat(baoyu-youtube-transcript): add yt-dlp fallback and modularize codebase Retry with alternate InnerTube client identities when YouTube returns anti-bot responses, then fall back to yt-dlp when available. Split monolithic main.ts into typed modules (youtube, transcript, storage, shared, types) and add unit tests.	2026-03-24 20:59:04 -05:00
Jim Liu 宝玉	7c995fcc24	chore: release v1.80.1	2026-03-24 20:06:02 -05:00
Jim Liu 宝玉	151f1ec2a8	fix(baoyu-image-gen): use correct prompt field name for Jimeng API	2026-03-24 20:04:21 -05:00
Jim Liu 宝玉	12e207dc3f	chore: release v1.80.0	2026-03-24 19:27:57 -05:00
Jim Liu 宝玉	00e74ab071	feat(baoyu-image-gen): improve Azure OpenAI provider with flexible endpoint parsing and deployment resolution	2026-03-24 19:19:49 -05:00
优弧	1653b8544b	feat(baoyu-image-gen): add Azure OpenAI as independent image generation provider (#111 ) Azure OpenAI differs from standard OpenAI in two ways: 1. Auth via api-key header instead of Authorization: Bearer 2. URL requires ?api-version query param with deployment path Changes: - New file: scripts/providers/azure.ts (generations + edits, reuses openai utilities) - types.ts: add "azure" to Provider type and default_model - main.ts: register azure across rate limits, CLI args, auto-detection, provider loading, model resolution, help text, ref validation, EXTEND.md parsing, and batch logging Env vars: AZURE_OPENAI_API_KEY, AZURE_OPENAI_BASE_URL (required), AZURE_API_VERSION, AZURE_OPENAI_IMAGE_MODEL (optional) Co-authored-by: CatFly <zw.catfly@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-24 19:04:34 -05:00
Jim Liu 宝玉	dad8f3a800	chore: release v1.79.2	2026-03-23 22:39:14 -05:00
Jim Liu 宝玉	35298d7c9d	fix(baoyu-post-to-weibo): add no-theme rule for article markdown-to-HTML conversion	2026-03-23 22:38:30 -05:00
Jim Liu 宝玉	f22374ab62	fix(baoyu-cover-image): simplify reference image handling based on model capability	2026-03-23 22:38:27 -05:00
Jim Liu 宝玉	d4e80b1bc3	Fix Node-compatible parser tests (#107 ) * Fix Node-compatible parser tests * Add parser test dependencies to root test env	2026-03-23 15:30:42 -05:00