@aigne/doc-smith 0.9.6-beta.1 → 0.9.6-beta.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.6-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.6-beta.1...v0.9.6-beta.2) (2025-11-20)
+
+
+### Bug Fixes
+
+* enhance the robustness of add/remove document ([#325](https://github.com/AIGNE-io/aigne-doc-smith/issues/325)) ([f78668a](https://github.com/AIGNE-io/aigne-doc-smith/commit/f78668ad93fb1c9913cfd62de466018f177990b3))
+* ignore video media temporary ([#326](https://github.com/AIGNE-io/aigne-doc-smith/issues/326)) ([e65e7fd](https://github.com/AIGNE-io/aigne-doc-smith/commit/e65e7fda49d870c1e60b433fac121193ee72a328))
+
 ## [0.9.6-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.6-beta...v0.9.6-beta.1) (2025-11-19)
 
 

package/agents/create/document-structure-tools/delete-document.mjs

@@ -3,6 +3,7 @@ import {
   getDeleteDocumentOutputJsonSchema,
   validateDeleteDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
+import { userContextAt } from "../../../utils/utils.mjs";
 
 export default async function deleteDocument(input, options) {
   // Validate input using Zod schema
@@ -23,6 +24,21 @@ export default async function deleteDocument(input, options) {
     documentStructure = input.documentStructure;
   }
 
+  const deletedPathsContext = userContextAt(options, "deletedPaths");
+  const deletedPaths = deletedPathsContext.get() || [];
+
+  // Check if path has already been deleted
+  if (recursive) {
+    if (deletedPaths.includes(path)) {
+      const message = `Skipping duplicate deletion. Document '${path}' has already been deleted.`;
+      return {
+        documentStructure,
+        message,
+        deletedDocuments: [],
+      };
+    }
+  }
+
   // Find the document to delete
   const documentIndex = documentStructure.findIndex((item) => item.path === path);
   if (documentIndex === -1) {
@@ -72,6 +88,11 @@ export default async function deleteDocument(input, options) {
   // Remove all documents from the structure
   const updatedStructure = documentStructure.filter((item) => !pathsToDelete.has(item.path));
 
+  // Add paths to deleted paths
+  if (recursive) {
+    deletedPathsContext.set(deletedPaths.concat(Array.from(pathsToDelete)));
+  }
+
   // Build success message
   const successMessage = `deleteDocument executed successfully.
   Successfully deleted document '${documentToDelete.title}' with path '${path}'${recursive && deletedCount > 0 ? ` along with ${deletedCount} child document(s)` : ""}.

package/agents/create/user-add-document/print-add-document-summary.mjs

@@ -1,15 +1,24 @@
 import chalk from "chalk";
 
+import { recordUpdate } from "../../../utils/history-utils.mjs";
 /**
  * Print summary of added documents and documents with new links
  */
 export default async function printAddDocumentSummary({
   newDocuments = [],
   documentsWithNewLinks = [],
+  allFeedback = [],
 }) {
-  let message = `\n${"=".repeat(80)}\n`;
-  message += `${chalk.bold.cyan("📊 Summary")}\n`;
-  message += `${"=".repeat(80)}\n\n`;
+  let message = `\n---\n`;
+  message += `${chalk.bold.cyan("📊 Summary")}\n\n`;
+
+  // Record the update
+  if (allFeedback.length > 0) {
+    recordUpdate({
+      operation: "structure_update",
+      feedback: allFeedback.join("\n"),
+    });
+  }
 
   // Display added documents
   if (newDocuments && newDocuments.length > 0) {
@@ -47,8 +56,6 @@ export default async function printAddDocumentSummary({
     message += `${chalk.gray("   No documents needed to be updated.\n\n")}`;
   }
 
-  message += `${"=".repeat(80)}\n\n`;
-
   return { message };
 }
 

package/agents/create/user-add-document/review-documents-with-new-links.mjs

@@ -1,24 +1,61 @@
+import { join } from "node:path";
+import chalk from "chalk";
+import pLimit from "p-limit";
+import { generateFileName, pathToFlatName } from "../../../utils/docs-finder-utils.mjs";
+import { pathExists } from "../../../utils/file-utils.mjs";
+
 /**
  * Review documentsWithNewLinks and let user select which documents should be updated
  */
 export default async function reviewDocumentsWithNewLinks(
-  { documentsWithNewLinks = [], documentExecutionStructure = [] },
+  { documentsWithNewLinks = [], documentExecutionStructure = [], locale = "en", docsDir },
   options,
 ) {
   // If no documents to review, return empty array
   if (!documentsWithNewLinks || documentsWithNewLinks.length === 0) {
-    return { documentsWithNewLinks: [] };
+    return { documentsWithNewLinks: [], documentsToUpdate: [] };
   }
 
+  // Build choices with file existence check
+  const limit = pLimit(50);
+  const choices = await Promise.all(
+    documentsWithNewLinks.map((document, index) =>
+      limit(async () => {
+        // Find corresponding document in documentStructure to get title
+        const structureDoc = documentExecutionStructure.find((item) => item.path === document.path);
+        const title = structureDoc?.title || document.path;
+
+        // Generate filename from document path
+        const flatName = pathToFlatName(document.path);
+        const filename = generateFileName(flatName, locale);
+
+        // Check file existence if docsDir is provided
+        let fileExists = true;
+        let missingFileText = "";
+        if (docsDir) {
+          const filePath = join(docsDir, filename);
+          fileExists = await pathExists(filePath);
+          if (!fileExists) {
+            missingFileText = chalk.red(" - file not found");
+          }
+        }
+
+        return {
+          name: `${title} (${filename})${missingFileText}`,
+          value: index,
+          checked: fileExists, // Only check if file exists
+          disabled: !fileExists, // Disable if file doesn't exist
+          description: `New Links: ${document.newLinks.join(", ")}`,
+        };
+      }),
+    ),
+  );
+
   // Let user select which documents to update (default: all selected)
   const selectedDocs = await options.prompts.checkbox({
     message:
       "Select documents that need new links added (all selected by default, press Enter to confirm, or unselect all to skip):",
-    choices: documentsWithNewLinks.map((document, index) => ({
-      name: `${document.path} → ${document.newLinks.join(", ")}`,
-      value: index,
-      checked: true, // Default to all selected
-    })),
+    choices,
   });
 
   // Filter documentsWithNewLinks based on user selection
@@ -42,7 +79,7 @@ export default async function reviewDocumentsWithNewLinks(
     };
   }
 
-  // Prepare documents: add necessary fields for update (without content)
+  // Prepare documents: add necessary fields for update (e.g. feedback)
   const preparedDocs = [];
 
   for (const doc of filteredDocs) {

package/agents/create/user-remove-document/find-documents-with-invalid-links.mjs

@@ -1,9 +1,11 @@
+import { join } from "node:path";
 import {
   buildAllowedLinksFromStructure,
   generateFileName,
   pathToFlatName,
   readFileContent,
 } from "../../../utils/docs-finder-utils.mjs";
+import { pathExists } from "../../../utils/file-utils.mjs";
 import { checkMarkdown, getLinkFromError } from "../../../utils/markdown-checker.mjs";
 
 export default async function findDocumentsWithInvalidLinks({
@@ -35,6 +37,15 @@ export default async function findDocumentsWithInvalidLinks({
     const flatName = pathToFlatName(doc.path);
     const fileName = generateFileName(flatName, locale);
 
+    // Check if file exists before reading
+    const filePath = join(docsDir, fileName);
+    const fileExists = await pathExists(filePath);
+
+    if (!fileExists) {
+      // Skip if file doesn't exist
+      continue;
+    }
+
     // Read document content
     const content = await readFileContent(docsDir, fileName);
 

package/agents/create/user-remove-document/print-remove-document-summary.mjs

@@ -7,9 +7,8 @@ export default async function printRemoveDocumentSummary({
   deletedDocuments = [],
   documentsWithInvalidLinks = [],
 }) {
-  let message = `\n${"=".repeat(80)}\n`;
-  message += `${chalk.bold.cyan("📊 Summary")}\n`;
-  message += `${"=".repeat(80)}\n\n`;
+  let message = `\n---\n`;
+  message += `${chalk.bold.cyan("📊 Summary")}\n\n`;
 
   // Display removed documents
   if (deletedDocuments && deletedDocuments.length > 0) {
@@ -47,8 +46,6 @@ export default async function printRemoveDocumentSummary({
     message += `${chalk.gray("   No documents needed to be fixed.\n\n")}`;
   }
 
-  message += `${"=".repeat(80)}\n\n`;
-
   return { message };
 }
 

package/agents/create/user-remove-document/remove-documents-from-structure.mjs

@@ -1,10 +1,8 @@
-import chooseDocs from "../../utils/choose-docs.mjs";
 import deleteDocument from "../document-structure-tools/delete-document.mjs";
-import { DOC_ACTION } from "../../../utils/constants/index.mjs";
-import addTranslatesToStructure from "../../utils/add-translates-to-structure.mjs";
+import { buildDocumentTree, buildChoicesFromTree } from "../../../utils/docs-finder-utils.mjs";
 
 export default async function removeDocumentsFromStructure(input = {}, options = {}) {
-  const { docsDir, locale = "en", translateLanguages = [], originalDocumentStructure } = input;
+  const { originalDocumentStructure, locale = "en", docsDir } = input;
 
   if (!Array.isArray(originalDocumentStructure) || originalDocumentStructure.length === 0) {
     console.warn(
@@ -13,43 +11,43 @@ export default async function removeDocumentsFromStructure(input = {}, options =
     process.exit(0);
   }
 
-  const { documentExecutionStructure } = addTranslatesToStructure({
-    originalDocumentStructure,
-    translateLanguages,
-  });
-
   // Initialize currentStructure in userContext
   options.context.userContext.currentStructure = [...originalDocumentStructure];
 
-  // Use chooseDocs to select documents to delete
-  const chooseResult = await chooseDocs(
-    {
-      docs: [],
-      documentExecutionStructure,
-      docsDir,
-      locale,
-      isTranslate: false,
-      feedback: "no feedback",
-      requiredFeedback: false,
-      action: DOC_ACTION.clear,
-    },
-    options,
-  );
+  // Build tree structure
+  const { rootNodes } = buildDocumentTree(originalDocumentStructure);
+
+  // Build choices with tree structure visualization
+  const choices = await buildChoicesFromTree(rootNodes, "", 0, { locale, docsDir });
+
+  // Let user select documents to delete
+  let selectedPaths = [];
+  try {
+    selectedPaths = await options.prompts.checkbox({
+      message: "Select documents to remove (Press Enter with no selection to finish):",
+      choices,
+    });
+  } catch {
+    // User cancelled or no selection made
+    console.log("No documents were removed.");
+    process.exit(0);
+  }
 
-  if (!chooseResult?.selectedDocs || chooseResult.selectedDocs.length === 0) {
-    console.log("No documents selected for removal.");
+  // If no documents selected, exit
+  if (!selectedPaths || selectedPaths.length === 0) {
+    console.log("No documents were removed.");
     process.exit(0);
   }
 
-  // Delete each selected document
+  // Delete each selected document with cascade deletion
   const deletedDocuments = [];
   const errors = [];
 
-  for (const selectedDoc of chooseResult.selectedDocs) {
+  for (const path of selectedPaths) {
     try {
       const deleteResult = await deleteDocument(
         {
-          path: selectedDoc.path,
+          path,
           recursive: true,
         },
         options,
@@ -57,21 +55,21 @@ export default async function removeDocumentsFromStructure(input = {}, options =
 
       if (deleteResult.error) {
         errors.push({
-          path: selectedDoc.path,
+          path,
           error: deleteResult.error.message,
         });
       } else {
-        // deletedDocuments is now always an array
         deletedDocuments.push(...deleteResult.deletedDocuments);
       }
     } catch (error) {
       errors.push({
-        path: selectedDoc.path,
+        path,
         error: error.message,
       });
     }
   }
 
+  // Check if there are errors
   if (errors.length > 0) {
     console.warn(
       `🗑️ Remove Documents\n  • Failed to remove documents:\n${errors
@@ -81,7 +79,12 @@ export default async function removeDocumentsFromStructure(input = {}, options =
     process.exit(0);
   }
 
-  // Get updated document structure
+  if (deletedDocuments.length === 0) {
+    console.log("No documents were removed.");
+    process.exit(0);
+  }
+
+  // Get final updated document structure
   const updatedStructure = options.context.userContext.currentStructure;
 
   return {

package/agents/create/user-remove-document/review-documents-with-invalid-links.mjs

@@ -1,4 +1,8 @@
-import { buildAllowedLinksFromStructure } from "../../../utils/docs-finder-utils.mjs";
+import {
+  buildAllowedLinksFromStructure,
+  generateFileName,
+  pathToFlatName,
+} from "../../../utils/docs-finder-utils.mjs";
 
 /**
  * Generate feedback message for fixing invalid links in a document
@@ -44,27 +48,26 @@ ${allowedLinksList}
 }
 
 export default async function reviewDocumentsWithInvalidLinks(input = {}, options = {}) {
-  const { documentsWithInvalidLinks = [], documentExecutionStructure = [] } = input;
+  const { documentsWithInvalidLinks = [], documentExecutionStructure = [], locale = "en" } = input;
 
   // If no documents with invalid links, return empty array
   if (!Array.isArray(documentsWithInvalidLinks) || documentsWithInvalidLinks.length === 0) {
     return {
       documentsWithInvalidLinks: [],
+      documentsToUpdate: [],
     };
   }
 
   // Create choices for user selection, default all checked
   const choices = documentsWithInvalidLinks.map((doc) => {
-    const invalidLinksText =
-      doc.invalidLinks && doc.invalidLinks.length > 0
-        ? ` (${doc.invalidLinks.length} invalid link${doc.invalidLinks.length > 1 ? "s" : ""})`
-        : "";
+    const flatName = pathToFlatName(doc.path);
+    const filename = generateFileName(flatName, locale);
 
     return {
-      name: `${doc.title || doc.path}${invalidLinksText}`,
+      name: `${doc.title} (${filename})`,
       value: doc.path,
       checked: true, // Default all selected
-      description: `Invalid Links: ${doc.invalidLinks.join(", ")}`,
+      description: `Invalid Links(${doc.invalidLinks?.length || 0}): ${doc.invalidLinks?.join(", ")}`,
     };
   });
 

package/agents/init/index.mjs

@@ -14,6 +14,7 @@ import {
   SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
 } from "../../utils/constants/index.mjs";
+import { isRemoteFile } from "../../utils/file-utils.mjs";
 import loadConfig from "../../utils/load-config.mjs";
 import {
   detectSystemLanguage,
@@ -22,9 +23,8 @@ import {
   isGlobPattern,
   validatePath,
 } from "../../utils/utils.mjs";
-import { isRemoteFile } from "../../utils/file-utils.mjs";
-import { validateDocDir } from "./validate.mjs";
 import mapReasoningEffortLevel from "../utils/map-reasoning-effort-level.mjs";
+import { validateDocDir } from "./validate.mjs";
 
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
@@ -362,8 +362,7 @@ async function _init(
         continue;
       }
       sourcePaths.push(trimmedPath);
-    }
-    if (isGlobPatternResult) {
+    } else if (isGlobPatternResult) {
       // For glob patterns, just add them without validation
       if (sourcePaths.includes(trimmedPath)) {
         console.log(`⚠️ Pattern already exists: ${trimmedPath}`);

package/agents/utils/load-sources.mjs

@@ -1,27 +1,42 @@
-import { readFile } from "node:fs/promises";
 import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import imageSize from "image-size";
+import {
+  DEFAULT_EXCLUDE_PATTERNS,
+  DEFAULT_INCLUDE_PATTERNS,
+  INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD,
+} from "../../utils/constants/index.mjs";
+import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
 import {
   buildSourcesContent,
-  loadFilesFromPaths,
-  readFileContents,
+  calculateTokens,
   getMimeType,
   isRemoteFile,
-  calculateTokens,
+  loadFilesFromPaths,
+  readFileContents,
 } from "../../utils/file-utils.mjs";
+import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
 import {
   getCurrentGitHead,
   getModifiedFilesBetweenCommits,
   toRelativePath,
 } from "../../utils/utils.mjs";
-import {
-  INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD,
-  DEFAULT_EXCLUDE_PATTERNS,
-  DEFAULT_INCLUDE_PATTERNS,
-} from "../../utils/constants/index.mjs";
-import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
-import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
+
+const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".heic", ".heif"];
+const videoExts = [
+  ".mp4",
+  ".mpeg",
+  ".mpg",
+  ".mov",
+  ".avi",
+  ".flv",
+  ".mkv",
+  ".webm",
+  ".wmv",
+  ".m4v",
+  ".3gpp",
+];
 
 export default async function loadSources(
   {
@@ -77,7 +92,13 @@ export default async function loadSources(
       .filter(Boolean);
     const allFiles = await loadFilesFromPaths(pickSourcesPath, {
       includePatterns,
-      excludePatterns: [...new Set([...(excludePatterns || []), ...customExcludePatterns])],
+      excludePatterns: [
+        ...new Set([
+          ...(excludePatterns || []),
+          ...customExcludePatterns,
+          ...videoExts.map((x) => `**/*${x}`),
+        ]),
+      ],
       useDefaultPatterns,
       defaultIncludePatterns: DEFAULT_INCLUDE_PATTERNS,
       defaultExcludePatterns: DEFAULT_EXCLUDE_PATTERNS,
@@ -90,26 +111,9 @@ export default async function loadSources(
 
   // Define media file extensions
   const mediaExtensions = [
-    ".jpg",
-    ".jpeg",
-    ".png",
-    ".gif",
-    ".bmp",
-    ".webp",
-    ".svg",
-    ".heic",
-    ".heif",
-    ".mp4",
-    ".mpeg",
-    ".mpg",
-    ".mov",
-    ".avi",
-    ".flv",
-    ".mkv",
-    ".webm",
-    ".wmv",
-    ".m4v",
-    ".3gpp",
+    ...imageExts,
+    // ignore video temporary
+    // ...videoExts
   ];
 
   // Separate source files from media files
@@ -119,20 +123,6 @@ export default async function loadSources(
   // Helper function to determine file type from extension
   const getFileType = (filePath) => {
     const ext = path.extname(filePath).toLowerCase();
-    const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".heic", ".heif"];
-    const videoExts = [
-      ".mp4",
-      ".mpeg",
-      ".mpg",
-      ".mov",
-      ".avi",
-      ".flv",
-      ".mkv",
-      ".webm",
-      ".wmv",
-      ".m4v",
-      ".3gpp",
-    ];
 
     if (imageExts.includes(ext)) return "image";
     if (videoExts.includes(ext)) return "video";

package/aigne.yaml

@@ -132,7 +132,7 @@ cli:
       alias: ["add"]
       url: ./agents/create/user-add-document/index.yaml
     - name: remove-document
-      alias: ["rm"]
+      alias: ["remove", "rm"]
       url: ./agents/create/user-remove-document/index.yaml
     - ./agents/clear/index.yaml
 mcp_server:

package/package.json

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

package/prompts/detail/custom/custom-components/x-cards-usage-rules.md

@@ -5,7 +5,7 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
 
 ### Attributes
 
-- `data-columns` (optional): Must be an **integer ≥ 2**. Values below 2 are disallowed. Default is 2.
+- `data-columns` (required): must be an integer ≥ 2; no upper bound.
 
 ### Children
 
@@ -20,20 +20,21 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
 
 ### Good Examples
 
-- Example 1: Three-column cards with icons
+- Example 1: Two-column cards with images
   ```md
-  <x-cards data-columns="3">
-    <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-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+  <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-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
   </x-cards>
   ```
 
-- Example 2: Two-column cards with images
+- Example 2: Four-column cards with icons
   ```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-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+  <x-cards data-columns="4">
+    <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-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+    <x-card data-title="Feature 4" data-icon="lucide:star">Description of Feature 4.</x-card>
   </x-cards>
   ```
 
@@ -72,4 +73,11 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
   - [Using the Blog](./blog.md)
   - [Using Chat](./chat.md)
   ```
+
+- Example 4: Missing `data-columns` attribute (required)
+  <x-cards>
+    <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>
+  
 </x-card-usage-rules>

package/utils/docs-finder-utils.mjs

@@ -1,5 +1,7 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import chalk from "chalk";
+import pLimit from "p-limit";
 import { pathExists } from "./file-utils.mjs";
 
 /**
@@ -393,6 +395,83 @@ export function buildDocumentTree(documentStructure) {
   return { rootNodes, nodeMap };
 }
 
+/**
+ * Build checkbox choices from tree structure with visual hierarchy
+ * @param {Array} nodes - Array of tree nodes
+ * @param {string} prefix - Current prefix for indentation
+ * @param {number} depth - Current depth level (0 for root)
+ * @param {Object} context - Context object containing locale, docsDir, etc.
+ * @param {string} context.locale - Main language locale (e.g., 'en', 'zh', 'fr')
+ * @param {string} [context.docsDir] - Docs directory path for file existence check
+ * @returns {Promise<Array>} Array of choice objects
+ */
+export async function buildChoicesFromTree(nodes, prefix = "", depth = 0, context = {}) {
+  const { locale = "en", docsDir } = context;
+  const choices = [];
+
+  // Limit concurrent file checks to 50 per level to avoid overwhelming the file system
+  const limit = pLimit(50);
+
+  // Process nodes with controlled concurrency while maintaining order
+  const nodePromises = nodes.map((node, i) =>
+    limit(async () => {
+      const isLastSibling = i === nodes.length - 1;
+      const hasChildren = node.children && node.children.length > 0;
+
+      // Build the tree prefix - top level nodes don't have ├─ or └─
+      const treePrefix = depth === 0 ? "" : prefix + (isLastSibling ? "└─ " : "├─ ");
+      const flatName = pathToFlatName(node.path);
+      const filename = generateFileName(flatName, locale);
+
+      // Check file existence if docsDir is provided
+      let fileExists = true;
+      let missingFileText = "";
+      if (docsDir) {
+        const filePath = join(docsDir, filename);
+        fileExists = await pathExists(filePath);
+        if (!fileExists) {
+          missingFileText = chalk.red(" - file not found");
+        }
+      }
+
+      // warningText only shows when file exists, missingFileText has higher priority
+      const warningText =
+        fileExists && hasChildren ? chalk.yellow(" - will cascade delete all child documents") : "";
+
+      const displayName = `${treePrefix}${node.title} (${filename})${warningText}${missingFileText}`;
+
+      const choice = {
+        name: displayName,
+        value: node.path,
+        short: node.title,
+        disabled: !fileExists,
+      };
+
+      // Recursively process children
+      let childChoices = [];
+      if (hasChildren) {
+        const childPrefix = depth === 0 ? "" : prefix + (isLastSibling ? "   " : "│  ");
+        childChoices = await buildChoicesFromTree(node.children, childPrefix, depth + 1, context);
+      }
+
+      return { choice, childChoices };
+    }),
+  );
+
+  // Wait for all nodes at this level to complete, maintaining order
+  const results = await Promise.all(nodePromises);
+
+  // Build choices array in order
+  for (const { choice, childChoices } of results) {
+    choices.push(choice);
+    if (childChoices.length > 0) {
+      choices.push(...childChoices);
+    }
+  }
+
+  return choices;
+}
+
 /**
  * Format document structure for printing
  * @param {Array} structure - Document structure array

package/utils/file-utils.mjs

@@ -900,17 +900,19 @@ export function isDirExcluded(dir, excludePatterns) {
 
 /**
  * Return source paths that would be excluded by exclude patterns (files are skipped, directories use minimatch, glob patterns use path prefix heuristic)
+ * @returns {{excluded: string[], notFound: string[]}} Object with excluded and notFound arrays
  */
 export async function findInvalidSourcePaths(sourcePaths, excludePatterns) {
   if (!Array.isArray(sourcePaths) || sourcePaths.length === 0) {
-    return [];
+    return { excluded: [], notFound: [] };
   }
 
   if (!Array.isArray(excludePatterns) || excludePatterns.length === 0) {
-    return [];
+    return { excluded: [], notFound: [] };
   }
 
-  const invalidPaths = [];
+  const excluded = [];
+  const notFound = [];
 
   for (const sourcePath of sourcePaths) {
     if (typeof sourcePath !== "string" || !sourcePath) {
@@ -931,7 +933,7 @@ export async function findInvalidSourcePaths(sourcePaths, excludePatterns) {
     if (isGlobPattern(sourcePath)) {
       const representativePath = getPathPrefix(sourcePath);
       if (isDirExcluded(representativePath, excludePatterns)) {
-        invalidPaths.push(sourcePath);
+        excluded.push(sourcePath);
       }
       continue;
     }
@@ -945,14 +947,14 @@ export async function findInvalidSourcePaths(sourcePaths, excludePatterns) {
       // Check dir with minimatch
       if (stats.isDirectory()) {
         if (isDirExcluded(sourcePath, excludePatterns)) {
-          invalidPaths.push(sourcePath);
+          excluded.push(sourcePath);
         }
       }
     } catch {
       // Path doesn't exist
-      invalidPaths.push(sourcePath);
+      notFound.push(sourcePath);
     }
   }
 
-  return invalidPaths;
+  return { excluded, notFound };
 }

package/utils/load-config.mjs

@@ -41,11 +41,28 @@ export default async function loadConfig({ config, appUrl }) {
         ...(processedConfig.excludePatterns || parsedConfig.excludePatterns || []),
       ];
 
-      const invalidPaths = await findInvalidSourcePaths(sourcesPath, excludePatterns);
-      if (invalidPaths.length > 0) {
-        console.warn(
-          `⚠️  Some source paths have been excluded and will not be processed:\n${invalidPaths.map((p) => `  - ${chalk.yellow(p)}`).join("\n")}\n💡 Tip: You can remove these paths in ${toDisplayPath(configPath)}\n`,
+      const { excluded, notFound } = await findInvalidSourcePaths(sourcesPath, excludePatterns);
+
+      if (excluded.length > 0 || notFound.length > 0) {
+        const warnings = [];
+
+        if (excluded.length > 0) {
+          warnings.push(
+            `⚠️  These paths were excluded (ignored by config):\n${excluded.map((p) => `  - ${chalk.yellow(p)}`).join("\n")}`,
+          );
+        }
+
+        if (notFound.length > 0) {
+          warnings.push(
+            `🚫 These paths were skipped because they do not exist:\n${notFound.map((p) => `  - ${chalk.red(p)}`).join("\n")}`,
+          );
+        }
+
+        warnings.push(
+          `💡 Tip: You can remove these paths in ${chalk.cyan(toDisplayPath(configPath))}`,
         );
+
+        console.warn(`${warnings.join("\n\n")}\n`);
       }
     }