@aigne/doc-smith 0.8.11-beta.5 → 0.8.11-beta.7

package/docs/cli-reference.md

@@ -1,82 +1,144 @@
 # CLI Command Reference
 
-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.
+This guide provides a comprehensive reference for all available `aigne doc` sub-commands, their arguments, and options. It is intended for users who want to utilize the command-line interface to its full potential.
 
 The general syntax is:
 
-```bash
+```bash command icon=lucide:terminal
 aigne doc <command> [options]
 ```
 
 ### Command Workflow
 
-The following diagram illustrates the typical lifecycle of creating and maintaining documentation with DocSmith's CLI commands:
+The following diagram illustrates the typical lifecycle of creating and maintaining documentation with DocSmith's CLI commands, along with the data they interact with.
 
 ```d2
 direction: down
 
-Start: {
-  label: "Project Setup"
-  shape: circle
+# Artifacts
+Source-Code: {
+  label: "Source Code"
+  shape: cylinder
 }
-
-init: {
-  label: "aigne doc init\n(Interactive Setup)"
-  shape: rectangle
+Configuration: {
+  label: "Configuration\n(.aigne/doc-smith/config.yml)"
+  shape: cylinder
 }
-
-generate: {
-  label: "aigne doc generate\n(Create/Update All Docs)"
-  shape: rectangle
+Generated-Docs: {
+  label: "Generated Docs"
+  shape: cylinder
+}
+Published-Docs: {
+  label: "Published Site"
+  shape: cylinder
 }
 
-refinement-cycle: {
-  label: "Refinement Cycle"
-  shape: rectangle
-  grid-columns: 2
+# --- Core Workflow ---
+Lifecycle: {
+  label: "Documentation Lifecycle"
+  
+  init: {
+    label: "1. Init\n`aigne doc init`"
+    shape: rectangle
+  }
 
-  update: {
-    label: "aigne doc update\n(Refine Single Doc)"
+  generate: {
+    label: "2. Generate\n`aigne doc generate`"
+    shape: rectangle
   }
-  translate: {
-    label: "aigne doc translate\n(Localize Content)"
+
+  Refinement: {
+    label: "3. Refine (Iterative)"
+    grid-columns: 2
+
+    update: {
+      label: "Update\n`aigne doc update`"
+      shape: rectangle
+    }
+    translate: {
+      label: "Translate\n`aigne doc translate`"
+      shape: rectangle
+    }
   }
-}
 
-publish: {
-  label: "aigne doc publish\n(Deploy Docs)"
-  shape: rectangle
+  publish: {
+    label: "4. Publish\n`aigne doc publish`"
+    shape: rectangle
+  }
 }
 
-End: {
-  label: "Docs Live"
-  shape: circle
-  style.fill: "#a2eeaf"
+# --- Utility Commands ---
+Utilities: {
+  label: "Utility Commands"
+  grid-columns: 2
+  
+  prefs: {
+    label: "Manage Prefs\n`aigne doc prefs`"
+    shape: rectangle
+  }
+  clear: {
+    label: "Clear Data\n`aigne doc clear`"
+    shape: rectangle
+  }
 }
 
-Start -> init: "Optional" {
+
+# --- Connections ---
+
+# Setup and Generation
+Lifecycle.init -> Configuration: "Creates"
+Source-Code -> Lifecycle.generate: "Reads"
+Configuration -> Lifecycle.generate: "Reads"
+Lifecycle.generate -> Generated-Docs: "Creates / Overwrites"
+Lifecycle.generate -> Lifecycle.init: {
+  label: "Runs if no config"
   style.stroke-dash: 4
 }
-init -> generate: "Configure"
-Start -> generate: "Direct"
-generate -> refinement-cycle: "Refine"
-refinement-cycle -> publish: "Ready"
-generate -> publish: "Direct Deploy"
-publish -> End
+
+# Refinement Loop
+Generated-Docs <-> Lifecycle.Refinement: "Reads & Writes"
+
+# Publishing
+Lifecycle.Refinement -> Lifecycle.publish
+Lifecycle.publish -> Published-Docs: "Uploads to"
+
+# Utility Connections
+Utilities.prefs -> Configuration: "Reads"
+Utilities.clear -> Configuration: "Deletes"
+Utilities.clear -> Generated-Docs: "Deletes"
 ```
 
 ---
 
+## `aigne doc init`
+
+Manually starts the interactive configuration wizard. This is useful for setting up a new project or modifying the configuration of an existing one. The wizard guides you through defining source code paths, setting output directories, choosing languages, and defining the documentation's style and target audience.
+
+### Usage Example
+
+**Launch the setup wizard:**
+
+```bash
+aigne doc init
+```
+![Screenshot of the interactive setup wizard completion.](../assets/screenshots/doc-complete-setup.png)
+
+For more details on how to tailor DocSmith to your needs, see the [Configuration Guide](./configuration.md).
+
+---
+
 ## `aigne doc generate`
 
-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.
+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 (`aigne doc init`).
+
+![Screenshot of the generate command running.](../assets/screenshots/doc-generate.png)
 
 ### 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.                                     |
+| Option              | Type    | Description                                                                                              |
+| :------------------ | :------ | :------------------------------------------------------------------------------------------------------- |
+| `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch.                                |
+| `--feedback`        | string  | Provides feedback to adjust and refine the overall documentation structure.                              |
 | `--model`           | string  | Specifies a particular large language model to use for generation (e.g., `openai:gpt-4o`). Overrides the default. |
 
 ### Usage Examples
@@ -93,16 +155,16 @@ aigne doc generate
 aigne doc generate --forceRegenerate
 ```
 
-**Refine the document structure with feedback:**
+**Refine the documentation 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:**
+**Generate using a specific model:**
 
 ```bash
-aigne doc generate --model google:gemini-1.5-flash
+aigne doc generate --model openai:gpt-4o
 ```
 
 ---
@@ -111,12 +173,14 @@ aigne doc generate --model google:gemini-1.5-flash
 
 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.
 
+![Screenshot of the update command running.](../assets/screenshots/doc-update.png)
+
 ### Options
 
-| 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).              |
+| Option     | Type  | Description                                                                 |
+| :--------- | :---- | :-------------------------------------------------------------------------- |
+| `--docs`     | array | A list of document paths to regenerate. Can be specified multiple times.    |
+| `--feedback` | string  | Provides specific feedback to improve the content of the selected document(s). |
 
 ### Usage Examples
 
@@ -129,7 +193,7 @@ aigne doc update
 **Update a specific document with targeted feedback:**
 
 ```bash
-aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
+aigne doc update --docs /overview --feedback "Add more detailed FAQ entries"
 ```
 
 ---
@@ -138,14 +202,16 @@ aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
 
 Translates existing documentation into one or more languages. It can be run interactively to select documents and languages, or non-interactively by specifying them as arguments.
 
+![Screenshot of the translate command running.](../assets/screenshots/doc-translate.png)
+
 ### 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`). 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 specified multiple times.              |
+| `--langs`    | array | A list of target language codes (e.g., `zh-CN`, `ja`). Can be specified 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
 
@@ -158,10 +224,10 @@ aigne doc translate
 **Translate specific documents into Chinese and Japanese:**
 
 ```bash
-aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
+aigne doc translate --langs zh-CN --langs ja --docs /features/generate-documentation --docs /overview
 ```
 
-**Translate with a glossary and feedback for better quality:**
+**Translate with a glossary and feedback for improved quality:**
 
 ```bash
 aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
@@ -171,12 +237,14 @@ aigne doc translate --glossary @glossary.md --feedback "Use technical terminolog
 
 ## `aigne doc publish`
 
-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.
+Publishes your documentation and generates a shareable link. This command uploads your content to a Discuss Kit instance. You can use the official AIGNE DocSmith platform or run your own instance of [Discuss Kit](https://www.web3kit.rocks/discuss-kit).
+
+![Screenshot of the publish command running.](../assets/screenshots/doc-publish.png)
 
 ### 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
@@ -195,16 +263,49 @@ aigne doc publish --appUrl https://your-discuss-kit-instance.com
 
 ---
 
-## `aigne doc init`
+## `aigne doc prefs`
 
-Manually starts the interactive configuration wizard. This is useful for setting up a new project or modifying the configuration of an existing one. The wizard guides you through defining source code paths, setting output directories, choosing languages, and defining the documentation's style and target audience.
+Manages user preferences and feedback-driven rules. Over time, DocSmith learns from your feedback and creates persistent preferences. This command allows you to view, toggle, or remove these learned rules.
 
-### Usage Example
+### Options
 
-**Launch the setup wizard:**
+| Option   | Type    | Description                                                                |
+| :------- | :------ | :------------------------------------------------------------------------- |
+| `--list`   | boolean | Lists all saved preferences.                                               |
+| `--remove` | boolean | Interactively prompts to select and remove one or more preferences.        |
+| `--toggle` | boolean | Interactively prompts to select and toggle the active state of preferences. |
+| `--id`     | array   | Specifies one or more preference IDs to remove or toggle directly.         |
+
+### Usage Examples
+
+**List all saved preferences:**
 
 ```bash
-aigne doc init
+aigne doc prefs --list
 ```
 
-For more details on how to tailor DocSmith to your needs, see the [Configuration Guide](./configuration.md).
+**Start interactive removal mode:**
+
+```bash
+aigne doc prefs --remove
+```
+
+**Toggle a specific preference by ID:**
+
+```bash
+aigne doc prefs --toggle --id "pref_2a1dfe2b09695aab"
+```
+
+---
+
+## `aigne doc clear`
+
+Launches an interactive session to clear locally stored data. This can be used to remove the generated documentation, the document structure configuration, or cached authentication tokens.
+
+### Usage Example
+
+**Start the interactive cleanup process:**
+
+```bash
+aigne doc clear
+```