@aigne/doc-smith 0.8.10-beta → 0.8.10-beta.2

package/docs/configuration-interactive-setup.zh.md

@@ -1,33 +1,33 @@
 # 交互式设置
 
-为简化项目配置，AIGNE DocSmith 提供了一个交互式设置向导，可通过 `aigne doc init` 命令启动。该引导式流程会询问一系列关于文档目标的问题，并根据您的回答生成一个 `config.yaml` 文件。这是开始新文档项目的推荐方式，因为它有助于防止配置错误并提供具体建议。
+AIGNE DocSmith 包含一个交互式设置向导，通过 `aigne doc init` 命令启动，以简化项目配置。该引导过程会询问一系列关于你的文档目标的问题，并根据你的回答生成一个 `config.yaml` 文件。这是启动新文档项目的推荐方法，因为它有助于防止配置错误，并根据你的输入提供具体建议。
 
 ## 运行向导
 
-首先，在您项目的根目录中运行以下命令：
+要开始此过程，请在项目的根目录中运行以下命令：
 
 ```bash aigne doc init icon=lucide:sparkles
 npx aigne doc init
 ```
 
-然后，向导将引导您完成一个 8 步流程来配置您的文档。
+然后，向导将引导你完成一个 8 步流程来配置文档。
 
-## 引导式流程
+## 引导流程
 
-向导涵盖以下关键领域：
+向导会提示输入以下关键配置细节：
 
-1.  **主要目标**：定义读者的主要预期成果（例如，快速入门、快速找到答案）。
-2.  **目标受众**：明确文档的阅读对象（例如，非技术最终用户、开发者）。
+1.  **主要目标**：定义读者的主要目的（例如，入门、寻找答案）。
+2.  **目标受众**：指明文档的主要读者（例如，非技术最终用户、开发者）。
 3.  **读者知识水平**：评估受众的典型初始知识水平。
-4.  **文档深度**：决定内容的详尽程度。
+4.  **文档深度**：确定内容的详细程度和范围。
 5.  **主要语言**：设置文档的主要语言。
-6.  **翻译语言**：选择用于翻译的其他语言。
-7.  **输出目录**：指定保存生成的文档文件的位置。
+6.  **翻译语言**：选择其他需要翻译的语言。
+7.  **输出目录**：指定生成文档文件的位置。
 8.  **源代码路径**：定义要分析的文件和目录，支持 glob 模式。
 
 ## 辅助配置
 
-该向导包含内置逻辑，可帮助您创建更有效、更一致的配置。
+向导使用一套预定义规则来帮助你创建一致且有效的配置。
 
 ```d2
 direction: down
@@ -38,12 +38,12 @@ User-Selections: {
 }
 
 Wizard-Engine: {
-  label: "2. 向导的逻辑引擎"
+  label: "2. 向导的规则引擎"
   shape: rectangle
   grid-columns: 2
 
   Filtering: {
-    label: "选项过滤\n（防止无效组合）"
+    label: "选项筛选\n（防止不兼容的选择）"
   }
 
   Conflict-Detection: {
@@ -59,61 +59,61 @@ Guided-Experience: {
 
 Final-Config: {
   label: "4. 最终配置"
-  content: "config.yaml 根据\n冲突解决策略生成"
+  content: "config.yaml 生成时\n包含冲突解决策略"
 }
 
 User-Selections -> Wizard-Engine
 Wizard-Engine.Filtering -> Guided-Experience
 Wizard-Engine.Conflict-Detection -> Final-Config
-Guided-Experience -> User-Selections: "优化"
+Guided-Experience -> User-Selections: "完善"
 ```
 
-### 默认建议和选项过滤
+### 默认建议和选项筛选
 
-在您回答问题时，向导会提供默认值并筛选后续选项，以引导您进行逻辑配置。例如：
+在你进行选择时，向导会提供默认值并筛选后续选项，以引导你进行逻辑配置。这是基于一套跨问题冲突规则。
 
--   **默认建议**：如果您选择“快速入门”作为主要目标，向导将推荐“完全是初学者”作为读者的知识水平。
--   **实时过滤**：如果您的目标受众是“最终用户（非技术人员）”，向导将隐藏“试图做特定事情的专家”等技术高级知识水平，以防止不兼容的选择。
+-   **默认建议**：如果你选择“快速入门”作为主要目标，向导将推荐“完全是初学者”作为读者的知识水平。
+-   **实时筛选**：如果你的目标受众是“最终用户（非技术人员）”，向导将隐藏“是专家”这一知识水平选项。该规则的理由是，非技术用户通常不是经验丰富的技术用户，从而防止不兼容的选择。
 
 ### 冲突检测与解决
 
-有时，您可能有多个似乎相互冲突的目标或受众，例如同时为非技术的**最终用户**和专业的**开发者**创建文档。向导会将这些识别为“可解决的冲突”。
+在某些情况下，你可能有多个目标或受众，需要特定的文档结构才能有效，例如为非技术的 **最终用户** 和专业的 **开发者** 创建文档。向导将这些识别为“可解决的冲突”。
 
-然后，它会制定一个策略，在文档结构中解决这些多样化的需求。对于最终用户与开发者的例子，解决方法是创建独立的用户路径：
+然后，它会制定一个策略来解决文档结构中的这些需求。对于最终用户与开发者的例子，解决策略是创建独立的用户路径：
 
--   **用户指南路径**：使用通俗易懂的语言，侧重于 UI 交互，并面向业务成果。
+-   **用户指南路径**：使用通俗易懂的语言，侧重于 UI 交互，并以业务成果为导向。
 -   **开发者指南路径**：代码优先，技术上精确，并包含 SDK 示例和配置片段。
 
-这种方法可确保最终的文档结构能够有效地服务于多个受众，而不是产生令人困惑的内容混合。
+这种方法确保最终的文档结构能够有效地服务于多个受众，而不是创建一个单一、混乱的内容混合体。
 
-## 生成的输出
+## 生成输出
 
-完成后，向导会在您的项目中保存一个 `config.yaml` 文件。该文件带有完整的注释，解释了每个选项并列出了所有可用选择，方便日后手动审查和修改。
+完成向导后，它会在你的项目中保存一个 `config.yaml` 文件。该文件带有完整的注释，解释了每个选项并列出了所有可用选择，这使得以后手动审查和修改变得容易。
 
-以下是生成文件的片段示例：
+以下是生成文件的片段：
 
 ```yaml config.yaml icon=logos:yaml
 # 用于文档发布的项目信息
 projectName: your-project-name
-projectDesc: 您的项目描述。
+projectDesc: 你的项目描述。
 projectLogo: ""
 
 # =============================================================================
 # 文档配置
 # =============================================================================
 
-# 目的：您希望读者达到的主要成果是什么？
+# 目的：你希望读者实现的主要成果是什么？
 # 可用选项（根据需要取消注释并修改）：
 #   getStarted       - 快速入门：帮助新用户在 30 分钟内从零开始上手
-#   completeTasks    - 完成特定任务：引导用户完成常见的工作流程和用例
+#   completeTasks    - 完成特定任务：引导用户了解常见工作流程和用例
 documentPurpose:
   - completeTasks
   - findAnswers
 
-# 目标受众：谁会最常阅读这份文档？
+# 目标受众：谁会最常阅读本文档？
 # 可用选项（根据需要取消注释并修改）：
 #   endUsers         - 最终用户（非技术人员）：使用产品但不编写代码的人
-#   developers       - 开发者（集成您的产品/API）：将此添加到其项目中的工程师
+#   developers       - 集成你的产品/API 的开发者：将此产品添加到其项目中的工程师
 targetAudienceTypes:
   - endUsers
   - developers
@@ -123,11 +123,11 @@ targetAudienceTypes:
 
 ## 后续步骤
 
-配置文件就绪后，您就可以生成、翻译或发布您的文档了。
+配置文件就绪后，你就可以生成、翻译或发布文档了。
 
 <x-cards>
   <x-card data-title="生成文档" data-icon="lucide:play-circle" data-href="/features/generate-documentation">
-    了解如何使用单个命令从您的源代码自动创建一套完整的文档。
+    了解如何使用单个命令从源代码自动创建一套完整的文档。
   </x-card>
   <x-card data-title="配置指南" data-icon="lucide:settings" data-href="/configuration">
     深入了解所有可用设置，并学习如何手动微调 config.yaml 文件。

package/docs/configuration-language-support.md

@@ -1,8 +1,8 @@
 # Language Support
 
-AIGNE DocSmith provides automated translation for 12 languages, allowing you to generate and maintain documentation for a global audience. The entire process is handled by the `aigne doc translate` command, which uses an AI engine to process your source documents and create localized versions.
+AIGNE DocSmith uses AI to provide automated documentation translation into 12 languages. This allows you to generate and maintain documentation for a global audience using the `aigne doc translate` command.
 
-The translation workflow processes your source documents through the AIGNE AI engine to generate localized versions in your selected target languages.
+The translation workflow processes your source documents through an AI engine to generate localized versions in your selected target languages.
 
 ```d2
 direction: down
@@ -55,25 +55,25 @@ DocSmith offers AI-powered translations for the following languages. You can def
 
 ## How to Configure and Use Translation
 
-Translation languages are set when you initialize your project with `aigne doc init`. You can add new languages or translate documents at any time using the `aigne doc translate` command, which offers two modes of operation.
+Translation languages are set when you initialize your project with `aigne doc init`. You can add new languages or translate documents at any time using the `aigne doc translate` command, which has two modes of operation.
 
-### Interactive Mode
+### Interactive Mode for Guided Translation
 
-For a guided experience, run the command without any arguments. This is the recommended approach for most users.
+For a step-by-step guided experience, run the command without any arguments. This is the recommended approach for most users.
 
 ```bash Interactive Translation icon=lucide:wand
 aigne doc translate
 ```
 
-The interactive mode will then prompt you to:
+The interactive mode will then present a series of prompts that allow you to:
 
-- Select which of your existing documents to translate.
-- Choose one or more target languages from the supported list.
-- Add new translation languages to your project's configuration if they are not already included.
+1.  Select which of your existing documents to translate from a list.
+2.  Choose one or more target languages from the supported list.
+3.  Add new translation languages to your project's configuration if they are not already included.
 
-### Command-Line Arguments
+### Command-Line Arguments for Automation
 
-For direct control or for use in automated scripts (like CI/CD pipelines), you can specify documents and languages directly as command-line arguments.
+For direct control or for use in automated scripts, you can specify documents and languages directly as command-line arguments. This is ideal for developers and CI/CD pipelines.
 
 ```bash Command Example icon=lucide:terminal
 # Translate overview.md and examples.md into Chinese and Japanese
@@ -91,4 +91,4 @@ Key parameters for the command include:
 
 ---
 
-This section covers the available languages and how to enable them. For a complete guide on the translation workflow, including advanced options and best practices, see the [Translate Documentation](./features-translate-documentation.md) guide.
+This section covers the available languages and how to enable them. For a complete guide on the translation workflow, see the [Translate Documentation](./features-translate-documentation.md) guide.

package/docs/configuration-language-support.zh.md

@@ -1,8 +1,8 @@
 # 语言支持
 
-AIGNE DocSmith 提供 12 种语言的自动翻译功能，让你能够为全球用户生成和维护文档。整个过程由 `aigne doc translate` 命令处理，该命令使用 AI 引擎处理你的源文档并创建本地化版本。
+AIGNE DocSmith 使用 AI 提供 12 种语言的自动化文档翻译。这使您可以使用 `aigne doc translate` 命令为全球用户生成和维护文档。
 
-翻译工作流通过 AIGNE AI 引擎处理你的源文档，以在你选择的目标语言中生成本地化版本。
+翻译工作流通过 AI 引擎处理您的源文档，以生成您所选目标语言的本地化版本。
 
 ```d2
 direction: down
@@ -18,7 +18,7 @@ AI-Engine: {
 }
 
 Translated-Docs: {
-  label: "翻译后文档"
+  label: "翻译后的文档"
   shape: rectangle
   grid-columns: 3
 
@@ -36,11 +36,11 @@ AI-Engine -> Translated-Docs: "生成"
 
 ## 支持的语言
 
-DocSmith 为以下语言提供 AI 翻译功能。你可以在初始设置期间定义项目的主要语言，并选择任意数量的目标语言进行翻译。
+DocSmith 为以下语言提供 AI 翻译。您可以在初始设置期间定义项目的主要语言，并选择任意数量的目标语言进行翻译。
 
 | 语言 | 语言代码 | 示例文本 |
 |---|---|---|
-| 英语 | `en` | Hello |
+| English | `en` | Hello |
 | 简体中文 | `zh` | 你好 |
 | 繁體中文 | `zh-TW` | 你好 |
 | 日本語 | `ja` | こんにちは |
@@ -53,27 +53,27 @@ DocSmith 为以下语言提供 AI 翻译功能。你可以在初始设置期间
 | Italiano | `it` | Ciao |
 | العربية | `ar` | مرحبا |
 
-## 如何配置和使用翻译功能
+## 如何配置和使用翻译
 
-翻译语言在你使用 `aigne doc init` 初始化项目时设置。你可以随时使用 `aigne doc translate` 命令添加新语言或翻译文档，该命令提供两种操作模式。
+翻译语言在您使用 `aigne doc init` 初始化项目时设置。您可以随时使用 `aigne doc translate` 命令添加新语言或翻译文档，该命令有两种操作模式。
 
-### 交互模式
+### 用于引导式翻译的交互模式
 
-如需引导式体验，请在不带任何参数的情况下运行该命令。这是为大多数用户推荐的方法。
+要获得分步指导体验，请在不带任何参数的情况下运行该命令。这是推荐给大多数用户的方法。
 
 ```bash Interactive Translation icon=lucide:wand
 aigne doc translate
 ```
 
-交互模式将提示你：
+然后，交互模式将显示一系列提示，允许您：
 
-- 选择要翻译的现有文档。
-- 从支持的语言列表中选择一个或多个目标语言。
-- 如果项目中尚未包含新的翻译语言，则将其添加到项目配置中。
+1.  从列表中选择要翻译的现有文档。
+2.  从支持的列表中选择一个或多个目标语言。
+3.  如果项目中尚未包含新的翻译语言，则将其添加到项目配置中。
 
-### 命令行参数
+### 用于自动化的命令行参数
 
-为了直接控制或在自动化脚本（如 CI/CD 流水线）中使用，你可以直接将文档和语言指定为命令行参数。
+为了直接控制或在自动化脚本中使用，您可以直接将文档和语言指定为命令行参数。这对于开发人员和 CI/CD 流水线非常理想。
 
 ```bash Command Example icon=lucide:terminal
 # 将 overview.md 和 examples.md 翻译成中文和日文
@@ -84,11 +84,11 @@ aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
 
 | 参数 | 描述 |
 |---|---|
-| `--langs` | 指定目标语言代码。该标志可以多次使用以选择多种语言。 |
-| `--docs` | 指定要翻译的文档路径（例如 `overview.md`）。该标志也可以多次使用。 |
-| `--feedback` | 提供具体指令以指导翻译模型（例如，`"Use a formal tone"`）。 |
-| `--glossary` | 使用自定义术语表文件（例如 `@path/to/glossary.md`）以确保项目特定术语的翻译一致性。 |
+| `--langs` | 指定目标语言代码。此标志可多次使用以选择多种语言。 |
+| `--docs` | 指定要翻译的文档路径（例如 `overview.md`）。此标志也可以多次使用。 |
+| `--feedback` | 提供具体说明以指导翻译模型（例如 `"Use a formal tone"`）。 |
+| `--glossary` | 使用自定义术语表文件（例如 `@path/to/glossary.md`）以确保项目特定术语的翻译一致。 |
 
 ---
 
-本节介绍了可用语言以及如何启用它们。有关翻译工作流的完整指南，包括高级选项和最佳实践，请参阅[翻译文档](./features-translate-documentation.md)指南。
+本节介绍了可用的语言以及如何启用它们。有关翻译工作流的完整指南，请参阅[翻译文档](./features-translate-documentation.md)指南。

package/docs/configuration-llm-setup.md

@@ -1,17 +1,18 @@
 # LLM Setup
 
-AIGNE DocSmith uses Large Language Models (LLMs) to generate documentation content. The tool provides two primary methods for configuring your AI model provider: using the integrated AIGNE Hub for a streamlined experience, or connecting your own custom API keys for direct provider access.
+AIGNE DocSmith uses Large Language Models (LLMs) to generate documentation content. You can configure the AI model provider in two ways: using the integrated AIGNE Hub, or by connecting your own custom API keys.
 
 ## AIGNE Hub (Recommended)
 
-The simplest way to get started is with AIGNE Hub. It acts as a gateway to multiple LLM providers, offering two key advantages:
+The most direct way to start is with AIGNE Hub. It functions as a gateway to multiple LLM providers, offering two main benefits:
 
-- **No API Key Required:** Generate documents without needing to manage your own API keys or service subscriptions.
-- **Easy Model Switching:** Change the AI model for any command using a simple flag.
+- **No API Key Required:** You can generate documents without managing your own API keys or service subscriptions.
+- **Easy Model Switching:** You can change the AI model for any command by using the `--model` flag.
 
 To use a specific model through AIGNE Hub, add the `--model` flag to your command. Here are a few examples:
 
-```bash Use Google's Gemini 2.5 Flash model
+```bash Using Different Models via AIGNE Hub icon=mdi:code-braces
+# Use Google's Gemini 2.5 Flash model
 aigne doc generate --model google:gemini-2.5-flash
 
 # Use Anthropic's Claude 3.5 Sonnet model
@@ -21,33 +22,33 @@ aigne doc generate --model claude:claude-3-5-sonnet
 aigne doc generate --model openai:gpt-4o
 ```
 
-If you don't specify a model, DocSmith will use the default model defined in your project's configuration.
+If you do not specify a model, DocSmith will use the default model defined in your project's configuration.
 
 ## Using Custom API Keys
 
-If you prefer to use your own accounts with providers like OpenAI or Anthropic, you can configure DocSmith with your personal API keys. This gives you direct control over API usage and billing.
+If you prefer to use your own accounts with providers like OpenAI or Anthropic, you can configure DocSmith with your personal API keys. This method gives you direct control over API usage and billing.
 
-Configuration is handled through an interactive wizard. To launch it, run:
+Configuration is handled through an interactive wizard. To launch it, run the following command:
 
 ```bash
 aigne doc init
 ```
 
-The wizard will prompt you to select your provider and enter your credentials. For a complete guide, please see the [Interactive Setup](./configuration-interactive-setup.md) documentation.
+The wizard will prompt you to select your provider and enter your credentials. For a complete guide, refer to the [Interactive Setup](./configuration-interactive-setup.md) documentation.
 
 ## Setting a Default Model
 
-To ensure consistency across all documentation generation tasks, you can set a default LLM in your project's `aigne.yaml` configuration file. This model will be used automatically unless you override it with the `--model` flag.
+To maintain consistency across all documentation generation tasks, you can set a default LLM in your project's `aigne.yaml` configuration file. This model will be used for any command that does not include the `--model` flag.
 
-```yaml aigne.yaml icon=mdi:file-document
+```yaml aigne.yaml icon=mdi:file-code
 chat_model:
   provider: google
   name: gemini-2.5-pro
   temperature: 0.8
 ```
 
-In this configuration, DocSmith defaults to using Google's `gemini-2.5-pro` model with a `temperature` of `0.8` for all generation tasks.
+In this example, DocSmith is configured to use Google's `gemini-2.5-pro` model with a `temperature` setting of `0.8` by default.
 
 ---
 
-Now that your LLM provider is configured, you can explore how to manage translations for your documentation. Proceed to the [Language Support](./configuration-language-support.md) guide to see the full list of supported languages and learn how to enable them.
+With your LLM provider configured, you are ready to manage language settings for your documentation. Proceed to the [Language Support](./configuration-language-support.md) guide to see the full list of supported languages and learn how to enable them.

package/docs/configuration-llm-setup.zh.md

@@ -1,17 +1,18 @@
 # LLM 设置
 
-AIGNE DocSmith 使用大型语言模型 (LLMs) 生成文档内容。该工具提供两种配置 AI 模型提供商的主要方法：使用集成的 AIGNE Hub 以获得简化的体验，或连接你自己的自定义 API 密钥以直接访问提供商。
+AIGNE DocSmith 使用大语言模型 (LLM) 生成文档内容。你可以通过两种方式配置 AI 模型提供商：使用集成的 AIGNE Hub，或连接你自己的自定义 API 密钥。
 
-## AIGNE Hub (推荐)
+## AIGNE Hub（推荐）
 
-最简单的入门方法是使用 AIGNE Hub。它充当多个 LLM 提供商的网关，提供两大关键优势：
+最直接的入门方式是使用 AIGNE Hub。它作为一个通往多个 LLM 提供商的网关，提供两大主要优势：
 
-- **无需 API 密钥：** 无需管理自己的 API 密钥或服务订阅即可生成文档。
-- **轻松切换模型：** 使用一个简单的标志即可为任何命令更改 AI 模型。
+- **无需 API 密钥：** 你无需管理自己的 API 密钥或服务订阅即可生成文档。
+- **轻松切换模型：** 你可以通过使用 `--model` 标志为任何命令更改 AI 模型。
 
-要通过 AIGNE Hub 使用特定模型，请在命令中添加 `--model` 标志。以下是一些示例：
+要通过 AIGNE Hub 使用特定模型，请在命令中添加 `--model` 标志。以下是几个示例：
 
-```bash 使用 Google 的 Gemini 2.5 Flash 模型
+```bash 通过 AIGNE Hub 使用不同模型 icon=mdi:code-braces
+# 使用 Google 的 Gemini 2.5 Flash 模型
 aigne doc generate --model google:gemini-2.5-flash
 
 # 使用 Anthropic 的 Claude 3.5 Sonnet 模型
@@ -21,33 +22,33 @@ aigne doc generate --model claude:claude-3-5-sonnet
 aigne doc generate --model openai:gpt-4o
 ```
 
-如果不指定模型，DocSmith 将使用项目配置中定义的默认模型。
+如果你未指定模型，DocSmith 将使用项目配置中定义的默认模型。
 
 ## 使用自定义 API 密钥
 
-如果你更喜欢使用自己在 OpenAI 或 Anthropic 等提供商处的账户，可以用个人 API 密钥来配置 DocSmith。这样你就可以直接控制 API 的使用和计费。
+如果你更喜欢使用自己在 OpenAI 或 Anthropic 等提供商处的账户，可以用你的个人 API 密钥来配置 DocSmith。这种方法让你能够直接控制 API 的使用和计费。
 
-配置通过交互式向导完成。运行以下命令以启动它：
+配置通过一个交互式向导进行处理。要启动它，请运行以下命令：
 
 ```bash
 aigne doc init
 ```
 
-该向导将提示你选择提供商并输入凭据。有关完整指南，请参阅 [交互式设置](./configuration-interactive-setup.md) 文档。
+向导将提示你选择提供商并输入凭据。有关完整指南，请参阅 [交互式设置](./configuration-interactive-setup.md) 文档。
 
 ## 设置默认模型
 
-为确保所有文档生成任务的一致性，你可以在项目的 `aigne.yaml` 配置文件中设置默认的 LLM。除非使用 `--model` 标志覆盖，否则将自动使用此模型。
+为了在所有文档生成任务中保持一致性，你可以在项目的 `aigne.yaml` 配置文件中设置一个默认的 LLM。任何不包含 `--model` 标志的命令都将使用此模型。
 
-```yaml aigne.yaml icon=mdi:file-document
+```yaml aigne.yaml icon=mdi:file-code
 chat_model:
   provider: google
   name: gemini-2.5-pro
   temperature: 0.8
 ```
 
-在此配置中，DocSmith 默认对所有生成任务使用 Google 的 `gemini-2.5-pro` 模型，并将 `temperature` 设置为 `0.8`。
+在此示例中，DocSmith 被配置为默认使用 Google 的 `gemini-2.5-pro` 模型，并将 `temperature` 设置为 `0.8`。
 
 ---
 
-既然你的 LLM 提供商已配置完毕，你可以探索如何管理文档的翻译。请继续阅读 [语言支持](./configuration-language-support.md) 指南，查看支持的语言完整列表并了解如何启用它们。
+配置好 LLM 提供商后，你就可以管理文档的语言设置了。请继续阅读 [语言支持](./configuration-language-support.md) 指南，查看支持的语言完整列表并了解如何启用它们。

package/docs/configuration-preferences.md

@@ -4,7 +4,7 @@ AIGNE DocSmith is designed to learn from your feedback. When you refine or corre
 
 ## The Preference Lifecycle
 
-The following diagram illustrates how your feedback becomes a reusable rule that can be applied to future tasks and managed via the command line.
+The following diagram illustrates how your feedback becomes a reusable rule that can be applied to future tasks and managed from the command line.
 
 ```d2 The Preference Lifecycle
 direction: down
@@ -48,23 +48,23 @@ cli <-> pref_file: "Manages"
 
 ```
 
-### How DocSmith Learns from Feedback
+### How Preferences are Created
 
-When you provide feedback during the `refine` or `translate` stages, an internal agent called the 'Feedback Refiner' analyzes your input. Its goal is to distinguish between a one-time fix (e.g., correcting a typo) and a reusable policy (e.g., "always write code comments in English"). If it determines the feedback represents a lasting instruction, it creates a new preference rule.
+When you provide feedback during the `refine` or `translate` stages, an internal agent analyzes your input. It determines if the feedback is a one-time fix (e.g., correcting a typo) or a reusable policy (e.g., "always write code comments in English"). If it represents a lasting instruction, it creates a new preference rule.
 
-Each rule has several key properties that define its behavior:
+### Rule Properties
 
-| Property | Description |
-|---|---|
-| **id** | A unique identifier for the rule (e.g., `pref_a1b2c3d4`). |
-| **active** | A boolean (`true`/`false`) indicating if the rule is currently enabled. |
-| **scope** | Defines when the rule should be applied: `global`, `structure`, `document`, or `translation`. |
-| **rule** | The instruction that will be passed to the AI in future tasks. |
-| **feedback** | The original natural language feedback you provided. |
-| **createdAt** | The ISO 8601 timestamp of when the rule was created. |
-| **paths** | An optional list of file paths. If present, the rule only applies to content generated for those specific paths. |
+Each rule saved in `preferences.yml` has the following structure:
 
-## Managing Preferences via the CLI
+<x-field data-name="id" data-type="string" data-desc="A unique, randomly generated identifier for the rule (e.g., pref_a1b2c3d4e5f6g7h8)."></x-field>
+<x-field data-name="active" data-type="boolean" data-desc="Indicates if the rule is currently enabled. Inactive rules are ignored during generation tasks."></x-field>
+<x-field data-name="scope" data-type="string" data-desc="Defines when the rule should be applied. Valid scopes are 'global', 'structure', 'document', or 'translation'."></x-field>
+<x-field data-name="rule" data-type="string" data-desc="The specific, distilled instruction that will be passed to the AI in future tasks."></x-field>
+<x-field data-name="feedback" data-type="string" data-desc="The original, natural language feedback provided by the user, preserved for reference."></x-field>
+<x-field data-name="createdAt" data-type="string" data-desc="The ISO 8601 timestamp indicating when the rule was created."></x-field>
+<x-field data-name="paths" data-type="string[]" data-required="false" data-desc="An optional list of file paths. If present, the rule only applies to content generated for these specific source files."></x-field>
+
+## Managing Preferences with the CLI
 
 You can view and manage all your saved preferences using the `aigne doc prefs` command. This allows you to list, activate, deactivate, or permanently remove rules.
 
@@ -76,9 +76,7 @@ To see all saved preferences, both active and inactive, use the `--list` flag.
 aigne doc prefs --list
 ```
 
-The command displays a formatted list explaining the status, scope, ID, and any path limitations for each rule.
-
-**Example Output:**
+The command displays a formatted list showing the status, scope, ID, and any path limitations for each rule.
 
 ```text Example Output icon=lucide:clipboard-list
 # User Preferences
@@ -94,20 +92,17 @@ The command displays a formatted list explaining the status, scope, ID, and any
  
 ⚪ [document] pref_i9j0k1l2m3n4o5p6
    Code comments must be written in English.
- 
 ```
 
-### Toggling Preference Status
-
-If you want to temporarily disable a rule without deleting it, you can toggle its active status. Use the `--toggle` flag.
+### Deactivating and Reactivating Preferences
 
-Running the command without an ID will launch an interactive mode, allowing you to select one or more preferences to toggle:
+If you want to temporarily disable a rule without deleting it, you can toggle its active status using the `--toggle` flag. Running the command without an ID will launch an interactive mode, allowing you to select one or more preferences to toggle.
 
 ```bash Toggle preferences interactively icon=lucide:terminal
 aigne doc prefs --toggle
 ```
 
-To toggle specific rules directly, provide their IDs using the `--id` flag:
+To toggle a specific rule directly, provide its ID using the `--id` flag. This corresponds to the `deactivateRule` function, which sets the rule's `active` property to `false`.
 
 ```bash Toggle a specific preference icon=lucide:terminal
 aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
@@ -115,15 +110,15 @@ aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
 
 ### Removing Preferences
 
-To permanently delete one or more preferences, use the `--remove` flag. This action cannot be undone.
+To permanently delete one or more preferences, use the `--remove` flag. This action, which corresponds to the `removeRule` function, cannot be undone.
 
-For an interactive selection prompt, run the command without an ID:
+For an interactive selection prompt, run the command without an ID.
 
 ```bash Remove preferences interactively icon=lucide:terminal
 aigne doc prefs --remove
 ```
 
-To remove specific rules directly by their ID, use the `--id` flag:
+To remove a specific rule directly by its ID, use the `--id` flag.
 
 ```bash Remove a specific preference icon=lucide:terminal
 aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
@@ -131,4 +126,4 @@ aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
 
 ## Next Steps
 
-Managing preferences is a key part of tailoring DocSmith to your project's specific needs. For more customization options, explore the main [Configuration Guide](./configuration.md).
+Managing preferences is a key part of tailoring DocSmith to your project's specific needs. For more customization options, explore the main [Configuration Guide](./configuration.md).