@aigne/doc-smith 0.8.5 → 0.8.7

package/.aigne/doc-smith/output/structure-plan.json

@@ -136,11 +136,7 @@
     "description": "Understand the built-in checks DocSmith performs to ensure high-quality, well-formatted, and error-free documentation, including link checking and diagram validation.",
     "path": "/advanced/quality-assurance",
     "parentId": "/advanced",
-    "sourceIds": [
-      "utils/markdown-checker.mjs",
-      "utils/mermaid-validator.mjs",
-      "utils/kroki-utils.mjs"
-    ]
+    "sourceIds": ["utils/markdown-checker.mjs", "utils/mermaid-validator.mjs", "utils/d2-utils.mjs"]
   },
   {
     "title": "Changelog",

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.8.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.6...v0.9.0) (2025-09-12)
+
+
+### Features
+
+* support defining API parameters with field element ([#104](https://github.com/AIGNE-io/aigne-doc-smith/issues/104)) ([2296ead](https://github.com/AIGNE-io/aigne-doc-smith/commit/2296ead15a00aaf809b3854bf349361f0213f522))
+
+## [0.8.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.5...v0.8.6) (2025-09-11)
+
+
+### Features
+
+* add deploy unit tests and improve publish workflow with better logging ([e33a94b](https://github.com/AIGNE-io/aigne-doc-smith/commit/e33a94bef5eda09398901fa1f953e662ae5fbd16))
+* **publish:** display publish url for the default publish processing ([9d1d018](https://github.com/AIGNE-io/aigne-doc-smith/commit/9d1d0180dc9c8bb0a4393a893eed2395eec300ab))
+
+
+### Bug Fixes
+
+* **deploy:** ensure log is saved after await to prevent save failure ([793343f](https://github.com/AIGNE-io/aigne-doc-smith/commit/793343fc7f96ab962e70eb310cb07f4e7eaec9e0))
+
+
+### Miscellaneous Chores
+
+* release 0.8.6 ([1e25cb4](https://github.com/AIGNE-io/aigne-doc-smith/commit/1e25cb49a26d8bcc3c83ec36120b6bad4042cadf))
+
 ## [0.8.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.4...v0.8.5) (2025-09-10)
 
 

package/README.md

@@ -1,7 +1,7 @@
 [![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-doc-smith?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-doc-smith)
 [![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-doc-smith?style=flat-square)](https://github.com/AIGNE-io/aigne-doc-smith/issues)
 [![codecov](https://codecov.io/gh/AIGNE-io/aigne-doc-smith/graph/badge.svg?token=95TQO2NKYC)](https://codecov.io/gh/AIGNE-io/aigne-doc-smith)
-[![NPM Version](https://img.shields.io/npm/v/@aigne/core)](https://www.npmjs.com/package/@aigne/doc-smith)
+[![NPM Version](https://img.shields.io/npm/v/@aigne/doc-smith)](https://www.npmjs.com/package/@aigne/doc-smith)
 
 # AIGNE DocSmith
 
@@ -17,7 +17,7 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 ## Features
 
-- **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
+- **Automated Generate Document Structure:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
 - **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
 - **Multi-Language Support:** Seamlessly translates your documentation into 12 languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
 - **AIGNE Hub Integration:** Use [AIGNE Hub](https://www.aigne.io/en/hub) as your LLM provider without needing your own API keys, with easy switching between different large language models.
@@ -185,7 +185,7 @@ aigne doc update --docs overview.md --feedback "Add more comprehensive FAQ entri
 
 **Interactive Mode:** When run without parameters, `aigne doc update` will present an interactive menu for you to select which document to regenerate and provide feedback.
 
-#### Optimize Structure Planning
+#### Optimize Document Structure
 
 Improve the overall documentation structure based on feedback:
 

package/agents/{chat.yaml → chat/index.yaml}

@@ -21,10 +21,10 @@ instructions: |
 input_key: message
 memory: true
 skills:
-  - ./input-generator.mjs
-  - ./docs-generator.yaml
-  - ./detail-regenerator.yaml
-  - ./team-publish-docs.yaml
-  - ./retranslate.yaml
-  - ./docs-fs.yaml
-  - ./exit.mjs
+  - ../init/index.mjs
+  - ../generate/index.yaml
+  - ../update/index.yaml
+  - ../publish/index.yaml
+  - ../translate/index.yaml
+  - ../utils/docs-fs-actor.yaml
+  - ../utils/exit.mjs

package/agents/generate/check-document-structure.yaml

@@ -0,0 +1,30 @@
+name: checkDocumentStructure
+description: Check the Document Structure to ensure it meets expectations, especially in scenarios with previous generation results and user feedback.
+instructions:
+  url: ../../prompts/structure/check-document-structure.md
+input_schema:
+  type: object
+  properties:
+    documentStructure:
+      $ref: ../schema/document-structure.yaml
+      description: Newly generated document structure.
+    originalDocumentStructure:
+      $ref: ../schema/document-structure.yaml
+      description: Previous generation's document structure for comparison. If it doesn't exist, the check passes by default.
+    feedback:
+      type: string
+      description: User feedback provided for the previous generation's results.
+  required:
+    - documentStructure
+output_schema:
+  type: object
+  properties:
+    isValid:
+      type: boolean
+      description: Whether the check passes. true indicates pass, false indicates failure.
+    structureReviewFeedback:
+      type: string
+      description: Detailed explanation of the check results. If it fails, clearly specify which parts do not meet requirements.
+  required:
+    - isValid
+    - structureReviewFeedback

package/agents/{check-structure-plan.mjs → generate/check-need-generate-structure.mjs}

@@ -1,27 +1,27 @@
 import { access } from "node:fs/promises";
 import { join } from "node:path";
-import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import {
   getCurrentGitHead,
   getProjectInfo,
   hasFileChangesBetweenCommits,
   loadConfigFromFile,
   saveValueToConfig,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
-export default async function checkStructurePlan(
-  { originalStructurePlan, feedback, lastGitHead, docsDir, forceRegenerate, ...rest },
+export default async function checkNeedGenerateStructure(
+  { originalDocumentStructure, feedback, lastGitHead, docsDir, forceRegenerate, ...rest },
   options,
 ) {
-  // Check if we need to regenerate structure plan
+  // Check if we need to regenerate document structure
   let shouldRegenerate = false;
   let finalFeedback = feedback;
   let submittedFeedback = feedback;
 
-  // Prompt for feedback if originalStructurePlan exists and no feedback provided
-  if (originalStructurePlan && !feedback) {
+  // Prompt for feedback if originalDocumentStructure exists and no feedback provided
+  if (originalDocumentStructure && !feedback) {
     const userFeedback = await options.prompts.input({
-      message: "Please provide feedback for structure planning (press Enter to skip):",
+      message: "How can we improve the documentation structure? (press Enter to skip):",
     });
 
     if (userFeedback?.trim()) {
@@ -30,8 +30,8 @@ export default async function checkStructurePlan(
     }
   }
 
-  // If no feedback and originalStructurePlan exists, check for git changes
-  if (originalStructurePlan) {
+  // If no feedback and originalDocumentStructure exists, check for git changes
+  if (originalDocumentStructure) {
     // If no lastGitHead, check if _sidebar.md exists to determine if we should regenerate
     if (!lastGitHead) {
       try {
@@ -78,16 +78,16 @@ export default async function checkStructurePlan(
     `;
   }
 
-  // If no regeneration needed, return original structure plan
-  if (originalStructurePlan && !finalFeedback && !shouldRegenerate) {
+  // If no regeneration needed, return original document structure
+  if (originalDocumentStructure && !finalFeedback && !shouldRegenerate) {
     return {
-      structurePlan: originalStructurePlan,
+      documentStructure: originalDocumentStructure,
     };
   }
 
-  const panningAgent = options.context.agents["structurePlanning"];
+  const panningAgent = options.context.agents["refineDocumentStructure"];
 
-  // Get user preferences for structure planning and global scope
+  // Get user preferences for document structure and global scope
   const structureRules = getActiveRulesForScope("structure", []);
   const globalRules = getActiveRulesForScope("global", []);
 
@@ -100,7 +100,7 @@ export default async function checkStructurePlan(
 
   const result = await options.context.invoke(panningAgent, {
     feedback: finalFeedback || "",
-    originalStructurePlan,
+    originalDocumentStructure,
     userPreferences,
     ...rest,
   });
@@ -155,12 +155,12 @@ export default async function checkStructurePlan(
   return {
     ...result,
     feedback: "", // clear feedback
-    structurePlanFeedback: submittedFeedback,
+    documentStructureFeedback: submittedFeedback,
     projectInfoMessage: message,
-    originalStructurePlan: originalStructurePlan
-      ? originalStructurePlan
-      : JSON.parse(JSON.stringify(result.structurePlan || [])),
+    originalDocumentStructure: originalDocumentStructure
+      ? originalDocumentStructure
+      : JSON.parse(JSON.stringify(result.documentStructure || [])),
   };
 }
 
-checkStructurePlan.taskTitle = "Check if structure plan needs regeneration";
+checkNeedGenerateStructure.taskTitle = "Check if document structure needs generate or update";

package/agents/generate/generate-structure.yaml

@@ -0,0 +1,58 @@
+name: generateStructure
+description: Generate the structure and organization of your documentation
+instructions:
+  url: ../../prompts/structure/generate-structure.md
+input_schema:
+  type: object
+  properties:
+    rules:
+      type: string
+      description: Your specific requirements for documentation structure
+    locale:
+      type: string
+      description: Primary language for documentation (e.g., zh, en, ja)
+    datasources:
+      type: string
+      description: Project content and context to help generate document structure
+    targetAudience:
+      type: string
+      description: Target audience for the documentation
+    nodeName:
+      type: string
+      description: Specific section or page name to focus on
+    glossary:
+      type: string
+      description: Glossary for consistent terminology
+    feedback:
+      type: string
+      description: Tell us how to improve the documentation structure
+    userPreferences:
+      type: string
+      description: Your saved preferences for structure and documentation style
+    docsType:
+      type: string
+      description: "Documentation type (options: general, getting-started, reference, faq)"
+      default: general
+  required:
+    - rules
+    - datasources
+output_schema:
+  type: object
+  properties:
+    projectName:
+      type: string
+      description: Project name identified from your content sources
+    projectDesc:
+      type: string
+      description: Brief project description generated from content analysis (under 50 words)
+    documentStructure: ../schema/document-structure.yaml
+    documentStructureTree:
+      type: string
+      description: |
+        Visual tree structure showing documentation hierarchy with indented levels for easy review:
+        ```
+        - Home
+          - Getting Started
+            - Installation
+              - Requirements
+        ```

package/agents/{docs-generator.yaml → generate/index.yaml}

@@ -3,17 +3,16 @@ name: generate
 alias:
   - gen
   - g
-description: Automatically generates comprehensive project documentation
+description: Generate complete documentation for your project
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - ./load-config.mjs
-  - ./load-sources.mjs
-  - ./check-structure-plan.mjs
-  - url: ./save-output.mjs
+  - ../utils/load-sources.mjs
+  - ./check-need-generate-structure.mjs
+  - url: ../utils/save-output.mjs
     default_input:
-      saveKey: structurePlan
+      saveKey: documentStructure
       savePath:
         $get: outputDir
       fileName: structure-plan.json
@@ -24,7 +23,7 @@ skills:
       $merge([
         $,
         {
-          'structurePlanResult': $map(structurePlan, function($item) {
+          'documentExecutionStructure': $map(documentStructure, function($item) {
             $merge([
               $item,
               {
@@ -35,25 +34,25 @@ skills:
           "datasources": ""
         }
       ])
-  - ./format-structure-plan.mjs
-  - ./batch-docs-detail-generator.yaml
-  - url: ./check-feedback-refiner.mjs
+  - ../utils/format-document-structure.mjs
+  - ../update/batch-generate-document.yaml
+  - url: ../utils/check-feedback-refiner.mjs
     default_input:
-      stage: structure_planning
-  - ./save-docs.mjs
+      stage: document_structure
+  - ../utils/save-docs.mjs
 
 input_schema:
   type: object
   properties:
     glossary:
       type: string
-      description: Glossary of terms for consistent terminology, use @<file> to read from a file
+      description: Glossary file for consistent terminology (use @filename.md)
     feedback:
       type: string
-      description: Feedback for structure planning adjustments
+      description: Tell us how to improve the documentation structure
     forceRegenerate:
       type: boolean
-      description: Force regenerate all documentation
+      description: Rebuild all documentation from scratch
   required:
     - config
 mode: sequential

package/agents/generate/refine-document-structure.yaml

@@ -0,0 +1,12 @@
+type: team
+name: refineDocumentStructure
+description: A team of agents that generate the structure of the documentation.
+skills:
+  - generate-structure.yaml
+task_title: Generate the structure of the documentation
+task_render_mode: collapse
+reflection:
+  reviewer: check-document-structure.yaml
+  is_approved: isValid
+  max_iterations: 3
+  return_last_on_max_iterations: true

package/agents/{input-generator.mjs → init/index.mjs}

@@ -2,7 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import chalk from "chalk";
 import { stringify as yamlStringify } from "yaml";
-import { getFilteredOptions } from "../utils/conflict-detector.mjs";
+import { getFilteredOptions } from "../../utils/conflict-detector.mjs";
 import {
   DEPTH_RECOMMENDATION_LOGIC,
   DOCUMENT_STYLES,
@@ -11,14 +11,15 @@ import {
   READER_KNOWLEDGE_LEVELS,
   SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
-} from "../utils/constants.mjs";
+} from "../../utils/constants.mjs";
+import loadConfig from "../../utils/load-config.mjs";
 import {
   detectSystemLanguage,
   getAvailablePaths,
   getProjectInfo,
   isGlobPattern,
   validatePath,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
 // UI constants
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
@@ -31,7 +32,7 @@ const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
  * @returns {Promise<Object>}
  */
 export default async function init(
-  { outputPath = ".aigne/doc-smith", fileName = "config.yaml", skipIfExists = false },
+  { outputPath = ".aigne/doc-smith", fileName = "config.yaml", skipIfExists = false, appUrl },
   options,
 ) {
   if (skipIfExists) {
@@ -39,19 +40,20 @@ export default async function init(
     const configContent = await readFile(filePath, "utf8").catch(() => null);
     // Only skip if file exists AND has non-empty content
     if (configContent && configContent.trim() !== "") {
-      return {};
+      // load config from file
+      return loadConfig({ config: filePath, appUrl });
     }
   }
 
   console.log("🚀 Welcome to AIGNE DocSmith!");
-  console.log("Let's create your documentation configuration.\n");
+  console.log("Let's set up your documentation preferences.\n");
 
   // Collect user information
   const input = {};
 
   // 1. Primary purpose - what's the main outcome you want readers to achieve?
   const purposeChoices = await options.prompts.checkbox({
-    message: "📝 [1/8]: What is the primary goal for your readers? (Select all that apply)",
+    message: "📝 [1/8]: What should your documentation help readers achieve?",
     choices: Object.entries(DOCUMENT_STYLES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, style]) => ({
@@ -61,7 +63,7 @@ export default async function init(
       })),
     validate: (input) => {
       if (input.length === 0) {
-        return "Please select at least one purpose.";
+        return "Please choose at least one goal for your documentation.";
       }
       return true;
     },
@@ -81,10 +83,10 @@ export default async function init(
         })),
       validate: (input) => {
         if (input.length === 0) {
-          return "Please select at least one priority.";
+          return "Please choose at least one priority.";
         }
         if (input.length > 2) {
-          return "Please select maximum 2 priorities.";
+          return "Please choose maximum 2 priorities.";
         }
         return true;
       },
@@ -99,7 +101,7 @@ export default async function init(
 
   // 2. Target audience - who will be reading this most often?
   const audienceChoices = await options.prompts.checkbox({
-    message: "👥 [2/8]: Who is the primary audience for this documentation?",
+    message: "👥 [2/8]: Who will be reading your documentation?",
     choices: Object.entries(TARGET_AUDIENCES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, audience]) => ({
@@ -109,7 +111,7 @@ export default async function init(
       })),
     validate: (input) => {
       if (input.length === 0) {
-        return "Please select at least one audience.";
+        return "Please choose at least one audience.";
       }
       return true;
     },
@@ -133,7 +135,7 @@ export default async function init(
   );
 
   const knowledgeChoice = await options.prompts.select({
-    message: "🧠 [3/8]: What is your reader's typical starting knowledge level?",
+    message: "🧠 [3/8]: How much do readers already know about your project?",
     choices: Object.entries(filteredKnowledgeOptions).map(([key, level]) => ({
       name: `${level.name}`,
       description: level.description,
@@ -178,7 +180,7 @@ export default async function init(
   );
 
   const depthChoice = await options.prompts.select({
-    message: "📊 [4/8]: How comprehensive should the documentation be?",
+    message: "📊 [4/8]: How detailed should your documentation be?",
     choices: Object.entries(filteredDepthOptions).map(([key, depth]) => ({
       name: `${depth.name}`,
       description: depth.description,
@@ -196,7 +198,7 @@ export default async function init(
 
   // Let user select primary language from supported list
   const primaryLanguageChoice = await options.prompts.select({
-    message: "🌐 [5/8]: Choose primary documentation language:",
+    message: "🌐 [5/8]: What's your main documentation language?",
     choices: SUPPORTED_LANGUAGES.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -213,7 +215,7 @@ export default async function init(
   );
 
   const translateLanguageChoices = await options.prompts.checkbox({
-    message: "🔄 [6/8]: Select translation languages:",
+    message: "🔄 [6/8]: Which languages should we translate to?",
     choices: availableTranslationLanguages.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -224,21 +226,23 @@ export default async function init(
 
   // 7. Documentation directory
   const docsDirInput = await options.prompts.input({
-    message: `📁 [7/8]: Where to save generated docs:`,
+    message: `📁 [7/8]: Where should we save your documentation?`,
     default: `${outputPath}/docs`,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
-  // 8. Source code paths
-  console.log("\n🔍 [8/8]: Source Code Paths");
-  console.log("Enter paths to analyze for documentation (e.g., ./src, ./lib)");
-  console.log("💡 You can also enter glob patterns (e.g., src/**/*.js, **/*.md)");
-  console.log("💡 If no paths are configured, './' will be used as default");
+  // 8. Content sources
+  console.log("\n🔍 [8/8]: Content Sources");
+  console.log(
+    "What folders/files should we analyze for documentation? (e.g., ./src, ./docs, ./README.md)",
+  );
+  console.log("💡 Advanced: Use patterns like src/**/*.js or docs/**/*.md for specific files");
+  console.log("💡 Leave empty to scan everything");
 
   const sourcePaths = [];
   while (true) {
     const selectedPath = await options.prompts.search({
-      message: "Path or glob pattern:",
+      message: "File/folder path or pattern:",
       source: async (input) => {
         if (!input || input.trim() === "") {
           return [
@@ -330,15 +334,18 @@ export default async function init(
     await mkdir(dirPath, { recursive: true });
 
     await writeFile(filePath, yamlContent, "utf8");
-    console.log(`\n🎉 Configuration saved to: ${chalk.cyan(filePath)}`);
+    console.log(`\n✅ Setup complete! Configuration saved to: ${chalk.cyan(filePath)}`);
     // Print YAML content for user review
     console.log(chalk.cyan("---"));
     console.log(chalk.cyan(yamlContent));
     console.log(chalk.cyan("---"));
     console.log("💡 You can edit the configuration file anytime to modify settings.\n");
-    console.log(
-      `🚀 Run ${chalk.cyan("'aigne doc generate'")} to start documentation generation!\n`,
-    );
+    console.log(`🚀 Ready to generate docs? Run: ${chalk.cyan("aigne doc generate")}\n`);
+
+    // load config from file
+    if (skipIfExists) {
+      return loadConfig({ config: filePath, appUrl });
+    }
 
     return {};
   } catch (error) {

package/agents/{manage-prefs.mjs → prefs/index.mjs}

@@ -1,4 +1,4 @@
-import { readPreferences, removeRule, writePreferences } from "../utils/preferences-utils.mjs";
+import { readPreferences, removeRule, writePreferences } from "../../utils/preferences-utils.mjs";
 
 /**
  * List all user preferences with formatted display
@@ -8,7 +8,7 @@ function listPreferences() {
   const preferences = readPreferences();
 
   if (preferences.rules.length === 0) {
-    return { message: "No preferences found." };
+    return { message: "No saved preferences found." };
   }
 
   let message = "# User Preferences\n\n";
@@ -53,7 +53,7 @@ async function removePreferences(id, options) {
   if (!targetIds || targetIds.length === 0) {
     // Interactive selection
     if (preferences.rules.length === 0) {
-      return { message: "No preferences found to remove." };
+      return { message: "No preferences available to remove." };
     }
 
     const choices = preferences.rules.map((rule) => ({
@@ -63,18 +63,18 @@ async function removePreferences(id, options) {
     }));
 
     targetIds = await options.prompts.checkbox({
-      message: "Select preferences to remove:",
+      message: "Choose preferences to delete:",
       choices,
       validate: (answer) => {
         if (answer.length === 0) {
-          return "Please select at least one preference to remove";
+          return "Please choose at least one preference to delete";
         }
         return true;
       },
     });
 
     if (!targetIds || targetIds.length === 0) {
-      return { message: "No preferences selected for removal." };
+      return { message: "No preferences selected for deletion." };
     }
   }
 
@@ -108,7 +108,7 @@ async function togglePreferences(id, options) {
   if (!targetIds || targetIds.length === 0) {
     // Interactive selection
     if (preferences.rules.length === 0) {
-      return { message: "No preferences found to toggle." };
+      return { message: "No preferences available to toggle." };
     }
 
     const choices = preferences.rules.map((rule) => ({
@@ -118,18 +118,18 @@ async function togglePreferences(id, options) {
     }));
 
     targetIds = await options.prompts.checkbox({
-      message: "Select preferences to toggle active status:",
+      message: "Choose preferences to enable/disable:",
       choices,
       validate: (answer) => {
         if (answer.length === 0) {
-          return "Please select at least one preference to toggle";
+          return "Please choose at least one preference to toggle";
         }
         return true;
       },
     });
 
     if (!targetIds || targetIds.length === 0) {
-      return { message: "No preferences selected for toggling." };
+      return { message: "No preferences selected to toggle." };
     }
   }
 
@@ -172,7 +172,7 @@ export default async function prefs({ list, remove, toggle, id }, options) {
     return await togglePreferences(id, options);
   }
 
-  return { message: "Please specify an action: --list, --remove, or --toggle." };
+  return { message: "Please choose an action: --list, --remove, or --toggle." };
 }
 
 prefs.input_schema = {
@@ -180,24 +180,24 @@ prefs.input_schema = {
   properties: {
     list: {
       type: "boolean",
-      description: "List all preferences",
+      description: "Show all saved preferences",
     },
     remove: {
       type: "boolean",
-      description: "Remove preferences",
+      description: "Delete saved preferences",
     },
     toggle: {
       type: "boolean",
-      description: "Toggle preferences active status",
+      description: "Enable/disable preferences",
     },
     id: {
       type: "array",
       items: {
         type: "string",
       },
-      description: "Preference IDs to manage",
+      description: "Specific preference IDs to work with",
     },
   },
 };
 
-prefs.description = "Manage user preferences learned from feedback";
+prefs.description = "Manage your saved documentation preferences";