@aigne/doc-smith 0.8.12-beta.7 → 0.8.12-beta.8

package/docs/guides-generating-documentation.md

@@ -1,151 +1,89 @@
 # Generating Documentation
 
-This guide provides a systematic procedure for creating a complete set of documentation from your project's source files. The process is initiated using the `aigne doc generate` command, which analyzes your codebase, proposes a logical structure, and then writes the content for each document.
-
-This command is the primary tool for the initial creation of your documentation. For modifying documents after they have been created, refer to the [Updating Documentation](./guides-updating-documentation.md) guide.
-
-### The Generation Workflow
-
-The `generate` command executes a sequence of automated steps to build your documentation. The process is designed to be interactive, allowing you to review and approve the proposed structure before content is written.
-
-```d2
-direction: down
-
-start: {
-  label: "Start"
-  shape: oval
-}
-
-run_command: {
-  label: "Run 'aigne doc generate'"
-  shape: rectangle
-}
-
-check_config: {
-  label: "Configuration file exists?"
-  shape: diamond
-}
-
-interactive_setup: {
-  label: "Guide through interactive setup"
-  shape: rectangle
-  tooltip: "If .aigne/doc-smith/config.yaml is not found, an interactive setup is triggered."
-}
-
-propose_structure: {
-  label: "Analyze project and propose document structure"
-  shape: rectangle
-}
-
-review_structure: {
-  label: "User reviews the proposed structure"
-  shape: rectangle
-}
-
-user_approve: {
-  label: "Approve structure?"
-  shape: diamond
-}
-
-provide_feedback: {
-  label: "Provide feedback to refine structure"
-  shape: rectangle
-  tooltip: "User can request changes like renaming, adding, or removing sections."
-}
-
-generate_content: {
-  label: "Generate content for all documents"
-  shape: rectangle
-}
-
-end: {
-  label: "End"
-  shape: oval
-}
-
-start -> run_command
-run_command -> check_config
-check_config -> interactive_setup: {
-  label: "No"
-}
-interactive_setup -> propose_structure
-check_config -> propose_structure: {
-  label: "Yes"
-}
-propose_structure -> review_structure
-review_structure -> user_approve
-user_approve -> provide_feedback: {
-  label: "No"
-}
-provide_feedback -> review_structure
-user_approve -> generate_content: {
-  label: "Yes"
-}
-generate_content -> end
-```
+This guide provides a step-by-step process for creating a new set of documentation for your project using the `generate` command. This is the primary command used to transform your source files into a structured set of documents from start to finish.
+
+The generation process is designed to be systematic and interactive, ensuring the final output meets your project's specific needs.
 
-## Step-by-Step Process
+## The Generation Process
 
-To generate your documentation, navigate to the root directory of your project in your terminal and follow these steps.
+When you run `aigne doc generate`, the tool follows a methodical process to create your documentation. Here is a breakdown of each step.
 
-### 1. Run the Generate Command
+### Step 1: Initiate Generation
 
-Execute the `generate` command to begin the process. The tool will start by analyzing your project's files and structure.
+To begin, navigate to your project's root directory in your terminal and execute the core command.
 
-```bash Basic Generation Command
+```bash title="Terminal" icon=lucide:terminal
 aigne doc generate
 ```
 
-You can also use the aliases `gen` or `g` for brevity.
+This single command initiates the entire documentation creation workflow. If it's your first time running the command, you will be guided through an interactive setup process.
 
-### 2. Review the Documentation Structure
+![Generate Documentation Dialog](https://docsmith.aigne.io/image-bin/uploads/d409b85c2c7760778c18251e06d997d9.png)
 
-After the analysis is complete, the tool will display the proposed documentation structure and prompt you for review:
+### Step 2: Code Analysis and Structure Planning
 
-```
-Would you like to optimize the documentation structure?
-❯ No, looks good
-  Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')
-```
+First, DocSmith analyzes your source code to understand its structure, components, and relationships. Based on this analysis, it proposes an initial documentation structure. This plan organizes topics into a logical hierarchy, which may include sections like "Getting Started," "Guides," and "API Reference," tailored to your project's content.
+
+### Step 3: Interactive Structure Review
+
+After the initial structure is planned, you will be prompted to review it in the terminal. This is a critical step that allows you to refine the organization of your documents before the content is written.
+
+You can either approve the structure as is or provide feedback in plain language to make changes.
+
+![Reviewing the Documentation Structure](https://docsmith.aigne.io/image-bin/uploads/c530510525d8041c304d9c0258169904.png)
+
+Examples of feedback you can provide:
 
--   **No, looks good**: Select this option to approve the proposed structure and proceed directly to content generation.
--   **Yes, optimize the structure**: Select this option to modify the plan. The tool will then ask for your feedback in an interactive loop. You can provide instructions in plain text, such as:
-    -   `Add a new document 'Troubleshooting'`
-    -   `Remove the 'Legacy Features' document`
-    -   `Move 'Installation' to the top of the structure`
+*   Rename a section (e.g., change "Getting Started" to "Quick Start").
+*   Add a new document for "Troubleshooting."
+*   Remove a document that is not needed.
+*   Reorder sections to place "API Reference" before "Configuration."
 
-    After each piece of feedback, the AI will revise the structure, and you can review it again. Press Enter without typing any feedback to exit the loop and approve the final structure.
+The tool will apply your feedback and present the updated structure for another review. You can repeat this process until the structure aligns perfectly with your requirements.
 
-### 3. Content Generation
+### Step 4: Content Creation
 
-Once the documentation structure is approved, DocSmith will begin generating the detailed content for each document in the plan. This process runs automatically, and its duration depends on the size and complexity of your project.
+Once you approve the final structure, DocSmith proceeds to generate the detailed content for each document. It reads the relevant source files and writes clear explanations, code examples, and descriptions for every planned section. This process is executed for all documents in the approved plan.
 
-Upon completion, the generated files will be saved to the output directory specified in your configuration (e.g., `./docs`).
+### Step 5: Completion
 
-## Command Parameters
+When the process is complete, you will see a confirmation message indicating that the documentation has been generated successfully. The output files will be located in the directory specified in your configuration (the default is `./docs`).
 
-The `generate` command accepts several optional parameters to control its behavior.
+![Documentation Generated Successfully](https://docsmith.aigne.io/image-bin/uploads/19c72054cd662d51259e8f668571891e.png)
 
-| Parameter | Description | Example |
-|---|---|---|
-| `--forceRegenerate` | Rebuilds all documentation from scratch, ignoring any existing structure or content. This is useful when you want a complete reset. | `aigne doc generate --forceRegenerate` |
-| `--feedback` | Provides initial text-based instructions to guide the AI during the structure generation phase, before the interactive review starts. | `aigne doc generate --feedback "Add more API examples"` |
-| `--glossary` | Specifies a glossary file (e.g., `glossary.md`) to ensure consistent use of terminology throughout the documentation. | `aigne doc generate --glossary @/path/to/glossary.md` |
+## Command Options
 
-### Example: Forcing a Complete Rebuild
+You can modify the behavior of the `generate` command by using optional flags. These flags provide more control over the generation process.
 
-If you want to discard all previously generated documents and create a new set based on the current state of your code, use the `--forceRegenerate` flag.
+| Option                | Description                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--forceRegenerate`   | Re-creates all documentation from scratch, ignoring any existing files. This is useful if you have made significant changes to your source code or want a completely fresh build. |
+| `--glossary <path>`   | Specifies a glossary file (e.g., `--glossary @glossary.md`). This ensures that technical terms are defined and used consistently across all generated documents.               |
 
-```bash Forcing Regeneration
+### Example Usage
+
+Here are a few examples demonstrating how to use the command with its options.
+
+**Standard Generation**
+This is the most common use case for creating your initial set of documents.
+```bash title="Terminal" icon=lucide:terminal
+aigne doc generate
+```
+
+**Forced Regeneration**
+Use this command when you need to discard all existing documents and rebuild them entirely.
+```bash title="Terminal" icon=lucide:terminal
 aigne doc generate --forceRegenerate
 ```
 
-## Summary
+**Using a Glossary**
+To ensure consistent terminology, provide a path to your glossary file.
+```bash title="Terminal" icon=lucide:terminal
+aigne doc generate --glossary @./glossary.md
+```
 
-The `generate` command orchestrates the entire process of creating your initial project documentation. It combines automated code analysis with an interactive review process to produce a structured and relevant set of documents.
+## Summary
 
-After your documents are generated, you may want to:
+You have now learned the complete process for generating documentation from your project's source files. This workflow involves initiating the command, interactively reviewing the proposed structure, and allowing the tool to write the content.
 
--   [Update Documentation](./guides-updating-documentation.md): Make changes to specific documents.
--   [Translate Documentation](./guides-translating-documentation.md): Translate your content into other languages.
--   [Publishing Your Docs](./guides-publishing-your-docs.md): Make your documentation available online.
+After generating your documents, your next steps might be to [update specific documents](./guides-updating-documentation.md) with new information or [publish your documentation](./guides-publishing-your-docs.md) to make it accessible to your audience.

package/docs/guides-interactive-chat.md

@@ -1,85 +1,93 @@
 # Interactive Chat
 
-The interactive chat assistant provides a conversational interface for generating, modifying, and managing your documentation. Instead of running individual commands, you can describe what you need to do, and the assistant will guide you through the process, calling on the appropriate tools to complete the task.
+The interactive chat assistant provides a conversational command-line interface to manage all aspects of your documentation lifecycle. It interprets natural language instructions to execute commands for document generation, updates, translation, and publishing.
 
-This approach simplifies the documentation workflow by handling the underlying commands for you. It is the recommended method for most interactions with the tool.
+This guided approach removes the need to memorize individual commands and options, making it the recommended method for most documentation tasks.
 
 ## Starting the Chat Assistant
 
-To begin an interactive session, run the `chat` command from your terminal:
+To begin an interactive session, run the `chat` command from your project's root directory:
 
 ```bash
 aigndoc chat
 ```
 
-This will launch the assistant, and you can begin typing your requests.
+This command launches the assistant and presents a prompt, ready to receive your instructions.
 
 ## Core Capabilities
 
-The chat assistant is designed to handle the entire documentation lifecycle. Its primary functions include:
+The chat assistant is designed to handle the entire documentation lifecycle. Its primary functions are based on a set of specialized skills that it can call upon based on your requests.
 
 <x-cards data-columns="2">
   <x-card data-title="Generate Documentation" data-icon="lucide:file-plus-2">
-    Create a complete documentation structure and initial content by analyzing your project's source files.
+    Creates a complete documentation structure and initial content by analyzing your project's source code.
   </x-card>
   <x-card data-title="Refine and Update" data-icon="lucide:edit">
-    Regenerate specific sections or entire documents based on your feedback or changes in the source code.
+    Modifies specific documents or sections based on your feedback or changes in the source code.
   </x-card>
   <x-card data-title="Translate Content" data-icon="lucide:languages">
-    Translate existing documentation into multiple languages to reach a broader audience.
+    Translates existing documentation into multiple supported languages to reach a broader audience.
   </x-card>
   <x-card data-title="Publish and Manage" data-icon="lucide:upload-cloud">
-    Assist with publishing your documentation and managing team-based workflows.
+    Guides you through the process of publishing your documentation and managing team-based workflows.
   </x-card>
 </x-cards>
 
+## How It Works
+
+You can interact with the assistant in two ways:
+
+1.  **Natural Language**: State your goal in plain language. The assistant will identify the correct tool and guide you through the required steps. For example, you can type "update the getting started guide" or "I need to translate my docs into French."
+2.  **Direct Commands**: You can also type specific commands directly into the chat prompt to initiate a task, such as `generate` or `publish`.
+
 ## Available Commands
 
-Within the chat, you can state your goal in plain language (e.g., "update the getting started guide") or invoke specific commands. The assistant understands the following core commands, which correspond to its specialized skills:
+The assistant understands a set of core commands that correspond to its specialized skills. You can invoke these directly or describe a task that requires them.
 
 | Command | Description |
 | :--- | :--- |
-| `generate` | Starts the process of creating a new documentation structure from source files. |
-| `update` | Modifies existing documents based on code changes or user feedback. |
+| `generate` | Starts the process of creating a new documentation structure from your source files. |
+| `update` | Modifies existing documents based on code changes or specific feedback. |
 | `translate` | Translates documents into one or more supported languages. |
 | `publish` | Publishes your documentation to make it accessible online. |
 | `init` | Guides you through creating an initial configuration file for the project. |
 | `clear` | Removes generated files, configurations, and cached data. |
 | `prefs` | Manages your saved preferences for document generation. |
 | `evaluate` | Assesses the quality and completeness of your generated documentation. |
-| `history` | Shows the history of updates made to your documentation. |
-| `exit` | Ends the interactive chat session. |
+| `history` | Shows the history of updates and changes made to your documentation. |
+| `exit` | Ends the interactive chat session and returns you to the standard terminal prompt. |
 
 ## Example Interaction
 
-Here is a sample conversation to illustrate how the interactive assistant works.
+The following is a sample conversation that illustrates a typical workflow for generating new documentation.
 
 ```text
 You:
-> Hello, I need to create documentation for a new project.
+> I need to create documentation for my project located in the 'src' folder.
 
 AI Assistant:
-Of course. To get started, I need to analyze your project structure. Could you please provide the path to your source code directory?
+Understood. I will start the documentation generation process for the directory './src'.
+First, I will analyze your project to propose a documentation structure. This may take a few moments...
+...
+Analysis complete. I have created a proposed structure. Would you like to review it before I generate the content? (yes/no)
 
 You:
-> ./src
+> yes
 
 AI Assistant:
-Thank you. I will now analyze the files in ./src to propose a documentation structure. This may take a few moments...
+(The proposed documentation structure is displayed here for your review.)
 ...
-I have analyzed your project and created a proposed structure. Would you like to review it before I proceed with generating the content? (yes/no)
+You can request changes, such as 'add a guide for API authentication' or 'remove the section on deployment'. If the structure is correct, simply type 'continue'.
 
 You:
-> yes
+> continue
 
 AI Assistant:
-(Displays the proposed documentation structure for review)
-...
-Please review the structure above. You can ask me to add, remove, or modify any part of it.
+Great. I will now proceed with generating the content for each document. This may take a few minutes.
 ```
 
 ## Summary
 
-The interactive chat assistant is a powerful tool for managing your documentation in a guided, conversational manner. It streamlines complex tasks by handling the necessary steps and commands for you.
+The interactive chat assistant provides a structured and guided method for managing your documentation. It consolidates the functionality of all individual commands into a single, conversational interface, ensuring a consistent and straightforward workflow.
 
-For a more detailed walkthrough of a specific workflow, see the [Generating Documentation](./guides-generating-documentation.md) guide.
+For a detailed walkthrough of creating your first set of documents using the assistant, please proceed to the [Generating Documentation](./guides-generating-documentation.md) guide.

package/docs/guides-managing-history.md

@@ -1,41 +1,46 @@
 # Managing History
 
-AIGNE DocSmith maintains a chronological log of all updates made to your documentation. This feature allows you to track changes, review feedback provided during updates, and understand the evolution of your documents over time. This guide provides instructions on how to access and interpret this history.
+AIGNE DocSmith maintains a chronological log of all updates made to your documentation. This feature allows you to track changes, review the feedback provided for each update, and observe the evolution of your documents over time. This guide provides instructions on how to access and interpret this history log.
 
 ## Viewing Update History
 
-To view the log of all documentation updates, you can use the `history view` command. This command displays a compact, one-line summary for each entry, similar to a version control log.
+To view the log of all documentation updates, use the `history view` command. This command displays a compact, one-line summary for each entry, formatted similarly to a version control log.
 
-Execute the following command in your terminal:
+Execute the following command in your project's root directory:
 
 ```bash Viewing History icon=material-symbols:history
 aigne history view
 ```
 
-The `history` command also supports two aliases for the `view` subcommand: `log` and `list`. The following commands are equivalent and will produce the same output:
+For convenience, the `history` command also supports two aliases for the `view` subcommand: `log` and `list`. The following commands are equivalent to the one above and will produce the identical output:
 
 ```bash
 aigne history log
+```
+
+```bash
 aigne history list
 ```
 
+If no updates have been made yet, the tool will display the message: `No update history found`.
+
 ### Understanding the History Output
 
-The output of the `history view` command is formatted to provide key information about each update at a glance. Each line represents a single update entry.
+The output of the `history view` command is structured to provide key information about each update in a concise format. Each line in the log represents a single update event.
 
-Here is a breakdown of the format:
+The format is composed of the following components:
 
 | Component | Description |
 | :--- | :--- |
-| **Short Hash** | An 8-character unique identifier generated from the timestamp of the update. |
-| **Date** | A relative timestamp indicating when the update occurred (e.g., "5 minutes ago", "2 days ago"). For older entries, a specific date is shown. |
+| **Short Hash** | An 8-character unique identifier generated from the timestamp of the update. This hash is deterministic, meaning the same timestamp will always produce the same hash. |
+| **Date** | A relative timestamp indicating when the update occurred (e.g., "5 minutes ago", "2 days ago"). For entries older than one week, a specific date is shown. |
 | **Operation** | The type of action performed, such as `generate_document` or `update_document_detail`. |
-| **Document Path** | The path of the specific document that was modified, if the operation targeted a single file. This is enclosed in parentheses. |
-| **Feedback** | The feedback or summary message that was provided when the update was made. |
+| **Document Path** | The path of the specific document that was modified, if the operation targeted a single file. This is enclosed in parentheses for clarity. |
+| **Feedback** | The summary message or feedback that was provided when the update was executed. |
 
-### Example
+### Example Output
 
-Below is a sample output from running the `aigne history view` command.
+Below is a sample output from running the `aigne history view` command. This example illustrates how different operations are recorded in the log.
 
 ```bash
 📜 Update History
@@ -45,4 +50,4 @@ a3b1c9d2 1 day ago  update_document_detail (/overview): Refined the introduction
 f8d2e0c3 3 days ago generate_document (/guides/managing-history): Initial generation of the history management guide.
 ```
 
-This log provides a clear and orderly record of your documentation's modification history, which is useful for tracking progress and reviewing past changes.
+This log provides a clear and orderly record of your documentation's modification history, which is an effective tool for tracking progress and reviewing past changes.

package/docs/guides-publishing-your-docs.md

@@ -1,14 +1,14 @@
 # Publishing Your Docs
 
-Once you have generated your documentation, the next step is to publish it online, making it accessible to your audience. This guide provides a systematic overview of the publishing process using the `aigne doc publish` command.
+After generating your documentation, the next step is to make it accessible online. This guide provides a systematic procedure for publishing your documentation using the `aigne doc publish` command.
 
 ## The Publish Command
 
-The primary command for making your documentation live is `aigne doc publish`. This command uploads your generated files to a web service, where they can be viewed in a browser.
+The `aigne doc publish` command uploads your generated documentation files to a web service, making them available to your audience through a web browser.
 
-You can execute the command using its full name or its shorter aliases:
+You can execute the command using its full name or one of its aliases for convenience.
 
-```bash
+```bash Command Execution icon=lucide:terminal
 # Full command
 aigne doc publish
 
@@ -17,62 +17,67 @@ aigne doc pub
 aigne doc p
 ```
 
-When you run the publish command for the first time, you will be presented with an interactive prompt to select your preferred publishing platform.
+When this command is run for the first time, it initiates an interactive prompt to guide you through selecting a publishing platform.
 
-## Publishing Options
+![Publish Documentation Dialog](../assets/screenshots/doc-publish.png)
 
-You have several options for where to host your documentation. The interactive prompt will guide you through the selection.
+## Publishing Destinations
 
-### 1. DocSmith Cloud (Free Hosting)
+The tool provides several destinations for hosting your documentation. The interactive setup will present the following choices.
 
-This option publishes your documentation to `docsmith.aigne.io`, a free hosting service provided by AIGNE.
+### Option 1: DocSmith Cloud
 
--   **Use Case:** Ideal for open-source projects, personal blogs, or any scenario where public accessibility is desired without the need for custom infrastructure.
--   **Cost:** Free.
--   **Outcome:** Your documents will be publicly available at a URL provided upon successful publication.
+This option publishes your documentation to `docsmith.aigne.io`, a free hosting service.
 
-### 2. Your Existing Website
+*   **Intended Use**: This method is suitable for open-source projects or any documentation that is intended for public access.
+*   **Cost**: Free.
+*   **Outcome**: Your documentation will be publicly available at a URL provided after the publishing process is complete.
 
-This option allows you to publish the documentation to a website that you already own and manage.
+### Option 2: Your Existing Website
 
--   **Use Case:** Best for integrating documentation directly into an existing company website, product site, or personal domain. This method requires you to run your own instance of Discuss Kit.
--   **Cost:** Requires your own hosting infrastructure.
--   **Setup:**
-    1.  Select this option in the prompt.
-    2.  You will be asked to enter the URL of your website (e.g., `https://docs.your-company.com`).
-    3.  To set up your own documentation website, you can get a Discuss Kit instance from the official store: [https://www.web3kit.rocks/discuss-kit](https://www.web3kit.rocks/discuss-kit).
+This option allows you to publish documentation to a website you already own and manage. It requires you to operate your own instance of Discuss Kit.
 
-### 3. New Website (Paid Service)
+*   **Intended Use**: This is for integrating documentation directly into an existing company website, product portal, or personal domain.
+*   **Requirements**: You must have your own hosting infrastructure and a running instance of Discuss Kit.
+*   **Procedure**:
+    1.  Select the "Your existing website" option from the interactive prompt.
+    2.  When prompted, enter the full URL of your website (e.g., `https://docs.your-company.com`).
+    3.  To set up your own documentation website, you can obtain a Discuss Kit instance from the official store: [https://www.web3kit.rocks/discuss-kit](https://www.web3kit.rocks/discuss-kit). Discuss Kit is a non-open-source service that provides the necessary backend for hosting.
 
-If you do not have an existing website, this service helps you set up a new, dedicated site for your documentation.
+### Option 3: New Website
 
--   **Use Case:** Suitable for creating a professional, standalone documentation portal with a custom domain and hosting managed for you.
--   **Cost:** This is a paid service.
--   **Process:** The command will guide you through the necessary steps to deploy and configure a new Discuss Kit instance. If you have started this process before, you will also see an option to resume your previous setup.
+This option assists you in setting up a new, dedicated website for your documentation.
 
-## Direct Publishing
+*   **Intended Use**: This is for users who need a standalone documentation portal but do not have an existing website.
+*   **Cost**: This is a paid service.
+*   **Procedure**: The command-line interface will guide you through the process of deploying and configuring a new Discuss Kit instance. If you have previously started this process, an option to resume the setup will also be available.
 
-For automated workflows, such as CI/CD pipelines, or after you have completed the initial setup, you can bypass the interactive prompt by specifying the application URL directly.
+## Automated Publishing
 
-Use the `--appUrl` flag followed by your website's URL.
+For automated environments, such as a Continuous Integration/Continuous Deployment (CI/CD) pipeline, you can bypass the interactive prompt by specifying the destination URL directly.
 
-```bash
-# Example for a custom documentation site
+Use the `--appUrl` flag with the command to define the publishing target.
+
+```bash Direct Publishing Example icon=lucide:terminal
 aigne doc publish --appUrl https://docs.your-company.com
 ```
 
-Once you successfully publish to a specific URL (either by selecting an option in the prompt or by using the `--appUrl` flag), DocSmith saves this URL in your local configuration. On subsequent runs, it will automatically publish to the saved URL without asking again.
+Once you publish to a specific URL for the first time (either through the interactive prompt or the `--appUrl` flag), the tool saves this URL to your local configuration file. Subsequent executions of `aigne doc publish` will automatically use the saved URL, streamlining the update process.
 
 ## Troubleshooting
 
 ### Authorization Errors
 
-If you encounter an error message containing "401" or "403," it indicates that your authentication token is invalid or has expired. This can happen if permissions have changed or if the token is old.
+If the publishing process fails with an error message that includes "401" or "403," it signifies an issue with your authentication token. The token may be invalid, expired, or lack the required permissions.
 
-To resolve this, you can clear all stored configuration and credentials by running the `clear` command:
+To resolve this, reset your local configuration and credentials by running the `clear` command:
 
-```bash
+```bash Clear Configuration icon=lucide:terminal
 aigne doc clear
 ```
 
-After clearing the configuration, run `aigne doc publish` again. You will be guided through the authentication and setup process as if it were the first time.
+After the command completes, run `aigne doc publish` again. You will be prompted to re-authenticate and configure your publishing destination.
+
+---
+
+After successfully publishing your documentation, you may need to update it as your project evolves. For instructions on this process, please see the [Updating Documentation](./guides-updating-documentation.md) guide.