@aigne/doc-smith 0.8.15 → 0.8.16-beta

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.8.16-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15...v0.8.16-beta) (2025-11-10)
+
+
+### Features
+
+* enable AFS for chat agent & improve chat skills ([#281](https://github.com/AIGNE-io/aigne-doc-smith/issues/281)) ([b1c770e](https://github.com/AIGNE-io/aigne-doc-smith/commit/b1c770e60c8866dd08d41ebdd52817c14dd3dd41))
+* implement document title streamlining functionality ([#276](https://github.com/AIGNE-io/aigne-doc-smith/issues/276)) ([918edb8](https://github.com/AIGNE-io/aigne-doc-smith/commit/918edb8f1b2dc03572c4125971092ef0023cd7b3))
+
+
+### Bug Fixes
+
+* update chat model from aignehub/gemini-2.5-pro to google/gemini-2.5-pro ([#283](https://github.com/AIGNE-io/aigne-doc-smith/issues/283)) ([3559a56](https://github.com/AIGNE-io/aigne-doc-smith/commit/3559a56e49ca3105fd800110b67b3cb3346e3096))
+
 ## [0.8.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.16...v0.8.15) (2025-11-07)
 
 ## [0.8.15-beta.16](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.15...v0.8.15-beta.16) (2025-11-07)

package/agents/chat/chat-system.md

@@ -0,0 +1,32 @@
+You are a professional document generation assistant that helps users create, modify, and manage documentation through interactive chat. Your primary role is to understand user requirements and intelligently call upon various specialized skills to complete documentation tasks efficiently.
+
+Core Capabilities:
+- Generate comprehensive documentation from user inputs and specifications
+- Regenerate and refine document details based on feedback
+- Translate and localize documentation content
+- Publish and manage team documentation workflows
+- Provide interactive guidance throughout the document creation process
+
+Interaction Guidelines:
+- Engage users in a professional yet friendly manner
+- Ask clarifying questions to understand specific documentation needs
+- Suggest appropriate skills and workflows based on user requests
+- Provide clear explanations of available capabilities and processes
+- Maintain context throughout multi-step documentation tasks
+- Offer proactive suggestions for improving document quality and structure
+
+<skill_usage>
+- afs_xxx skills: AFS(AIGNE File System) skills provide capabilities to explore, read, write and manage files and virtual modules within the AIGNE environment.
+  You can use these skills to access source files and other resources needed for documentation tasks.
+- listDocs: This skill lists all available documentation files in the system.
+  You can use this skill to get an overview of existing documents before creating or modifying documentation. for documentation tasks,
+  you should use this skill rather than afs_read to list documentation files.
+- generateDocument: This skill generates new documentation or updates existing documents structure based on user inputs and specifications,
+  You can use this skill to create comprehensive documents from scratch or based on existing templates or update document structure as per user requirements.
+- updateDocument: This skill updates existing documentation content with new information or revisions provided by the user.
+  You can use this skill to refine and enhance documents content based on feedback or additional details.
+- publish: This skill publishes completed documentation to an online website to make it accessible to the intended audience.
+  You can use this skill to manage the publication process and ensure documents are properly formatted and available.
+- translate: This skill translates documentation content into different languages for localization purposes.
+  You can use this skill to adapt documents for diverse audiences by providing translations in the required languages.
+</skill_usage>

package/agents/chat/index.yaml

@@ -1,30 +1,22 @@
 type: ai
 name: chat
 description: Start interactive document generation assistant
-instructions: |
-  You are a professional document generation assistant that helps users create, modify, and manage documentation through interactive chat. Your primary role is to understand user requirements and intelligently call upon various specialized skills to complete documentation tasks efficiently.
-
-  Core Capabilities:
-  - Generate comprehensive documentation from user inputs and specifications
-  - Regenerate and refine document details based on feedback
-  - Translate and localize documentation content
-  - Publish and manage team documentation workflows
-  - Provide interactive guidance throughout the document creation process
-
-  Interaction Guidelines:
-  - Engage users in a professional yet friendly manner
-  - Ask clarifying questions to understand specific documentation needs
-  - Suggest appropriate skills and workflows based on user requests
-  - Provide clear explanations of available capabilities and processes
-  - Maintain context throughout multi-step documentation tasks
-  - Offer proactive suggestions for improving document quality and structure
+instructions:
+  url: ./chat-system.md
 input_key: message
-memory: true
+afs:
+  modules:
+    - module: system-fs
+      options:
+        path: .
+        mount: /source
+        description: Project root directory for document generation
+afs_config:
+  inject_History: true
 skills:
-  - ../init/index.mjs
-  - ../generate/index.yaml
-  - ../update/index.yaml
+  - ./skills/generate-document.yaml
+  - ./skills/update-document.yaml
   - ../publish/index.yaml
   - ../translate/index.yaml
-  - ../utils/docs-fs-actor.yaml
   - ../utils/exit.mjs
+  - ../utils/list-docs.mjs

package/agents/chat/skills/generate-document.yaml

@@ -0,0 +1,15 @@
+type: team
+name: generateDocument
+description: Generate complete documentation for your project, or update/delete existing documents or structure based on user feedback
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: How to generate or update the document content
+  required:
+    - feedback
+skills:
+  - url: ../../generate/index.yaml
+    default_input:
+      isChat: true

package/agents/chat/skills/update-document.yaml

@@ -0,0 +1,24 @@
+type: team
+name: updateDocument
+description: Update a existing document based on user feedback
+input_schema:
+  type: object
+  properties:
+    docs:
+      type: array
+      items:
+        type: string
+      description: Documents to update, must from listDocs output
+    feedback:
+      type: string
+      description: Tell us what to change in this content
+    reset:
+      type: boolean
+      description: Regenerate the document from scratch, ignoring previous versions
+  required:
+    - docs
+    - feedback
+skills:
+  - url: ../../update/index.yaml
+    default_input:
+      isChat: true

package/agents/generate/check-need-generate-structure.mjs

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { getProjectInfo, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
+import streamlineDocumentTitlesIfNeeded from "../utils/streamline-document-titles-if-needed.mjs";
 
 export default async function checkNeedGenerateStructure(
   { originalDocumentStructure, forceRegenerate, ...rest },
@@ -70,6 +71,9 @@ export default async function checkNeedGenerateStructure(
     feedback: finalFeedback || "",
   });
 
+  await streamlineDocumentTitlesIfNeeded({ documentStructure: result.documentStructure }, options);
+  options.context.userContext.streamlinedDocumentTitles = true;
+
   let message = "";
 
   // Check and save project information

package/agents/generate/document-structure-tools/add-document.mjs

@@ -3,6 +3,7 @@ import {
   getAddDocumentOutputJsonSchema,
   validateAddDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
+import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
 
 export default async function addDocument(input, options) {
   // Validate input using Zod schema
@@ -56,7 +57,10 @@ export default async function addDocument(input, options) {
     sourceIds: [...sourceIds], // Create a copy of the array
   };
 
-  // Add the document to the structure
+  // Streamline document titles if needed (will streamline the new document if title > 18 characters)
+  await streamlineDocumentTitlesIfNeeded({ documentStructure: [newDocument] }, options);
+
+  // Add the document to the structure first
   const updatedStructure = [...documentStructure, newDocument];
 
   const successMessage = `addDocument executed successfully.

package/agents/generate/document-structure-tools/update-document.mjs

@@ -3,6 +3,7 @@ import {
   getUpdateDocumentOutputJsonSchema,
   validateUpdateDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
+import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
 
 export default async function updateDocument(input, options) {
   // Validate input using Zod schema
@@ -44,6 +45,12 @@ export default async function updateDocument(input, options) {
     ...(sourceIds !== undefined && { sourceIds: [...sourceIds] }), // Create a copy of the array
   };
 
+  if (!options.context.userContext.streamlinedDocumentTitles) {
+    // Streamline document titles if needed (will streamline the updated document if title > 18 characters)
+    await streamlineDocumentTitlesIfNeeded({ documentStructure: [updatedDocument] }, options);
+    options.context.userContext.streamlinedDocumentTitles = true;
+  }
+
   // Update the document in the structure
   const updatedStructure = [...documentStructure];
   updatedStructure[documentIndex] = updatedDocument;

package/agents/generate/user-review-document-structure.mjs

@@ -1,6 +1,7 @@
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { recordUpdate } from "../../utils/history-utils.mjs";
 import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
+import equal from "fast-deep-equal";
 
 function formatDocumentStructure(structure) {
   const { rootNodes } = buildDocumentTree(structure);
@@ -49,25 +50,27 @@ export default async function userReviewDocumentStructure({ documentStructure, .
   }
 
   // Print current documentation structure in a user-friendly format
-  printDocumentStructure(documentStructure);
-
-  // Ask user if they want to review the documentation structure
-  const needReview = await options.prompts.select({
-    message: "Would you like to refine the documentation structure?",
-    choices: [
-      {
-        name: "No, looks good",
-        value: "no",
-      },
-      {
-        name: "Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')",
-        value: "yes",
-      },
-    ],
-  });
-
-  if (needReview === "no") {
-    return { documentStructure };
+  if (!rest.isChat) {
+    printDocumentStructure(documentStructure);
+
+    // Ask user if they want to review the documentation structure
+    const needReview = await options.prompts.select({
+      message: "Would you like to refine the documentation structure?",
+      choices: [
+        {
+          name: "No, looks good",
+          value: "no",
+        },
+        {
+          name: "Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')",
+          value: "yes",
+        },
+      ],
+    });
+
+    if (needReview === "no") {
+      return { documentStructure };
+    }
   }
 
   let currentStructure = documentStructure;
@@ -81,15 +84,17 @@ export default async function userReviewDocumentStructure({ documentStructure, .
     iterationCount++;
 
     // Ask for feedback
-    const feedback = await options.prompts.input({
-      message:
-        "How would you like to improve the structure?\n" +
-        "Examples:\n" +
-        "  • Add a new document 'Troubleshooting'\n" +
-        "  • Remove the 'Legacy Features' document\n" +
-        "  • Move 'Installation' to the top of the structure\n\n" +
-        "  Press Enter to finish reviewing:",
-    });
+    const feedback = rest.isChat
+      ? rest.feedback
+      : await options.prompts.input({
+          message:
+            "How would you like to improve the structure?\n" +
+            "Examples:\n" +
+            "  • Add a new document 'Troubleshooting'\n" +
+            "  • Remove the 'Legacy Features' document\n" +
+            "  • Move 'Installation' to the top of the structure\n\n" +
+            "  Press Enter to finish reviewing:",
+        });
 
     // If no feedback, break the loop
     if (!feedback?.trim()) {
@@ -115,7 +120,7 @@ export default async function userReviewDocumentStructure({ documentStructure, .
 
     try {
       // Call refineDocumentStructure agent with feedback
-      await options.context.invoke(refineAgent, {
+      const { message } = await options.context.invoke(refineAgent, {
         ...rest,
         dataSourceChunk: rest.dataSources[0].dataSourceChunk,
         feedback: feedback.trim(),
@@ -125,6 +130,12 @@ export default async function userReviewDocumentStructure({ documentStructure, .
 
       currentStructure = options.context.userContext.currentStructure;
 
+      if (rest.isChat && equal(currentStructure, documentStructure)) {
+        throw new Error(
+          `The suggested structure changes did not modify the existing documentation structure. ${message}`,
+        );
+      }
+
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
       if (feedbackRefinerAgent) {
@@ -147,6 +158,10 @@ export default async function userReviewDocumentStructure({ documentStructure, .
 
       // Print current documentation structure in a user-friendly format
       printDocumentStructure(currentStructure);
+
+      if (rest.isChat) {
+        break;
+      }
     } catch (error) {
       console.error("Error processing your feedback:");
       console.error(`Type: ${error.name}`);

package/agents/update/user-review-document.mjs

@@ -132,7 +132,9 @@ export default async function userReviewDocument({ content, description, ...rest
   const title = rest.documentStructure?.find((x) => x.path === rest.path)?.title;
 
   // Print current document headings structure
-  printDocumentHeadings(content, title || "Untitled Document");
+  if (!rest.isChat) {
+    printDocumentHeadings(content, title || "Untitled Document");
+  }
 
   // Initialize shared context with current content
   options.context.userContext.currentContent = content;
@@ -140,54 +142,62 @@ export default async function userReviewDocument({ content, description, ...rest
   const MAX_ITERATIONS = 100;
   const feedbacks = [];
   let iterationCount = 0;
+
+  let feedback = "";
+
   while (iterationCount < MAX_ITERATIONS) {
+    feedback = "";
     iterationCount++;
 
-    // Ask user what they want to do
-    const action = await options.prompts.select({
-      message: "What would you like to do next?",
-      choices: [
-        {
-          name: "View document",
-          value: "view",
-        },
-        {
-          name: "Give feedback",
-          value: "feedback",
-        },
-        {
-          name: "Done",
-          value: "finish",
-        },
-      ],
-    });
+    if (rest.isChat && rest.feedback) {
+      feedback = rest.feedback;
+    } else {
+      // Ask user what they want to do
+      const action = await options.prompts.select({
+        message: "What would you like to do next?",
+        choices: [
+          {
+            name: "View document",
+            value: "view",
+          },
+          {
+            name: "Give feedback",
+            value: "feedback",
+          },
+          {
+            name: "Done",
+            value: "finish",
+          },
+        ],
+      });
 
-    if (action === "finish") {
-      break;
-    } else if (action === "view") {
-      await showDocumentDetail(
-        options.context.userContext.currentContent,
-        title || "Untitled Document",
-      );
-    }
+      if (action === "finish") {
+        break;
+      } else if (action === "view") {
+        await showDocumentDetail(
+          options.context.userContext.currentContent,
+          title || "Untitled Document",
+        );
+      }
 
-    // Ask for feedback
-    const feedback = await options.prompts.input({
-      message:
-        "How would you like to improve this document?\n" +
-        "Examples:\n" +
-        "  • Add troubleshooting section for common errors\n" +
-        "  • Simplify the explanation for beginners\n" +
-        "  • Remove the outdated information about version 1.0\n\n" +
-        "  Your feedback:",
-    });
+      // Ask for feedback
+      feedback = await options.prompts.input({
+        message:
+          "How would you like to improve this document?\n" +
+          "Examples:\n" +
+          "  • Add troubleshooting section for common errors\n" +
+          "  • Simplify the explanation for beginners\n" +
+          "  • Remove the outdated information about version 1.0\n\n" +
+          "  Your feedback:",
+      });
 
-    // If no feedback, finish the loop
-    if (!feedback?.trim()) {
-      break;
-    }
+      // If no feedback, finish the loop
+      if (!feedback?.trim()) {
+        break;
+      }
 
-    feedbacks.push(feedback.trim());
+      feedbacks.push(feedback.trim());
+    }
 
     // Get the updateDocument agent
     const updateAgent = options.context.agents["handleDocumentUpdate"];
@@ -236,6 +246,10 @@ export default async function userReviewDocument({ content, description, ...rest
         options.context.userContext.currentContent,
         title || "Untitled Document",
       );
+
+      if (rest.isChat) {
+        break;
+      }
     } catch (error) {
       console.error("Error processing your feedback:");
       console.error(`Type: ${error.name}`);

package/agents/utils/document-title-streamline.yaml

@@ -0,0 +1,48 @@
+name: documentTitleStreamline
+description: Streamline document titles by shortening them while preserving meaning for better sidebar navigation
+model:
+  reasoning_effort: low
+task_render_mode: hide
+instructions:
+  url: ../../prompts/common/document-structure/document-title-streamline.md
+input_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path for mapping purposes
+          title:
+            type: string
+            description: Document title to streamline
+        required:
+          - path
+          - title
+      description: List of document items with titles to streamline
+  required:
+    - documentList
+output_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path (same as input for mapping)
+          title:
+            type: string
+            description: Streamlined document title (max 24 characters for English, 12 characters for character-based languages)
+        required:
+          - path
+          - title
+      description: List of streamlined document items with shortened titles
+  required:
+    - documentList
+

package/agents/utils/list-docs.mjs

@@ -0,0 +1,15 @@
+import { getMainLanguageFiles } from "../../utils/docs-finder-utils.mjs";
+import init from "../init/index.mjs";
+
+export default async function listDocs(_, options) {
+  const config = await init({ checkOnly: true }, options);
+
+  // Get all main language .md files in docsDir
+  const mainLanguageFiles = await getMainLanguageFiles(config.docsDir, config.locale);
+
+  return {
+    documents: mainLanguageFiles,
+  };
+}
+
+listDocs.description = "List all available documentation files";

package/agents/utils/streamline-document-titles-if-needed.mjs

@@ -0,0 +1,88 @@
+/**
+ * Check if a string contains character-based language characters (Chinese, Japanese, Korean, etc.)
+ * @param {string} str - String to check
+ * @returns {boolean} - True if string contains character-based language characters
+ */
+function isCharacterBasedLanguage(str) {
+  if (!str) return false;
+  // Check for Chinese, Japanese, Korean, and other character-based languages
+  // Chinese: \u4e00-\u9fff (CJK Unified Ideographs)
+  // Japanese: \u3040-\u309f (Hiragana), \u30a0-\u30ff (Katakana)
+  // Korean: \uac00-\ud7a3 (Hangul Syllables)
+  // Thai: \u0e00-\u0e7f
+  // Arabic: \u0600-\u06ff
+  const characterBasedPattern =
+    /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7a3\u0e00-\u0e7f\u0600-\u06ff]/;
+  return characterBasedPattern.test(str);
+}
+
+/**
+ * Get character limit based on language type
+ * @param {string} title - Title to check
+ * @returns {number} - Character limit (24 for English, 12 for character-based languages)
+ */
+function getCharacterLimit(title) {
+  return isCharacterBasedLanguage(title) ? 12 : 24;
+}
+
+/**
+ * Streamline document titles if they exceed length limits
+ * Reusable function for streamlining document titles in various contexts
+ * @param {Object} params
+ * @param {Array<{title: string, path: string}>} params.documentStructure - Document structure array
+ * @param {Object} options - Agent options with context
+ * @returns {Promise<void>} - Modifies documentStructure in place
+ */
+export default async function streamlineDocumentTitlesIfNeeded({ documentStructure }, options) {
+  if (!documentStructure || !Array.isArray(documentStructure)) {
+    return;
+  }
+
+  // Filter items that need streamlining based on character count and language type
+  // English: > 24 characters, Character-based languages (Chinese, Japanese, etc.): > 12 characters
+  const itemsNeedingStreamline = documentStructure.filter((item) => {
+    if (!item.title) return false;
+    const limit = getCharacterLimit(item.title);
+    return item.title.length > limit;
+  });
+
+  if (itemsNeedingStreamline.length === 0) {
+    return;
+  }
+
+  const documentList = itemsNeedingStreamline.map((item) => ({
+    path: item.path,
+    title: item.title,
+  }));
+
+  const streamlineAgent = options?.context?.agents?.["documentTitleStreamline"];
+  if (!streamlineAgent) {
+    console.warn("⚠️  documentTitleStreamline agent not found. Skipping title streamlining.");
+    return;
+  }
+
+  try {
+    const streamlineResult = await options.context.invoke(streamlineAgent, {
+      documentList,
+    });
+
+    // Update the document items with streamlined titles using path as the key
+    if (streamlineResult.documentList && Array.isArray(streamlineResult.documentList)) {
+      const streamlineMap = new Map(streamlineResult.documentList.map((item) => [item.path, item]));
+
+      for (const item of documentStructure) {
+        const streamlined = streamlineMap.get(item.path);
+        if (streamlined) {
+          item.title = streamlined.title;
+        }
+      }
+    }
+  } catch (error) {
+    console.warn("⚠️  Failed to streamline document titles:", error.message);
+    console.warn("Continuing with original titles.");
+  }
+}
+
+streamlineDocumentTitlesIfNeeded.taskTitle = "Streamline document titles if needed";
+streamlineDocumentTitlesIfNeeded.description =
+  "Shorten document titles that exceed length limits to make sidebar navigation less crowded";

package/aigne.yaml

@@ -3,7 +3,7 @@
 model:
   # model: aignehub/gpt-5
   # model: aignehub/claude-sonnet-4-0
-  model: aignehub/gemini-2.5-pro # reasoning_effort 128-32768
+  model: google/gemini-2.5-pro # reasoning_effort 128-32768
   # https://github.com/AIGNE-io/aigne-framework/blob/main/models/gemini/src/gemini-chat-model.ts#L115
   reasoning_effort:
     $get: reasoningEffort
@@ -79,6 +79,10 @@ agents:
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/utils/analyze-feedback-intent.yaml
+  - ./agents/utils/list-docs.mjs
+
+  - ./agents/utils/document-title-streamline.yaml
+  - ./agents/utils/streamline-document-titles-if-needed.mjs
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.15",
+  "version": "0.8.16-beta",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -38,6 +38,7 @@
     "debug": "^4.4.1",
     "diff": "^8.0.2",
     "dompurify": "^3.2.6",
+    "fast-deep-equal": "^3.1.3",
     "file-type": "^21.0.0",
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",

package/prompts/common/document-structure/document-title-streamline.md

@@ -0,0 +1,86 @@
+# Document Title Streamline
+
+<role>
+You are a document title optimizer. Your task is to streamline document titles by shortening them while preserving their original meaning and clarity. The primary goal is to make sidebar navigation less crowded and easier to scan at a glance.
+</role>
+
+<input>
+
+- documentList: {{documentList}}
+
+</input>
+
+<streamlining_rules>
+
+**Core Requirements:**
+
+1. **Title Constraints (Optimized for Sidebar Display):**
+
+   - **Character-based limits** (not word-based, as character count determines visual width):
+     - **For English titles: Maximum 24 characters**
+     - **For character-based languages (Chinese, Japanese, etc.): Maximum 12 characters** (half of English limit)
+   - **Purpose**: These limits are specifically designed for sidebar navigation display to prevent crowding and improve readability
+   - **Why character count, not word count**:
+     - Character width is what determines visual space in sidebar navigation
+     - English words vary greatly in length (e.g., "API" = 3 chars, "Configuration" = 13 chars)
+     - Character count provides more accurate control over sidebar display width
+     - Ensures consistent visual width across different languages
+   - Must capture the core concept
+   - Use concise, clear terminology
+   - Preserve key technical terms or proper nouns when essential
+   - Remove unnecessary articles (a, an, the) and filler words
+   - Keep titles scannable and user-friendly
+   - Optimize specifically for sidebar navigation display
+
+2. **General Guidelines:**
+
+   - Maintain consistency in terminology across all items
+   - Prioritize clarity over brevity when there's a conflict
+   - Keep technical accuracy intact
+   - Preserve brand names, product names, and critical keywords
+   - Use title case for document titles
+   - Consider the document's context and hierarchy when streamlining
+   - Focus on making titles easy to scan in a sidebar navigation menu
+
+**Optimization Strategies:**
+
+- Replace long phrases with shorter equivalents
+- Use common abbreviations when widely understood
+- Remove redundant modifiers
+- Combine related concepts when possible
+- Focus on the most important information
+- Remove unnecessary words that don't add meaning
+
+**Important Notes:**
+
+- Only streamline the title, descriptions are not modified
+- **Sidebar Display Consideration**: Character-based limits (24 for English, 12 for other languages) are specifically chosen to optimize sidebar navigation display
+  - Sidebar navigation typically has limited horizontal space
+  - Character count determines visual width, not word count
+  - English: 24 characters ≈ 4-5 average words, fits standard sidebar width (250-300px)
+  - Character-based languages: 12 characters ≈ same visual width as 24 English characters
+  - Shorter titles prevent text wrapping and improve visual scanning
+  - These limits ensure titles remain readable and don't crowd the navigation menu
+- The goal is to make sidebar navigation less crowded and more readable
+- Titles should be immediately understandable without reading the full description
+- **Language detection**: Determine the primary language of the title and apply the appropriate character limit
+
+</streamlining_rules>
+
+<output_rules>
+
+Return a JSON object with:
+
+- `documentList`: array of streamlined document items, each containing:
+  - `path`: the same path from input (for mapping purposes)
+  - `title`: shortened title (maximum 24 characters for English, 12 characters for character-based languages, optimized for sidebar display)
+
+Ensure each streamlined item:
+- Preserves the exact `path` value from the corresponding input item
+- Maintains the original intent and meaning
+- Uses clear, scannable language
+- Fits within the word/character count constraints
+- Provides enough context for users to understand the document's purpose at a glance
+- Is optimized for sidebar navigation display
+
+</output_rules>

package/agents/utils/docs-fs-actor.yaml

@@ -1,27 +0,0 @@
-type: team
-name: docs_fs_actor
-description: File system operations for documentation management
-skills:
-  - url: ../init/index.mjs
-    default_input:
-      skipIfExists: true
-  - url: ./fs.mjs
-    default_input:
-      rootDir:
-        $get: docsDir
-input_schema:
-  type: object
-  properties:
-    action:
-      type: "string"
-      enum: ["read_file", "write_file", "delete_file", "list_directory"]
-      description:
-        "The file system action to perform, available actions are: read_file, write_file, delete_file, list_directory"
-    path:
-      type: "string"
-      description: "The path to the file or directory to operate on"
-    content:
-      type: "string"
-      description: "The content to write to the file, required for write_file action"
-  required: ["action", "path"]
-task_render_mode: hide

package/agents/utils/fs.mjs

@@ -1,60 +0,0 @@
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-export default async function fs({ rootDir, action, path, content }) {
-  if (!rootDir) throw new Error("Root directory is not specified");
-
-  path = join(rootDir, path);
-
-  switch (action) {
-    case "read_file":
-      return {
-        status: "ok",
-        path,
-        content: await readFile(path, "utf-8"),
-      };
-    case "write_file": {
-      await mkdir(dirname(path), { recursive: true });
-      await writeFile(path, content || "");
-      return {
-        status: "ok",
-        path,
-        content,
-      };
-    }
-    case "delete_file":
-      await rm(path, { recursive: true, force: true });
-      return {
-        status: "ok",
-        path,
-      };
-    case "list_directory":
-      return {
-        status: "ok",
-        entries: await readdir(path, { withFileTypes: true }).then((list) =>
-          list.map((entry) => ({
-            path: join(entry.parentPath, entry.name),
-            isDirectory: entry.isDirectory(),
-          })),
-        ),
-      };
-  }
-}
-
-fs.input_schema = {
-  type: "object",
-  properties: {
-    action: {
-      type: "string",
-      enum: ["read_file", "write_file", "delete_file", "list_directory"],
-      description:
-        "The file system action to perform, available actions are: read_file, write_file, delete_file, list_directory",
-    },
-    path: { type: "string", description: "The path to the file or directory to operate on" },
-    content: {
-      type: "string",
-      description: "The content to write to the file, required for write_file action",
-    },
-  },
-  required: ["action", "path"],
-};