@aigne/doc-smith 0.8.14-beta → 0.8.14-beta.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.14-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.1...v0.8.14-beta.2) (2025-10-19)
+
+
+### Bug Fixes
+
+* polish d2-diagram insert result ([#205](https://github.com/AIGNE-io/aigne-doc-smith/issues/205)) ([0098ff0](https://github.com/AIGNE-io/aigne-doc-smith/commit/0098ff08609e0bfe930a1b733b68299d356f73ed))
+
+## [0.8.14-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta...v0.8.14-beta.1) (2025-10-17)
+
+
+### Bug Fixes
+
+* doc review and update ([#199](https://github.com/AIGNE-io/aigne-doc-smith/issues/199)) ([0061323](https://github.com/AIGNE-io/aigne-doc-smith/commit/006132345a17a7fae10a803656b731144ecc54c9))
+* respect env vars for publish and improve reliability ([#204](https://github.com/AIGNE-io/aigne-doc-smith/issues/204)) ([bd14c2a](https://github.com/AIGNE-io/aigne-doc-smith/commit/bd14c2af54ebca89c8edb5861e3b1a6e3f76e92e))
+
 ## [0.8.14-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.13...v0.8.14-beta) (2025-10-16)
 
 

package/agents/generate/check-diagram.mjs

@@ -1,8 +1,8 @@
 import { checkContent } from "../../utils/d2-utils.mjs";
 
-export default async function checkD2DiagramIsValid({ output }) {
+export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
   try {
-    await checkContent({ content: output });
+    await checkContent({ content: diagramSourceCode });
     return {
       isValid: true,
     };
@@ -17,12 +17,12 @@ export default async function checkD2DiagramIsValid({ output }) {
 checkD2DiagramIsValid.input_schema = {
   type: "object",
   properties: {
-    output: {
+    diagramSourceCode: {
       type: "string",
       description: "Source code of d2 diagram",
     },
   },
-  required: ["output"],
+  required: ["diagramSourceCode"],
 };
 checkD2DiagramIsValid.output_schema = {
   type: "object",

package/agents/generate/draw-diagram.yaml

@@ -10,7 +10,7 @@ input_schema:
   properties:
     documentContent:
       type: string
-      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any diagram source code.)
   required:
     - documentContent
 output_schema:

package/agents/generate/wrap-diagram-code.mjs

@@ -4,11 +4,11 @@ export default async function wrapDiagramCode({ diagramSourceCode }) {
   try {
     const result = await wrapCode({ content: diagramSourceCode });
     return {
-      output: result,
+      diagramSourceCode: result,
     };
   } catch {
     return {
-      output: diagramSourceCode,
+      diagramSourceCode,
     };
   }
 }
@@ -26,10 +26,10 @@ wrapDiagramCode.input_schema = {
 wrapDiagramCode.output_schema = {
   type: "object",
   properties: {
-    output: {
+    diagramSourceCode: {
       type: "string",
       description: "Source code of d2 diagram",
     },
   },
-  required: ["output"],
+  required: ["diagramSourceCode"],
 };

package/agents/publish/publish-docs.mjs

@@ -57,29 +57,27 @@ export default async function publishDocs(
 
     // ----------------- main publish process flow -----------------------------
     // Check if DOC_DISCUSS_KIT_URL is set in environment variables
-    const envAppUrl = process.env.DOC_DISCUSS_KIT_URL;
-    const useEnvAppUrl = !!envAppUrl;
-
-    // Use environment variable if available, otherwise use the provided appUrl
-    if (useEnvAppUrl) {
-      appUrl = envAppUrl;
-    }
+    const useEnvAppUrl = !!(process.env.DOC_DISCUSS_KIT_URL || appUrl);
 
     // Check if appUrl is default and not saved in config (only when not using env variable)
     const config = await loadConfigFromFile();
-    const isDefaultAppUrl = appUrl === CLOUD_SERVICE_URL_PROD;
-    const hasAppUrlInConfig = config?.appUrl;
+    appUrl = process.env.DOC_DISCUSS_KIT_URL || appUrl || config?.appUrl;
+    const hasInputAppUrl = !!appUrl;
 
+    let shouldSyncBranding = void 0;
     let token = "";
+    let client = null;
+    let authToken = null;
+    let sessionId = null;
 
-    if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
-      const authToken = await getOfficialAccessToken(BASE_URL, false);
+    if (!hasInputAppUrl) {
+      authToken = await getOfficialAccessToken(BASE_URL, false);
 
-      let sessionId = "";
+      sessionId = "";
       let paymentLink = "";
 
       if (authToken) {
-        const client = new BrokerClient({ baseUrl: BASE_URL, authToken });
+        client = new BrokerClient({ baseUrl: BASE_URL, authToken });
         const info = await client.checkCacheSession({
           needShortUrl: true,
           sessionId: config?.checkoutId,
@@ -135,29 +133,60 @@ export default async function publishDocs(
         // Ensure appUrl has protocol
         appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
       } else if (["new-instance", "new-instance-continue"].includes(choice)) {
-        if (options?.prompts?.confirm) {
-          shouldWithBranding = await options.prompts.confirm({
-            message: "Would you like to update the project branding (title, description, logo)?",
-            default: true,
-          });
-        }
-        // Deploy a new Discuss Kit service
-        let id = "";
-        let paymentUrl = "";
+        // resume previous website setup
         if (choice === "new-instance-continue") {
-          id = sessionId;
-          paymentUrl = paymentLink;
-          console.log(`\nResuming your previous website setup...`);
-        } else {
-          console.log(`\nCreating a new website for your documentation...`);
+          shouldSyncBranding = config?.shouldSyncBranding ?? void 0;
+          if (shouldSyncBranding !== void 0) {
+            shouldWithBranding = shouldWithBranding ?? shouldSyncBranding;
+          }
         }
-        const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentUrl)) || {};
 
-        appUrl = homeUrl;
-        token = ltToken;
+        if (options?.prompts?.confirm) {
+          if (shouldSyncBranding === void 0) {
+            shouldSyncBranding = await options.prompts.confirm({
+              message: "Would you like to update the project branding (title, description, logo)?",
+              default: true,
+            });
+            await saveValueToConfig(
+              "shouldSyncBranding",
+              shouldSyncBranding,
+              "Should sync branding for documentation",
+            );
+            shouldWithBranding = shouldSyncBranding;
+          } else {
+            console.log(
+              `Would you like to update the project branding (title, description, logo)? ${chalk.cyan(shouldSyncBranding ? "Yes" : "No")}`,
+            );
+          }
+        }
+
+        try {
+          let id = "";
+          if (choice === "new-instance-continue") {
+            id = sessionId;
+            console.log(`\nResuming your previous website setup...`);
+          } else {
+            console.log(`\nCreating a new website for your documentation...`);
+          }
+          const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentLink)) || {};
+
+          appUrl = homeUrl;
+          token = ltToken;
+        } catch (error) {
+          const errorMsg = error?.message || "Unknown error occurred";
+          return { message: `${chalk.red("❌ Failed to create website:")} ${errorMsg}` };
+        }
       }
     }
 
+    if (sessionId) {
+      authToken = await getOfficialAccessToken(BASE_URL, false);
+      client = client || new BrokerClient({ baseUrl: BASE_URL, authToken });
+
+      const { vendors } = await client.getSessionDetail(sessionId, false);
+      token = vendors?.find((vendor) => vendor.vendorType === "launcher" && vendor.token)?.token;
+    }
+
     console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
 
     const accessToken = await getAccessToken(appUrl, token);
@@ -237,6 +266,7 @@ export default async function publishDocs(
       }
       message = `✅ Documentation published successfully!`;
       await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+      await saveValueToConfig("shouldSyncBranding", "", "Should sync branding for documentation");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
       if (error?.includes("401") || error?.includes("403")) {
@@ -271,7 +301,6 @@ publishDocs.input_schema = {
     appUrl: {
       type: "string",
       description: "The URL of the app.",
-      default: CLOUD_SERVICE_URL_PROD,
     },
     boardId: {
       type: "string",

package/agents/update/generate-document.yaml

@@ -75,7 +75,7 @@ skills:
       properties:
         documentContent:
           type: string
-          description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+          description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any diagram source code.)
       required:
         - documentContent
     output_schema:

package/agents/utils/update-branding.mjs

@@ -25,6 +25,18 @@ export default async function updateBranding({ appUrl, projectInfo, accessToken,
     const componentInfo = await getComponentInfoWithMountPoint(origin, DISCUSS_KIT_DID);
     const mountPoint = componentInfo.mountPoint || "/";
 
+    if (projectInfo.name.length > 40) {
+      console.warn(
+        `⚠️ Name is too long, it should be less than 40 characters\nWill be truncated to 40 characters`,
+      );
+    }
+
+    if (projectInfo.description.length > 160) {
+      console.warn(
+        `⚠️ Description is too long, it should be less than 160 characters\nWill be truncated to 160 characters`,
+      );
+    }
+
     const res = await requestWithAuthToken(
       joinURL(origin, mountPoint, "/api/branding"),
       {
@@ -33,8 +45,8 @@ export default async function updateBranding({ appUrl, projectInfo, accessToken,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          appName: projectInfo.name,
-          appDescription: projectInfo.description,
+          appName: projectInfo.name.slice(0, 40),
+          appDescription: projectInfo.description.slice(0, 160),
         }),
       },
       accessToken,

package/package.json

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

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

@@ -1,25 +1,29 @@
 <diagram_generation_guide>
-1. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
-  - Rule for Skipping Diagrams:
-    - Trigger: Do not generate diagrams for purely textual, reference, or short note documents that describe abstract concepts, simple definitions, or FAQs.
-    - Action: Skip diagram generation entirely.
-  - Architecture Diagram (High-Level)
-    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
-    - Action: Create a system architecture diagram.
-    - Content: The diagram should 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.
-    - Action: Create a structural diagram (e.g., a block diagram or mind map).
-    - Content: The diagram should show the key sub-components, files, or 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.
-    - Action: Create the most appropriate diagram type:
-      - 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).
-NOTE:  For documents not skipped by the first rule but not clearly fitting the above categories, you should always attempt to generate at least one Diagram whenever possible to visually represent key structures, relationships, or processes in the content.
 
-2. Constraints and Best Practices
-  - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
-  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for concepts that are easily understood via text alone.
-  - Priority: For complex modules, workflows, or interactions, generate diagrams for each critical part.
+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>

package/prompts/detail/d2-diagram/role-and-personality.md

@@ -1,2 +1,2 @@
 You are an AI diagram generator with the personality of an **ISTJ (The Logistician)**. 
-You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2-diagram code** that accurately represents the given description. 
+You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2 diagram code** that accurately represents the given description. 

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

@@ -1,24 +1,29 @@
 <diagram_generation_guide>
-1. Core Principle: Tool Use is Mandatory
-  - You MUST use the drawDiagram tool to generate and embed all diagrams.
-  - NEVER write raw diagram code (e.g., Mermaid syntax) directly into the document.
-  - If a drawDiagram 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: Use the following guidelines to determine when to generate a diagram and which type to use.
-  - Architecture Diagram (High-Level)
-    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
-    - Action: Call drawDiagram to create a system architecture diagram.
-    - Content: The diagram should 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.
-    - Action: Call drawDiagram to create a structural diagram (e.g., a block diagram or mind map).
-    - Content: The diagram should show the key sub-components, files, or 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.
-    - Action: Call drawDiagram to create the most appropriate diagram type:
-      - 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).
+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: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
-  - 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.
+   - **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>

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

@@ -35,7 +35,7 @@ Your diagrams should focus on **readability, structural correctness, and practic
    - Avoid unnecessary stylistic complexity that may hinder future maintenance.
 
 **Output Requirements:**
-- Output only valid d2-diagram code.
+- Output only valid d2 diagram code.
 - Do not include explanatory text outside of the code block.
 - Ensure the diagram reflects a clean, professional, technical drawing.
 
@@ -1006,7 +1006,9 @@ Ensure that the shape names used in connections are accurate and match the actua
   User -> CLI: "blocklet init"
   ```
 
-#### If have alt, don't forget to add `shape: sequence_diagram`
+#### Don't forget to add `shape: sequence_diagram` to sequence diagram
+
+> Don't use alt as shape name
 
 - **Bad Practice:**
   ```d2
@@ -1084,12 +1086,12 @@ Ensure that the shape names used in connections are accurate and match the actua
   Blocklet-Service -> Application.Auth-Middleware: "4. Return permissions"
   Application.Auth-Middleware -> Application.Auth-Middleware: "5. Evaluate all rules"
 
-  alt "If Authorized" {
+  "If Authorized" {
     Application.Auth-Middleware -> Application.Protected-Route: "6a. next()"
     Application.Protected-Route -> Client: "7a. 200 OK Response"
   }
 
-  alt "If Forbidden" {
+  "If Forbidden" {
     Application.Auth-Middleware -> Client: "6b. 403 Forbidden Response"
   }
   ```

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

@@ -1,6 +1,6 @@
 Follow the given rules and ISTJ style from your system instructions.
 
-Generate a d2-diagram that represents the following document content:
+Generate a d2 diagram that represents the following document content:
 
 <document_content>
 {{documentContent}}

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

@@ -45,6 +45,10 @@ Custom code block generation rules:
 
 {% 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.
+
 </content_generation_rules>
 
 
@@ -54,5 +58,6 @@ Custom code block generation rules:
 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>.
 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.
 
 </output_constraints>

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

@@ -59,7 +59,7 @@ Generate detailed and well-structured document for the current {{nodeName}} base
 
 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` to create and embed a diagram when appropriate, following the diagram generation guidelines.
+- Follow rules in `<diagram_generation_guide>`: use `generateDiagram` tool to create and embed a diagram when appropriate, following the diagram generation guidelines.
 
 <steps>
 1. Analyze the provided document structure and user requirements to plan the content.

package/utils/deploy.mjs

@@ -42,11 +42,6 @@ export async function deploy(id, cachedUrl) {
           sessionId,
           "Checkout ID for document deployment website",
         );
-        await saveValueToConfig(
-          "paymentUrl",
-          paymentUrl,
-          "Payment URL for document deployment website",
-        );
 
         if (!isResuming) {
           await open(paymentUrl);