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

package/agents/utils/map-reasoning-effort-level.mjs

@@ -0,0 +1,15 @@
+import {
+  DEFAULT_REASONING_EFFORT_LEVEL,
+  DEFAULT_REASONING_EFFORT_VALUE,
+  REASONING_EFFORT_LEVELS,
+} from "../../utils/constants/index.mjs";
+
+export default function mapReasoningEffortLevel({ level }, options) {
+  const g =
+    REASONING_EFFORT_LEVELS[level] || REASONING_EFFORT_LEVELS[DEFAULT_REASONING_EFFORT_LEVEL];
+
+  return {
+    reasoningEffort:
+      g[options.context.userContext.thinkingEffort] ?? DEFAULT_REASONING_EFFORT_VALUE,
+  };
+}

package/agents/utils/save-sidebar.mjs

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import fs from "fs-extra";
+import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
 
 export default async function saveSidebar({ documentStructure, docsDir }) {
   // Generate _sidebar.md
@@ -16,44 +17,22 @@ export default async function saveSidebar({ documentStructure, docsDir }) {
 }
 
 // Recursively generate sidebar text, the link path is the flattened file name
-function walk(node, parentSegments = [], indent = "") {
+function walk(nodes, 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}  `);
+  for (const node of nodes) {
+    const relPath = node.path.replace(/^\//, "");
+    const flatFile = `${relPath.split("/").join("-")}.md`;
+    const realIndent = node.parentId === null ? "" : indent;
+    out += `${realIndent}* [${node.title}](/${flatFile})\n`;
+
+    if (node.children && node.children.length > 0) {
+      out += walk(node.children, `${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+$/, "");
+  const { rootNodes } = buildDocumentTree(documentStructure);
+  return walk(rootNodes).replace(/\n+$/, "");
 }

package/agents/utils/{transform-detail-datasources.mjs → transform-detail-data-sources.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,8 +1,12 @@
 #!/usr/bin/env aigne
 
 model:
-  model: google/gemini-2.5-pro
-  # name: gemini-2.5-flash
+  # model: aignehub/gpt-5
+  # model: aignehub/claude-sonnet-4-0
+  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:
+    $get: reasoningEffort
   temperature: 0.8
 agents:
   # Initialization
@@ -66,7 +70,7 @@ agents:
   - ./agents/utils/load-sources.mjs
   - ./agents/utils/post-generate.mjs
   - ./agents/utils/save-sidebar.mjs
-  - ./agents/utils/transform-detail-datasources.mjs
+  - ./agents/utils/transform-detail-data-sources.mjs
   - ./agents/utils/save-doc.mjs
   - ./agents/utils/save-doc-translation.mjs
   - ./agents/utils/save-output.mjs
@@ -74,6 +78,7 @@ agents:
   - ./agents/utils/find-item-by-path.mjs
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
+  - ./agents/utils/analyze-feedback-intent.yaml
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs
@@ -93,6 +98,12 @@ 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
+  - ./agents/update/pre-check-generate-diagram.yaml
 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",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,14 +24,14 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.10.0",
-    "@aigne/anthropic": "^0.14.0",
-    "@aigne/cli": "^1.49.1",
-    "@aigne/core": "^1.61.0",
-    "@aigne/gemini": "^0.14.0",
-    "@aigne/openai": "^0.16.0",
-    "@aigne/publish-docs": "^0.12.0",
-    "@blocklet/payment-broker-client": "^1.21.10",
+    "@aigne/aigne-hub": "^0.10.5-beta.3",
+    "@aigne/anthropic": "^0.14.5-beta.3",
+    "@aigne/cli": "^1.53.1-beta.4",
+    "@aigne/core": "^1.65.1-beta.3",
+    "@aigne/gemini": "^0.14.5-beta.3",
+    "@aigne/openai": "^0.16.5-beta.3",
+    "@aigne/publish-docs": "^0.12.1",
+    "@blocklet/payment-broker-client": "^1.22.8",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11",
@@ -48,6 +48,7 @@
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
     "mermaid": "^11.9.0",
+    "minimatch": "^10.1.1",
     "open": "^10.2.0",
     "p-limit": "^7.1.1",
     "p-map": "^7.0.3",

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/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-code-block.md

@@ -18,6 +18,11 @@ The following are the available enhanced attributes and their descriptions:
   * `language` and `title` are written directly after \`\`\`, separated by spaces.
   * Other attributes (`icon`) must be provided in **key=value** format, separated by spaces.
 
+### Special Rules
+- If the language is a shell (includes `sh`, `bash`, `zsh`, etc.):
+  - Executable shell code blocks must be a single-line command to make copying and running easier.
+  - Do not include comments inside executable shell code blocks; place explanatory comments outside the code block.
+
 ### Examples
 
 <code_block_good_examples>
@@ -70,9 +75,26 @@ class ShoppingCart {
   }
 }
 ```
+
+**Example 5: Shell code block should in one line**
+
+```sh Install aigne deps icon=lucide:terminal
+npm i -g @aigne/cli @aigne/doc-smith @aigne/websmith-smith
+```
+
+**Example 6: Shell code block use `\` to split multiple lines**
+```bash Deploying with Access Keys icon=lucide:terminal
+blocklet deploy . \
+  --endpoint https://my-server.arcblock.io \
+  --access-key 'your_access_key_id' \
+  --access-secret 'your_access_key_secret' \
+  --app-id z2qa9sD2tFAP8gM7C1i8iETg3a1T3A3aT3bQ
+```
+
 </code_block_good_examples>
 
 <code_block_bad_examples>
+
 **Example 1**
 
 There are two errors in this example:
@@ -97,5 +119,18 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+**Example 2: shell code block have multiple lines**
+```sh
+npm i -g @aigne/cli
+npm i -g @aigne/doc-smith
+npm i -g @aigne/websmith-smith
+```
+
+**Example 3: shell code block comments**
+```sh
+# add aigne deps
+npm i -g @aigne/cli
+```
+
 </code_block_bad_examples>
-</enhanced_code_block_rules>
+</enhanced_code_block_rules>

package/prompts/detail/custom/{custom-components.md → custom-components-usage-rules.md}

@@ -1,4 +1,4 @@
-<custom_components_usage>
+<custom_components_usage_rules>
 When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
 
 ## XCard: Individual link display card
@@ -48,11 +48,11 @@ Example 1: Inline Markdown formatting in card content
 
 Example 2: Code block inside card content
 
-```md
+````md
 <x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
   Creates a listener for "ctrl-break" events.
 
-\`\`\`rust
+```rust
 use tokio::signal::windows::ctrl_break;
 
 #[tokio::main]
@@ -62,10 +62,11 @@ stream.recv().await;
 println!("got ctrl-break");
 Ok(())
 }
-\`\`\`
-</x-card>
 ```
 
+````
+
+
 ## XCards: Multiple cards container
 
 Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
@@ -80,7 +81,7 @@ Suitable for displaying multiple links using a card list format, providing a ric
 
 ### Usage Rules
 
-- **Visual Consistency**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+- **Visual Consistency**: All `<x-card>` elements within the same `<x-cards>` must maintain visual consistency:
   - It's recommended to always provide data-icon for each card.
   - Or all cards should have data-image.
   - Avoid mixing (some with icons, some with only images).
@@ -106,6 +107,18 @@ Example 2: Two-column cards with images
 </x-cards>
 ```
 
+Example 3: Replace markdown format multiple links
+
+```md
+For more detailed information on specific features, please refer to the following sections:
+
+<x-cards data-columns="3">
+  <x-card data-title="Using Discussions" data-href="/discussions">Introduce how to use discussions</x-card>
+  <x-card data-title="Using the Blog" data-href="/blog">Introduce how to use the Blog</x-card>
+  <x-card data-title="Using Chat" data-href="/chat">Introduce how to use Chat</x-card>
+</x-cards>
+```
+
 ### Bad Examples
 
 Example 1: Using a single-column layout (`data-columns="1"`) is not allowed
@@ -125,6 +138,15 @@ Example 2: Contains only one `<x-card>` (must include multiple cards)
 </x-cards>
 ```
 
+Example 3: Markdown format multiple links
+
+```md
+For more detailed information on specific features, please refer to the following sections:
+- [Using Discussions](./discussions.md)
+- [Using the Blog](./blog.md)
+- [Using Chat](./chat.md)
+```
+
 ## 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.
@@ -517,4 +539,4 @@ Example 6: Missing blank line before x-field-group (violates "Spacing Around" ru
 </x-field-group>
 ```
 
-</custom_components_usage>
+</custom_components_usage_rules>

package/prompts/detail/d2-diagram/pre-check.md

@@ -0,0 +1,23 @@
+<document_content>
+{{documentContent}}
+</document_content>
+
+{% if feedback %}
+<feedback>
+{{feedback}}
+</feedback>
+{% endif %}
+
+{% if detailFeedback %}
+<content_review_feedback>
+{{ detailFeedback }}
+</content_review_feedback>
+{% endif %}
+
+{% if previousGenerationContent %}
+<previous_generation_content>
+{{ previousGenerationContent }}
+</previous_generation_content>
+{% endif %}
+
+{% include "./rules.md" %}

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

@@ -1,29 +1,44 @@
-<diagram_generation_guide>
-
-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.
-
-2. 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.
-   - 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).
-3. 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>
+
+You must analyze the provided inputs to determine if a diagram is needed and where to insert a placeholder. You must not generate the diagram itself (e.g., no Mermaid, PlantUML, or other code). You are only deciding and placing the placeholder.
+
+## Inputs
+
+- `<document_content>`: The main body of text to be evaluated.
+- `<previous_generation_content>`: The content from the previous run, which may contain DIAGRAM_PLACEHOLDER.
+- `<feedback>`: Specific user instructions for this run (e.g., "add a diagram," "remove the diagram").
+- `<content_review_feedback>`: General automated or human feedback on the content.
+
+## Scoring conditions
+
+- `add`: If `<feedback>` explicitly requests to add a diagram, ignore other conditions, +30000
+- `remove`: If `<feedback>` explicitly requests to remove a diagram, ignore other conditions, -30000
+- `previous-exists`: If `<previous_generation_content>` contains diagram, +21000
+- `path-exclude`: If the document path or filename matches excluded patterns (e.g., `/faq/`, `CHANGELOG`, `release-notes`), -10000
+- `less-words`: If document length <= 200 words AND less than 2 headings, -10000
+- `overview`: If `<document_content>` provides a high-level overview, +3
+- `architectural`: If `<document_content>` contains an architectural description (components/services/layers/modules), +3
+- `workflow`: If `<document_content>` describes a workflow, sequence, user interactions, or data flow, +2
+- `hierarchy`: If `<document_content>` describes a clear hierarchy (linked sub-docs / deeply nested sections), +1
+- `introductory-major`: If `<document_content>` is an introductory page for a major section, +1
+
+## Output Requirements
+- `details` is an array. Each element must include:
+  - `type`: matched scoring condition's type name
+  - `score`: matched scoring condition's score
+  - `reason`: text explaining why this scoring condition is matched
+- `content`: `<document_content>` with placeholder inserted
+  - Identify the most logical insertion point in the `<document_content>`. (This is often after an introductory paragraph or before a list/section that the diagram will explain).
+  - Insert the exact placeholder string: DIAGRAM_PLACEHOLDER
+  - Crucially: Adjust the surrounding text to integrate the placeholder smoothly. Add a lead-in sentence.
+  - Good example: "The following diagram illustrates this data flow:"
+  - Good example: "This architecture is shown in the overview below:"
+  - Bad example: (Just inserting the placeholder with no context).
+  - Return the modified document content.
+    - Keep the original structure of the document, including page headings and hierarchy
+      - Only modify parts of the document text to improve the alignment between diagrams and their context
+      - The output must not include the `document_content` tag
+      - Do not provide any explanations; include only the document content itself
+
+</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

@@ -14,4 +14,13 @@ Generate a d2 diagram that represents the following document content:
 
 <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
@@ -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>