@leeguoo/yapi-mcp 0.4.0 → 0.4.1

package/README.md

@@ -54,27 +54,46 @@ Yapi Auto MCP Server 是一个基于 [Model Context Protocol](https://modelconte
 
 ### 推荐方式：用 Cross Request Master 一键安装 Skill（免手动找 Token）
 
-如果你日常就在浏览器里使用 YApi，推荐安装 Chrome 扩展 [cross-request-master](https://github.com/leeguooooo/cross-request-master)。它会在 YApi 接口详情页（基本信息区域右上角）提供 **「YApi 工具箱」** 按钮，包含 Skill 一键安装（推荐）/MCP 配置（兼容）/CLI docs-sync 说明；另外保留 **「复制给 AI」** 一键复制接口 Markdown：
+如果你日常就在浏览器里使用 YApi，推荐安装 Chrome 扩展 [cross-request-master](https://github.com/leeguooooo/cross-request-master)。它会在 YApi 接口详情页（基本信息区域右上角）提供 **「YApi 工具箱」** 按钮，包含 Skill 一键安装（推荐，支持 `npx skills add`）/MCP 配置（兼容）/CLI docs-sync 说明；另外保留 **「复制给 AI」** 一键复制接口 Markdown：
 
-- Skill 一键安装（推荐）：生成 Codex/Claude Skill，并写入全局配置 `~/.yapi/config.toml`
+- Skill 一键安装（推荐）：优先生成 `npx skills add` 命令安装仓库导出的 Skill，再配合 `yapi config init` 初始化全局配置；如需一步写入配置，保留 `yapi install-skill` 兼容路径
 - MCP 配置（兼容）：使用 `--yapi-auth-mode=global`（账号密码），默认会自动懒登录；也可手动调用一次 `yapi_update_token` 预热缓存
 - CLI 使用与 docs-sync：提供本地 CLI 安装命令和文档同步示例
 
 ### Skill 一键安装与 CLI
 
-一条命令把 Skill 安装到 Codex / Claude Code / Cursor，并写入 `~/.yapi/config.toml`（缺省会提示输入）：
+推荐先用 `skills` 安装仓库导出的 Skill：
 
 ```bash
-# 推荐：全局安装后使用 yapi 命令
+# 推荐：把仓库里的 yapi Skill 装到全局 agent 目录
+npx skills add leeguooooo/cross-request-master -y -g
+```
+
+这条命令只负责安装 Skill 文件，不会写入 `~/.yapi/config.toml`。如果你还没有本地配置，继续执行下面任一方式：
+
+```bash
+# 方式一：推荐单独初始化配置
 npm install -g @leeguoo/yapi-mcp
+yapi config init \
+  --base-url=https://your-yapi-domain.com \
+  --auth-mode=global \
+  --email=your_email@example.com
 
+# 如未保存密码，首次再同步一次浏览器登录态
+yapi login --base-url=https://your-yapi-domain.com --browser
+```
+
+也可以继续使用兼容命令，在安装 Skill 的同时写入 `~/.yapi/config.toml`：
+
+```bash
+npm install -g @leeguoo/yapi-mcp
 yapi install-skill \
   --yapi-base-url=https://your-yapi-domain.com \
   --yapi-email=your_email@example.com \
   --yapi-password=your_password
 ```
 
-也可以用 npx 临时运行（不全局安装）：
+也可以用 npx 临时运行兼容命令（不全局安装）：
 
 ```bash
 npx -y -p @leeguoo/yapi-mcp yapi install-skill \
@@ -83,22 +102,20 @@ npx -y -p @leeguoo/yapi-mcp yapi install-skill \
   --yapi-password=your_password
 ```
 
-Skill 安装目录：
-- Codex: `~/.codex/skills/yapi/`
-- Claude Code: `~/.claude/skills/yapi/`
-- Cursor: `~/.cursor/skills/yapi/`
+`skills` CLI 会维护一份规范化安装副本，并按目标 agent 建立链接/映射。当前全局安装通常可在 `~/.agents/skills/yapi/` 看到 canonical copy，具体 agent 侧落点由 `skills` CLI 决定。
 
-Skill 模板来源：`packages/yapi-mcp/skill-template/SKILL.md`（发布后从包内复制到技能目录）。
+仓库导出的 Skill 来源：`skills/yapi/SKILL.md`（供 `npx skills add` 发现）。
+npm 包内安装模板来源：`packages/yapi-mcp/skill-template/SKILL.md`（供 `yapi install-skill` 复制到技能目录）。
 后续当 CLI 升级而本地 Skill 仍是旧版本时，`yapi` 会自动提示：
 
 ```bash
-skill update available: installed Codex@0.3.24, current 0.3.25. Run: yapi install-skill --force
+skill update available: installed Codex@0.3.24, current 0.3.25. Run: npx skills add leeguooooo/cross-request-master -y -g
 ```
 
 也可以手动重装 Skill：
 
 ```bash
-yapi install-skill --force
+npx skills add leeguooooo/cross-request-master -y -g
 ```
 
 ### CLI 使用
@@ -106,13 +123,14 @@ yapi install-skill --force
 推荐全局安装后直接使用 `yapi` 命令（走同一份 `~/.yapi/config.toml`）：
 
 当前 CLI 能力补充：
+- 支持 `yapi config init`：单独初始化/更新 `~/.yapi/config.toml`，适合和 `npx skills add` 组合使用
 - 支持 `yapi login --browser`：通过 `agent-browser-stealth` 打开页面，登录后自动同步 `_yapi_token/_yapi_uid` 到本地缓存
 - 默认打开 `base-url` 首页（不强制 `/login`），适配“已登录可直接拿 Cookie”的场景
 - 支持 `yapi login --login-url <url>` 指定登录页
 - 支持 `yapi logout` 清理当前 `base_url` 对应的全局会话缓存
 - 适用于 SSO/额外验证体系：无法使用账号密码时可只走浏览器登录
 - 支持 `yapi self-update` 升级全局 CLI
-- 当已安装的 Skill 版本落后于当前 CLI 时，会自动提示重新执行 `yapi install-skill --force`
+- 当已安装的 Skill 版本落后于当前 CLI 时，会自动提示重新执行 `npx skills add leeguooooo/cross-request-master -y -g`
 
 ```bash
 # 检查版本
@@ -194,12 +212,14 @@ yapi docs-sync
 - 绑定模式同步后会写入 `.yapi/docs-sync.deployments.json`（本地文档 → 已部署 URL）
 - 兼容旧方式：`--dir` 读取目录内 `.yapi.json` 的 `project_id/catid` 与 `source_files`
 - 管理绑定：`yapi docs-sync bind list|get|add|update|remove`
+- 也可以在运行时临时过滤文件：`yapi docs-sync --binding projectA --source-file architecture.md`；优先级是 `--source-file` > 绑定里的 `source_files` > 目录全量扫描
 - `--query` 支持像 curl 一样写成单个字符串：`--query "catid=4631&limit=50&page=1"`
 - 可用 `--dry-run` 只做预览不更新；现在会输出每个文件的 Markdown/HTML/请求体大小，并提前暴露超大文档风险
 - 默认只同步内容变更的文件，如需全量更新使用 `--force`
 - 普通同步命中相同 `file_hashes` 时会在渲染前直接跳过，不再重复渲染 Mermaid / PlantUML / Graphviz / D2；`--dry-run` 仍会保留预览渲染
-- 如果上传返回 `413 Payload Too Large`，CLI 会显示当前请求大小、解析出的服务端限制值（如果响应里有）、以及最大的 Mermaid 块大小，并建议先拆分文档
+- 如果上传返回 `413 Payload Too Large`，CLI 会按 `默认 Mermaid -> --mermaid-classic -> --no-mermaid` 自动降级；某个文件一旦降级成功，会把该模式记住，后续同步优先直接使用，避免每次先撞一次 413
 - Mermaid 预渲染依赖 `mmdc`（默认手绘风格；安装时会尝试拉取，失败不影响同步）
+- 如果 `mmdc` 已安装但提示缺少 `chrome-headless-shell` / Puppeteer 浏览器，执行：`npx puppeteer browsers install chrome-headless-shell`
 - PlantUML 预渲染依赖 `plantuml`（需要本机 Java 环境）
 - Graphviz 预渲染依赖 `dot`（graphviz）
 - D2 预渲染依赖 `d2`（默认手绘风格输出）

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const REQUIRED_DEPS = ["yargs", "axios"];
+const missing = [];
+for (const dep of REQUIRED_DEPS) {
+    try {
+        require.resolve(dep);
+    }
+    catch {
+        missing.push(dep);
+    }
+}
+if (missing.length > 0) {
+    const path = require("path");
+    const pkgDir = path.resolve(__dirname, "..");
+    const lines = [
+        `[yapi-cli] Missing runtime dependencies: ${missing.join(", ")}`,
+        "",
+        "This usually means the package directory has no node_modules installed.",
+        "",
+        "To fix, run one of the following in the package directory:",
+        `  cd "${pkgDir}"`,
+        "  pnpm install           # if using pnpm (recommended for this repo)",
+        "  # or",
+        "  npm install            # if using npm",
+        "",
+        "If you installed @leeguoo/yapi-mcp globally, try reinstalling:",
+        "  npm i -g @leeguoo/yapi-mcp",
+    ];
+    console.error(lines.join("\n"));
+    process.exit(1);
+}
+require("./yapi-cli");
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";;;AAQA,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEzC,MAAM,OAAO,GAAa,EAAE,CAAC;AAC7B,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAA0B,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG;QACZ,4CAA4C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAChE,EAAE;QACF,yEAAyE;QACzE,EAAE;QACF,4DAA4D;QAC5D,SAAS,MAAM,GAAG;QAClB,sEAAsE;QACtE,QAAQ;QACR,yCAAyC;QACzC,EAAE;QACF,gEAAgE;QAChE,8BAA8B;KAC/B,CAAC;IAEF,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAGD,OAAO,CAAC,YAAY,CAAC,CAAC"}

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,2 @@
+import type { Options } from "../types";
+export declare function runConfig(action: string, options: Options): Promise<number>;

package/dist/cli/commands/config.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConfig = runConfig;
+const fs_1 = __importDefault(require("fs"));
+const utils_1 = require("../utils");
+function resolveAuthMode(explicit, existing, merged) {
+    const normalized = String(explicit || existing.auth_mode || "").trim().toLowerCase();
+    if (!normalized) {
+        return merged.token ? "token" : "global";
+    }
+    if (normalized === "token" || normalized === "global")
+        return normalized;
+    return null;
+}
+async function runConfig(action, options) {
+    const normalizedAction = String(action || "init").trim().toLowerCase() || "init";
+    if (normalizedAction !== "init") {
+        console.error(`unknown config action: ${normalizedAction}`);
+        return 2;
+    }
+    const configPath = options.config || (0, utils_1.globalConfigPath)();
+    const existing = fs_1.default.existsSync(configPath)
+        ? (0, utils_1.parseSimpleToml)(fs_1.default.readFileSync(configPath, "utf8"))
+        : {};
+    const merged = { ...existing };
+    if (options.baseUrl !== undefined)
+        merged.base_url = options.baseUrl;
+    if (options.email !== undefined)
+        merged.email = options.email;
+    if (options.password !== undefined)
+        merged.password = options.password;
+    if (options.token !== undefined)
+        merged.token = options.token;
+    if (options.projectId !== undefined)
+        merged.project_id = options.projectId;
+    if (!merged.base_url) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error("missing --base-url");
+            return 2;
+        }
+        merged.base_url = await (0, utils_1.promptRequired)("YApi base URL: ", false);
+    }
+    const authMode = resolveAuthMode(options.authMode || "", existing, merged);
+    if (!authMode) {
+        console.error("invalid --auth-mode (use token or global)");
+        return 2;
+    }
+    merged.auth_mode = authMode;
+    merged.email = merged.email || "";
+    merged.password = merged.password || "";
+    merged.token = merged.token || "";
+    merged.project_id = merged.project_id || "";
+    (0, utils_1.writeConfig)(configPath, merged);
+    console.log(`Config written to: ${configPath}`);
+    if (authMode === "global" && !merged.password) {
+        console.log("Global auth configured without saved password. Run `yapi login --base-url <url> --browser` once to sync cookie, or rerun with --password to enable password relogin.");
+    }
+    if (authMode === "token" && !merged.token) {
+        console.log("Token mode configured without token. Pass --token now or set it later before requests.");
+    }
+    return 0;
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/commands/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/docs-sync.js

@@ -149,20 +149,6 @@ function saveDocsSyncDeployments(homeDir, config) {
     const configPath = docsSyncDeploymentsPath(homeDir);
     fs_1.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
-function resolveBindingDir(rootDir, bindingDir) {
-    if (!bindingDir)
-        return rootDir;
-    return path_1.default.isAbsolute(bindingDir) ? bindingDir : path_1.default.resolve(rootDir, bindingDir);
-}
-function normalizeBindingDir(rootDir, bindingDir) {
-    const resolved = resolveBindingDir(rootDir, bindingDir);
-    const relative = path_1.default.relative(rootDir, resolved);
-    if (!relative || relative === ".")
-        return ".";
-    if (relative.startsWith("..") || path_1.default.isAbsolute(relative))
-        return resolved;
-    return relative;
-}
 function getBindingBaseDir(homeDir, rootDir, cwd) {
     if (!isGlobalDocsSyncHome(homeDir)) {
         return { baseDir: rootDir, gitRoot: (0, utils_1.findGitRoot)(cwd), usedGitRoot: false };
@@ -241,6 +227,26 @@ function resolveSourceFiles(dirPath, mapping) {
         return resolved;
     });
 }
+function cloneMappingForSync(mapping, sourceFiles) {
+    const next = {
+        ...mapping,
+        files: mapping.files ? { ...mapping.files } : {},
+        file_hashes: mapping.file_hashes ? { ...mapping.file_hashes } : {},
+        file_render_modes: mapping.file_render_modes ? { ...mapping.file_render_modes } : {},
+    };
+    if (sourceFiles?.length) {
+        next.source_files = [...sourceFiles];
+    }
+    return next;
+}
+function mergeSyncState(target, source) {
+    target.project_id = source.project_id;
+    target.catid = source.catid;
+    target.template_id = source.template_id;
+    target.files = source.files ? { ...source.files } : {};
+    target.file_hashes = source.file_hashes ? { ...source.file_hashes } : {};
+    target.file_render_modes = source.file_render_modes ? { ...source.file_render_modes } : {};
+}
 async function listExistingInterfaces(catId, request) {
     const resp = await request("/api/interface/list_cat", "GET", {
         catid: catId,
@@ -319,7 +325,7 @@ function buildDocsSyncPreviewLine(item) {
     }
     return `preview ${parts.join(" ")}`;
 }
-function buildDocsSyncPayloadTooLargeMessage(fileName, preview, error) {
+function buildDocsSyncPayloadTooLargeMessage(fileName, preview, error, attempts = []) {
     const lines = [
         `413 Payload Too Large while syncing ${fileName}`,
         `- request payload: ${(0, utils_1.formatBytes)(preview.payloadBytes)}`,
@@ -339,10 +345,85 @@ function buildDocsSyncPayloadTooLargeMessage(fileName, preview, error) {
     else {
         lines.push("- largest Mermaid block: none");
     }
+    attempts.forEach((attempt) => {
+        if (attempt.mode === "default")
+            return;
+        const label = attempt.mode === "classic" ? "--mermaid-classic" : "--no-mermaid";
+        if (attempt.payloadBytes && attempt.htmlBytes) {
+            lines.push(`- retry with ${label}: payload=${(0, utils_1.formatBytes)(attempt.payloadBytes)} html=${(0, utils_1.formatBytes)(attempt.htmlBytes)}`);
+        }
+        if (attempt.message) {
+            lines.push(`- ${label} retry result: ${attempt.message}`);
+        }
+    });
     lines.push("- suggestion: run `yapi docs-sync --dry-run ...` to preview all files before upload");
     lines.push("- suggestion: split oversized Mermaid diagrams or move them into separate docs");
+    lines.push("- suggestion: if even `--no-mermaid` still hits 413, the remaining limit is on the YApi server/proxy side");
     return lines.join("\n");
 }
+function resolveRenderModeLabel(mode) {
+    if (mode === "classic")
+        return "--mermaid-classic";
+    if (mode === "no-mermaid")
+        return "--no-mermaid";
+    return "default Mermaid rendering";
+}
+function resolveDocsSyncOptionsForMode(options, mode) {
+    if (mode === "classic") {
+        return {
+            ...options,
+            noMermaid: false,
+            mermaidLook: "classic",
+        };
+    }
+    if (mode === "no-mermaid") {
+        return {
+            ...options,
+            noMermaid: true,
+        };
+    }
+    return { ...options };
+}
+function resolveInitialRenderMode(options, rememberedMode) {
+    if (options.noMermaid)
+        return "no-mermaid";
+    if (options.mermaidLook === "classic")
+        return "classic";
+    if (rememberedMode)
+        return rememberedMode;
+    return "default";
+}
+function resolveRetryModes(mode, hasMermaidBlocks) {
+    if (!hasMermaidBlocks)
+        return [];
+    if (mode === "default")
+        return ["classic", "no-mermaid"];
+    if (mode === "classic")
+        return ["no-mermaid"];
+    return [];
+}
+function renderDocsSyncHtml(markdown, options, logPrefix) {
+    let mermaidFailed = false;
+    let diagramFailed = false;
+    const diagramMetrics = [];
+    const html = (0, markdown_1.renderMarkdownToHtml)(markdown, {
+        noMermaid: options.noMermaid,
+        logMermaid: true,
+        mermaidLook: options.mermaidLook,
+        mermaidHandDrawnSeed: options.mermaidHandDrawnSeed,
+        logger: (message) => console.log(`${logPrefix} ${message}`),
+        onDiagramRendered: (metric) => {
+            diagramMetrics.push(metric);
+        },
+        onMermaidError: () => {
+            mermaidFailed = true;
+        },
+        onDiagramError: () => {
+            diagramFailed = true;
+        },
+    });
+    return { html, mermaidFailed, diagramFailed, diagramMetrics };
+}
 async function addInterface(title, apiPath, mapping, request) {
     const projectId = Number(mapping.project_id || 0);
     const catId = Number(mapping.catid || 0);
@@ -432,7 +513,17 @@ async function syncDocsDir(dirPath, mapping, options, request) {
             const resolvedPath = byId[String(docId)]?.path || apiPath;
             fileInfos[relName] = { docId: Number(docId), apiPath: resolvedPath };
         }
-        const contentHash = (0, utils_1.buildDocsSyncHash)(markdown, options);
+        const logPrefix = `[docs-sync:${relName}]`;
+        const hasMermaidBlocks = /```mermaid\s*\r?\n/i.test(markdown);
+        const rememberedMode = !options.noMermaid && options.mermaidLook === "handDrawn"
+            ? mapping.file_render_modes?.[relName]
+            : undefined;
+        let appliedMode = resolveInitialRenderMode(options, rememberedMode);
+        let effectiveOptions = resolveDocsSyncOptionsForMode(options, appliedMode);
+        if (rememberedMode) {
+            console.log(`${logPrefix} using remembered fallback: ${resolveRenderModeLabel(appliedMode)}.`);
+        }
+        let contentHash = (0, utils_1.buildDocsSyncHash)(markdown, effectiveOptions);
         const previousHash = mapping.file_hashes[relName];
         const currentTitle = docId ? byId[String(docId)]?.title : "";
         const titleToUpdate = !docId
@@ -450,26 +541,7 @@ async function syncDocsDir(dirPath, mapping, options, request) {
             skipped += 1;
             continue;
         }
-        const logPrefix = `[docs-sync:${relName}]`;
-        let mermaidFailed = false;
-        let diagramFailed = false;
-        const diagramMetrics = [];
-        const html = (0, markdown_1.renderMarkdownToHtml)(markdown, {
-            noMermaid: options.noMermaid,
-            logMermaid: true,
-            mermaidLook: options.mermaidLook,
-            mermaidHandDrawnSeed: options.mermaidHandDrawnSeed,
-            logger: (message) => console.log(`${logPrefix} ${message}`),
-            onDiagramRendered: (metric) => {
-                diagramMetrics.push(metric);
-            },
-            onMermaidError: () => {
-                mermaidFailed = true;
-            },
-            onDiagramError: () => {
-                diagramFailed = true;
-            },
-        });
+        let { html, mermaidFailed, diagramFailed, diagramMetrics } = renderDocsSyncHtml(markdown, effectiveOptions, logPrefix);
         if (shouldSkipUnchanged) {
             action = "skip";
             skipped += 1;
@@ -494,11 +566,54 @@ async function syncDocsDir(dirPath, mapping, options, request) {
             }
             catch (error) {
                 if (error instanceof http_1.HttpStatusError && error.status === 413) {
-                    throw new Error(buildDocsSyncPayloadTooLargeMessage(relName, preview, error));
+                    const attempts = [];
+                    let resolved = false;
+                    for (const retryMode of resolveRetryModes(appliedMode, hasMermaidBlocks)) {
+                        console.warn(`${logPrefix} 413 received, retrying with ${resolveRenderModeLabel(retryMode)} for this file.`);
+                        const retryAttempt = { mode: retryMode };
+                        attempts.push(retryAttempt);
+                        try {
+                            const retryOptions = resolveDocsSyncOptionsForMode(options, retryMode);
+                            const retryResult = renderDocsSyncHtml(markdown, retryOptions, logPrefix);
+                            const retryPayload = buildUpdatePayload(docId, titleToUpdate, markdown, retryResult.html);
+                            retryAttempt.payloadBytes = Buffer.byteLength(JSON.stringify(retryPayload), "utf8");
+                            retryAttempt.htmlBytes = Buffer.byteLength(retryResult.html, "utf8");
+                            await updateInterface(docId, titleToUpdate, markdown, retryResult.html, request);
+                            html = retryResult.html;
+                            mermaidFailed = retryResult.mermaidFailed;
+                            diagramFailed = retryResult.diagramFailed;
+                            diagramMetrics = retryResult.diagramMetrics;
+                            appliedMode = retryMode;
+                            effectiveOptions = retryOptions;
+                            contentHash = (0, utils_1.buildDocsSyncHash)(markdown, effectiveOptions);
+                            resolved = true;
+                            break;
+                        }
+                        catch (retryError) {
+                            retryAttempt.message =
+                                retryError instanceof Error ? retryError.message : String(retryError);
+                        }
+                    }
+                    if (!resolved) {
+                        throw new Error(buildDocsSyncPayloadTooLargeMessage(relName, preview, error, attempts));
+                    }
+                }
+                else {
+                    throw error;
                 }
-                throw error;
             }
         }
+        if (appliedMode === "default") {
+            if (mapping.file_render_modes) {
+                delete mapping.file_render_modes[relName];
+            }
+        }
+        else {
+            if (!mapping.file_render_modes || typeof mapping.file_render_modes !== "object") {
+                mapping.file_render_modes = {};
+            }
+            mapping.file_render_modes[relName] = appliedMode;
+        }
         if (docId && !mermaidFailed && !diagramFailed) {
             mapping.file_hashes[relName] = contentHash;
         }
@@ -740,6 +855,15 @@ async function runDocsSync(options) {
             console.warn("mmdc not found, Mermaid blocks will stay as code.");
             console.warn("Install mermaid-cli: npm i -g @mermaid-js/mermaid-cli");
         }
+        else if (!options.noMermaid) {
+            const mermaidRuntime = (0, markdown_1.probeMermaidRuntime)({
+                look: options.mermaidLook,
+                handDrawnSeed: options.mermaidHandDrawnSeed,
+            });
+            if (!mermaidRuntime.ok) {
+                console.warn(`mermaid runtime check failed: ${mermaidRuntime.message}`);
+            }
+        }
         if (!(0, markdown_1.isPlantUmlAvailable)()) {
             console.warn("plantuml not found, PlantUML blocks will be removed from HTML.");
             console.warn("Install PlantUML (macOS): brew install plantuml");
@@ -970,12 +1094,14 @@ async function runDocsSync(options) {
                 if (!fs_1.default.existsSync(dirPath) || !fs_1.default.statSync(dirPath).isDirectory()) {
                     throw new Error(`dir not found for binding ${name}: ${dirPath}`);
                 }
-                const result = await syncDocsDir(dirPath, binding, options, request);
+                const runtimeBinding = cloneMappingForSync(binding, options.sourceFiles);
+                const result = await syncDocsDir(dirPath, runtimeBinding, options, request);
                 if (options.dryRun) {
                     console.log(`dry-run preview binding=${name}`);
                     result.previews.forEach((item) => console.log(buildDocsSyncPreviewLine(item)));
                 }
                 console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} preview_only=${result.previewOnly} binding=${name} dir=${dirPath}`);
+                mergeSyncState(binding, runtimeBinding);
                 bindingResults[name] = { binding, files: result.files };
             }
             if (!options.dryRun) {
@@ -990,12 +1116,14 @@ async function runDocsSync(options) {
                     throw new Error(`dir not found: ${dirPath}`);
                 }
                 const { mapping, mappingPath } = loadMapping(dirPath);
-                const result = await syncDocsDir(dirPath, mapping, options, request);
+                const runtimeMapping = cloneMappingForSync(mapping, options.sourceFiles);
+                const result = await syncDocsDir(dirPath, runtimeMapping, options, request);
                 if (options.dryRun) {
                     console.log(`dry-run preview dir=${dirPath}`);
                     result.previews.forEach((item) => console.log(buildDocsSyncPreviewLine(item)));
                 }
                 if (!options.dryRun) {
+                    mergeSyncState(mapping, runtimeMapping);
                     saveMapping(mapping, mappingPath);
                 }
                 console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} preview_only=${result.previewOnly} dir=${dirPath}`);