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

package/docs/cli-reference.md

@@ -54,11 +54,6 @@ End: {
   style.fill: "#a2eeaf"
 }
 
-prefs: {
-  label: "aigne doc prefs\n(Manage Learned Rules)"
-  shape: cylinder
-}
-
 Start -> init: "Optional" {
   style.stroke-dash: 4
 }
@@ -68,50 +63,44 @@ generate -> refinement-cycle: "Refine"
 refinement-cycle -> publish: "Ready"
 generate -> publish: "Direct Deploy"
 publish -> End
-
-prefs <-> generate: "Influences" {
-  style.stroke-dash: 2
-}
-prefs <-> refinement-cycle: "Influences" {
-  style.stroke-dash: 2
-}
 ```
 
 ---
 
 ## `aigne doc generate`
 
-**Aliases:** `gen`, `g`
-
 Analyzes your source code and generates a complete set of documentation based on your configuration. If no configuration is found, it automatically launches the interactive setup wizard.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--feedback` | string | Provides feedback to adjust and refine the overall documentation structure. |
-| `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch. |
-| `--model` | string | Specifies a particular LLM to use for generation (e.g., `openai:gpt-4o`). Overrides the default model. |
-| `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |
+| Option              | Type    | Description                                                                                                   |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `--feedback`        | string  | Provides feedback to adjust and refine the overall documentation structure.                                   |
+| `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch.                                     |
+| `--model`           | string  | Specifies a particular large language model to use for generation (e.g., `openai:gpt-4o`). Overrides the default. |
 
 ### Usage Examples
 
-**Generate documentation for the first time or update it:**
+**Generate or update documentation:**
+
 ```bash
 aigne doc generate
 ```
 
 **Force a complete regeneration of all documents:**
+
 ```bash
 aigne doc generate --forceRegenerate
 ```
 
 **Refine the document structure with feedback:**
+
 ```bash
 aigne doc generate --feedback "Add a new section for API examples and remove the 'About' page."
 ```
 
 **Generate using a specific model from AIGNE Hub:**
+
 ```bash
 aigne doc generate --model google:gemini-1.5-flash
 ```
@@ -120,29 +109,27 @@ aigne doc generate --model google:gemini-1.5-flash
 
 ## `aigne doc update`
 
-**Alias:** `up`
-
 Optimizes and regenerates specific documents. You can run it interactively to select documents or specify them directly with options. This is useful for making targeted improvements based on feedback without regenerating the entire project.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | A list of document paths to regenerate (e.g., `--docs overview.md`). Can be used multiple times. |
-| `--feedback` | string | Provides specific feedback to improve the content of the selected document(s). |
-| `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |
-| `--reset` | boolean | Ignores previous results and regenerates content from scratch for the selected documents. |
+| Option     | Type  | Description                                                                                 |
+| ---------- | ----- | ------------------------------------------------------------------------------------------- |
+| `--docs`     | array | A list of document paths to regenerate. Can be used multiple times.                         |
+| `--feedback` | string | Provides specific feedback to improve the content of the selected document(s).              |
 
 ### Usage Examples
 
-**Start an interactive session to select which document to update:**
+**Start an interactive session to select a document to update:**
+
 ```bash
 aigne doc update
 ```
 
 **Update a specific document with targeted feedback:**
+
 ```bash
-aigne doc update --docs /cli-reference --feedback "Clarify the difference between the --docs and --langs options."
+aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
 ```
 
 ---
@@ -153,54 +140,57 @@ Translates existing documentation into one or more languages. It can be run inte
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | A list of document paths to translate. Can be used multiple times. |
-| `--langs` | array | A list of target language codes (e.g., `zh`, `ja`, `es`). Can be used multiple times. |
-| `--feedback` | string | Provides feedback to improve the quality of the translation. |
-| `--glossary` | string | Path to a glossary file to ensure consistent terminology across languages. Use `@path/to/glossary.md`. |
+| Option       | Type  | Description                                                                                                |
+| ------------ | ----- | ---------------------------------------------------------------------------------------------------------- |
+| `--docs`       | array | A list of document paths to translate. Can be used multiple times.                                         |
+| `--langs`      | array | A list of target language codes (e.g., `zh`, `ja`). Can be used multiple times.                            |
+| `--feedback`   | string | Provides feedback to improve the quality of the translation.                                               |
+| `--glossary`   | string | Path to a glossary file to ensure consistent terminology across languages. Use `@path/to/glossary.md`. |
 
 ### Usage Examples
 
 **Start an interactive translation session:**
+
 ```bash
 aigne doc translate
 ```
 
 **Translate specific documents into Chinese and Japanese:**
+
 ```bash
-aigne doc translate --docs overview.md --docs getting-started.md --langs zh --langs ja
+aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
 ```
 
 **Translate with a glossary and feedback for better quality:**
+
 ```bash
-aigne doc translate --glossary @glossary.md --feedback "Use formal language for the Japanese translation."
+aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
 ```
 
 ---
 
 ## `aigne doc publish`
 
-**Aliases:** `pub`, `p`
-
 Publishes your generated documentation to a Discuss Kit platform. You can publish to the official AIGNE DocSmith platform or to your own self-hosted instance.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
+| Option     | Type   | Description                                                                                          |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
 | `--appUrl` | string | The URL of your self-hosted Discuss Kit instance. If not provided, the command runs interactively. |
 
 ### Usage Examples
 
 **Start an interactive publishing session:**
+
 ```bash
 aigne doc publish
 ```
 
 **Publish directly to a self-hosted instance:**
+
 ```bash
-aigne doc publish --appUrl https://docs.my-company.com
+aigne doc publish --appUrl https://your-discuss-kit-instance.com
 ```
 
 ---
@@ -212,40 +202,9 @@ Manually starts the interactive configuration wizard. This is useful for setting
 ### Usage Example
 
 **Launch the setup wizard:**
-```bash
-aigne doc init
-```
-
----
-
-## `aigne doc prefs`
-
-Manages user preferences that DocSmith learns from your feedback over time. These preferences are applied as rules in future generation and update tasks to maintain consistency with your style.
-
-### Options
-
-| Option | Type | Description |
-|---|---|---|
-| `--list` | boolean | Lists all saved preferences, showing their status (active/inactive), scope, and content. |
-| `--remove` | boolean | Removes one or more preferences. Runs interactively if `--id` is not provided. |
-| `--toggle` | boolean | Toggles the active status of one or more preferences. Runs interactively if `--id` is not provided. |
-| `--id` | array | Specifies the preference ID(s) to act upon for `--remove` or `--toggle`. Can be used multiple times. |
 
-### Usage Examples
-
-**List all your saved preferences:**
-```bash
-aigne doc prefs --list
-```
-
-**Interactively select preferences to remove:**
 ```bash
-aigne doc prefs --remove
-```
-
-**Toggle the status of a specific preference by its ID:**
-```bash
-aigne doc prefs --toggle --id <preference-id>
+aigne doc init
 ```
 
 For more details on how to tailor DocSmith to your needs, see the [Configuration Guide](./configuration.md).

package/docs/cli-reference.zh.md

@@ -1,8 +1,8 @@
 # CLI 命令参考
 
-本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了参考。旨在帮助用户充分利用命令行界面。
+本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了参考。它旨在帮助希望充分利用命令行的用户。
 
-通用语法如下：
+通用语法为：
 
 ```bash
 aigne doc <command> [options]
@@ -10,7 +10,7 @@ aigne doc <command> [options]
 
 ### 命令工作流
 
-下图展示了使用 DocSmith 的 CLI 命令创建和维护文档的典型生命周期：
+下图展示了使用 DocSmith CLI 命令创建和维护文档的典型生命周期：
 
 ```d2
 direction: down
@@ -54,11 +54,6 @@ End: {
   style.fill: "#a2eeaf"
 }
 
-prefs: {
-  label: "aigne doc prefs\n(管理学习到的规则)"
-  shape: cylinder
-}
-
 Start -> init: "可选" {
   style.stroke-dash: 4
 }
@@ -68,50 +63,44 @@ generate -> refinement-cycle: "优化"
 refinement-cycle -> publish: "就绪"
 generate -> publish: "直接部署"
 publish -> End
-
-prefs <-> generate: "影响" {
-  style.stroke-dash: 2
-}
-prefs <-> refinement-cycle: "影响" {
-  style.stroke-dash: 2
-}
 ```
 
 ---
 
 ## `aigne doc generate`
 
-**别名：** `gen`, `g`
-
 分析您的源代码，并根据您的配置生成一套完整的文档。如果未找到配置，它将自动启动交互式设置向导。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--feedback` | string | 提供反馈以调整和优化整体文档结构规划。 |
-| `--forceRegenerate` | boolean | 丢弃现有内容，从头开始重新生成所有文档。 |
-| `--model` | string | 指定用于生成的特定 LLM（例如，`openai:gpt-4o`）。此选项将覆盖默认模型。 |
-| `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
+| Option              | Type    | Description                                                                                                   |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `--feedback`        | string  | 提供反馈以调整和优化整体文档结构。                                   |
+| `--forceRegenerate` | boolean | 丢弃现有内容并从头开始重新生成所有文档。                                     |
+| `--model`           | string  | 指定用于生成的特定大语言模型（例如，`openai:gpt-4o`）。此选项将覆盖默认设置。 |
 
 ### 使用示例
 
-**首次生成或更新文档：**
+**生成或更新文档：**
+
 ```bash
 aigne doc generate
 ```
 
 **强制完全重新生成所有文档：**
+
 ```bash
 aigne doc generate --forceRegenerate
 ```
 
 **通过反馈优化文档结构：**
+
 ```bash
-aigne doc generate --feedback "为 API 示例添加一个新部分，并删除‘关于’页面。"
+aigne doc generate --feedback "Add a new section for API examples and remove the 'About' page."
 ```
 
-**使用 AIGNE Hub 中的特定模型进行生成：**
+**使用 AIGNE Hub 中的特定模型生成：**
+
 ```bash
 aigne doc generate --model google:gemini-1.5-flash
 ```
@@ -120,132 +109,102 @@ aigne doc generate --model google:gemini-1.5-flash
 
 ## `aigne doc update`
 
-**别名：** `up`
-
-优化并重新生成特定文档。您可以以交互方式运行以选择文档，或直接使用选项指定文档。此命令对于根据反馈进行有针对性的改进非常有用，无需重新生成整个项目。
+优化并重新生成特定文档。您可以以交互方式运行它来选择文档，或直接使用选项指定文档。这对于根据反馈进行有针对性的改进非常有用，而无需重新生成整个项目。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | 要重新生成的文档路径列表（例如，`--docs overview.md`）。可多次使用。 |
-| `--feedback` | string | 提供具体反馈以改进所选文档的内容。 |
-| `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
-| `--reset` | boolean | 忽略之前的结果，为所选文档从头开始重新生成内容。 |
+| Option     | Type  | Description                                                                                 |
+| ---------- | ----- | ------------------------------------------------------------------------------------------- |
+| `--docs`     | array | 要重新生成的文档路径列表。可多次使用。                         |
+| `--feedback` | string | 提供具体反馈以改进所选文档的内容。              |
 
 ### 使用示例
 
 **启动交互式会话以选择要更新的文档：**
+
 ```bash
 aigne doc update
 ```
 
-**使用针对性反馈更新特定文档：**
+**使用有针对性的反馈更新特定文档：**
+
 ```bash
-aigne doc update --docs /cli-reference --feedback "阐明 --docs 和 --langs 选项之间的区别。"
+aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
 ```
 
 ---
 
 ## `aigne doc translate`
 
-将现有文档翻译成一种或多种语言。可以以交互方式运行以选择文档和语言，也可以通过参数指定以非交互方式运行。
+将现有文档翻译成一种或多种语言。可以以交互方式运行它来选择文档和语言，也可以通过将它们指定为参数以非交互方式运行。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | 要翻译的文档路径列表。可多次使用。 |
-| `--langs` | array | 目标语言代码列表（例如，`zh`、`ja`、`es`）。可多次使用。 |
-| `--feedback` | string | 提供反馈以提高翻译质量。 |
-| `--glossary` | string | 用于确保跨语言术语一致性的术语表文件路径。使用 `@path/to/glossary.md`。 |
+| Option       | Type  | Description                                                                                                |
+| ------------ | ----- | ---------------------------------------------------------------------------------------------------------- |
+| `--docs`       | array | 要翻译的文档路径列表。可多次使用。                                         |
+| `--langs`      | array | 目标语言代码列表（例如，`zh`、`ja`）。可多次使用。                            |
+| `--feedback`   | string | 提供反馈以提高翻译质量。                                               |
+| `--glossary`   | string | 词汇表文件的路径，以确保跨语言术语的一致性。使用 `@path/to/glossary.md`。 |
 
 ### 使用示例
 
 **启动交互式翻译会话：**
+
 ```bash
 aigne doc translate
 ```
 
 **将特定文档翻译成中文和日文：**
+
 ```bash
-aigne doc translate --docs overview.md --docs getting-started.md --langs zh --langs ja
+aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
 ```
 
-**结合使用术语表和反馈以获得更高质量的翻译：**
+**使用词汇表和反馈进行翻译以获得更好的质量：**
+
 ```bash
-aigne doc translate --glossary @glossary.md --feedback "日语翻译请使用正式语言。"
+aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
 ```
 
 ---
 
 ## `aigne doc publish`
 
-**别名：** `pub`, `p`
-
-将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台，也可以发布到您自己托管的实例。
+将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台或您自己托管的实例。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--appUrl` | string | 您自托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行。 |
+| Option     | Type   | Description                                                                                          |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
+| `--appUrl` | string | 您自行托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行。 |
 
 ### 使用示例
 
 **启动交互式发布会话：**
+
 ```bash
 aigne doc publish
 ```
 
-**直接发布到自托管实例：**
+**直接发布到自行托管的实例：**
+
 ```bash
-aigne doc publish --appUrl https://docs.my-company.com
+aigne doc publish --appUrl https://your-discuss-kit-instance.com
 ```
 
 ---
 
 ## `aigne doc init`
 
-手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导将引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
+手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导会引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
 
 ### 使用示例
 
 **启动设置向导：**
-```bash
-aigne doc init
-```
-
----
-
-## `aigne doc prefs`
-
-管理 DocSmith 随时间从您的反馈中学习到的用户偏好。这些偏好将在未来的生成和更新任务中作为规则应用，以保持与您的风格一致。
-
-### 选项
-
-| Option | Type | Description |
-|---|---|---|
-| `--list` | boolean | 列出所有已保存的偏好，显示其状态（激活/未激活）、范围和内容。 |
-| `--remove` | boolean | 移除一个或多个偏好。如果未提供 `--id`，则以交互方式运行。 |
-| `--toggle` | boolean | 切换一个或多个偏好的激活状态。如果未提供 `--id`，则以交互方式运行。 |
-| `--id` | array | 为 `--remove` 或 `--toggle` 指定要操作的偏好 ID。可多次使用。 |
 
-### 使用示例
-
-**列出所有已保存的偏好：**
-```bash
-aigne doc prefs --list
-```
-
-**以交互方式选择要移除的偏好：**
 ```bash
-aigne doc prefs --remove
-```
-
-**通过 ID 切换特定偏好的状态：**
-```bash
-aigne doc prefs --toggle --id <preference-id>
+aigne doc init
 ```
 
-有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅[配置指南](./configuration.md)。
+有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅[配置指南](./configuration.md)。

package/docs/configuration-interactive-setup.md

@@ -1,33 +1,33 @@
 # Interactive Setup
 
-To simplify project configuration, AIGNE DocSmith provides an interactive setup wizard launched with the `aigne doc init` command. This guided process asks a series of questions about your documentation goals and generates a `config.yaml` file based on your answers. It is the recommended way to start a new documentation project, as it helps prevent configuration errors and provides specific recommendations.
+AIGNE DocSmith includes an interactive setup wizard, launched with the `aigne doc init` command, to streamline project configuration. This guided process asks a series of questions about your documentation goals and generates a `config.yaml` file from your answers. It is the recommended method for starting a new documentation project, as it helps prevent configuration errors and provides specific recommendations based on your inputs.
 
 ## Running the Wizard
 
-To begin, run the following command in your project's root directory:
+To start the process, run the following command in the root directory of your project:
 
 ```bash aigne doc init icon=lucide:sparkles
 npx aigne doc init
 ```
 
-The wizard will then guide you through an 8-step process to configure your documentation.
+The wizard will then walk you through an 8-step process to configure your documentation.
 
 ## The Guided Process
 
-The wizard covers the following key areas:
+The wizard prompts for the following key configuration details:
 
-1.  **Primary Goal**: Defines the main outcome for your readers (e.g., getting started quickly, finding answers fast).
-2.  **Target Audience**: Specifies who will be reading the documentation (e.g., non-technical end-users, developers).
+1.  **Primary Goal**: Defines the main purpose for your readers (e.g., getting started, finding answers).
+2.  **Target Audience**: Specifies the primary readers of the documentation (e.g., non-technical end-users, developers).
 3.  **Reader Knowledge Level**: Assesses the typical starting knowledge of your audience.
-4.  **Documentation Depth**: Determines how comprehensive the content should be.
+4.  **Documentation Depth**: Determines the level of detail and scope of the content.
 5.  **Primary Language**: Sets the main language for the documentation.
 6.  **Translation Languages**: Selects additional languages for translation.
-7.  **Output Directory**: Specifies where to save the generated documentation files.
+7.  **Output Directory**: Specifies the location for the generated documentation files.
 8.  **Source Code Paths**: Defines which files and directories to analyze, with support for glob patterns.
 
 ## Assisted Configuration
 
-The wizard includes built-in logic to help you create a more effective and coherent configuration.
+The wizard uses a set of predefined rules to help you create a coherent and effective configuration.
 
 ```d2
 direction: down
@@ -38,12 +38,12 @@ User-Selections: {
 }
 
 Wizard-Engine: {
-  label: "2. Wizard's Logic Engine"
+  label: "2. Wizard's Rule Engine"
   shape: rectangle
   grid-columns: 2
 
   Filtering: {
-    label: "Option Filtering\n(Prevents invalid combos)"
+    label: "Option Filtering\n(Prevents incompatible selections)"
   }
 
   Conflict-Detection: {
@@ -70,27 +70,27 @@ Guided-Experience -> User-Selections: "Refines"
 
 ### Default Suggestions and Option Filtering
 
-As you answer questions, the wizard provides defaults and filters subsequent options to guide you toward a logical configuration. For instance:
+As you make selections, the wizard provides defaults and filters subsequent options to guide you toward a logical configuration. This is based on a set of cross-question conflict rules.
 
 -   **Default Suggestions**: If you select "Get started quickly" as your primary goal, the wizard will recommend "Is a total beginner" as the reader's knowledge level.
--   **Real-time Filtering**: If your target audience is "End users (non-technical)," the wizard will hide technically advanced knowledge levels like "Is an expert trying to do something specific" to prevent incompatible selections.
+-   **Real-time Filtering**: If your target audience is "End users (non-technical)," the wizard will hide the "Is an expert" knowledge level. The rule's reasoning is that non-technical users are typically not experienced technical users, thus preventing an incompatible selection.
 
 ### Conflict Detection and Resolution
 
-Sometimes, you may have multiple goals or audiences that seem to conflict, such as creating documentation for both non-technical **End Users** and expert **Developers**. The wizard identifies these as "resolvable conflicts."
+In some cases, you may have multiple goals or audiences that require a specific documentation structure to be effective, such as creating documentation for both non-technical **End Users** and expert **Developers**. The wizard identifies these as "resolvable conflicts."
 
-It then formulates a strategy to address these diverse needs within the documentation's structure. For the End User vs. Developer example, the resolution strategy is to create separate user paths:
+It then formulates a strategy to address these needs within the document structure. For the End User vs. Developer example, the resolution strategy is to create separate user paths:
 
 -   **User Guide Path**: Uses plain language, focuses on UI interactions, and is oriented toward business outcomes.
 -   **Developer Guide Path**: Is code-first, technically precise, and includes SDK examples and configuration snippets.
 
-This approach ensures that the final documentation is structured to serve multiple audiences effectively, rather than creating a confusing mix of content.
+This approach ensures the final documentation is structured to serve multiple audiences effectively, rather than creating a single, confusing mix of content.
 
 ## Generated Output
 
-Upon completion, the wizard saves a `config.yaml` file in your project. This file is fully commented, explaining each option and listing all available choices, making it easy to review and modify manually later.
+After you complete the wizard, it saves a `config.yaml` file in your project. This file is fully commented, explaining each option and listing all available choices, which makes it easy to review and modify manually later.
 
-Here is a snippet of what the generated file looks like:
+Here is a snippet of a generated file:
 
 ```yaml config.yaml icon=logos:yaml
 # Project information for documentation publishing