@aigne/doc-smith 0.8.15-beta.9 → 0.8.15

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [0.8.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.16...v0.8.15) (2025-11-07)
+
+## [0.8.15-beta.16](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.15...v0.8.15-beta.16) (2025-11-07)
+
+
+### Features
+
+* support customize diagramming quantity ([#277](https://github.com/AIGNE-io/aigne-doc-smith/issues/277)) ([9d9fa6a](https://github.com/AIGNE-io/aigne-doc-smith/commit/9d9fa6a1f344c93df187f2dc502c5479e304e0f4))
+
+## [0.8.15-beta.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.14...v0.8.15-beta.15) (2025-11-07)
+
+
+### Bug Fixes
+
+* add two-tier thinking effort configuration system ([#273](https://github.com/AIGNE-io/aigne-doc-smith/issues/273)) ([b72d066](https://github.com/AIGNE-io/aigne-doc-smith/commit/b72d066698bae253a9ee2dfa231bf73cd59d7529))
+
+## [0.8.15-beta.14](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.13...v0.8.15-beta.14) (2025-11-06)
+
+
+### Features
+
+* add reasoning effort configuration for customizable AI model settings ([#270](https://github.com/AIGNE-io/aigne-doc-smith/issues/270)) ([9f15638](https://github.com/AIGNE-io/aigne-doc-smith/commit/9f156387120e8705bf16cf611d7f8f39995c36b3))
+* **cli:** enhance auth with short link responses and detailed error reporting for publishing ([#269](https://github.com/AIGNE-io/aigne-doc-smith/issues/269)) ([31cc252](https://github.com/AIGNE-io/aigne-doc-smith/commit/31cc25236667236dfe91543acdd7e8cccff659c5))
+
+
+### Bug Fixes
+
+* use default reasoning effort for existing config ([#272](https://github.com/AIGNE-io/aigne-doc-smith/issues/272)) ([2fc9c89](https://github.com/AIGNE-io/aigne-doc-smith/commit/2fc9c89e383c1c5446f2109a2846e831d1e1e871))
+
+## [0.8.15-beta.13](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.12...v0.8.15-beta.13) (2025-11-05)
+
+
+### Bug Fixes
+
+* make paid deployment more smooth stable ([#266](https://github.com/AIGNE-io/aigne-doc-smith/issues/266)) ([ce8c00a](https://github.com/AIGNE-io/aigne-doc-smith/commit/ce8c00ab3eb045c482e07dc3c4e3bd149e754a06))
+* validate docsDir on init and ensure latest doc on view after publish ([#267](https://github.com/AIGNE-io/aigne-doc-smith/issues/267)) ([e45864d](https://github.com/AIGNE-io/aigne-doc-smith/commit/e45864da4a7fb5b09af2bbffdb7ca93abd74397c))
+
+## [0.8.15-beta.12](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.11...v0.8.15-beta.12) (2025-11-05)
+
+
+### Features
+
+* tune token consumption for update ops with intent analysis ([#264](https://github.com/AIGNE-io/aigne-doc-smith/issues/264)) ([8c53d28](https://github.com/AIGNE-io/aigne-doc-smith/commit/8c53d288346ae622e8841866db1b6fbed9d5023d))
+
+## [0.8.15-beta.11](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.10...v0.8.15-beta.11) (2025-11-04)
+
+
+### Features
+
+* warn on invalid sources and tuning translate messages ([#241](https://github.com/AIGNE-io/aigne-doc-smith/issues/241)) ([bd786ca](https://github.com/AIGNE-io/aigne-doc-smith/commit/bd786cad8b0c6fa837511fdc2982c83b7f0095dd))
+
+
+### Bug Fixes
+
+* avoid useless diagram generate ([#245](https://github.com/AIGNE-io/aigne-doc-smith/issues/245)) ([de7600f](https://github.com/AIGNE-io/aigne-doc-smith/commit/de7600fb5839be9d1f0743adc34fd08c4c11729d))
+* iterate on chunk of datasource to generate structure ([#242](https://github.com/AIGNE-io/aigne-doc-smith/issues/242)) ([0b4db2a](https://github.com/AIGNE-io/aigne-doc-smith/commit/0b4db2a8cac77d6f4a1c197374b9dadbe078346b))
+
+## [0.8.15-beta.10](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.9...v0.8.15-beta.10) (2025-11-03)
+
+
+### Bug Fixes
+
+* remove empty xml tag in prompt ([#239](https://github.com/AIGNE-io/aigne-doc-smith/issues/239)) ([1ec771e](https://github.com/AIGNE-io/aigne-doc-smith/commit/1ec771eb8855bca3730f732a1b68404275633787))
+* standardized variable names and xml tag usage ([#237](https://github.com/AIGNE-io/aigne-doc-smith/pull/237))([00f18b9](https://github.com/AIGNE-io/aigne-doc-smith/commit/00f18b95ba21cd376e369eefb102d2d258e95529))
+
 ## [0.8.15-beta.9](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.8...v0.8.15-beta.9) (2025-11-03)
 
 

package/agents/evaluate/document-structure.yaml

@@ -2,7 +2,9 @@ name: evaluateDocumentStructure
 description: Evaluates the results generated by the document-structure agent to ensure they meet expectations, especially in scenarios with previous generation results and user feedback.
 instructions:
   url: ../../prompts/evaluate/document-structure.md
-model: openai/gpt-5
+model:
+  model: openai/gpt-5
+  temperature: 1
 # model: anthropic/claude-opus-4-0
 task_render_mode: collapse
 task_title: Evaluate the structure of the documentation

package/agents/evaluate/document.yaml

@@ -2,7 +2,9 @@ name: evaluateDocument
 description: Evaluates the quality of generated document content, ensuring compliance with user-configured goals, audiences, and knowledge level requirements.
 instructions:
   url: ../../prompts/evaluate/document.md
-model: openai/gpt-5
+model:
+  model: openai/gpt-5
+  temperature: 1
 # model: anthropic/claude-opus-4-0
 task_render_mode: collapse
 task_title: Evaluate document for '{{ title }}'

package/agents/generate/generate-structure.yaml

@@ -4,11 +4,9 @@ description: Generate the structure and organization of your documentation
 skills:
   - type: team
     name: generateStructureWorker
-    iterate_on: datasources
+    iterate_on: dataSources
     skills:
       - type: ai
-        model:
-          reasoning_effort: 500
         instructions:
           - role: system
             url: ../../prompts/structure/generate/system-prompt.md
@@ -82,8 +80,6 @@ skills:
 
   - type: ai
     name: refineStructure
-    model:
-      reasoning_effort: 500
     instructions:
       - role: system
         url: ../../prompts/structure/review/structure-review-system.md

package/agents/generate/merge-diagram.yaml

@@ -3,13 +3,13 @@ description: Merge Diagram source code into document
 instructions: |
   You are an AI assistant that helps to merge d2 diagram into document.
 
-  <detail_dataSource>
+  <detail_data_source>
   {{ content }}
-  </detail_dataSource>
+  </detail_data_source>
 
-  <diagramSourceCode>
+  <diagram_source_code>
   {{ diagramSourceCode }}
-  </diagramSourceCode>
+  </diagram_source_code>
 
   Given the source content of a document and the D2 diagram source code, your task is to:
   - **Keep the original content as soon as possible.**

package/agents/generate/update-document-structure.yaml

@@ -1,48 +1,54 @@
-type: ai
+type: team
 name: updateDocumentStructure
 description: Update documentation structure based on user feedback and intentions using structure modification tools
-instructions:
-  - role: system
-    url: ../../prompts/structure/update/system-prompt.md
-  - role: user
-    url: ../../prompts/structure/update/user-prompt.md
-input_schema:
-  type: object
-  properties:
-    documentStructure: ../schema/document-structure.yaml
-    rules:
-      type: string
-      description: User configuration rules
-    locale:
-      type: string
-      description: User language, e.g. zh, en
-    dataSourceChunk:
-      type: string
-      description: Context for documentation structure
-    glossary:
-      type: string
-      description: Glossary of terms
-    feedback:
-      type: string
-      description: User feedback for structure modifications
-    userPreferences:
-      type: string
-      description: Your saved preferences for structure and documentation style
-  required:
-    - documentStructure
-    - feedback
-output_key: message
-afs:
-  modules:
-    - module: system-fs
-      options:
-        mount: /sources
-        path: .
-        description: |
-          Codebase of the project to be documented used as context for document generation,
-          should search and read as needed while generating document content
 skills:
-  - ./document-structure-tools/add-document.mjs
-  - ./document-structure-tools/delete-document.mjs
-  - ./document-structure-tools/update-document.mjs
-  - ./document-structure-tools/move-document.mjs
+  - url: ../utils/analyze-feedback-intent.yaml
+  - type: ai
+    instructions:
+      - role: system
+        url: ../../prompts/structure/update/system-prompt.md
+      - role: user
+        url: ../../prompts/structure/update/user-prompt.md
+    input_schema:
+      type: object
+      properties:
+        documentStructure: ../schema/document-structure.yaml
+        rules:
+          type: string
+          description: User configuration rules
+        locale:
+          type: string
+          description: User language, e.g. zh, en
+        dataSourceChunk:
+          type: string
+          description: Context for documentation structure
+        glossary:
+          type: string
+          description: Glossary of terms
+        feedback:
+          type: string
+          description: User feedback for structure modifications
+        userPreferences:
+          type: string
+          description: Your saved preferences for structure and documentation style
+        needDataSources:
+          type: boolean
+          description: Whether data sources are needed for content modifications
+      required:
+        - documentStructure
+        - feedback
+    output_key: message
+    afs:
+      modules:
+        - module: system-fs
+          options:
+            mount: /sources
+            path: .
+            description: |
+              Codebase of the project to be documented used as context for document generation,
+              should search and read as needed while generating document content
+    skills:
+      - ./document-structure-tools/add-document.mjs
+      - ./document-structure-tools/delete-document.mjs
+      - ./document-structure-tools/update-document.mjs
+      - ./document-structure-tools/move-document.mjs

package/agents/generate/user-review-document-structure.mjs

@@ -1,32 +1,9 @@
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { recordUpdate } from "../../utils/history-utils.mjs";
+import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
 
 function formatDocumentStructure(structure) {
-  // Create a map of nodes for easy lookup
-  const nodeMap = new Map();
-  const rootNodes = [];
-
-  // First pass: create node map
-  structure.forEach((node) => {
-    nodeMap.set(node.path, {
-      ...node,
-      children: [],
-    });
-  });
-
-  // Build the tree structure
-  structure.forEach((node) => {
-    if (node.parentId) {
-      const parent = nodeMap.get(node.parentId);
-      if (parent) {
-        parent.children.push(nodeMap.get(node.path));
-      } else {
-        rootNodes.push(nodeMap.get(node.path));
-      }
-    } else {
-      rootNodes.push(nodeMap.get(node.path));
-    }
-  });
+  const { rootNodes } = buildDocumentTree(structure);
 
   function printNode(node, depth = 0) {
     const INDENT_SPACES = "  ";
@@ -140,7 +117,7 @@ export default async function userReviewDocumentStructure({ documentStructure, .
       // Call refineDocumentStructure agent with feedback
       await options.context.invoke(refineAgent, {
         ...rest,
-        dataSourceChunk: rest.datasources[0].dataSourceChunk,
+        dataSourceChunk: rest.dataSources[0].dataSourceChunk,
         feedback: feedback.trim(),
         documentStructure: currentStructure,
         userPreferences,

package/agents/generate/utils/merge-document-structures.mjs

@@ -11,13 +11,13 @@ export default async function mergeDocumentStructures(input, options) {
 
   options.context.userContext.originalDocumentStructure ??= [];
 
-  const originalStructures = options.context.userContext.originalDocumentStructure;
+  const originalStructures = [...options.context.userContext.originalDocumentStructure];
 
   if (input.structures) {
     for (const item of input.structures) {
-      const old = originalStructures.find((s) => s.path === item.path);
-      if (old) {
-        Object.assign(old, item);
+      const index = originalStructures.findIndex((s) => s.path === item.path);
+      if (index !== -1) {
+        originalStructures[index] = item;
       } else {
         originalStructures.push(item);
       }

package/agents/init/check.mjs

@@ -6,7 +6,7 @@ export default async function checkNeedGenerate({ docsDir, locale, documentExecu
 
   if (mainLanguageFiles.length === 0) {
     console.log(
-      `No documents found in the docs directory. Please run ${chalk.yellow("`aigne doc generate`")} to generate the documents`,
+      `No documents found in the docs directory. You can generate them with ${chalk.yellow("`aigne doc generate`")}`,
     );
     process.exit(0);
   }

package/agents/init/index.mjs

@@ -4,6 +4,8 @@ import chalk from "chalk";
 import { stringify as yamlStringify } from "yaml";
 import { getFilteredOptions } from "../../utils/conflict-detector.mjs";
 import {
+  DEFAULT_REASONING_EFFORT_LEVEL,
+  DEFAULT_THINKING_EFFORT_LEVEL,
   DEPTH_RECOMMENDATION_LOGIC,
   DOCUMENT_STYLES,
   DOCUMENTATION_DEPTH,
@@ -21,6 +23,8 @@ import {
   validatePath,
 } from "../../utils/utils.mjs";
 import { isRemoteFile } from "../../utils/file-utils.mjs";
+import { validateDocDir } from "./validate.mjs";
+import mapReasoningEffortLevel from "../utils/map-reasoning-effort-level.mjs";
 
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
@@ -31,7 +35,23 @@ const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
  * @param {string} params.fileName - The name of the file.
  * @returns {Promise<Object>}
  */
-export default async function init(
+export default async function init(input, options) {
+  const config = await _init(input, options);
+
+  // Set thinking effort (lite/standard/pro) and map to reasoningEffort
+  options.context.userContext.thinkingEffort =
+    config.thinking?.effort || DEFAULT_THINKING_EFFORT_LEVEL;
+
+  // Set global reasoningEffort based on thinkingEffort
+  options.context.userContext.reasoningEffort = mapReasoningEffortLevel(
+    { level: DEFAULT_REASONING_EFFORT_LEVEL },
+    options,
+  )?.reasoningEffort;
+
+  return config;
+}
+
+async function _init(
   {
     outputPath = ".aigne/doc-smith",
     fileName = "config.yaml",
@@ -64,7 +84,19 @@ export default async function init(
     // Only skip if file exists AND has non-empty content
     if (configContent && configContent.trim() !== "") {
       // load config from file
-      return loadConfig({ config: filePath, appUrl });
+      const config = await loadConfig({ config: filePath, appUrl });
+      const isValid = validateDocDir(config.docsDir);
+      if (typeof isValid === "string") {
+        console.log(
+          `${chalk.red("Invalid docsDir")}: ${isValid}\nPlease check your configuration.`,
+        );
+        process.exit(1);
+      }
+      if (!isValid) {
+        console.log(`${chalk.red("Invalid docsDir")}, please check your configuration.`);
+        process.exit(1);
+      }
+      return config;
     }
   }
 
@@ -241,6 +273,7 @@ export default async function init(
   const docsDirInput = await options.prompts.input({
     message: `📁 [7/9]: Where should we save your documentation?`,
     default: `${outputPath}/docs`,
+    validate: validateDocDir,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
@@ -424,6 +457,10 @@ export function generateYAML(input) {
     projectDesc: input.projectDesc || "",
     projectLogo: input.projectLogo || "",
 
+    thinking: {
+      effort: input.thinking?.effort || DEFAULT_THINKING_EFFORT_LEVEL,
+    },
+
     // Documentation configuration
     documentPurpose: input.documentPurpose || [],
     targetAudienceTypes: input.targetAudienceTypes || [],
@@ -459,6 +496,19 @@ export function generateYAML(input) {
 
   yaml += `${projectSection}\n\n`;
 
+  const modelSection = yamlStringify({
+    thinking: config.thinking,
+  }).trim();
+
+  yaml += `\
+# AI Thinking Configuration
+# thinking.effort: Determines the depth of reasoning and cognitive effort the AI uses when responding, available options:
+#   - lite: Fast responses with basic reasoning
+#   - standard: Balanced speed and reasoning capability
+#   - pro: In-depth reasoning with longer response times
+${modelSection}
+\n`;
+
   // Add documentation configuration with comments
   yaml += "# =============================================================================\n";
   yaml += "# Documentation Configuration\n";

package/agents/init/validate.mjs

@@ -0,0 +1,16 @@
+import path from "node:path";
+export function validateDocDir(input) {
+  const currentDir = process.cwd();
+  const targetDir = path.resolve(input);
+  const relativePath = path.relative(currentDir, targetDir);
+  if (relativePath.length === 0) {
+    return `Can't use current directory: ${targetDir}`;
+  }
+  if (relativePath.startsWith("..")) {
+    return `Can't use directory outside current directory: ${targetDir}`;
+  }
+  if (path.isAbsolute(relativePath)) {
+    return `Can't use absolute path: ${targetDir}`;
+  }
+  return true;
+}

package/agents/publish/publish-docs.mjs

@@ -163,8 +163,13 @@ export default async function publishDocs(
           } else {
             console.log(`\nCreating a new website for your documentation...`);
           }
-          const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentLink)) || {};
+          const {
+            appUrl: homeUrl,
+            token: ltToken,
+            sessionId: newSessionId,
+          } = (await deploy(id, paymentLink)) || {};
 
+          sessionId = newSessionId;
           appUrl = homeUrl;
           token = ltToken;
         } catch (error) {
@@ -174,13 +179,7 @@ export default async function publishDocs(
       }
     }
 
-    if (sessionId) {
-      authToken = await getOfficialAccessToken(BASE_URL, false);
-      client = client || new BrokerClient({ baseUrl: BASE_URL, authToken });
-
-      const { vendors } = await client.getSessionDetail(sessionId, false);
-      token = vendors?.find((vendor) => vendor.vendorType === "launcher" && vendor.token)?.token;
-    }
+    appUrl = appUrl ?? CLOUD_SERVICE_URL_PROD;
 
     console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
 
@@ -264,8 +263,15 @@ export default async function publishDocs(
       await saveValueToConfig("shouldSyncBranding", "", "Should sync branding for documentation");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
-      if (error?.includes("401") || error?.includes("403")) {
-        message = `❌ Publishing failed due to an authorization error. Please run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+      try {
+        const obj = JSON.parse(error);
+        message = `❌ Publishing failed with error: \n💡 ${obj.message || error}`;
+      } catch {
+        if (error?.includes("401")) {
+          message = `❌ Publishing failed due to an authorization error: \n💡 Please run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+        } else if (error?.includes("403")) {
+          message = `❌ Publishing failed due to an authorization error: \n💡 You’re not the creator of this document (Board ID: ${boardId}). You can change the board ID and try again. \n💡  Or run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+        }
       }
     }
 

package/agents/schema/document-execution-structure.yaml

@@ -25,7 +25,7 @@ items:
       type: array
       items:
         type: string
-      description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, cannot be empty
+      description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, cannot be empty
   required:
     - title
     - description

package/agents/schema/document-structure-item.yaml

@@ -13,7 +13,7 @@ properties:
     description: Parent node path, if null indicates it is a top-level node
   sourceIds:
     type: array
-    description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, **cannot be empty**
+    description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, **cannot be empty**
     items:
       type: string
 required:

package/agents/schema/document-structure.yaml

@@ -10,11 +10,13 @@ items:
       type: string
       description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
     parentId:
-      type: string
+      type:
+        - string
+        - "null"
       description: Parent node path, if null indicates it is a top-level node
     sourceIds:
       type: array
-      description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, **cannot be empty**
+      description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, **cannot be empty**
       items:
         type: string
   required:

package/agents/update/check-generate-diagram.mjs

@@ -1,26 +1,84 @@
-const placeholder = "DIAGRAM_PLACEHOLDER";
+const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+const DEFAULT_DIAGRAMMING_EFFORT = 5;
+const MIN_DIAGRAMMING_EFFORT = 0;
+const MAX_DIAGRAMMING_EFFORT = 10;
 
 export default async function checkGenerateDiagram(
-  { needDiagram, documentContent, locale },
+  {
+    documentContent,
+    locale,
+    feedback,
+    detailFeedback,
+    originalContent,
+    path: docPath,
+    diagramming,
+  },
   options,
 ) {
-  if (!needDiagram) {
-    return {};
+  let content = documentContent;
+  let diagramSourceCode;
+  let skipGenerateDiagram = false;
+
+  const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
+
+  const preCheckResult = await options.context.invoke(preCheckAgent, {
+    documentContent,
+    feedback,
+    detailFeedback,
+    previousGenerationContent: originalContent,
+  });
+
+  const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
+  if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
+    content = preCheckResult.content;
   }
 
-  const generateAgent = options.context?.agents?.["generateDiagram"];
-  let content = documentContent;
+  let diagrammingEffort = diagramming?.effort
+    ? Number(diagramming?.effort)
+    : DEFAULT_DIAGRAMMING_EFFORT;
 
-  try {
-    const { diagramSourceCode } = await options.context.invoke(generateAgent, {
-      documentContent,
-      locale,
-    });
-    content = content.replace(placeholder, diagramSourceCode);
-  } catch (error) {
-    // FIXME: @zhanghan should regenerate document without diagram
-    content = content.replace(placeholder, "");
-    console.log(`⚠️  Skip generate any diagram: ${error.message}`);
+  if (Number.isNaN(diagrammingEffort)) {
+    diagrammingEffort = DEFAULT_DIAGRAMMING_EFFORT;
+  } else {
+    diagrammingEffort = Math.min(
+      Math.max(MIN_DIAGRAMMING_EFFORT, diagrammingEffort),
+      MAX_DIAGRAMMING_EFFORT,
+    );
   }
+
+  if (totalScore <= diagrammingEffort) {
+    skipGenerateDiagram = true;
+  }
+
+  if (skipGenerateDiagram) {
+    content = documentContent;
+  } else {
+    try {
+      const generateAgent = options.context?.agents?.["generateDiagram"];
+      ({ diagramSourceCode } = await options.context.invoke(generateAgent, {
+        documentContent: content,
+        locale,
+      }));
+    } catch (error) {
+      diagramSourceCode = "";
+      skipGenerateDiagram = true;
+      console.log(`⚠️  Skip generate any diagram for ${docPath}: ${error.message}`);
+    }
+
+    if (diagramSourceCode && !skipGenerateDiagram) {
+      if (content.includes(PLACEHOLDER)) {
+        content = content.replace(PLACEHOLDER, diagramSourceCode);
+      } else {
+        const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
+        ({ content } = await options.context.invoke(mergeAgent, {
+          diagramSourceCode,
+          content,
+        }));
+      }
+    } else {
+      content = documentContent;
+    }
+  }
+
   return { content };
 }

package/agents/update/generate-document.yaml

@@ -46,19 +46,7 @@ input_schema:
     - rules
     - detailDataSource
     - originalDocumentStructure
-# output_key: content
-output_schema:
-  type: object
-  properties:
-    content:
-      type: string
-      description: Document content
-    needDiagram:
-      type: boolean
-      description: Does this document need to generate diagram?
-  required:
-    - content
-    - detailDataSource
+output_key: content
 afs:
   modules:
     - module: system-fs

package/agents/update/handle-document-update.yaml

@@ -2,7 +2,7 @@ type: team
 name: handleDocumentUpdate
 description: Update a document in a batch
 skills:
-  - ../utils/transform-detail-datasources.mjs
+  - ../utils/transform-detail-data-sources.mjs
   - type: team
     task_render_mode: collapse
     name: generateDocumentContent