@aigne/doc-smith 0.8.11-beta.4 → 0.8.11-beta.6

package/agents/publish/publish-docs.mjs

@@ -5,13 +5,17 @@ import chalk from "chalk";
 import fs from "fs-extra";
 
 import { getAccessToken } from "../../utils/auth-utils.mjs";
-import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../../utils/constants/index.mjs";
+import {
+  DEFAULT_APP_URL,
+  DISCUSS_KIT_STORE_URL,
+  DOC_SMITH_DIR,
+  TMP_DIR,
+  TMP_DOCS_DIR,
+} from "../../utils/constants/index.mjs";
 import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
 import { deploy } from "../../utils/deploy.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 
-const DEFAULT_APP_URL = "https://docsmith.aigne.io";
-
 export default async function publishDocs(
   { docsDir: rawDocsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
   options,
@@ -19,9 +23,7 @@ export default async function publishDocs(
   // move work dir to tmp-dir
   await ensureTmpDir();
 
-  const hasDocSmithBaseUrl = !!process.env.DOC_SMITH_BASE_URL;
-
-  const docsDir = join(".aigne", "doc-smith", TMP_DIR, TMP_DOCS_DIR);
+  const docsDir = join(DOC_SMITH_DIR, TMP_DIR, TMP_DOCS_DIR);
   await fs.rm(docsDir, { recursive: true, force: true });
   await fs.mkdir(docsDir, {
     recursive: true,
@@ -61,22 +63,18 @@ export default async function publishDocs(
           name: `${chalk.blue("Your existing website")} - Integrate and publish directly on your current site (setup required)`,
           value: "custom",
         },
-        ...(hasCachedCheckoutId && hasDocSmithBaseUrl
+        ...(hasCachedCheckoutId
           ? [
               {
-                name: `${chalk.yellow("Resume previous website setup")} - ${chalk.green("Already paid.")} Continue where you left off. Your payment is already processed.`,
+                name: `${chalk.yellow("Resume previous website setup")} - ${chalk.green("Already paid.")} Continue where you left off. Your payment has already been processed.`,
                 value: "new-instance-continue",
               },
             ]
           : []),
-        ...(hasDocSmithBaseUrl
-          ? [
-              {
-                name: `${chalk.blue("New website")} - ${chalk.yellow("Paid service.")} We'll help you set up a brand-new website with custom domain and hosting. Great if you want a professional presence.`,
-                value: "new-instance",
-              },
-            ]
-          : []),
+        {
+          name: `${chalk.blue("New website")} - ${chalk.yellow("Paid service.")} We'll help you set up a brand-new website with custom domain and hosting. Great if you want a professional presence.`,
+          value: "new-instance",
+        },
       ],
     });
 
@@ -100,7 +98,7 @@ export default async function publishDocs(
       });
       // Ensure appUrl has protocol
       appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
-    } else if (hasDocSmithBaseUrl && ["new-instance", "new-instance-continue"].includes(choice)) {
+    } else if (["new-instance", "new-instance-continue"].includes(choice)) {
       // Deploy a new Discuss Kit service
       try {
         let id = "";
@@ -118,8 +116,7 @@ export default async function publishDocs(
         token = ltToken;
       } catch (error) {
         const errorMsg = error?.message || "Unknown error occurred";
-        console.error(`${chalk.red("❌ Failed to publish to website:")} ${errorMsg}`);
-        return { message: `❌ Publish failed: ${errorMsg}` };
+        return { message: `${chalk.red("❌ Failed to publish to website:")} ${errorMsg}` };
       }
     }
   }
@@ -168,7 +165,7 @@ export default async function publishDocs(
       boardDesc: projectInfo.description,
       boardCover: projectInfo.icon,
       mediaFolder: rawDocsDir,
-      cacheFilePath: join(".aigne", "doc-smith", "upload-cache.yaml"),
+      cacheFilePath: join(DOC_SMITH_DIR, "upload-cache.yaml"),
       boardMeta,
     });
 

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

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

package/agents/update/check-document.mjs

@@ -36,10 +36,10 @@ export default async function checkDocument(
     detailGenerated = false;
   }
 
-  // Check if sourceIds have changed by comparing with original document structure
+  // Check if sourceIds have changed by comparing with original documentation structure
   let sourceIdsChanged = false;
   if (originalDocumentStructure && sourceIds) {
-    // Find the original node in the document structure
+    // Find the original node in the documentation structure
     const originalNode = originalDocumentStructure.find((node) => node.path === path);
 
     if (originalNode?.sourceIds) {

package/agents/update/generate-document.yaml

@@ -48,3 +48,28 @@ output_schema:
       type: string
   required:
     - content
+skills:
+  - type: team
+    task_render_mode: collapse
+    name: generateD2DiagramContent
+    skills:
+      - ../generate/generate-d2-diagram.yaml
+    reflection:
+      reviewer: ../generate/check-d2-diagram-valid.mjs
+      is_approved: isValid
+      max_iterations: 5
+      return_last_on_max_iterations: true
+    input_schema:
+      type: object
+      properties:
+        documentContent:
+          type: string
+          description: Source code of current document (without the D2 diagram)
+      required:
+        - documentContent
+    output_schema:
+      type: object
+      properties:
+        d2DiagramSourceCode:
+          type: string
+          description: Source code for the D2 diagram

package/agents/utils/check-feedback-refiner.mjs

@@ -62,7 +62,7 @@ checkFeedbackRefiner.input_schema = {
     },
     documentStructureFeedback: {
       type: "string",
-      description: "Feedback from document structure stage",
+      description: "Feedback from documentation structure stage",
     },
     stage: {
       type: "string",

package/agents/utils/choose-docs.mjs

@@ -41,7 +41,7 @@ export default async function chooseDocs(
 
       // Convert files to choices with titles
       const choices = mainLanguageFiles.map((file) => {
-        // Convert filename to flat path to find corresponding document structure item
+        // Convert filename to flat path to find corresponding documentation structure item
         const flatName = file.replace(/\.md$/, "").replace(/\.\w+(-\w+)?$/, "");
         const docItem = documentExecutionStructure.find((item) => {
           const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");

package/agents/utils/load-document-all-content.mjs

@@ -4,19 +4,19 @@ import { findItemByPath, readFileContent } from "../../utils/docs-finder-utils.m
 /**
  * Loads a document's content along with all its translations from the docs directory.
  *
- * This function finds a document by its path in the document structure, then searches
+ * This function finds a document by its path in the documentation structure, then searches
  * for all translation files in the docs directory that match the document's naming pattern.
  * Translation files are identified by the pattern: {flatName}.{language-code}.md
  *
  * @param {Object} params - The parameters object
  * @param {string} params.path - The document path to find in the structure
  * @param {string} params.docsDir - The directory containing document files and translations
- * @param {Object} params.documentStructure - The document structure object to search in
+ * @param {Object} params.documentStructure - The documentation structure object to search in
  * @returns {Promise<Object>} An object containing the document data with translations
  * @throws {Error} Throws an error if the document path is not found in the structure
  */
 export default async function loadDocumentAllContent({ path, docsDir, documentStructure }) {
-  // Find the document item by path in the document structure
+  // Find the document item by path in the documentation structure
   const result = await findItemByPath(documentStructure, path, null, docsDir);
 
   if (!result) {

package/agents/utils/load-sources.mjs

@@ -175,7 +175,7 @@ export default async function loadSources({
     }),
   );
 
-  // Get the last document structure
+  // Get the last documentation structure
   let originalDocumentStructure;
   if (outputDir) {
     const documentStructurePath = path.join(outputDir, "structure-plan.json");

package/agents/utils/save-docs.mjs

@@ -35,39 +35,18 @@ export default async function saveDocs({
     console.error("Failed to save _sidebar.md:", err.message);
   }
 
-  // Clean up invalid .md files that are no longer in the document structure
+  // Clean up invalid .md files that are no longer in the documentation structure
   try {
     await cleanupInvalidFiles(documentStructure, docsDir, translateLanguages, locale);
   } catch (err) {
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  const message = `# ✅ Documentation Generated Successfully!
-
-Generated **${documentStructure.length}** documents and saved to: \`${docsDir}\`
+  const message = `
+✅ Documentation generated successfully! (\`${documentStructure.length}\` documents → \`${docsDir}\`)
 ${projectInfoMessage || ""}
-## 🚀 Next Steps
-
-**Publish Your Documentation**
-
-Generate a shareable preview link for your team:
-
-  \`aigne doc publish\`
-
-## 🔧 Optional Actions
-
-**Update Specific Documents**
-
-Regenerate content for individual documents:
-
-  \`aigne doc update\`
-
-**Refine Document Structure**
-
-Review and improve your documentation organization:
-
-  \`aigne doc generate\`
-
+🚀 Next: Make your documentation live and generate a shareable link, run: \`aigne doc publish\`
+💡 Optional: Update specific document (\`aigne doc update\`) or refine documentation structure (\`aigne doc generate\`)
   `;
 
   // Shutdown mermaid worker pool to ensure clean exit
@@ -94,7 +73,7 @@ function generateFileName(flatName, language) {
 }
 
 /**
- * Clean up .md files that are no longer in the document structure
+ * Clean up .md files that are no longer in the documentation structure
  * @param {Array<{path: string, title: string}>} documentStructure
  * @param {string} docsDir
  * @param {Array<string>} translateLanguages
@@ -109,7 +88,7 @@ async function cleanupInvalidFiles(documentStructure, docsDir, translateLanguage
     const files = await readdir(docsDir);
     const mdFiles = files.filter((file) => file.endsWith(".md"));
 
-    // Generate expected file names from document structure
+    // Generate expected file names from documentation structure
     const expectedFiles = new Set();
 
     // Add main document files

package/aigne.yaml

@@ -9,7 +9,7 @@ agents:
   # Initialization
   - ./agents/init/index.mjs
 
-  # Document Structure Generation
+  # Documentation Structure Generation
   - ./agents/generate/generate-structure.yaml
   - ./agents/generate/update-document-structure.yaml
   - ./agents/generate/check-need-generate-structure.mjs
@@ -18,7 +18,7 @@ agents:
   - ./agents/generate/user-review-document-structure.mjs
   - ./agents/generate/index.yaml
   
-  # Document Structure Tools
+  # Documentation Structure Tools
   - ./agents/generate/document-structure-tools/add-document.mjs
   - ./agents/generate/document-structure-tools/delete-document.mjs
   - ./agents/generate/document-structure-tools/update-document.mjs

package/docs/_sidebar.md

@@ -14,4 +14,4 @@
 * [Advanced Topics](/advanced.md)
   * [How It Works](/advanced-how-it-works.md)
   * [Quality Assurance](/advanced-quality-assurance.md)
-* [Changelog](/changelog.md)
+* [Changelog](/changelog.md)

package/docs/advanced-how-it-works.md

@@ -73,7 +73,7 @@ User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 
 1.  **Input Analysis**: The process begins when agents load your source code and project configuration (`aigne.yaml`).
 
-2.  **Structure Planning**: An agent analyzes the codebase to propose a logical document structure. It creates an outline based on the project's composition and any specified rules.
+2.  **Structure Planning**: An agent analyzes the codebase to propose a logical documentation structure. It creates an outline based on the project's composition and any specified rules.
 
 3.  **Content Generation**: With the structure in place, content generation agents populate each section of the document plan with detailed text, code examples, and explanations.
 
@@ -88,8 +88,8 @@ DocSmith's functionality is provided by a collection of agents defined in the pr
 | Functional Role          | Key Agent Files                                      | Description                                                                          |
 | ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | **Structure Planning**   | `generate/generate-structure.yaml`                   | Analyzes source code to propose the initial document outline.                        |
-| **Structure Refinement** | `generate/refine-document-structure.yaml`            | Modifies the document structure based on user feedback.                              |
-| **Content Generation**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | Populates the document structure with detailed content for each section.             |
+| **Structure Refinement** | `generate/refine-document-structure.yaml`            | Modifies the documentation structure based on user feedback.                              |
+| **Content Generation**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | Populates the documentation structure with detailed content for each section.             |
 | **Translation**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | Translates generated documentation into multiple target languages.                   |
 | **Publishing**           | `publish/publish-docs.mjs`                           | Manages the process of publishing documents to Discuss Kit instances.                |
 | **Data I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | Responsible for reading source files and writing the final markdown documents to disk. |

package/docs/advanced-quality-assurance.md

@@ -68,7 +68,7 @@ DocSmith performs several checks to ensure the structural integrity of the conte
 
 #### Link and Media Integrity
 
-- **Link Integrity**: All relative links within the documentation are validated against the document structure plan to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
+- **Link Integrity**: All relative links within the documentation are validated against the documentation structure to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
 
 - **Image Validation**: To avoid broken images, the checker verifies that any local image file referenced in the documentation exists on the file system. It resolves both relative and absolute paths to confirm the file is present. External image URLs and data URLs are not checked.