@aigne/doc-smith 0.8.3 → 0.8.4

package/docs/cli-reference.md

@@ -1,10 +1,6 @@
----
-labels: ["Reference"]
----
-
 # CLI Command Reference
 
-This guide provides a comprehensive reference for all available `aigne doc` sub-commands, their arguments, and options. It's designed for users who want to understand the full capabilities of the command-line interface.
+This guide provides a reference for all available `aigne doc` sub-commands, their arguments, and options. It is intended for users who want to use the command-line interface to its full potential.
 
 The general syntax is:
 
@@ -12,13 +8,82 @@ The general syntax is:
 aigne doc <command> [options]
 ```
 
+### Command Workflow
+
+The following diagram illustrates the typical lifecycle of creating and maintaining documentation with DocSmith's CLI commands:
+
+```d2
+direction: down
+
+Start: {
+  label: "Project Setup"
+  shape: circle
+}
+
+init: {
+  label: "aigne doc init\n(Interactive Setup)"
+  shape: rectangle
+}
+
+generate: {
+  label: "aigne doc generate\n(Create/Update All Docs)"
+  shape: rectangle
+}
+
+refinement-cycle: {
+  label: "Refinement Cycle"
+  shape: rectangle
+  grid-columns: 2
+
+  update: {
+    label: "aigne doc update\n(Refine Single Doc)"
+  }
+  translate: {
+    label: "aigne doc translate\n(Localize Content)"
+  }
+}
+
+publish: {
+  label: "aigne doc publish\n(Deploy Docs)"
+  shape: rectangle
+}
+
+End: {
+  label: "Docs Live"
+  shape: circle
+  style.fill: "#a2eeaf"
+}
+
+prefs: {
+  label: "aigne doc prefs\n(Manage Learned Rules)"
+  shape: cylinder
+}
+
+Start -> init: "Optional" {
+  style.stroke-dash: 4
+}
+init -> generate: "Configure"
+Start -> generate: "Direct"
+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`
 
-Automatically analyzes your source code and generates a complete set of documentation based on your configuration. If no configuration is found, it will automatically launch the interactive setup wizard.
+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
 
@@ -26,7 +91,7 @@ Automatically analyzes your source code and generates a complete set of document
 |---|---|---|
 | `--feedback` | string | Provides feedback to adjust and refine the overall document structure plan. |
 | `--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`, `claude:claude-3-5-sonnet`). Overrides the default model. |
+| `--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`. |
 
 ### Usage Examples
@@ -63,9 +128,10 @@ Optimizes and regenerates specific documents. You can run it interactively to se
 
 | Option | Type | Description |
 |---|---|---|
-| `--docs` | array | A list of document paths to regenerate (e.g., `--docs overview.md --docs /features/authentication.md`). |
+| `--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. |
 
 ### Usage Examples
 
@@ -76,7 +142,7 @@ aigne doc update
 
 **Update a specific document with targeted feedback:**
 ```bash
-aigne doc update --docs /cli-reference.md --feedback "Clarify the difference between the --docs and --langs options."
+aigne doc update --docs /cli-reference --feedback "Clarify the difference between the --docs and --langs options."
 ```
 
 ---
@@ -89,8 +155,8 @@ Translates existing documentation into one or more languages. It can be run inte
 
 | Option | Type | Description |
 |---|---|---|
-| `--docs` | array | A list of document paths to translate. If omitted in interactive mode, you can select them. |
-| `--langs` | array | A list of target language codes (e.g., `zh`, `ja`, `es`). If omitted, you can select them interactively. |
+| `--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`. |
 
@@ -123,7 +189,7 @@ Publishes your generated documentation to a Discuss Kit platform. You can publis
 
 | Option | Type | Description |
 |---|---|---|
-| `--appUrl` | string | The URL of your self-hosted Discuss Kit instance. If not provided, the command runs interactively, allowing you to choose between the official platform and a custom URL. |
+| `--appUrl` | string | The URL of your self-hosted Discuss Kit instance. If not provided, the command runs interactively. |
 
 ### Usage Examples
 
@@ -163,7 +229,7 @@ Manages user preferences that DocSmith learns from your feedback over time. Thes
 | `--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`. |
+| `--id` | array | Specifies the preference ID(s) to act upon for `--remove` or `--toggle`. Can be used multiple times. |
 
 ### Usage Examples
 

package/docs/cli-reference.zh.md

@@ -1,10 +1,6 @@
----
-labels: ["Reference"]
----
-
 # CLI 命令参考
 
-本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了全面的参考。它专为希望了解命令行界面全部功能的用户设计。
+本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了参考。旨在帮助用户充分利用命令行界面。
 
 通用语法如下：
 
@@ -12,21 +8,90 @@ labels: ["Reference"]
 aigne doc <command> [options]
 ```
 
+### 命令工作流
+
+下图展示了使用 DocSmith 的 CLI 命令创建和维护文档的典型生命周期：
+
+```d2
+direction: down
+
+Start: {
+  label: "项目设置"
+  shape: circle
+}
+
+init: {
+  label: "aigne doc init\n(交互式设置)"
+  shape: rectangle
+}
+
+generate: {
+  label: "aigne doc generate\n(创建/更新所有文档)"
+  shape: rectangle
+}
+
+refinement-cycle: {
+  label: "优化周期"
+  shape: rectangle
+  grid-columns: 2
+
+  update: {
+    label: "aigne doc update\n(优化单个文档)"
+  }
+  translate: {
+    label: "aigne doc translate\n(本地化内容)"
+  }
+}
+
+publish: {
+  label: "aigne doc publish\n(部署文档)"
+  shape: rectangle
+}
+
+End: {
+  label: "文档上线"
+  shape: circle
+  style.fill: "#a2eeaf"
+}
+
+prefs: {
+  label: "aigne doc prefs\n(管理学习到的规则)"
+  shape: cylinder
+}
+
+Start -> init: "可选" {
+  style.stroke-dash: 4
+}
+init -> generate: "配置"
+Start -> generate: "直接"
+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`、`claude:claude-3-5-sonnet`）。这将覆盖默认模型。 |
+| `--forceRegenerate` | boolean | 丢弃现有内容，从头开始重新生成所有文档。 |
+| `--model` | string | 指定用于生成的特定 LLM（例如，`openai:gpt-4o`）。此选项将覆盖默认模型。 |
 | `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
 
 ### 使用示例
@@ -57,15 +122,16 @@ aigne doc generate --model google:gemini-1.5-flash
 
 **别名：** `up`
 
-优化并重新生成特定文档。您可以以交互方式运行它来选择文档，或直接使用选项指定文档。这对于根据反馈进行有针对性的改进非常有用，而无需重新生成整个项目。
+优化并重新生成特定文档。您可以以交互方式运行以选择文档，或直接使用选项指定文档。此命令对于根据反馈进行有针对性的改进非常有用，无需重新生成整个项目。
 
 ### 选项
 
-| 选项 | 类型 | 描述 |
+| Option | Type | Description |
 |---|---|---|
-| `--docs` | array | 要重新生成的文档路径列表（例如，`--docs overview.md --docs /features/authentication.md`）。 |
+| `--docs` | array | 要重新生成的文档路径列表（例如，`--docs overview.md`）。可多次使用。 |
 | `--feedback` | string | 提供具体反馈以改进所选文档的内容。 |
 | `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
+| `--reset` | boolean | 忽略之前的结果，为所选文档从头开始重新生成内容。 |
 
 ### 使用示例
 
@@ -74,23 +140,23 @@ aigne doc generate --model google:gemini-1.5-flash
 aigne doc update
 ```
 
-**使用有针对性的反馈更新特定文档：**
+**使用针对性反馈更新特定文档：**
 ```bash
-aigne doc update --docs /cli-reference.md --feedback "阐明 --docs 和 --langs 选项之间的区别。"
+aigne doc update --docs /cli-reference --feedback "阐明 --docs 和 --langs 选项之间的区别。"
 ```
 
 ---
 
 ## `aigne doc translate`
 
-将现有文档翻译成一种或多种语言。可以以交互方式运行以选择文档和语言，也可以通过将它们指定为参数以非交互方式运行。
+将现有文档翻译成一种或多种语言。可以以交互方式运行以选择文档和语言，也可以通过参数指定以非交互方式运行。
 
 ### 选项
 
-| 选项 | 类型 | 描述 |
+| Option | Type | Description |
 |---|---|---|
-| `--docs` | array | 要翻译的文档路径列表。如果在交互模式下省略，您可以进行选择。 |
-| `--langs` | array | 目标语言代码列表（例如，`zh`、`ja`、`es`）。如果省略，您可以以交互方式选择它们。 |
+| `--docs` | array | 要翻译的文档路径列表。可多次使用。 |
+| `--langs` | array | 目标语言代码列表（例如，`zh`、`ja`、`es`）。可多次使用。 |
 | `--feedback` | string | 提供反馈以提高翻译质量。 |
 | `--glossary` | string | 用于确保跨语言术语一致性的术语表文件路径。使用 `@path/to/glossary.md`。 |
 
@@ -117,13 +183,13 @@ aigne doc translate --glossary @glossary.md --feedback "日语翻译请使用正
 
 **别名：** `pub`, `p`
 
-将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台，也可以发布到您自己自托管的实例。
+将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台，也可以发布到您自己托管的实例。
 
 ### 选项
 
-| 选项 | 类型 | 描述 |
+| Option | Type | Description |
 |---|---|---|
-| `--appUrl` | string | 您自托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行，允许您在官方平台和自定义 URL 之间进行选择。 |
+| `--appUrl` | string | 您自托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行。 |
 
 ### 使用示例
 
@@ -141,7 +207,7 @@ aigne doc publish --appUrl https://docs.my-company.com
 
 ## `aigne doc init`
 
-手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导会引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
+手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导将引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
 
 ### 使用示例
 
@@ -154,16 +220,16 @@ aigne doc init
 
 ## `aigne doc prefs`
 
-管理 DocSmith 随着时间的推移从您的反馈中学习到的用户偏好。这些偏好将在未来的生成和更新任务中作为规则应用，以保持与您的风格一致。
+管理 DocSmith 随时间从您的反馈中学习到的用户偏好。这些偏好将在未来的生成和更新任务中作为规则应用，以保持与您的风格一致。
 
 ### 选项
 
-| 选项 | 类型 | 描述 |
+| Option | Type | Description |
 |---|---|---|
 | `--list` | boolean | 列出所有已保存的偏好，显示其状态（激活/未激活）、范围和内容。 |
 | `--remove` | boolean | 移除一个或多个偏好。如果未提供 `--id`，则以交互方式运行。 |
 | `--toggle` | boolean | 切换一个或多个偏好的激活状态。如果未提供 `--id`，则以交互方式运行。 |
-| `--id` | array | 指定要执行 `--remove` 或 `--toggle` 操作的偏好 ID。 |
+| `--id` | array | 为 `--remove` 或 `--toggle` 指定要操作的偏好 ID。可多次使用。 |
 
 ### 使用示例
 
@@ -182,4 +248,4 @@ aigne doc prefs --remove
 aigne doc prefs --toggle --id <preference-id>
 ```
 
-有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅 [配置指南](./configuration.md)。
+有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅[配置指南](./configuration.md)。

package/docs/configuration-interactive-setup.md

@@ -1,82 +1,135 @@
----
-labels: ["Reference"]
----
-
 # Interactive Setup
 
-Setting up a new documentation project is straightforward with the interactive setup wizard. By running a single command, `aigne doc init`, you can generate a comprehensive `config.yaml` file tailored to your project's needs. The wizard guides you through a series of questions, provides intelligent defaults, and helps prevent configuration mistakes.
+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.
+
+## Running the Wizard
+
+To begin, run the following command in your project's root directory:
+
+```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.
 
-This is the recommended way to start a new DocSmith project, as it ensures all necessary settings are considered from the beginning.
+## The Guided Process
 
-## The Setup Process
+The wizard covers the following key areas:
 
-The `init` command launches a guided, 8-step process to understand your documentation goals. At each step, it asks a question and often suggests a default based on your previous answers.
+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).
+3.  **Reader Knowledge Level**: Assesses the typical starting knowledge of your audience.
+4.  **Documentation Depth**: Determines how comprehensive the content should be.
+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.
+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.
 
 ```d2
 direction: down
 
-start: "Start: `aigne doc init`" {
-  shape: hexagon
+User-Selections: {
+  label: "1. User provides input\n(Purpose, Audience, etc.)"
+  shape: rectangle
 }
 
-step1: "[1/8] Define Primary Goal"
-step2: "[2/8] Select Target Audience"
-step3: "[3/8] Set Reader Knowledge Level"
-step4: "[4/8] Choose Documentation Depth"
-step5: "[5/8] Select Primary Language"
-step6: "[6/8] Add Translation Languages"
-step7: "[7/8] Specify Output Directory"
-step8: "[8/8] Configure Source Paths"
-
-finish: "config.yaml is generated!" {
-  shape: hexagon
+Wizard-Engine: {
+  label: "2. Wizard's Logic Engine"
+  shape: rectangle
+  grid-columns: 2
+
+  Filtering: {
+    label: "Option Filtering\n(Prevents invalid combos)"
+  }
+
+  Conflict-Detection: {
+    label: "Conflict Detection\n(Identifies complex needs)"
+  }
 }
 
-start -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7 -> step8 -> finish
+Guided-Experience: {
+  label: "3. Guided Experience"
+  shape: rectangle
+  content: "User sees simplified, relevant options"
+}
 
-subsystem: "Throughout the process, DocSmith provides intelligent defaults and detects potential configuration conflicts to ensure a coherent setup." {
-    shape: callout
+Final-Config: {
+  label: "4. Final Configuration"
+  content: "config.yaml is generated with\nconflict resolution strategies"
 }
 
-subsystem -- step3
-subsystem -- step4
+User-Selections -> Wizard-Engine
+Wizard-Engine.Filtering -> Guided-Experience
+Wizard-Engine.Conflict-Detection -> Final-Config
+Guided-Experience -> User-Selections: "Refines"
 ```
 
-Here is a breakdown of each step:
+### Default Suggestions and Option Filtering
 
-1.  **Primary Goal**: Define the main purpose of your documentation. This choice heavily influences the style and structure of the generated content.
-2.  **Target Audience**: Specify who will be reading the documentation. This helps tailor the tone, language, and examples to the right audience.
-3.  **Reader Knowledge Level**: Indicate the typical starting knowledge of your readers. The wizard filters this list to show only options compatible with your previous selections.
-4.  **Documentation Depth**: Decide how comprehensive the documentation should be. A recommended default is provided based on your goal and audience.
-5.  **Primary Language**: Choose the main language for your documentation. It defaults to your detected system language.
-6.  **Translation Languages**: Select any additional languages you want to translate the documentation into.
-7.  **Documentation Directory**: Set the output folder for the generated documentation files.
-8.  **Source Code Paths**: Specify which files and folders DocSmith should analyze to generate documentation. You can use both direct paths (e.g., `./src`) and glob patterns (e.g., `src/**/*.js`).
+As you answer questions, the wizard provides defaults and filters subsequent options to guide you toward a logical configuration. For instance:
 
-## Intelligent Conflict Prevention
+-   **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.
 
-A key feature of the interactive setup is its ability to prevent conflicting configurations. As you make selections, the wizard intelligently filters the options in subsequent steps to ensure your final configuration is logical and effective.
+### Conflict Detection and Resolution
 
-For example, if you select **"Get started quickly"** as your primary goal, the wizard will prevent you from choosing **"Is an expert trying to do something specific"** as the reader's knowledge level. A quick-start guide is fundamentally incompatible with the needs of an expert who requires advanced, in-depth reference material. This mechanism guides you toward creating a coherent documentation strategy without requiring you to memorize every possible combination of settings.
+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."
 
-## Handling Complex Scenarios
+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:
 
-Sometimes, you may want to target multiple, distinct audiences. For instance, you might need documentation for both non-technical **End Users** and expert **Developers**. While these audiences have conflicting needs, the setup wizard allows you to select both.
+-   **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.
 
-Instead of treating this as an error, DocSmith uses this information as a guideline for the documentation's structure. It will resolve the conflict by planning separate user paths:
+This approach ensures that the final documentation is structured to serve multiple audiences effectively, rather than creating a confusing mix of content.
 
-*   **A User Guide**: Written in plain language, focusing on UI and business outcomes.
-*   **A Developer Guide**: Featuring code snippets, API references, and technical details.
+## Generated Output
 
-This approach ensures that the final documentation can serve diverse needs effectively through intelligent structural design rather than simple concatenation.
+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 completing the wizard, your configuration will be saved, and you'll be ready to generate your first set of documents.
+Here is a snippet of what the generated file looks like:
+
+```yaml config.yaml icon=logos:yaml
+# Project information for documentation publishing
+projectName: your-project-name
+projectDesc: Your project description.
+projectLogo: ""
+
+# =============================================================================
+# Documentation Configuration
+# =============================================================================
+
+# Purpose: What's the main outcome you want readers to achieve?
+# Available options (uncomment and modify as needed):
+#   getStarted       - Get started quickly: Help new users go from zero to working in <30 minutes
+#   completeTasks    - Complete specific tasks: Guide users through common workflows and use cases
+documentPurpose:
+  - completeTasks
+  - findAnswers
+
+# Target Audience: Who will be reading this most often?
+# Available options (uncomment and modify as needed):
+#   endUsers         - End users (non-technical): People who use the product but don't code
+#   developers       - Developers integrating your product/API: Engineers adding this to their projects
+targetAudienceTypes:
+  - endUsers
+  - developers
+
+# ... other settings
+```
+
+## Next Steps
+
+With your configuration file in place, you are ready to generate, translate, or publish your documentation.
 
 <x-cards>
-  <x-card data-title="Configuration Guide" data-icon="lucide:file-cog" data-href="/configuration">
-    Learn how to manually edit the `config.yaml` file for advanced customization.
-  </x-card>
   <x-card data-title="Generate Documentation" data-icon="lucide:play-circle" data-href="/features/generate-documentation">
-    Run the command to generate your first set of documents based on your new configuration.
+    Learn how to use a single command to automatically create a complete set of documentation from your source code.
+  </x-card>
+  <x-card data-title="Configuration Guide" data-icon="lucide:settings" data-href="/configuration">
+    Dive deeper into all available settings and learn how to fine-tune the config.yaml file manually.
   </x-card>
 </x-cards>