@aigne/doc-smith 0.8.15-beta.5 → 0.8.15-beta.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.8.15-beta.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.6...v0.8.15-beta.7) (2025-10-31)
+
+
+### Features
+
+* add web-smith powered web-pages ([#229](https://github.com/AIGNE-io/aigne-doc-smith/issues/229)) ([c3c00c1](https://github.com/AIGNE-io/aigne-doc-smith/commit/c3c00c12f092b125b6adb1a13ed5ff9720fbdab7))
+* support cleaning specific documents ([#231](https://github.com/AIGNE-io/aigne-doc-smith/issues/231)) ([67607c9](https://github.com/AIGNE-io/aigne-doc-smith/commit/67607c9ff3852cc81a29e5a11b2151d26879b000))
+
+
+### Bug Fixes
+
+* tune custom component prompt and batch update history ([#228](https://github.com/AIGNE-io/aigne-doc-smith/issues/228)) ([ab13b97](https://github.com/AIGNE-io/aigne-doc-smith/commit/ab13b9737e5f111d0939f9c39ee76e13c0692a68))
+
+## [0.8.15-beta.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.5...v0.8.15-beta.6) (2025-10-30)
+
+
+### Bug Fixes
+
+* ensure document embed image is accessible ([#226](https://github.com/AIGNE-io/aigne-doc-smith/issues/226)) ([47dfc5d](https://github.com/AIGNE-io/aigne-doc-smith/commit/47dfc5d48440f435258c7d4b5629712c7eb886e7))
+
 ## [0.8.15-beta.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.4...v0.8.15-beta.5) (2025-10-29)
 
 

package/agents/clear/choose-contents.mjs

@@ -10,7 +10,7 @@ const TARGET_METADATA = {
   generatedDocs: {
     label: "Generated Documents",
     description: ({ docsDir }) =>
-      `Delete all generated documents in './${toDisplayPath(docsDir)}'. The documentation structure will be preserved.`,
+      `Select and delete specific generated documents in './${toDisplayPath(docsDir)}'. The documentation structure will be preserved.`,
     agent: "clearGeneratedDocs",
   },
   documentStructure: {
@@ -150,9 +150,9 @@ export default async function chooseContents(input = {}, options = {}) {
   }
 
   const header = hasError
-    ? "Cleanup finished with some issues."
-    : "Cleanup completed successfully!";
-  const detailLines = results.map((item) => `- ${item.message}`).join("\n");
+    ? "🧹 Cleanup finished with some issues.\n"
+    : "🧹 Cleanup completed successfully!\n";
+  const detailLines = results.map((item) => `${item.message}`).join("\n\n");
 
   const suggestions = [];
   results.forEach((result) => {

package/agents/clear/clear-auth-tokens.mjs

@@ -9,7 +9,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
   // Check if the file exists
   if (!existsSync(DOC_SMITH_ENV_FILE)) {
     return {
-      message: "No site authorizations found to clear",
+      message: "🔑 No site authorizations found to clear",
     };
   }
 
@@ -23,7 +23,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
 
     if (siteHostnames.length === 0) {
       return {
-        message: "No site authorizations found to clear",
+        message: "🔑 No site authorizations found to clear",
       };
     }
 
@@ -58,7 +58,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
 
     if (selectedSites.length === 0) {
       return {
-        message: "No sites selected for clearing authorization",
+        message: "🔑 No sites selected for clearing authorization",
       };
     }
 
@@ -68,7 +68,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
     if (selectedSites.includes("__ALL__")) {
       // Clear all site authorizations
       await writeFile(DOC_SMITH_ENV_FILE, stringify({}));
-      results.push(`Cleared site authorization for all sites (${siteHostnames.length} sites)`);
+      results.push(`✔ Cleared site authorization for all sites (${siteHostnames.length} sites)`);
       clearedCount = siteHostnames.length;
     } else {
       // Clear site authorizations for selected sites
@@ -79,7 +79,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
           // Remove the entire site object
           delete updatedEnvs[hostname];
 
-          results.push(`Cleared site authorization for ${chalk.cyan(hostname)}`);
+          results.push(`✔ Cleared site authorization for ${chalk.cyan(hostname)}`);
           clearedCount++;
         }
       }
@@ -87,8 +87,8 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
       await writeFile(DOC_SMITH_ENV_FILE, stringify(updatedEnvs));
     }
 
-    const header = `Successfully cleared site authorizations!`;
-    const detailLines = results.join("\n");
+    const header = `🔑 Successfully cleared site authorizations!`;
+    const detailLines = results.map((item) => `  ${item}`).join("\n");
 
     const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
 
@@ -99,7 +99,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
     };
   } catch (error) {
     return {
-      message: `Failed to clear site authorizations: ${error.message}`,
+      message: `⚠️ Failed to clear site authorizations: ${error.message}`,
       error: true,
     };
   }

package/agents/clear/clear-deployment-config.mjs

@@ -36,12 +36,12 @@ export default async function clearDeploymentConfig(input = {}) {
     }
 
     return {
-      message: `🧹 Cleared appUrl from config file (${displayPath})`,
+      message: `📦 Cleared appUrl from config file (${displayPath})`,
     };
   } catch (error) {
     return {
       error: true,
-      message: `❌ Failed to clear deployment config: ${error.message}`,
+      message: `⚠️ Failed to clear deployment config: ${error.message}`,
     };
   }
 }

package/agents/clear/clear-document-config.mjs

@@ -10,8 +10,8 @@ export default async function clearDocumentConfig({ workDir }) {
     await rm(documentConfigPath, { recursive: true, force: true });
 
     const message = existed
-      ? `Cleared document configuration (${displayPath})`
-      : `Document configuration already empty (${displayPath})`;
+      ? `⚙️ Cleared document configuration (${displayPath})`
+      : `⚙️ Document configuration already empty (${displayPath})`;
 
     const suggestions = existed
       ? ["Run `aigne doc init` to generate a fresh configuration file."]
@@ -25,7 +25,7 @@ export default async function clearDocumentConfig({ workDir }) {
     };
   } catch (error) {
     return {
-      message: `Failed to clear document configuration: ${error.message}`,
+      message: `⚠️ Failed to clear document configuration: ${error.message}`,
       error: true,
       path: displayPath,
     };

package/agents/clear/clear-document-structure.mjs

@@ -16,8 +16,8 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
     const structureDisplayPath = toDisplayPath(structurePlanPath);
     const structureMessage = structureExists
-      ? `Cleared documentation structure (${structureDisplayPath})`
-      : `Documentation structure already empty (${structureDisplayPath})`;
+      ? `✔ Cleared documentation structure (${structureDisplayPath})`
+      : `• Documentation structure already empty (${structureDisplayPath})`;
 
     results.push({
       type: "structure",
@@ -29,7 +29,7 @@ export default async function clearDocumentStructure(input = {}, _options = {})
     results.push({
       type: "structure",
       error: true,
-      message: `Failed to clear documentation structure: ${error.message}`,
+      message: `✗ Failed to clear documentation structure: ${error.message}`,
     });
   }
 
@@ -41,8 +41,8 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
       const docsDisplayPath = toDisplayPath(docsDir);
       const docsMessage = docsExists
-        ? `Cleared documents directory (${docsDisplayPath})`
-        : `Documents directory already empty (${docsDisplayPath})`;
+        ? `✔ Cleared documents directory (${docsDisplayPath})`
+        : `• Documents directory already empty (${docsDisplayPath})`;
 
       results.push({
         type: "documents",
@@ -54,7 +54,7 @@ export default async function clearDocumentStructure(input = {}, _options = {})
       results.push({
         type: "documents",
         error: true,
-        message: `Failed to clear documents directory: ${error.message}`,
+        message: `✗ Failed to clear documents directory: ${error.message}`,
       });
     }
   }
@@ -65,14 +65,14 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
   let header;
   if (errorItems > 0) {
-    header = "Documentation Structure cleanup finished with some issues.";
+    header = "⚠️ Documentation Structure cleanup finished with some issues.";
   } else if (clearedItems > 0) {
-    header = "Documentation Structure cleared successfully!";
+    header = "📖 Documentation Structure cleared successfully!";
   } else {
-    header = "Documentation Structure already empty.";
+    header = "📖 Documentation Structure already empty.";
   }
 
-  const detailLines = results.map((item) => `- ${item.message}`).join("\n");
+  const detailLines = results.map((item) => `  ${item.message}`).join("\n");
   const message = [header, "", detailLines].filter(Boolean).join("\n");
 
   return {

package/agents/clear/clear-generated-docs.mjs

@@ -1,12 +1,19 @@
 import { rm } from "node:fs/promises";
+import { join } from "node:path";
 import { pathExists, resolveToAbsolute, toDisplayPath } from "../../utils/file-utils.mjs";
+import {
+  pathToFlatName,
+  generateFileName,
+  loadDocumentStructure,
+} from "../../utils/docs-finder-utils.mjs";
+import chooseDocs from "../utils/choose-docs.mjs";
 
-export default async function clearGeneratedDocs(input = {}, _options = {}) {
-  const { docsDir } = input;
+export default async function clearGeneratedDocs(input = {}, options = {}) {
+  const { docsDir, outputDir, locale, translateLanguages } = input;
 
   if (!docsDir) {
     return {
-      message: "No generated documents directory specified",
+      message: "📁 No generated documents directory specified",
     };
   }
 
@@ -14,23 +21,104 @@ export default async function clearGeneratedDocs(input = {}, _options = {}) {
   const displayPath = toDisplayPath(generatedDocsPath);
 
   try {
-    const existed = await pathExists(generatedDocsPath);
-    await rm(generatedDocsPath, { recursive: true, force: true });
+    const dirExists = await pathExists(generatedDocsPath);
+    if (!dirExists) {
+      return {
+        message: `📁 Generated documents directory does not exist (${displayPath})`,
+        cleared: false,
+      };
+    }
 
-    const message = existed
-      ? `Cleared generated documents (${displayPath})`
-      : `Generated documents already empty (${displayPath})`;
+    const documentExecutionStructure = (await loadDocumentStructure(outputDir)) || [];
+    // select documents interactively
+    const chooseResult = await chooseDocs(
+      {
+        docs: [], // Empty to trigger interactive selection
+        documentExecutionStructure,
+        docsDir: generatedDocsPath,
+        locale: locale || "en",
+        isTranslate: false,
+        title: "Select documents to delete:",
+        feedback: "Skip feedback",
+        requiredFeedback: false,
+      },
+      options,
+    );
+
+    if (!chooseResult?.selectedDocs || chooseResult.selectedDocs.length === 0) {
+      return {
+        message: "📁 No documents selected for deletion",
+        cleared: false,
+        path: displayPath,
+      };
+    }
+
+    // Extract file names
+    const filesToDelete = new Set();
+    const allLanguages = [locale || "en", ...(translateLanguages || [])];
+
+    for (const selectedDoc of chooseResult.selectedDocs) {
+      // Convert path to flat filename format using utility function
+      const flatName = pathToFlatName(selectedDoc.path);
+
+      // Generate file names for all languages
+      for (const lang of allLanguages) {
+        const fileName = generateFileName(flatName, lang);
+        filesToDelete.add(fileName);
+      }
+    }
+
+    if (filesToDelete.size === 0) {
+      return {
+        message: "📁 No documents were deleted.",
+        cleared: false,
+      };
+    }
+
+    // Delete selected files (including all language versions)
+    const deletedFiles = [];
+    const failedFiles = [];
+    let hasError = false;
+
+    for (const file of filesToDelete) {
+      try {
+        const filePath = join(generatedDocsPath, file);
+        await rm(filePath, { force: true });
+        deletedFiles.push(file);
+      } catch (error) {
+        hasError = true;
+        failedFiles.push({ file, error: error.message });
+      }
+    }
+
+    // Build result message
+    const deletedCount = deletedFiles.length;
+    const failedCount = failedFiles.length;
+
+    let message = "";
+    if (deletedCount > 0) {
+      const lastIndex = deletedFiles.length - 1;
+      message = `📁 Deleted ${deletedCount} document(s) in "${displayPath}":\n${deletedFiles
+        .map((f, i) => `  ${i === lastIndex ? "└─" : "├─"} ${f}`)
+        .join("\n")}`;
+    }
+
+    if (failedCount > 0) {
+      const lastIndex = failedFiles.length - 1;
+      message = `⚠️ Failed to delete ${failedCount} document(s) in "${displayPath}":\n${failedFiles
+        .map((f, i) => `  ${i === lastIndex ? "└─" : "├─"} ${f.file}: ${f.error}`)
+        .join("\n")}`;
+    }
 
     return {
       message,
-      cleared: existed,
-      path: displayPath,
+      cleared: deletedCount > 0,
+      error: hasError,
     };
   } catch (error) {
     return {
-      message: `Failed to clear generated documents: ${error.message}`,
+      message: `⚠️ Failed to clear generated documents: ${error.message}`,
       error: true,
-      path: displayPath,
     };
   }
 }
@@ -46,5 +134,6 @@ clearGeneratedDocs.input_schema = {
   required: ["docsDir"],
 };
 
-clearGeneratedDocs.taskTitle = "Clear all generated documents";
-clearGeneratedDocs.description = "Clear the generated documents directory";
+clearGeneratedDocs.taskTitle = "Clear generated documents";
+clearGeneratedDocs.description =
+  "Select and delete specific generated documents from the docs directory";

package/agents/clear/clear-media-description.mjs

@@ -11,7 +11,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
   // Check if the cache file exists
   if (!existsSync(cacheFilePath)) {
     return {
-      message: "No media descriptions found to clear",
+      message: "🖼️ No media descriptions found to clear",
     };
   }
 
@@ -26,7 +26,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
 
     if (mediaHashes.length === 0) {
       return {
-        message: "No media descriptions found to clear",
+        message: "🖼️ No media descriptions found to clear",
       };
     }
 
@@ -68,7 +68,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
 
     if (selectedHashes.length === 0) {
       return {
-        message: "No media files selected for clearing descriptions",
+        message: "🖼️ No media files selected for clearing descriptions",
       };
     }
 
@@ -84,7 +84,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
           lastUpdated: new Date().toISOString(),
         }),
       );
-      results.push(`Cleared descriptions for all media files (${mediaHashes.length} files)`);
+      results.push(`✔ Cleared descriptions for all media files (${mediaHashes.length} files)`);
       clearedCount = mediaHashes.length;
     } else {
       // Clear descriptions for selected files
@@ -94,7 +94,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
         if (updatedCache[hash]) {
           const filename = path.basename(updatedCache[hash].path);
           delete updatedCache[hash];
-          results.push(`Cleared description for ${chalk.cyan(filename)}`);
+          results.push(`✔ Cleared description for ${chalk.cyan(filename)}`);
           clearedCount++;
         }
       }
@@ -108,8 +108,8 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
       );
     }
 
-    const header = `✨ Successfully cleared media descriptions`;
-    const detailLines = results.join("\n");
+    const header = `🖼️ Successfully cleared media descriptions`;
+    const detailLines = results.map((item) => `  ${item}`).join("\n");
 
     const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
 

package/agents/media/load-media-description.mjs

@@ -163,31 +163,19 @@ export default async function loadMediaDescription(input, options) {
   let enhancedAssetsContent = "# Available Media Assets for Documentation\n\n";
 
   if (mediaFiles.length > 0) {
-    enhancedAssetsContent += "```yaml\n";
-    enhancedAssetsContent += "assets:\n";
-
-    for (const asset of mediaFiles) {
-      enhancedAssetsContent += `  - name: "${asset.name}"\n`;
-      enhancedAssetsContent += `    path: "${asset.path}"\n`;
-      enhancedAssetsContent += `    type: "${asset.type}"\n`;
-
-      // Add description for images and videos
-      if (asset.type === "image" || asset.type === "video") {
-        const mediaHash = mediaHashMap.get(asset.path);
-        const cachedDesc = cache[mediaHash];
-        if (cachedDesc?.description) {
-          enhancedAssetsContent += `    description: "${cachedDesc.description}"\n`;
-        }
-      }
-
-      // Add dimensions for images and videos
-      if (asset.width && asset.height) {
-        enhancedAssetsContent += `    width: ${asset.width}\n`;
-        enhancedAssetsContent += `    height: ${asset.height}\n`;
+    const assets = mediaFiles.map((x) => {
+      const mediaHash = mediaHashMap.get(x.path);
+      const description = cache[mediaHash]?.description;
+      const result = {
+        name: x.name,
+        path: x.path,
+      };
+      if (description) {
+        result.description = description;
       }
-    }
-
-    enhancedAssetsContent += "```\n";
+      return result;
+    });
+    enhancedAssetsContent += stringify(assets);
   }
 
   return {

package/agents/translate/index.yaml

@@ -33,12 +33,12 @@ skills:
     name: batchTranslateDocument
     skills:
       - ../translate/translate-multilingual.yaml
-      - url: ./record-translation-history.mjs
     iterate_on: selectedDocs
     concurrency: 10
   - url: ../utils/check-feedback-refiner.mjs
     default_input:
       stage: translation_refine
+  - url: ./record-translation-history.mjs
   - url: ../utils/action-success.mjs
     default_input:
       action: '✅ Translation completed'

package/agents/translate/record-translation-history.mjs

@@ -1,16 +1,20 @@
 import { recordUpdate } from "../../utils/history-utils.mjs";
 
-export default function recordTranslationHistory({ feedback, path }) {
+export default function recordTranslationHistory({ selectedPaths, feedback }) {
   // Skip if no feedback provided
   if (!feedback?.trim()) {
     return {};
   }
 
+  if (!Array.isArray(selectedPaths) || selectedPaths.length === 0) {
+    return {};
+  }
+
   // Record translation history for this document
   recordUpdate({
     operation: "translation_update",
     feedback: feedback.trim(),
-    documentPath: path,
+    docPaths: selectedPaths,
   });
 
   return {};

package/agents/update/save-and-translate-document.mjs

@@ -1,4 +1,5 @@
 import pMap from "p-map";
+import { recordUpdate } from "../../utils/history-utils.mjs";
 
 export default async function saveAndTranslateDocument(input, options) {
   const { selectedDocs, docsDir, translateLanguages, locale } = input;
@@ -7,6 +8,16 @@ export default async function saveAndTranslateDocument(input, options) {
     return {};
   }
 
+  // Record history if feedback is provided
+  const doc = selectedDocs[0];
+  if (doc.feedback?.trim()) {
+    recordUpdate({
+      operation: "document_update",
+      feedback: doc.feedback.trim(),
+      docPaths: selectedDocs.map((v) => v.path),
+    });
+  }
+
   // Only prompt user if translation is actually needed
   let shouldTranslate = false;
   if (

package/agents/utils/choose-docs.mjs

@@ -18,6 +18,7 @@ export default async function chooseDocs(
     locale,
     reset = false,
     requiredFeedback = true,
+    title,
   },
   options,
 ) {
@@ -65,7 +66,7 @@ export default async function chooseDocs(
 
       // Let user select multiple files
       selectedFiles = await options.prompts.checkbox({
-        message: getActionText(isTranslate, "Select documents to {action}:"),
+        message: title || getActionText(isTranslate, "Select documents to {action}:"),
         source: (term) => {
           if (!term) return choices;
 

package/agents/utils/load-sources.mjs

@@ -21,6 +21,7 @@ import {
   DEFAULT_INCLUDE_PATTERNS,
 } from "../../utils/constants/index.mjs";
 import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
+import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
 
 export default async function loadSources(
   {
@@ -231,31 +232,7 @@ export default async function loadSources(
   const allFilesPaths = sourceFiles.map((x) => `- ${toRelativePath(x.sourceId)}`).join("\n");
 
   // Get the last documentation structure
-  let originalDocumentStructure;
-  if (outputDir) {
-    const documentStructurePath = path.join(outputDir, "structure-plan.json");
-    try {
-      const documentExecutionStructure = await readFile(documentStructurePath, "utf8");
-      if (documentExecutionStructure?.trim()) {
-        try {
-          // Validate that the content looks like JSON before parsing
-          const trimmedContent = documentExecutionStructure.trim();
-          if (trimmedContent.startsWith("{") || trimmedContent.startsWith("[")) {
-            originalDocumentStructure = JSON.parse(documentExecutionStructure);
-          } else {
-            console.warn(`structure-plan.json contains non-JSON content, skipping parse`);
-          }
-        } catch (err) {
-          console.error(`Failed to parse structure-plan.json: ${err.message}`);
-        }
-      }
-    } catch (err) {
-      if (err.code !== "ENOENT") {
-        console.warn(`Error reading structure-plan.json: ${err.message}`);
-      }
-      // The file does not exist or is not readable, originalDocumentStructure remains undefined
-    }
-  }
+  const originalDocumentStructure = await loadDocumentStructure(outputDir);
 
   // Get the last output result of the specified path
   let content;

package/agents/utils/save-doc.mjs

@@ -1,4 +1,3 @@
-import { recordUpdate } from "../../utils/history-utils.mjs";
 import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
 import { saveDoc as _saveDoc } from "../../utils/utils.mjs";
 
@@ -20,14 +19,6 @@ export default async function saveDoc({
     locale,
   });
 
-  if (feedback?.trim()) {
-    recordUpdate({
-      operation: "document_update",
-      feedback: feedback.trim(),
-      documentPath: path,
-    });
-  }
-
   if (isShowMessage) {
     // Shutdown mermaid worker pool to ensure clean exit
     try {

package/package.json

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

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/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/generate/system-prompt.md

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

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

@@ -19,11 +19,11 @@
 
 {{ additionalInformation }}
 
-<media_list>
+<media_file_list>
 {{ assetsContent }}
-</media_list>
+</media_file_list>
+
 
-{% include "../../common/document/media-handling-rules.md" %}
 
 </datasources>
 

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

@@ -38,6 +38,8 @@ Custom component optimization rules:
 Custom code block optimization rules:
 {% include "../custom/custom-code-block.md" %}
 
+{% include "../../common/document/media-file-list-usage-rules.md" %}
+
 Diagram generation rules:
 {% include "../d2-diagram/guide.md" %}
 <diagram_generation_rules>

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

@@ -21,11 +21,10 @@
 
 {{ additionalInformation }}
 
-<media_list>
+<media_file_list>
 {{ assetsContent }}
-</media_list>
+</media_file_list>
 
-{% include "../../common/document/media-handling-rules.md" %}
 </datasources>
 
 <user_feedback>

package/prompts/translate/code-block.md

@@ -2,13 +2,23 @@
 The following formats are considered Code Blocks:
 
 - Wrapped with ```
-- Supports configurations: language, title, icon, where title and icon are optional
+- Supports configurations: language, optional title, optional icon (icon uses key=value)
+- title is free text placed after the language (not as title=xxx), may contain spaces, and **must NEVER be wrapped in quotes**
 - content can be code, command line examples, text or any other content
 
 <code_block_sample>
 
-```{language} [{title}] [icon={icon}]
-{content}
+- `language`: javascript
+- `title`: Modern: Using createRoot()
+- `icon`: logos:javascript
+
+```javascript Modern: Using createRoot() icon=logos:javascript
+import { createRoot } from 'react-dom/client'
+
+const container = document.getElementById('root')
+const root = createRoot(container)
+
+root.unmount()
 ```
 
 </code_block_sample>

package/utils/docs-finder-utils.mjs

@@ -1,5 +1,6 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { pathExists } from "./file-utils.mjs";
 
 /**
  * Get action-specific text based on isTranslate flag
@@ -276,3 +277,50 @@ export function addFeedbackToItems(items, feedback) {
     feedback: feedback.trim(),
   }));
 }
+
+/**
+ * Load document execution structure from structure-plan.json
+ * @param {string} outputDir - Output directory containing structure-plan.json
+ * @returns {Promise<Array|null>} Document execution structure array or null if not found/failed
+ */
+export async function loadDocumentStructure(outputDir) {
+  if (!outputDir) {
+    return null;
+  }
+
+  try {
+    const structurePlanPath = join(outputDir, "structure-plan.json");
+    const structureExists = await pathExists(structurePlanPath);
+
+    if (!structureExists) {
+      return null;
+    }
+
+    const structureContent = await readFile(structurePlanPath, "utf8");
+    if (!structureContent?.trim()) {
+      return null;
+    }
+
+    try {
+      // Validate that the content looks like JSON before parsing
+      const trimmedContent = structureContent.trim();
+      if (!trimmedContent.startsWith("[") && !trimmedContent.startsWith("{")) {
+        console.warn("structure-plan.json contains non-JSON content, skipping parse");
+        return null;
+      }
+
+      const parsed = JSON.parse(structureContent);
+      // Return array if it's an array, otherwise return null
+      return Array.isArray(parsed) ? parsed : null;
+    } catch (parseError) {
+      console.error(`Failed to parse structure-plan.json: ${parseError.message}`);
+      return null;
+    }
+  } catch (readError) {
+    // Only warn if it's not a "file not found" error
+    if (readError.code !== "ENOENT") {
+      console.warn(`Error reading structure-plan.json: ${readError.message}`);
+    }
+    return null;
+  }
+}

package/utils/file-utils.mjs

@@ -408,10 +408,31 @@ async function isTextFile(filePath) {
 export function isRemoteFile(fileUrl) {
   if (typeof fileUrl !== "string") return false;
 
-  if (fileUrl.startsWith("http://") || fileUrl.startsWith("https://")) {
-    return true;
+  try {
+    const url = new URL(fileUrl);
+    // Only accept http and https url
+    if (["http:", "https:"].includes(url.protocol)) {
+      return true;
+    }
+    // other protocol will be treated as bad url
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export async function isRemoteFileAvailable(fileUrl) {
+  if (!isRemoteFile(fileUrl)) return false;
+
+  try {
+    const res = await fetch(fileUrl, {
+      method: "HEAD",
+    });
+    return res.ok;
+  } catch (error) {
+    debug(`Failed to check HTTP file availability: ${fileUrl} - ${error.message}`);
+    return false;
   }
-  return false;
 }
 
 export async function isRemoteTextFile(fileUrl) {

package/utils/history-utils.mjs

@@ -99,7 +99,7 @@ function recordUpdateGit({ feedback }) {
 /**
  * Records an update in the YAML file.
  */
-function recordUpdateYaml({ operation, feedback, documentPath = null }) {
+function recordUpdateYaml({ operation, feedback, docPaths = null }) {
   try {
     const docSmithDir = join(process.cwd(), DOC_SMITH_DIR);
     if (!existsSync(docSmithDir)) {
@@ -125,9 +125,9 @@ function recordUpdateYaml({ operation, feedback, documentPath = null }) {
       feedback,
     };
 
-    // Add document path if provided
-    if (documentPath) {
-      entry.documentPath = documentPath;
+    // Add document paths if provided
+    if (Array.isArray(docPaths) && docPaths.length > 0) {
+      entry.docPaths = docPaths;
     }
 
     // Add to beginning (newest first)
@@ -153,14 +153,14 @@ function recordUpdateYaml({ operation, feedback, documentPath = null }) {
  * @param {Object} params
  * @param {string} params.operation - The type of operation (e.g., 'document_update', 'structure_update', 'translation_update').
  * @param {string} params.feedback - The user's feedback text.
- * @param {string} params.documentPath - The document path.
+ * @param {string[]} [params.docPaths] - Document path list for updates.
  */
-export function recordUpdate({ operation, feedback, documentPath = null }) {
+export function recordUpdate({ operation, feedback, docPaths = null }) {
   // Skip if no feedback
   if (!feedback?.trim()) return;
 
   // Always record in YAML
-  recordUpdateYaml({ operation, feedback, documentPath });
+  recordUpdateYaml({ operation, feedback, docPaths });
 
   // Also record in git if git is available and not in a git repository
   if (isGitAvailable() && !isInGitRepository(process.cwd())) {
@@ -183,7 +183,19 @@ export function getHistory() {
 
   try {
     const content = readFileSync(historyPath, "utf8");
-    return parse(content) || { entries: [] };
+    const parsed = parse(content) || { entries: [] };
+    const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+
+    const normalized = entries.map((entry) => {
+      if (!entry) return entry;
+      // Normalize legacy entries: documentPath -> docPaths: [documentPath]
+      if (!entry.docPaths && entry.documentPath) {
+        return { ...entry, docPaths: [entry.documentPath] };
+      }
+      return entry;
+    });
+
+    return { ...parsed, entries: normalized };
   } catch (error) {
     console.warn("Could not read the history:", error.message);
     return { entries: [] };

package/utils/markdown-checker.mjs

@@ -3,9 +3,12 @@ import path from "node:path";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
+import { isRelative } from "ufo";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
+
+import { isRemoteFile, isRemoteFileAvailable } from "./file-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 
 /**
@@ -232,6 +235,34 @@ function checkLocalImages(markdown, source, errorMessages, markdownFilePath, bas
   }
 }
 
+async function checkRemoteImages(markdown, source, errorMessages) {
+  const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  let match;
+
+  while (true) {
+    match = imageRegex.exec(markdown);
+    if (match === null) break;
+    const imagePath = match[2].trim();
+    const altText = match[1];
+
+    if (isRelative(imagePath)) continue;
+    if (imagePath.startsWith("/")) continue;
+
+    // Skip data URLs
+    if (/^data:/.test(imagePath)) continue;
+
+    if (isRemoteFile(imagePath)) {
+      const isAvailable = await isRemoteFileAvailable(imagePath);
+      if (isAvailable) continue;
+      else {
+        errorMessages.push(
+          `Found invalid remote image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Check content structure and formatting issues
  * @param {string} markdown - The markdown content
@@ -370,7 +401,10 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // 2. Check local images existence
     checkLocalImages(markdown, source, errorMessages, filePath, baseDir);
 
-    // 3. Check content structure and formatting issues
+    // 3. Check remote images existence
+    await checkRemoteImages(markdown, source, errorMessages);
+
+    // 4. Check content structure and formatting issues
     checkContentStructure(markdown, source, errorMessages);
 
     // Check mermaid code blocks and other custom validations

package/prompts/common/document/media-handling-rules.md

@@ -1,9 +0,0 @@
-<media_handling_rules>
-Media resource usage rules:
-
-- When DataSources contain media resource files, incorporate them appropriately in the generated content
-- Media resources are provided in markdown format, example: ![Resource description](https://xxxx)
-- Display images in markdown format within generated results
-- Based on resource descriptions, place images strategically in contextually relevant positions to enhance the presentation
-- To ensure correct media resource paths, **only use media resources provided in media_list or remote URL media resources**
-</media_handling_rules>