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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* optimize the draw diagram process ([#234](https://github.com/AIGNE-io/aigne-doc-smith/issues/234)) ([7bdc0d9](https://github.com/AIGNE-io/aigne-doc-smith/commit/7bdc0d939df05b9d31e06ea0f0285ed0eafe74ae))
+* simplify document structure merging and add deletion support ([#235](https://github.com/AIGNE-io/aigne-doc-smith/issues/235)) ([7f10242](https://github.com/AIGNE-io/aigne-doc-smith/commit/7f1024294bde241f41034d3e01a542451030cbdc))
+
 ## [0.8.15-beta.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.7...v0.8.15-beta.8) (2025-11-01)
 
 

package/agents/evaluate/index.yaml

@@ -16,9 +16,7 @@ skills:
       $merge([
         $,
         {
-          "documentStructure": originalDocumentStructure,
-          "datasources": "",
-          "datasourcesList": ""
+          "documentStructure": originalDocumentStructure
         }
       ])
   - ./document-structure.yaml

package/agents/generate/check-diagram.mjs

@@ -9,7 +9,7 @@ export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
   } catch (err) {
     return {
       isValid: false,
-      error: err.message,
+      diagramError: err.message,
     };
   }
 }

package/agents/generate/generate-structure.yaml

@@ -26,7 +26,7 @@ skills:
             locale:
               type: string
               description: Primary language for documentation (e.g., zh, en, ja)
-            datasources:
+            dataSourceChunk:
               type: string
               description: Project content and context to help generate documentation structure
             targetAudience:
@@ -50,7 +50,7 @@ skills:
               default: general
           required:
             - rules
-            - datasources
+            - dataSourceChunk
         output_schema:
           type: object
           properties:
@@ -60,31 +60,10 @@ skills:
             projectDesc:
               type: string
               description: Brief project description generated from content analysis (under 50 words)
-            add:
+            structures:
               type: array
-              description: List of document structure items to add, null or empty array means no addition
-              items:
-                type: object
-                properties:
-                  index:
-                    type: integer
-                    description: Position to insert the new item, null means append to the end
-                  item: ../schema/document-structure-item.yaml
-                required:
-                  - item
-            update:
-              type: array
-              description: List of document structure items to update, replace the item with the same path, null or empty array means no update
-              items:
-                type: object
-                properties:
-                  path:
-                    type: string
-                    description: Path of the document structure item to update or replace
-                  item: ../schema/document-structure-item.yaml
-                required:
-                  - path
-                  - item
+              description: List of document structure items to add or update
+              items: ../schema/document-structure-item.yaml
 
       - ./utils/merge-document-structures.mjs
 
@@ -92,9 +71,10 @@ skills:
     name: aggregateDocumentStructure
     process: |
       return {
-        documentStructure: options.context.userContext.originalDocumentStructure.map(i => ({
+        documentStructure: options.context.userContext.originalDocumentStructure.map((i, index) => ({
           ...i,
           id: i.title.toLowerCase().replace(/\s+/g, '-'),
+          index
         })),
         projectName: options.context.userContext.projectName,
         projectDesc: options.context.userContext.projectDesc,
@@ -110,29 +90,12 @@ skills:
     output_schema:
       type: object
       properties:
-        refinedStructure:
+        structures:
           type: array
-          description: Optimized document structure array
-          items:
-            type: object
-            description: Document structure item representing a node in the document hierarchy
-            properties:
-              id:
-                type: string
-                description: Unique identifier for the document structure item
-              newIndex:
-                type: integer
-                description: Used for ordering purposes, indicates the new position index of the document structure item
-              newPath:
-                type: string
-                description: The new path of the document structure item if it has been changed, otherwise can be omitted
-              newParentPath:
-                type: string
-                description: The new parentPath of the document structure item if it has been changed, otherwise can be omitted
-            required:
-              - id
+          description: Document structure items that need to be updated or changed
+          items: ../schema/document-structure-refine-item.yaml
       required:
-        - refinedStructure
+        - structures
 
   - type: function
     name: finalizeDocumentStructure
@@ -140,23 +103,18 @@ skills:
       return {
         projectName: input.projectName,
         projectDesc: input.projectDesc,
-        documentStructure: input.documentStructure
-          .map((item) => {
-            const refined = input.refinedStructure?.find(i => i.id === item.id)
+        documentStructure: input.structures.map(refinedItem => {
+          // Find original item to get sourceIds and other fields
+          const originalItem = input.documentStructure.find(orig => orig.id === refinedItem.id)
+
+          const newItem = {
+            title: refinedItem.title,
+            description: refinedItem.description,
+            path: refinedItem.path,
+            parentId: refinedItem.parentPath || null,  // Convert parentPath to parentId
+            sourceIds: originalItem?.sourceIds || [],
+          }
 
-            return {
-              ...item,
-              index: refined?.newIndex || item.index,
-              path: refined?.newPath || item.path,
-              parentId: refined?.newParentPath || item.parentPath,
-            }
-          })
-          .sort((a, b) => a.index - b.index)
-          .map(i => {
-            const newItem = { ...i }
-            delete newItem.index
-            delete newItem.id
-            delete newItem.parentPath
-            return newItem
-          }),
+          return newItem
+        })
       }

package/agents/generate/index.yaml

@@ -38,8 +38,7 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          }),
-          "datasources": ""
+          })
         }
       ])
   - ../utils/format-document-structure.mjs

package/agents/generate/{merge-d2-diagram.yaml → merge-diagram.yaml}

@@ -1,14 +1,15 @@
-name: mergeD2DiagramToDocument
-description: Merge D2 Diagram source code into document
+name: mergeDiagramToDocument
+description: Merge Diagram source code into document
 instructions: |
   You are an AI assistant that helps to merge d2 diagram into document.
 
-  <datasources>
+  <detail_dataSource>
   {{ content }}
-  </datasources>
-  <datasources>
+  </detail_dataSource>
+
+  <diagramSourceCode>
   {{ diagramSourceCode }}
-  </datasources>
+  </diagramSourceCode>
 
   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

@@ -16,7 +16,7 @@ input_schema:
     locale:
       type: string
       description: User language, e.g. zh, en
-    datasources:
+    dataSourceChunk:
       type: string
       description: Context for documentation structure
     glossary:

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

@@ -140,7 +140,7 @@ export default async function userReviewDocumentStructure({ documentStructure, .
       // Call refineDocumentStructure agent with feedback
       await options.context.invoke(refineAgent, {
         ...rest,
-        datasources: rest.datasources[0].datasources,
+        dataSourceChunk: rest.datasources[0].dataSourceChunk,
         feedback: feedback.trim(),
         documentStructure: currentStructure,
         userPreferences,

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

@@ -11,44 +11,20 @@ export default async function mergeDocumentStructures(input, options) {
 
   options.context.userContext.originalDocumentStructure ??= [];
 
-  const structure = options.context.userContext.originalDocumentStructure;
+  const originalStructures = options.context.userContext.originalDocumentStructure;
 
-  if (input.add) {
-    for (const { index, item } of input.add) {
-      if (index != null && index >= 0 && index < structure.length) {
-        structure.splice(index, 0, item);
+  if (input.structures) {
+    for (const item of input.structures) {
+      const old = originalStructures.find((s) => s.path === item.path);
+      if (old) {
+        Object.assign(old, item);
       } else {
-        structure.push(item);
+        originalStructures.push(item);
       }
     }
   }
 
-  if (input.update) {
-    for (const upd of input.update) {
-      const idx = structure.findIndex((i) => i.path === upd.path);
-      if (idx !== -1) {
-        structure[idx] = upd.item;
-      }
-    }
-  }
-
-  if (input.delete) {
-    for (const del of input.delete) {
-      const idx = structure.findIndex((i) => i.path === del.path);
-      if (idx !== -1) {
-        structure.splice(idx, 1);
-      }
-    }
-  }
-
-  options.context.userContext.originalDocumentStructure = structure.map((i, index) => {
-    delete i.index;
-
-    return {
-      index,
-      ...i,
-    };
-  });
+  options.context.userContext.originalDocumentStructure = originalStructures;
 
   return {};
 }

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

@@ -0,0 +1,20 @@
+type: object
+description: Document structure item representing a node in the document hierarchy
+properties:
+  id:
+    type: string
+    description: Unique identifier for the document structure item
+  title:
+    type: string
+  description:
+    type: string
+  path:
+    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
+  parentPath:
+    type: string
+    description: Parent node path, if null indicates it is a top-level node
+required:
+  - title
+  - description
+  - path

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

@@ -6,7 +6,7 @@ skills:
 input_schema:
   type: object
   properties:
-    datasources:
+    detailDataSource:
       type: string
       description: Context for documentation structure generation, used to assist generate documentation structure
     documentExecutionStructure: ../schema/document-execution-structure.yaml

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

@@ -0,0 +1,26 @@
+const placeholder = "DIAGRAM_PLACEHOLDER";
+
+export default async function checkGenerateDiagram(
+  { needDiagram, documentContent, locale },
+  options,
+) {
+  if (!needDiagram) {
+    return {};
+  }
+
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  let content = documentContent;
+
+  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}`);
+  }
+  return { content };
+}

package/agents/update/generate-diagram.yaml

@@ -9,7 +9,6 @@ reflection:
   is_approved: isValid
   max_iterations: 5
   return_last_on_max_iterations: false
-  custom_error_message: "MUST NOT generate any diagram: validation failed after max iterations."
 input_schema:
   type: object
   properties:

package/agents/update/generate-document.yaml

@@ -16,7 +16,7 @@ input_schema:
     locale:
       type: string
       description: User language, such as zh, en
-    datasources:
+    detailDataSource:
       type: string
       description: Source data and context for document content generation
     targetAudience:
@@ -44,9 +44,21 @@ input_schema:
       description: Additional supplementary information
   required:
     - rules
-    - datasources
+    - detailDataSource
     - originalDocumentStructure
-output_key: content
+# 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
 afs:
   modules:
     - module: system-fs
@@ -57,5 +69,5 @@ afs:
           Codebase of the project to be documented used as context for document generation,
           should search and read as needed while generating document content
 keep_text_in_tool_uses: false
-skills:
-  - ./generate-diagram.yaml
+# skills:
+#   - ./generate-diagram.yaml

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

@@ -23,6 +23,14 @@ skills:
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate document for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "documentContent": content }
+      ])
+  - ./check-generate-diagram.mjs
+  # - ../generate/merge-diagram.yaml
   - ../utils/save-doc.mjs
 input_schema:
   type: object

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

@@ -23,7 +23,7 @@ input_schema:
     locale:
       type: string
       description: User language, e.g. zh, en
-    datasources:
+    detailDataSource:
       type: string
       description: Context for document content
     glossary:
@@ -57,5 +57,5 @@ afs:
 keep_text_in_tool_uses: false
 skills:
   - ./document-tools/update-document-content.mjs
-  - ./generate-diagram.yaml
+  # - ./generate-diagram.yaml
 task_render_mode: collapse

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

@@ -3,6 +3,5 @@ name: updateSingleDocument
 skills:
   - ../utils/transform-detail-datasources.mjs
   - ../update/user-review-document.mjs
-  - ../utils/save-doc.mjs
 iterate_on: selectedDocs
 concurrency: 1

package/agents/update/user-review-document.mjs

@@ -105,6 +105,7 @@ async function showDocumentDetail(content, title) {
       renderer: new markedTerminal(),
     });
 
+    // FIXME: @zhanghan fix error "Could not find the language 'd2', did you forget to load/include a language module?"
     const renderedMarkdown = marked(content);
 
     // Restore original console.error
@@ -121,16 +122,15 @@ async function showDocumentDetail(content, title) {
   }
 }
 
-export default async function userReviewDocument(
-  { content, title, description, ...rest },
-  options,
-) {
+export default async function userReviewDocument({ content, description, ...rest }, options) {
   // Check if document content exists
   if (!content || typeof content !== "string" || content.trim().length === 0) {
     console.log("Please provide document content to review.");
     return { content };
   }
 
+  const title = rest.documentStructure?.find((x) => x.path === rest.path)?.title;
+
   // Print current document headings structure
   printDocumentHeadings(content, title || "Untitled Document");
 
@@ -190,7 +190,7 @@ export default async function userReviewDocument(
     feedbacks.push(feedback.trim());
 
     // Get the updateDocument agent
-    const updateAgent = options.context.agents["updateDocumentDetail"];
+    const updateAgent = options.context.agents["handleDocumentUpdate"];
     if (!updateAgent) {
       console.log(
         "We can't process your feedback right now. The document update feature is temporarily unavailable.",
@@ -213,6 +213,7 @@ export default async function userReviewDocument(
         originalContent: options.context.userContext.currentContent,
         feedback: feedback.trim(),
         userPreferences,
+        title,
       });
 
       // Check if feedback should be saved as user preference

package/agents/utils/load-sources.mjs

@@ -219,7 +219,7 @@ export default async function loadSources(
   );
 
   const datasources = splitSourcesToChunks(sourceFiles, INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD).map(
-    (i) => ({ datasources: buildSourcesContent(i) }),
+    (i) => ({ dataSourceChunk: buildSourcesContent(i) }),
   );
 
   const remoteFileList = [];
@@ -350,7 +350,7 @@ loadSources.output_schema = {
       items: {
         type: "object",
         properties: {
-          datasources: { type: "string" },
+          dataSourceChunk: { type: "string" },
         },
       },
     },

package/agents/utils/transform-detail-datasources.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { isRemoteFile } from "../../utils/file-utils.mjs";
 import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
 
-export default function transformDetailDatasources({ sourceIds }, options = {}) {
+export default function transformDetailDatasource({ sourceIds }, options = {}) {
   // Read file content for each sourceId, ignoring failures
   let openAPISpec;
   const remoteFileList = options?.context?.userContext?.remoteFileList || [];
@@ -37,9 +37,9 @@ export default function transformDetailDatasources({ sourceIds }, options = {})
     .filter(Boolean);
 
   return {
-    detailDataSources: contents.join(""),
+    detailDataSource: contents.join(""),
     openAPISpec,
   };
 }
 
-transformDetailDatasources.task_render_mode = "hide";
+transformDetailDatasource.task_render_mode = "hide";

package/aigne.yaml

@@ -1,7 +1,9 @@
 #!/usr/bin/env aigne
 
 model:
-  model: google/gemini-2.5-pro
+  model: aignehub/gemini-2.5-pro # reasoning_effort 128-32768
+  # https://github.com/AIGNE-io/aigne-framework/blob/main/models/gemini/src/gemini-chat-model.ts#L115
+  reasoning_effort: 502
   # name: gemini-2.5-flash
   temperature: 0.8
 agents:
@@ -93,6 +95,11 @@ agents:
   - ./agents/evaluate/document-structure.yaml
   - ./agents/evaluate/document.yaml
   - ./agents/evaluate/code-snippet.mjs
+
+  # Diagram
+  - ./agents/generate/merge-diagram.yaml
+  - ./agents/update/generate-diagram.yaml
+  - ./agents/update/check-generate-diagram.mjs
 cli:
   chat: ./agents/chat/index.yaml
   agents:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.15-beta.8",
+  "version": "0.8.15-beta.9",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/common/document/content-rules-core.md

@@ -2,12 +2,12 @@ Target Audience: {{targetAudience}}
 
 Content Generation Rules:
 
-- Use only information from DataSources, never fabricate or supplement content not present in the sources
+- Use only information from detailDataSource, never fabricate or supplement content not present in the sources
 - Combine the current {{nodeName}} title and description to create a well-structured content plan that is rich, organized, and engaging
 - Content style must match the target audience
 - Clearly differentiate content from other {{nodeName}} items in the documentStructure to avoid duplication and highlight this {{nodeName}}'s unique value
 {% if enforceInfoCompleteness %}
-- If DataSources lack sufficient information, return an error message requesting users to provide additional content. Ensure page content is sufficiently rich, don't hesitate to ask users for supplementary information
+- If detailDataSource lack sufficient information, return an error message requesting users to provide additional content. Ensure page content is sufficiently rich, don't hesitate to ask users for supplementary information
 - Display only valuable, engaging information. If information is insufficient, prompt users to provide more details
 {% endif %}
 - Output complete information including all content planned for the {{nodeName}}
@@ -15,6 +15,6 @@ Content Generation Rules:
 - Maintain a strict, sequential heading hierarchy; no skipping (e.g., no jump from level-1 to level-3).
 - Format markdown output with proper line breaks and spacing for easy reading
 - For list data with many items, prioritize using markdown table for cleaner, more readable presentation
-- Do not mention 'DataSources' in output, your content is for user consumption, and users are unaware of DataSources
+- Do not mention 'detailDataSource' in output, your content is for user consumption, and users are unaware of detailDataSource
 - Do not include file paths from Data Sources in output as they are meaningless to users
-- Avoid phrases like 'current {{nodeName}}'
+- Avoid phrases like 'current {{nodeName}}'

package/prompts/common/document/openapi-usage-rules.md

@@ -0,0 +1,36 @@
+{% if openAPISpec %}
+<openapi_usage_rules>
+
+**Goal:** Use the provided OpenAPI (Swagger) specification, align it with the current page objective, and leverage it to refine this document.
+
+**OpenAPI File Content:** 
+<openapi_doc>
+
+{{ openAPISpec }}
+
+</openapi_doc>
+
+---
+
+### **Documentation Requirements and Constraints**
+
+1.  **Extract the core content:**
+    * Organize the document by functional modules.
+    * For each path item, include the following elements:
+        * HTTP method and path.
+        * Concise summary.
+        * Detailed description.
+        * Request parameters: name, location (`in`), type, required flag, description.
+        * Request body: describe its structure when present.
+        * Responses: at least the key status codes (e.g., 200, 201, 400, 500) and their schemas.
+
+2.  **Mandatory API description constraints (deduplication rule):**
+    * **Ensure that throughout the document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.**
+    * **Never** repeat or expand the interface list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
+
+---
+
+**Expected output format:** A concise, clear, and easy-to-scan Markdown document.
+
+</openapi_usage_rules>
+{% endif %}

package/prompts/common/document/role-and-personality.md

@@ -13,5 +13,4 @@ Your key strengths include:
 1.  **Fact-Driven:** Adhere strictly to the provided technical specifications. Do not infer or embellish information.
 2.  **Structured and Orderly:** Organize the content logically with clear headings, subheadings, lists, and tables. Present information sequentially where appropriate (e.g., installation steps).
 3.  **Clarity and Precision:** Use precise, unambiguous language. Define technical terms clearly. Avoid marketing jargon or emotionally charged words.
-4.  **Practical and Helpful:** Focus on providing practical examples, code snippets, and clear instructions that a user can directly apply.
-5.  **Tool Utilization:** Actively call tools as needed, potentially multiple times, to obtain complete information from AFS (AIGNE File System) or generate Diagrams. Do not embed Mermaid or other diagram markup directly; include diagrams only via generateDiagram tool responses.
+5.  **Tool Utilization:** Actively call tools as needed, potentially multiple times, to obtain complete information from AFS (AIGNE File System).

package/prompts/detail/d2-diagram/rules.md

@@ -1,13 +1,14 @@
-<diagram_generation_guide>
+<diagram_generation_rules>
+**Generation Workflow**
+1. Use the current `<detail_dataSource>`, `<content_review_feedback>`, and `<feedback>` to decide whether this document requires a diagram.
+2. When a diagram is needed, call the `generateDiagram` tool to create it and insert the returned content at the most fitting location in the document.
+3. Check whether the data sources include `diagramSourceCode`. If not, remove any embedded diagram from the document.
 
-1. Core Principles and Mandatory Constraints
-   - **Absolute Constraint (Mandatory)**: You **must only** call the `generateDiagram` tool to generate a diagram.
-     - **Do not** generate mermaid diagram.
-     - **Do not** generate base64 image.
-     - **Do not** generate fake image url.
-   - **Diagram Failure Handling**: If the `generateDiagram` tool call fails, **omit the diagram entirely** and proceed with generating the text. **Do not** attempt to describe the diagram in words as a replacement.
+**Generation Result Usage**
+When `diagramSourceCode` is available, insert it into the document exactly as returned without any edits.
 
-2. Diagram Triggers and Types: Call `generateDiagram` and select the most appropriate type when describing the following specific content
+**Generation Requirements**
+1. Diagram Triggers and Types: Call `generateDiagram` and select the most appropriate type when describing the following specific content
    - Architecture Diagram (High-Level)
      - **Trigger**: When the document provides a high-level overview of a system, project, or the overall documentation set.
      - **Content**: Must illustrate the main components, their relationships, and the overall structure.
@@ -19,11 +20,7 @@
      - **Diagram Type Selection**:
        - **Flowchart**: Use for step-by-step processes, algorithms, or decision-making logic.
        - **Sequence Diagram**: Use for time-ordered interactions between different components or actors (e.g., API calls).
-3. Constraints and Best Practices
+2. Constraints and Best Practices
    - **Quantity Limit**: Generate a maximum of **three** diagrams per document.
    - **Relevance**: Ensure every diagram **directly** illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
-4. Tool result using rules
-   - If the `generateDiagram` tool's result (`diagramSourceCode`) is present, insert the value of `diagramSourceCode` directly into the document as a string.
-   - If the `generateDiagram` tool's result is not present, do not attempt to add any diagrams.
-
-</diagram_generation_guide>
+</diagram_generation_rules>

package/prompts/detail/d2-diagram/system-prompt.md

@@ -201,20 +201,6 @@ D2 provides special syntax for creating complex, structured diagram types common
 - Lifeline activations, also known as spans, are defined by connecting to a nested object on an actor. This syntax indicates the start and end of an operation on an actor's lifeline. Example: `alice.t1 -> bob: "invoke operation"`.
 - Groups (fragments) like loops or optional blocks are defined using nested containers that are not connected to anything. Example: `loop: { alice -> bob: "ping"; bob -> alice: "pong" }`.
 
-#### UML Class Diagrams
-
-- A class diagram is created by setting `shape: class` on a shape.
-- Fields and methods are defined as key-value pairs within the shape's block.
-- Visibility is specified with a prefix: `+` for public (this is the default), `-` for private, and `#` for protected.
-- Methods are identified by keys containing parentheses `()`. The value of the key specifies the return type. Example: `D2Parser: { shape: class; +reader: io.RuneReader; "-lookahead:rune"; "+peek(): (rune, eof bool)" }`.
-
-#### SQL Table Diagrams
-
-- An SQL table is created by setting `shape: sql_table`.
-- Columns are defined as keys, with their data type as the value.
-- Constraints (e.g., `primary_key`, `foreign_key`, `unique`) are defined in a nested block for the relevant column. Example: `users: { shape: sql_table; id: int { constraint: primary_key }; email: string { constraint: unique } }`.
-- Foreign key relationships are established by creating a standard connection from the foreign key column in one table to the primary key column in another. Example: `orders.user_id -> users.id`.
-
 
 ### 1.4 Strict Adherence to Predefined Keyword Values
 

package/prompts/detail/d2-diagram/user-prompt.md

@@ -12,6 +12,35 @@ Generate a d2 diagram that represents the following document content:
 
 </user_rules>
 
+<diagram_rules>
+
+1. Diagram Triggers and Types: Select the most appropriate type when describing the following specific content
+   - Architecture Diagram (High-Level)
+     - **Trigger**: When the document provides a high-level overview of a system, project, or the overall documentation set.
+     - **Content**: Must illustrate the main components, their relationships, and the overall structure.
+   - Structural Diagram (Module-Level)
+     - **Trigger**: When generating the introductory document for a major section or module.
+     - **Content**: Must show the key sub-components, files, or core concepts within that specific module.
+   - Process and Interaction Diagrams (Detailed)
+     - **Trigger**: When the document describes a workflow, a sequence of events, user interactions, or data flow.
+     - **Diagram Type Selection**:
+       - **Flowchart**: Use for step-by-step processes, algorithms, or decision-making logic.
+       - **Sequence Diagram**: Use for time-ordered interactions between different components or actors (e.g., API calls).
+2. Constraints and Best Practices
+   - **Keep it Simple**: Avoid overcomplicating the diagram.
+   - **Relevance**: Ensure every diagram **directly** illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
+
+</diagram_rules>
+
 <document_content>
 {{documentContent}}
-</document_content>
+</document_content>
+
+{% if diagramError %}
+<diagram_check_feedback>
+
+**Diagram generation error**
+{{ diagramError }}
+
+</diagram_check_feedback>
+{% endif %}

package/prompts/detail/generate/document-rules.md

@@ -10,7 +10,7 @@ Documentation Generation Rules:
 - **Markdown Syntax Constraint**: Use only GitHub Flavored Markdown (GFM) syntax by default. Prohibited extensions include: custom blocks `:::`, footnotes `[^1]: notes`, math formulas `$$ LaTeX`, highlighted text `==code==`, and other non-GFM syntax unless explicitly defined in custom component rules
 - Use proper Markdown link syntax, for example: [Next Chapter Title](next_chapter_path)
 - **Ensure next_chapter_path references either external URLs or valid paths from the documentation structure**—use absolute paths from the documentation structure
-- When DataSources includes third-party links, incorporate them appropriately throughout the document
+- When detailDataSource includes third-party links, incorporate them appropriately throughout the document
 - Structure each section with: title, introduction, code examples, response data samples, and explanatory notes. Place explanations directly after code examples without separate "Example Description" subheadings
 - Maintain content completeness and logical flow so users can follow the documentation seamlessly
 - Provide comprehensive explanations for configuration options and parameters. When parameters accept multiple values, explain each option's purpose and include code examples where applicable

package/prompts/detail/generate/system-prompt.md

@@ -43,14 +43,8 @@ Custom component generation rules:
 Custom code block generation rules:
 {% include "../custom/custom-code-block.md" %}
 
-{% include "../d2-diagram/guide.md" %}
-
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
-Tool result usage rules:
-- Only use the `"role": "tool"` result as the datasource for document enhancement.
-- Do not include `"role": "agent"` content in the final output.
-
 </content_generation_rules>
 
 

package/prompts/detail/generate/user-prompt.md

@@ -2,20 +2,21 @@
 {{ locale }}
 </user_locale>
 
-
 <user_rules>
 {{ rules }}
 
-** Output content in {{ locale }} language **
-</user_rules>
+** Output content in {{ locale }} language. **
+
+** Don't generate any diagram in the document, give boolean value in `needDiagram` field & plan a placeholder in document content for diagram (use `DIAGRAM_PLACEHOLDER` as placeholder text). **
 
+- **Necessary**: Generate diagrams only when necessary.
+</user_rules>
 
 {% set operation_type = "generating" %}
 {% include "../../common/document/user-preferences.md" %}
 
-
-<datasources>
-{{ detailDataSources }}
+<detail_dataSource>
+{{ detailDataSource }}
 
 {{ additionalInformation }}
 
@@ -23,66 +24,25 @@
 {{ assetsContent }}
 </media_file_list>
 
+</detail_dataSource>
 
 
-</datasources>
-
-{% if openAPISpec %}
-<openapi>
-
-**Goal:** Use the provided OpenAPI (Swagger) specification, align it with the current page objective, and leverage it to refine this document.
-
-**OpenAPI File Content:** 
-<openapi_doc>
-
-{{ openAPISpec }}
-
-</openapi_doc>
-
----
-
-### **Documentation Requirements and Constraints**
-
-1.  **Extract the core content:**
-    * Organize the document by functional modules.
-    * For each path item, include the following elements:
-        * HTTP method and path.
-        * Concise summary.
-        * Detailed description.
-        * Request parameters: name, location (`in`), type, required flag, description.
-        * Request body: describe its structure when present.
-        * Responses: at least the key status codes (e.g., 200, 201, 400, 500) and their schemas.
-
-2.  **Mandatory API description constraints (deduplication rule):**
-    * **Ensure that throughout the document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.**
-    * **Never** repeat or expand the interface list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
-
----
-
-**Expected output format:** A concise, clear, and easy-to-scan Markdown document.
-
-</openapi>
-{% endif %}
-
+{% include "../../common/document/openapi-usage-rules.md" %}
 
 {% include "./detail-example.md" %}
 
-
 {% if content %}
-Content from previous generation:
-<last_content>
+<previous_generation_content>
 {{content}}
-</last_content>
+</previous_generation_content>
 {% endif %}
 
-
 {% if detailFeedback %}
 <content_review_feedback>
 {{ detailFeedback }}
 </content_review_feedback>
 {% endif %}
 
-
 {% if feedback %}
 User feedback on previous generation:
 <feedback>
@@ -90,19 +50,12 @@ User feedback on previous generation:
 </feedback>
 {% endif %}
 
-
 <instructions>
-Generate detailed and well-structured document for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), DataSources, documentStructure (overall structural planning), and other relevant information.
-
-YOU SHOULD:
-- Use AFS tools `afs_list` `afs_search` or `afs_read` to gather relevant and accurate information to enhance the content.
-- Follow rules in `<diagram_generation_guide>`: use `generateDiagram` tool to create and embed a diagram when appropriate, following the diagram generation guidelines.
-- If the `generateDiagram` tool is not called, do not attempt to add any diagrams.
+Generate detailed and well-structured document for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), detailDataSource, documentStructure (overall structural planning), and other relevant information.
 
 <steps>
 1. Analyze the provided document structure and user requirements to plan the content.
 2. Use AFS tools (`afs_list`/`afs_search`/`afs_read`) to search and gather relevant and accurate information to enhance the content.
-3. Use `generateDiagram` to create and embed a diagram when appropriate, following the diagram generation guidelines.
-4. Write clear, concise, and well-structured content for each section based on the planned structure and gathered information.
+3. Write clear, concise, and well-structured content for each section based on the planned structure and gathered information.
 </steps>
 </instructions>

package/prompts/detail/update/system-prompt.md

@@ -40,12 +40,6 @@ Custom code block optimization rules:
 
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
-Diagram generation rules:
-{% include "../d2-diagram/guide.md" %}
-<diagram_generation_rules>
-{% include "../d2-diagram/system-prompt.md" %}
-</diagram_generation_rules>
-
 </content_optimization_rules>
 
 

package/prompts/detail/update/user-prompt.md

@@ -15,9 +15,9 @@
 {{originalContent}}
 </original_page_content>
 
-<datasources>
+<detail_dataSource>
 
-{{ detailDataSources }}
+{{ detailDataSource }}
 
 {{ additionalInformation }}
 
@@ -25,7 +25,7 @@
 {{ assetsContent }}
 </media_file_list>
 
-</datasources>
+</detail_dataSource>
 
 <user_feedback>
 {{feedback}}

package/prompts/structure/generate/user-prompt.md

@@ -50,7 +50,8 @@ projectDesc: |
 
 {% if originalDocumentStructure %}
 {{ originalDocumentStructure | yaml.stringify }}
-{% else %}
+{% elseif userContext.originalDocumentStructure %}
+{{ userContext.originalDocumentStructure | yaml.stringify }}
 No previous document structure provided. generate a new structure based on the data sources!
 {% endif %}
 
@@ -117,14 +118,11 @@ You are not creating a structure from scratch, but rather **performing intellige
 
 ## Objective
 
-Your output should be a structured change plan containing the following three sections to indicate how to modify the existing document structure:
+Your output should contain a `structures` array with document structure items that need to be added or updated:
 
-- **add**: New structure items (array), can use index to specify insertion position (optional), each item is an object containing:
-  - `index` (optional): Insertion position index, if not specified, append to the end;
-  - `item`: New structure definition
-- **update**: Structure items that need modification (array), each item is an object containing:
-  - `path`: Path pointing to the node being updated;
-  - `update`: New structure definition
+- **structures**: Array of document structure items representing incremental changes to the existing document structure. Each item should include a `path` field - the system will automatically replace existing items with matching paths or add new items if the path doesn't exist.
+
+IMPORTANT: You should avoid duplicating existing structure items. Only include items that are genuinely new or need updates. The system will automatically merge these changes with the existing document structure based on the `path` field.
 
 ## Behavior Rules
 
@@ -138,8 +136,8 @@ Your output should be a structured change plan containing the following three se
    - Identify which parts represent new concepts, APIs, modules, configurations, or features; determine if they require adding or modifying corresponding sections in the document structure.
 
 3. **Structure Adjustment Strategy**
-   - If new content supplements details of existing sections, use `update`.
-   - If new content introduces new topics, modules, or hierarchies, use `add`.
+   - If new content supplements details of existing sections, include the updated item in the `structures` array with the same path.
+   - If new content introduces new topics, modules, or hierarchies, include new items in the `structures` array with new paths.
    - Ensure the position, hierarchy, and naming of new nodes align with the overall document logic.
 
 4. **Consistency and Clarity**

package/prompts/structure/review/structure-review-system.md

@@ -1,6 +1,5 @@
 <role_and_goal>
-You are an AI document strategist with the personality of an **INTJ (The Architect)**. Your core strengths are strategic thinking, understanding complex systems, and creating logically sound blueprints. You are a perfectionist, rigorously logical, and can anticipate future challenges.
-
+You are a **Documentation Structure Refiner** with the analytical mindset of an **INTJ (The Architect)**. You combine expert knowledge in technical documentation architecture and information design with strategic thinking, systematic analysis, and perfectionist attention to detail. Your core strengths are understanding complex systems, creating logically sound blueprints, and anticipating future documentation challenges.
 </role_and_goal>
 
 <document_structure>
@@ -14,11 +13,10 @@ documentStructure:
 </document_structure>
 
 <instructions>
-You are a Documentation Structure Refiner — an expert in technical documentation architecture and information design.
 
 Your task:
 Given an existing document structure (a JSON array or tree of sections), refine and optimize its **hierarchy and order** to improve clarity, usability, and conventional organization.
-️ You must not add, delete, rename, or rewrite any nodes. Only adjust the **order** and **nesting levels** of existing nodes.
+️ You must not add or rename any nodes. You may delete nodes when necessary for better organization and adjust the **order** and **nesting levels** of existing nodes.
 
 ---
 
@@ -35,11 +33,11 @@ Given an existing document structure (a JSON array or tree of sections), refine
      - “Overview” and “Quick Start” should have **1–2 levels max**.
      - Remove deeply nested technical details from “Overview” or “Quick Start”.
      - Relocate such details under “Architecture”, “API Reference”, or “Modules”.
-   - Preserve all nodes — only change their parent-child relationships when needed for clarity.
+   - Keep beneficial nodes — you may delete duplicated, redundant, or harmful nodes when needed for clarity.
 
 3. **Grouping and Alignment**
    - Align similar nodes logically (e.g., group “Usage”, “Examples”, “Tutorials” together).
-   - Avoid duplication or overlap by reordering, not by deletion.
+   - Avoid duplication or overlap by reordering or strategic deletion when necessary.
 
 4. **Naming and Identity**
    - You are **not allowed to rename or reword** any section titles or descriptions.
@@ -55,19 +53,26 @@ Given an existing document structure (a JSON array or tree of sections), refine
 ## Behavior Rules
 
 - Do **not** add new nodes.
-- Do **not** delete existing nodes.
+- You **may** delete nodes when they are redundant, duplicated, or detrimental to documentation clarity.
 - Do **not** rename or rewrite content.
 - You **may** move nodes to different parents or reorder siblings to achieve better logical flow.
-- You **must** maintain all data and structural integrity.
-- The final structure must remain fully valid and machine-readable (same schema as input).
+- You **must** maintain structural integrity for all remaining nodes.
+- The output must be a complete, valid document structure array matching the expected schema.
 
 ---
 
 ## Objective
 
-Output a single **optimized JSON structure** (same format as input), where:
-1. The hierarchy and order are improved.
-2. All nodes are preserved exactly as given.
-3. The structure reflects a natural and professional documentation layout
-4. Only return the nodes need to be changed to achieve the above goals.
+Output a complete `structures` array containing the optimized document structure:
+1. Include ALL nodes from the input structure (whether modified or not)
+2. Each item must include: `id`, `title`, `description`, `path`, `parentPath` (if not top-level)
+3. Apply your optimizations through proper ordering, hierarchy changes, and selective deletion
+4. Maintain all required fields and ensure paths are valid (start with /, no spaces/special chars)
+5. **Important**: Only modify structural aspects (`id`, `title`, `description`, `path`, `parentPath`). Do NOT modify `sourceIds` or other data fields
+
+**Optimization Approach:**
+- Reorder nodes by adjusting their position in the array
+- Change hierarchy by modifying `parentPath` values (use the path of the new parent node)
+- Delete problematic nodes by simply omitting them from the output array
+- Keep beneficial nodes with their original content intact
 </instructions>