@aigne/doc-smith 0.8.15-beta.1 → 0.8.15-beta.10

package/agents/utils/save-doc-translation.mjs

@@ -0,0 +1,27 @@
+import { saveDocTranslation as _saveDocTranslation } from "../../utils/utils.mjs";
+
+export default async function saveDocTranslation({
+  path,
+  docsDir,
+  translation,
+  language,
+  labels,
+  isShowMessage = false,
+}) {
+  await _saveDocTranslation({
+    path,
+    docsDir,
+    language,
+    translation,
+    labels,
+  });
+
+  if (isShowMessage) {
+    const message = `✅ Translation completed successfully.`;
+    return { message };
+  }
+
+  return {};
+}
+
+saveDocTranslation.task_render_mode = "hide";

package/agents/utils/{save-single-doc.mjs → save-doc.mjs}

@@ -1,24 +1,22 @@
 import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
-import { saveDocWithTranslations } from "../../utils/utils.mjs";
+import { saveDoc as _saveDoc } from "../../utils/utils.mjs";
 
-export default async function saveSingleDoc({
+export default async function saveDoc({
   path,
   content,
   docsDir,
-  translates,
   labels,
   locale,
-  isTranslate = false,
+  feedback,
   isShowMessage = false,
+  ...rest
 }) {
-  const _results = await saveDocWithTranslations({
+  await _saveDoc({
     path,
     content,
     docsDir,
-    translates,
     labels,
     locale,
-    isTranslate,
   });
 
   if (isShowMessage) {
@@ -29,13 +27,20 @@ export default async function saveSingleDoc({
       console.warn("Failed to shutdown mermaid worker pool:", error.message);
     }
 
-    const message = isTranslate
-      ? `✅ Translation completed successfully`
-      : `✅ Document updated successfully`;
+    const message = `✅ Document updated successfully.`;
     return { message };
   }
 
-  return {};
+  return {
+    path,
+    content,
+    docsDir,
+    labels,
+    locale,
+    feedback,
+    isShowMessage,
+    ...rest,
+  };
 }
 
-saveSingleDoc.task_render_mode = "hide";
+saveDoc.task_render_mode = "hide";

package/agents/utils/save-sidebar.mjs

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import fs from "fs-extra";
+
+export default async function saveSidebar({ documentStructure, docsDir }) {
+  // Generate _sidebar.md
+  try {
+    const sidebar = generateSidebar(documentStructure);
+    const sidebarPath = join(docsDir, "_sidebar.md");
+
+    await fs.ensureDir(docsDir);
+    await fs.writeFile(sidebarPath, sidebar, "utf8");
+  } catch (err) {
+    console.error("Failed to save _sidebar.md:", err.message);
+  }
+  return {};
+}
+
+// Recursively generate sidebar text, the link path is the flattened file name
+function walk(node, parentSegments = [], indent = "") {
+  let out = "";
+  for (const key of Object.keys(node)) {
+    const item = node[key];
+    const fullSegments = [...parentSegments, key];
+    const flatFile = `${fullSegments.join("-")}.md`;
+    if (item.__title) {
+      const realIndent = item.__parentId === null ? "" : indent;
+      out += `${realIndent}* [${item.__title}](/${flatFile})\n`;
+    }
+    const children = item.__children;
+    if (Object.keys(children).length > 0) {
+      out += walk(children, fullSegments, `${indent}  `);
+    }
+  }
+  return out;
+}
+
+function generateSidebar(documentStructure) {
+  // Build tree structure
+  const root = {};
+  for (const { path, title, parentId } of documentStructure) {
+    const relPath = path.replace(/^\//, "");
+    const segments = relPath.split("/");
+    let node = root;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (!node[seg])
+        node[seg] = {
+          __children: {},
+          __title: null,
+          __fullPath: segments.slice(0, i + 1).join("/"),
+          __parentId: parentId,
+        };
+      if (i === segments.length - 1) node[seg].__title = title;
+      node = node[seg].__children;
+    }
+  }
+
+  return walk(root).replace(/\n+$/, "");
+}

package/agents/utils/{transform-detail-datasources.mjs → transform-detail-data-sources.mjs}

@@ -1,11 +1,11 @@
 import fs from "node:fs";
+import { isRemoteFile } from "../../utils/file-utils.mjs";
 import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
-import { checkIsRemoteFile } from "../../utils/file-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 httpFileList = options?.context?.userContext?.httpFileList || [];
+  const remoteFileList = options?.context?.userContext?.remoteFileList || [];
   const contents = (sourceIds || [])
     .filter((id) => {
       const openApiSourceId = options?.context?.userContext?.openAPISpec?.sourceId;
@@ -17,8 +17,8 @@ export default function transformDetailDatasources({ sourceIds }, options = {})
     })
     .map((id) => {
       try {
-        if (checkIsRemoteFile(id)) {
-          const findFile = httpFileList.find((f) => f.sourceId === id);
+        if (isRemoteFile(id)) {
+          const findFile = remoteFileList.find((f) => f.sourceId === id);
           if (findFile) {
             return `// sourceId: ${id}\n${findFile.content}\n`;
           }
@@ -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,8 +1,9 @@
 #!/usr/bin/env aigne
 
-chat_model:
-  provider: google
-  name: gemini-2.5-pro
+model:
+  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:
@@ -11,14 +12,13 @@ agents:
 
   # Documentation Structure Generation
   - ./agents/generate/generate-structure.yaml
-  - ./agents/generate/generate-structure-without-tools.yaml
   - ./agents/generate/update-document-structure.yaml
   - ./agents/generate/check-need-generate-structure.mjs
   - ./agents/generate/refine-document-structure.yaml
   - ./agents/generate/check-document-structure.yaml
   - ./agents/generate/user-review-document-structure.mjs
   - ./agents/generate/index.yaml
-  
+
   # Documentation Structure Tools
   - ./agents/generate/document-structure-tools/add-document.mjs
   - ./agents/generate/document-structure-tools/delete-document.mjs
@@ -47,6 +47,7 @@ agents:
 
   # Publishing
   - ./agents/publish/publish-docs.mjs
+  - ./agents/publish/translate-meta.mjs
   - ./agents/publish/index.yaml
 
   # Media
@@ -65,9 +66,11 @@ agents:
 
   # Utilities
   - ./agents/utils/load-sources.mjs
-  - ./agents/utils/save-docs.mjs
-  - ./agents/utils/transform-detail-datasources.mjs
-  - ./agents/utils/save-single-doc.mjs
+  - ./agents/utils/post-generate.mjs
+  - ./agents/utils/save-sidebar.mjs
+  - ./agents/utils/transform-detail-data-sources.mjs
+  - ./agents/utils/save-doc.mjs
+  - ./agents/utils/save-doc-translation.mjs
   - ./agents/utils/save-output.mjs
   - ./agents/utils/format-document-structure.mjs
   - ./agents/utils/find-item-by-path.mjs
@@ -92,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.1",
+  "version": "0.8.15-beta.10",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -56,6 +56,7 @@
     "remark-lint": "^10.0.1",
     "remark-parse": "^11.0.0",
     "terminal-link": "^4.0.0",
+    "typescript": "^5.9.3",
     "ufo": "^1.6.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",

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 `<detail_data_source>`, 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
+- Clearly differentiate content from other {{nodeName}} items in the `<document_structure>` 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 `<detail_data_source>` 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 include file paths from Data Sources in output as they are meaningless to users
-- Avoid phrases like 'current {{nodeName}}'
+- Do not mention `<detail_data_source>` 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}}'

package/prompts/common/document/media-file-list-usage-rules.md

@@ -0,0 +1,12 @@
+<media_file_list_usage_rules>
+
+**Usage Workflow**
+1. Read the `<media_file_list>` data and take note of each file's `path` and `description` as references.
+2. Combine those descriptions with the current document's content to decide which images should be used and where they should be inserted.
+3. Confirm that every inserted image path comes from `<media_file_list>`. If a path is missing from that list, replace it with one that is included.
+
+**Usage Requirements**
+- Insert images with Markdown syntax: `![Descriptive alt text](<path-from-media_file_list>)`.
+- Never invent, reinterpret, fabricate, normalize, or rewrite any media file path under any circumstances.
+
+</media_file_list_usage_rules>

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/common/document-structure/conflict-resolution-guidance.md

@@ -1,5 +1,5 @@
 <conflict_resolution_guidance>
-When users select potentially conflicting options, conflict resolution guidance will be provided in user_rules. Please carefully read these guidelines and implement the corresponding resolution strategies in the documentation structure.
+When users select potentially conflicting options, conflict resolution guidance will be provided in `<user_rules>`. Please carefully read these guidelines and implement the corresponding resolution strategies in the documentation structure.
 
 Core principles for conflict resolution:
 1. **Layered need satisfaction**: Simultaneously satisfy multiple purposes and audiences through reasonable documentation structure hierarchy
@@ -13,4 +13,4 @@ Common conflict resolution patterns:
 - **Depth conflicts**: Adopt progressive structures that allow users to choose appropriate depth levels
 
 When generating documentation structure, prioritize conflict resolution strategies to ensure the final structure can harmoniously satisfy all user needs.
-</conflict_resolution_guidance>
+</conflict_resolution_guidance>

package/prompts/common/document-structure/document-structure-rules.md

@@ -1,18 +1,18 @@
 <document_structure_rules>
 The target audience for this document is: {{targetAudience}}
 
-DataSources usage rules:
-1. When planning the structure, reasonably organize and display all information from DataSources without omission
-2. Users may provide limited DataSources. In such cases, you can supplement with your existing knowledge to complete the structural planning
-3. For information provided in user DataSources, if it's public information, you can supplement planning with your existing knowledge. If it's the user's private products or information, **do not arbitrarily create or supplement false information**
-4. If DataSources don't match the target audience, you need to reframe the DataSources to match the target audience
+`<data_sources>` usage rules:
+1. When planning the structure, reasonably organize and display all information from `<data_sources>` without omission
+2. Users may provide limited `<data_sources>`. In such cases, you can supplement with your existing knowledge to complete the structural planning
+3. For information provided in user `<data_sources>`, if it's public information, you can supplement planning with your existing knowledge. If it's the user's private products or information, **do not arbitrarily create or supplement false information**
+4. If `<data_sources>` don't match the target audience, you need to reframe the `<data_sources>` to match the target audience
 
 Structural planning rules:
 
 1. {{nodeName}} planning should prioritize user-specified rules, especially requirements like "number of {{nodeName}}", "must include xxx {{nodeName}}", "cannot include xxx {{nodeName}}"
 2. {{nodeName}} planning should display as much information as possible from the user-provided context
 3. Structure planning should have reasonable hierarchical relationships, with content planned at appropriate levels, avoiding flat layouts with numerous {{nodeName}} items
-4. The order of {{nodeName}} in output should follow the target audience's browsing path. It doesn't need to follow the exact order in DataSources—progress from simple to advanced, from understanding to exploration, with reasonable pathways
+4. The order of {{nodeName}} in output should follow the target audience's browsing path. It doesn't need to follow the exact order in `<data_sources>` progress from simple to advanced, from understanding to exploration, with reasonable pathways
 5. Each {{nodeName}} should have a clear content plan and must not duplicate content from other {{nodeName}} items
 6. Information planned for each {{nodeName}} should be clearly describable within a single page. If there's too much information to display or the concepts are too broad, consider splitting into sub-{{nodeName}} items
 7. If previous documentation structure and user feedback are provided, make only necessary modifications based on user feedback without major changes
@@ -26,7 +26,7 @@ Structural planning rules:
 - Title
 - Description of the important information this {{nodeName}} plans to display, with descriptions tailored to the target audience
 
-2. Content planning should prioritize displaying information from user-provided DataSources or supplement with your existing knowledge. Do not arbitrarily fabricate information.
+2. Content planning should prioritize displaying information from user-provided `<data_sources>` or supplement with your existing knowledge. Do not arbitrarily fabricate information.
 
 {% ifAsync docsType == 'general' %}
   {% include "../../structure/document-rules.md" %}
@@ -41,4 +41,4 @@ Other requirements:
 
 1. Must satisfy user specified rules
 2. Return information using the user's language {{locale}}
-</document_structure_rules>
+</document_structure_rules>

package/prompts/common/document-structure/output-constraints.md

@@ -1,9 +1,9 @@
 <output_constraints>
 
-1. Associated sourceIds should be as comprehensive as possible. You can include as many related datasources as possible.
-  - If datasources contain source code, **include as much related and adjacent source code as possible** to ensure quality of subsequent detail generation.
+1. Associated sourceIds should be as comprehensive as possible. You can include as many related `<data_sources>` as possible.
+  - If `<data_sources>` contain source code, **include as much related and adjacent source code as possible** to ensure quality of subsequent detail generation.
   - First identify the most relevant source code files, then analyze the source code referenced within them. Referenced file paths, referenced files, and files in referenced paths all need to be included in sourceIds
   - For referenced files, analyze another layer of source code files referenced within them and add to sourceIds to ensure complete context for detail generation
 2. **Ensure sourceIds are never empty**. Do not plan {{nodeName}} items without related data sources
 
-</output_constraints>
+</output_constraints>

package/prompts/detail/custom/custom-components.md

@@ -72,12 +72,11 @@ Suitable for displaying multiple links using a card list format, providing a ric
 
 ### Attributes
 
-- data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
-  - Must contain multiple <x-card> elements internally.
+- data-columns (optional): Must be an **integer ≥ 2**. Values below 2 are disallowed. Default is 2.
 
 ### Children
 
-- Must contain multiple <x-card> elements internally.
+- Must contain multiple `<x-card>` elements internally.
 
 ### Usage Rules
 
@@ -107,6 +106,25 @@ Example 2: Two-column cards with images
 </x-cards>
 ```
 
+### Bad Examples
+
+Example 1: Using a single-column layout (`data-columns="1"`) is not allowed
+
+```md
+<x-cards data-columns="1">
+  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+</x-cards>
+```
+
+Example 2: Contains only one `<x-card>` (must include multiple cards)
+
+```md
+<x-cards data-columns="2">
+  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+</x-cards>
+```
+
 ## XField: Structured data field
 
 Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
@@ -414,6 +432,7 @@ Used to group multiple related `<x-field>` elements at the top level, indicating
 
 - **Top-Level Only**: Used only at the top level for grouping related `<x-field>` elements. Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
 - **Structured Data Only**: Use `<x-field-group>` for fields **other than simple types** (`string`, `number`, `boolean`, `symbol`), e.g., Properties, Context, Parameters, Return values. For simple-type fields, use plain Markdown text.
+- **Spacing Around**: Always insert a blank line before and after `<x-field-group>` when it’s adjacent to Markdown content.
 
 ### Good Examples
 
@@ -482,4 +501,20 @@ Example 5: Using x-field-group for simple-type (violates "Structured Data Only"
 </x-field-group>
 ```
 
+Example 6: Missing blank line before x-field-group (violates "Spacing Around" rule)
+
+```md
+**Parameters**
+<x-field-group>
+  <x-field data-name="initialState" data-type="any" data-required="false">
+    <x-field-desc markdown>The initial state value.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+`useReducer` returns an array with two items:
+<x-field-group>
+  <x-field data-name="dispatch" data-type="function" data-desc="A function that you can call with an action to update the state."></x-field>
+</x-field-group>
+```
+
 </custom_components_usage>

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

@@ -1,13 +1,14 @@
-<diagram_generation_guide>
+<diagram_generation_rules>
+**Generation Workflow**
+1. Use the current `<detail_data_source>`, `<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 `<diagram_source_code>`. 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 `<diagram_source_code>` 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

@@ -2,6 +2,45 @@ Follow the given rules and ISTJ style from your system instructions.
 
 Generate a d2 diagram that represents the following document content:
 
+<user_locale>
+{{ locale }}
+</user_locale>
+
+<user_rules>
+
+- Output only the diagram labels and text in the {{ locale }} language — keep all variable names, component names, and syntax unchanged.
+
+</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>
+
+{% 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
@@ -28,7 +28,7 @@ Documentation Generation Rules:
 
 </document_rules>
 
-<TONE_STYLE>
+<tone_style>
 - Documentation should be plain, rigorous and accurate, avoiding grandiose or empty vocabulary
 - You are writing for humans, not algorithms
 - Clarity and Flow
@@ -41,4 +41,4 @@ Documentation Generation Rules:
   - Use contractions and idioms sparingly to maintain an informal, yet credible tone
   - Blend technical precision with relatable language
   - Be direct: say what happened, why it matters, and how it helps
-</TONE_STYLE>
+</tone_style>

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

@@ -43,11 +43,7 @@ Custom component generation rules:
 Custom code block generation rules:
 {% include "../custom/custom-code-block.md" %}
 
-{% include "../d2-diagram/guide.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.
+{% include "../../common/document/media-file-list-usage-rules.md" %}
 
 </content_generation_rules>
 
@@ -56,7 +52,7 @@ Tool result usage rules:
 <output_constraints>
 
 1. Output the complete Markdown content for {{nodeName}}, only the content itself—no explanations or extra information.
-2. Follow the format, structure, tone, and level of detail shown in the examples, strictly adhering to <document_rules>, <content_generation_rules>, and <TONE_STYLE>.
+2. Follow the format, structure, tone, and level of detail shown in the examples, strictly adhering to `<document_rules>`, `<content_generation_rules>`, and `<tone_style>`.
 3. Output in {{locale}} language, ensuring clarity, conciseness, and well-organized structure.
 4. Do not include any self-introduction or conversational text. Output only the documentation content itself.