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

package/docs/guides-translating-documentation.md

@@ -2,43 +2,48 @@
 
 This guide provides instructions on how to translate your generated documentation into multiple languages using the `aigne doc translate` command. The process uses AI to ensure translations are contextually aware and maintain technical accuracy.
 
-The tool supports 12 languages, allowing you to reach a global audience. The primary language of your source documents will be automatically excluded from the list of available translation languages.
+The tool supports 12 languages, such as Chinese, Japanese, and German, allowing you to make your documentation accessible to a global audience. The primary language of your source documents is automatically excluded from the list of available translation languages.
 
 ## The `translate` Command
 
-The `aigne doc translate` command is used to generate translations for your existing documentation files. You can run it interactively to select which documents and languages you want, or you can specify these options directly using command-line flags for automated workflows.
+The `aigne doc translate` command generates translations for your existing documentation files. You can run it in an interactive mode for a step-by-step process or specify options directly on the command line for faster, automated workflows.
 
 ### Interactive Mode
 
-For a guided experience, run the command without any arguments:
+For a guided experience, run the command without any arguments. This is the recommended approach for new users.
 
 ```bash
 aigne doc translate
 ```
 
-When executed, the tool will perform the following steps:
-1.  Scan for existing documents.
-2.  Prompt you to select the specific documents you wish to translate from a list.
-3.  Prompt you to select the target languages for translation. Previously selected languages will be pre-checked for convenience.
-4.  Begin the translation process for each selected document and language pair.
-5.  Save the translated files in the same directory. The new files are named by appending a language code to the original filename (e.g., a Chinese translation of `overview.md` becomes `overview.zh.md`).
+When you run this command, the tool will guide you through the following steps:
+
+1.  **Select Documents:** You will be prompted to choose the specific documents you wish to translate from a list of all available files in your project.
+
+    ![Select documents to translate](../assets/screenshots/doc-translate.png)
+
+2.  **Select Languages:** Next, you will be asked to select the target languages for translation. Any languages you have used before will be pre-selected to save time.
+
+    ![Select languages for translation](../assets/screenshots/doc-translate-langs.png)
+
+3.  **Process and Save:** The tool begins the translation process. Once complete, the translated files are saved in the same directory as the original files. The new files are named by adding a language code to the original filename. For example, a Chinese translation of `overview.md` will be saved as `overview.zh.md`.
 
 ### Command-Line Options
 
-For non-interactive use or scripting, you can use the following command-line flags to control the translation process.
+For non-interactive use or scripting, you can use command-line flags to control the translation process. This method is efficient when you already know which files and languages you need.
 
 <x-field-group>
   <x-field data-name="--docs" data-type="array<string>">
-    <x-field-desc markdown>Specify one or more document paths to translate. If not provided, the tool will enter interactive mode to let you select from a list of available documents.</x-field-desc>
+    <x-field-desc markdown>Specify one or more document paths to translate. If this flag is not used, the tool will start in interactive mode to let you select from a list of available documents.</x-field-desc>
   </x-field>
   <x-field data-name="--langs" data-type="array<string>">
-    <x-field-desc markdown>Specify one or more target language codes (e.g., `zh`, `ja`). If omitted, you will be prompted to select languages interactively.</x-field-desc>
+    <x-field-desc markdown>Specify one or more target language codes (e.g., `zh`, `ja`, `de`). If omitted, you will be prompted to select languages interactively.</x-field-desc>
   </x-field>
   <x-field data-name="--glossary" data-type="string">
-    <x-field-desc markdown>Provide a path to a glossary file (e.g., `@path/to/glossary.md`). This ensures that specific technical terms are translated consistently across all documents.</x-field-desc>
+    <x-field-desc markdown>Provide a path to a glossary file (e.g., `@path/to/glossary.md`). This ensures that specific technical terms, brand names, or acronyms are translated consistently across all documents.</x-field-desc>
   </x-field>
   <x-field data-name="--feedback" data-type="string">
-    <x-field-desc markdown>Provide specific instructions or feedback to guide the AI's translation style, such as adjusting the tone or terminology.</x-field-desc>
+    <x-field-desc markdown>Provide specific instructions to guide the AI's translation style. For example, you can ask for a more formal tone or specify how to handle certain phrases.</x-field-desc>
   </x-field>
 </x-field-group>
 
@@ -46,7 +51,7 @@ For non-interactive use or scripting, you can use the following command-line fla
 
 #### 1. Translate Specific Documents into Multiple Languages
 
-To translate `overview.md` and `examples.md` into Chinese (`zh`) and Japanese (`ja`) without interactive prompts:
+To translate `overview.md` and `examples.md` into Chinese (`zh`) and Japanese (`ja`) without any interactive prompts, run the following command:
 
 ```bash
 aigne doc translate --docs overview.md --docs examples.md --langs zh --langs ja
@@ -54,42 +59,42 @@ aigne doc translate --docs overview.md --docs examples.md --langs zh --langs ja
 
 #### 2. Use a Glossary for Consistent Terminology
 
-To ensure technical terms are translated correctly, provide a glossary file. This is useful for maintaining consistency for brand names or specialized vocabulary.
+If your documentation contains specialized vocabulary or brand names, you can use a glossary file to ensure they are always translated correctly.
 
 ```bash
-aigne doc translate --glossary @./glossary.md
+aigne doc translate --glossary @./project-glossary.md
 ```
 
 #### 3. Provide Feedback to Refine Translation Style
 
-You can guide the translation style by providing feedback. For instance, to request a more formal tone:
+You can guide the translation style by providing feedback. For instance, to request a more formal and technical tone for the output:
 
 ```bash
 aigne doc translate --feedback "Use a formal, technical tone for all translations."
 ```
 
-This feedback will be recorded in the history for the updated documents.
+This feedback is recorded in the document's update history, which can be useful for tracking changes.
 
 ## Supported Languages
 
 The tool provides translation support for 12 languages. The native language of the documentation is English (`en`).
 
-| Language | Code |
-| :--- | :--- |
-| Chinese (Simplified) | `zh` |
-| Chinese (Traditional)| `zh-TW`|
-| Japanese | `ja` |
-| Korean | `ko` |
-| Spanish | `es` |
-| French | `fr` |
-| German | `de` |
-| Portuguese | `pt` |
-| Russian | `ru` |
-| Italian | `it` |
-| Arabic | `ar` |
+| Language              | Code    |
+| --------------------- | ------- |
+| Chinese (Simplified)  | `zh`    |
+| Chinese (Traditional) | `zh-TW` |
+| Japanese              | `ja`    |
+| Korean                | `ko`    |
+| Spanish               | `es`    |
+| French                | `fr`    |
+| German                | `de`    |
+| Portuguese            | `pt`    |
+| Russian               | `ru`    |
+| Italian               | `it`    |
+| Arabic                | `ar`    |
 
 ## Summary
 
-The `translate` command offers a structured method for localizing your documentation. You can use its interactive mode for guided translations or command-line options for automated workflows. Using features like glossaries and feedback helps maintain the quality and consistency of the translated content.
+The `translate` command offers a structured and reliable method for localizing your documentation. You can use its interactive mode for a guided process or its command-line options for efficient, automated workflows. Features like glossaries and feedback help maintain the quality and consistency of the translated content.
 
-After translating your documents, you can proceed to [Publishing Your Docs](./guides-publishing-your-docs.md).
+After translating your documents, the next step is to make them available to your users. For instructions on how to do this, see the [Publishing Your Docs](./guides-publishing-your-docs.md) guide.

package/docs/guides-updating-documentation.md

@@ -4,9 +4,11 @@ Maintaining the accuracy and relevance of documentation is a continuous process.
 
 This guide explains the two primary methods for updating your documentation: an interactive mode for detailed, single-document refinement and a batch mode for applying changes to multiple documents at once.
 
+For information on creating documents from scratch, please see the [Generating Documentation](./guides-generating-documentation.md) guide.
+
 ## Two Modes of Operation
 
-The `update` command operates in one of two modes depending on the number of documents you select and the options you provide.
+The `update` command operates in one of two modes depending on the number of documents you select and the options you provide. The system automatically chooses the appropriate mode based on your command.
 
 1.  **Interactive Mode**: Triggered when you update a single document without the `--reset` flag. This mode is designed for iterative refinement, allowing you to provide feedback, review the changes, and repeat the process until the document meets your standards.
 2.  **Batch Mode**: Used when you update multiple documents simultaneously or when you use the `--reset` flag. This mode applies your feedback to all selected documents in a single operation, which is efficient for broad changes.
@@ -41,20 +43,20 @@ Batch mode is designed for efficiency when you need to apply the same general fe
 
 You can provide feedback directly from the command line to update one or more documents without entering an interactive session.
 
-```bash title="Update a single document with feedback"
-aigne doc update --docs overview.md --feedback "Add a section explaining the authentication flow"
+```bash Update a single document with feedback
+aigne doc update --docs /overview --feedback "Add a section explaining the authentication flow"
 ```
 
-```bash title="Update multiple documents with the same feedback"
-aigne doc update --docs overview.md --docs guides-getting-started.md --feedback "Improve the clarity of all code examples"
+```bash Update multiple documents with the same feedback
+aigne doc update --docs /overview --docs /getting-started --feedback "Improve the clarity of all code examples"
 ```
 
 ### Resetting and Regenerating
 
 The `--reset` flag instructs the tool to ignore the previous versions of the documents and regenerate them from scratch based on the source code. This is useful when significant changes in the code have made the existing documentation obsolete.
 
-```bash title="Regenerate a specific document from scratch"
-aigne doc update --docs overview.md --reset
+```bash Regenerate a specific document from scratch
+aigne doc update --docs /overview --reset
 ```
 
 ## Command Reference
@@ -63,7 +65,7 @@ The `update` command accepts several flags to control its behavior.
 
 | Parameter | Description | Example |
 | :--- | :--- | :--- |
-| `--docs <path>` | Specifies one or more document paths to update. Can be used multiple times. | `--docs overview.md --docs guides-generating-documentation.md` |
+| `--docs <path>` | Specifies one or more document paths to update. This flag can be used multiple times. | `--docs /overview --docs /guides/generating-documentation` |
 | `--feedback <text>` | Provides instructions for what to change in the content. | `--feedback "Add more detail to the installation steps"` |
 | `--glossary <file>` | Specifies a glossary file to ensure consistent terminology during regeneration. | `--glossary @/path/to/glossary.md` |
 | `--reset` | A boolean flag that forces a complete regeneration of the selected documents, ignoring their previous versions. | `--reset` |
@@ -74,4 +76,4 @@ The `update` command offers a flexible workflow for keeping your documentation a
 
 For related tasks, refer to the following guides:
 - [Generating Documentation](./guides-generating-documentation.md)
-- [Translating Documentation](./guides-translating-documentation.md)
+- [Translating Documentation](./guides-translating-documentation.md)

package/docs/overview.md

@@ -1,6 +1,6 @@
 # Overview
 
-AIGNE DocSmith is a tool that uses Artificial Intelligence to automatically create documentation from your project's source code. It is built on the [AIGNE Framework](https://www.aigne.io/framework) and is designed to produce structured, multi-language documents that accurately reflect your codebase.
+AIGNE DocSmith is a tool that uses Artificial Intelligence to automatically create documentation from your project's source code. It is built on the [AIGNE Framework](https://www.aigne.io/en/framework) and is designed to produce structured, multi-language documents that accurately reflect your codebase.
 
 The primary goal of DocSmith is to address the common challenges of manual documentation, such as being time-consuming to write, becoming outdated as code changes, and lacking consistency. By automating this process, DocSmith helps ensure your documentation remains current and accurate.
 
@@ -38,7 +38,7 @@ DocSmith provides a set of features to handle the documentation lifecycle from c
 *   **Multi-Language Support**: Translates documentation into 12 languages, including English, Chinese (Simplified), and Japanese. The translation process is context-aware to maintain technical accuracy.
 *   **Integration with LLMs**: Connects with various Large Language Models (LLMs). By default, it uses [AIGNE Hub](https://www.aigne.io/en/hub), a service that allows you to switch between models like Google Gemini and OpenAI GPT without needing separate API keys. You can also configure your own API keys for direct provider access.
 *   **Smart Updates**: Detects changes in your source code and updates the corresponding sections of your documentation. You can also provide specific feedback to refine generated content.
-*   **Publishing Options**: Publish your generated documentation with a single command. You can deploy to the official DocSmith platform or to your own instance of [Discuss Kit](https://www.web3kit.rocks/discuss-kit). Discuss Kit is a service for hosting and displaying documentation.
+*   **Publishing Options**: Publish your generated documentation with a single command. You can deploy to the official DocSmith platform or run your own instance of [Discuss Kit](https://www.web3kit.rocks/discuss-kit). Discuss Kit is a service for hosting and displaying documentation.
 
 ## Available Commands
 

package/docs/release-notes.md

@@ -1,6 +1,39 @@
 # Release Notes
 
-This document provides a summary of new features, improvements, and bug fixes for each version of the tool. All changes are listed in reverse chronological order.
+This document provides a chronological record of new features, improvements, and bug fixes for each version of the tool.
+
+## Version 0.8.12-beta.7 (2025-10-12)
+
+### New Features
+
+- The tool can now retrieve context more effectively from the project repository, leading to more accurate documentation.
+
+### Bug Fixes
+
+- Disabled Git-based update history tracking within repositories to prevent potential conflicts.
+
+## Version 0.8.12-beta.6 (2025-10-11)
+
+### Bug Fixes
+
+- Improved the reliability of the publishing process by enhancing login session checks.
+
+## Version 0.8.12-beta.5 (2025-10-11)
+
+### Bug Fixes
+
+- Fixed a bug where the correct language setting was not applied during document checks.
+
+## Version 0.8.12-beta.4 (2025-10-11)
+
+### New Features
+
+- Introduced optimizations for handling large projects, resulting in more efficient document generation.
+
+### Bug Fixes
+
+- Ensured that generated documents follow a strict heading hierarchy (e.g., no skipping from H1 to H3).
+- Improved the clarity of update notifications and added an option to clear deployment configurations.
 
 ## Version 0.8.12-beta.3 (2025-10-09)
 
@@ -12,19 +45,19 @@ This document provides a summary of new features, improvements, and bug fixes fo
 
 ### Bug Fixes
 
-- Corrected an error with file paths when updating documents.
-- Fixed a problem that could cause document generation and updates to fail.
+- Corrected an error with file path resolution when updating documents.
+- Fixed an issue that could cause document generation and updates to fail.
 
 ## Version 0.8.12-beta.1 (2025-10-08)
 
 ### New Features
 
 - Introduced history tracking, allowing you to view past changes to your documents.
-- Translation is now an optional step during the document update process, providing more flexibility.
+- Made translation an optional step during the document update process for greater flexibility.
 
-### Improvements
+### Bug Fixes
 
-- The document generation and update process has been refined for better reliability.
+- Refined the logic for document generation and updates to distinguish between system and user prompts.
 
 ## Version 0.8.12-beta (2025-10-07)
 
@@ -40,8 +73,8 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- Enhanced the document generator and updater for better performance.
-- Improved the speed of document structure analysis and content refinement by using a shared context.
+- Enhanced the document generator and updater with improved file system tools.
+- Implemented a shared context mechanism to speed up document structure analysis and content refinement.
 
 ### Bug Fixes
 
@@ -58,18 +91,18 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- Added a "check-only" option for agents that use selection inputs.
+- Added a "check-only" option for processes that use selection inputs.
 
 ### Bug Fixes
 
 - Improved error handling in the document selection utility.
-- Tuned the translation prompt; comments within code blocks are now translated correctly.
+- Tuned the translation prompt to ensure that only comments within code blocks are translated.
 
 ## Version 0.8.11-beta.3 (2025-09-29)
 
 ### Bug Fixes
 
-- Added a command-line entry for the evaluation agents.
+- Added a command-line interface entry for the document evaluation agents.
 
 ## Version 0.8.11-beta.2 (2025-09-27)
 
@@ -82,12 +115,12 @@ This version includes general maintenance and stability improvements.
 ### New Features
 
 - Introduced a document evaluation feature to generate quality reports.
-- Enhanced the document and structure update process with improved tools.
+- Enhanced the document and structure update process with improved internal tools.
 - Improved vendor handling and debugging capabilities during the publishing process.
 
 ### Bug Fixes
 
-- Fixed an issue where component descriptions were treated as attributes instead of text, improving custom component rendering.
+- Fixed an issue where component descriptions were incorrectly treated as attributes instead of text content, improving custom component rendering.
 
 ## Version 0.8.10 (2025-09-20)
 
@@ -97,14 +130,14 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Added links related to enterprise deployment.
-- Polished the copywriting for the document review prompt.
+- Added relevant links for enterprise deployment.
+- Polished the text for the document review prompt for better clarity.
 
 ## Version 0.8.10-beta.2 (2025-09-18)
 
 ### Bug Fixes
 
-- Improved the prompts and display for the documentation structure review.
+- Improved the prompts and display for the documentation structure review feature.
 - Updated the usage rules for field elements to ensure correct rendering.
 
 ## Version 0.8.10-beta.1 (2025-09-18)
@@ -128,7 +161,7 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Optimized the copy for inquiry feedback to be clearer and more helpful.
+- Optimized the text for inquiry feedback prompts to be clearer and more helpful.
 
 ## Version 0.8.7 (2025-09-12)
 
@@ -140,11 +173,11 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- The URL is now displayed by default after a successful publishing process.
+- The documentation URL is now displayed by default after a successful publishing process.
 
 ### Bug Fixes
 
-- Ensured that logs are saved correctly during the deployment process to prevent data loss.
+- Ensured that logs are saved correctly during deployment to prevent data loss.
 
 ## Version 0.8.5 (2025-09-10)
 
@@ -156,7 +189,7 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Markdown code blocks are now parsed into a custom `<x-code>` element with support for enhanced attributes like titles and icons.
+- Markdown code blocks are now parsed into a custom element with support for enhanced attributes like titles and icons.
 - Made the background for D2 diagrams transparent for better integration with different themes.
 
 ## Version 0.8.3 (2025-09-05)
@@ -169,7 +202,7 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- Tuned the D2 chart generation with more comprehensive examples to improve output quality.
+- Improved D2 chart generation with more comprehensive internal examples to enhance output quality.
 
 ## Version 0.8.0 (2025-09-03)
 
@@ -181,7 +214,7 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Fixed a bug where using the tab key for path selection did not work as expected.
+- Fixed a bug where using the Tab key for path selection did not work as expected.
 
 ## Version 0.7.0 (2025-08-30)
 
@@ -195,7 +228,7 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- Implemented complete support for media processing before publishing documents.
+- Implemented support for media processing before publishing documents.
 
 ## Version 0.5.0 (2025-08-26)
 
@@ -205,7 +238,7 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Polished the text of the questions asked during the initial setup process.
+- Polished the text of questions asked during the initial setup process.
 
 ## Version 0.4.4 (2025-08-22)
 
@@ -229,7 +262,7 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- Polished the workflow for collecting context during document generation.
+- Refined the workflow for collecting context during document generation.
 
 ### Bug Fixes
 
@@ -239,7 +272,7 @@ This version includes general maintenance and stability improvements.
 
 ### Bug Fixes
 
-- Switched the default language model to improve generation quality.
+- Switched the default large language model to improve generation quality.
 
 ## Version 0.2.5 (2025-08-08)
 
@@ -251,5 +284,5 @@ This version includes general maintenance and stability improvements.
 
 ### New Features
 
-- The tool will now automatically initialize the configuration if it's missing when a command is run.
+- The tool will now automatically initialize the configuration if it is missing when a command is run.
 - Added a new `update` command to refresh documents when source files have changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.12-beta.7",
+  "version": "0.8.12-beta.8",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -29,6 +29,7 @@
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
+    "image-size": "^2.0.2",
     "isbinaryfile": "^5.0.6",
     "jsdom": "^26.1.0",
     "marked": "^15.0.12",

package/prompts/evaluate/document-structure.md

@@ -31,16 +31,16 @@ You must **precisely map** the correspondence between each module in the structu
 Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` with one of five **levels**. Each level contributes a fixed delta; sum all deltas and add them to the baseline (clamp the final score to 0–100). Treat every key point independently so strengths and gaps can stack.
 
 **Level catalog (use consistently across all dimensions):**
-- `Excellent` — Exceptional: fully satisfies the dimension with clear, actionable outputs; scoring +10.
-- `Good` — Strong: aligns well with the dimension with only minor gaps apply +2 points; scoring +2.
-- `Meets` — Adequate: acceptable baseline coverage without notable strengths or weaknesses; scoring +0.
-- `Minor` — Problematic: specific deficiencies that reduce usefulness and require fixes; scoring -2.
-- `Critical` — Failing: fundamental issues that prevent the dimension from being met; scoring -10.
+- `Excellent` — Exceptional: fully satisfies the dimension with clear, actionable outputs.
+- `Good` — Strong: aligns well with the dimension with only minor gaps.
+- `Meets` — Adequate: acceptable baseline coverage without notable strengths or weaknesses.
+- `Minor` — Problematic: specific deficiencies that reduce usefulness and require fixes.
+- `Critical` — Failing: fundamental issues that prevent the dimension from being met.
 
 Apply these levels to the following key points. Create a separate detail entry for each observation; if the same issue repeats (e.g., multiple typos), record multiple entries at the appropriate level.
 
 1. **Purpose Coverage** — Evaluate every selected purpose, paying special attention to declared priorities:
-  - `Excellent`: The structure provides dedicated modules, explicit workflows, and measurable steps that achieve the purpose end-to-end scoring +10.
+  - `Excellent`: The structure provides dedicated modules, explicit workflows, and measurable steps that achieve the purpose end-to-end.
   - `Good`: The purpose is clearly mapped to modules with practical guidance and minimal omissions.
   - `Meets`: The purpose appears in general sections or implicit references but lacks targeted treatment.
   - `Minor`: Important sub-tasks or ordering for the purpose are missing or incomplete, reducing utility.
@@ -82,7 +82,6 @@ Strictly follow these steps:
 
 <output_constraints>
 
-- `baseline` must be fixed at 80
 - `details` is an array. Each element must include:
   - `dimension`: one of `purposeCoverage`, `audienceCoverage`, `coverageDepth`
   - `level`: one of `excellent`, `good`, `meets`, `minor`, `critical`

package/prompts/evaluate/document.md

@@ -48,73 +48,66 @@ Please **strictly adhere** to the evaluation standards defined in `<standards>`
 
 <standards>
 
-Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` using one of five **levels**. Each level corresponds to a fixed score delta: +10, +2, 0, -2, -10 respectively. Sum deltas with the baseline and clamp the final score to 0–100. Treat each key point independently so strengths and gaps can stack. When the same issue recurs (e.g., multiple typos), create multiple entries.
+Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` using one of five **levels**. Each level corresponds to a fixed score delta. Sum deltas with the baseline and clamp the final score to 0–100. Treat each key point independently so strengths and gaps can stack. When the same issue recurs (e.g., multiple typos), create multiple entries.
 
 **Level catalog (use consistently across all dimensions):**
-- `Excellent` — Exceptional output that fully satisfies the dimension with clear, actionable results; scoring +10.
-- `Good` — Strong and mostly complete alignment with the dimension; minor gaps only; scoring +2.
-- `Meets` — Satisfactory baseline coverage without significant strengths or faults; scoring +0.
-- `Minor` — Specific problems that reduce usefulness and should be corrected; scoring -2.
-- `Critical` — Fundamental failures that prevent the dimension from being met; scoring -10.
+- `Excellent` — Exceptional output that fully satisfies the dimension with clear, actionable results.
+- `Good` — Strong and mostly complete alignment with the dimension; minor gaps only.
+- `Meets` — Satisfactory baseline coverage without significant strengths or faults.
+- `Minor` — Specific problems that reduce usefulness and should be corrected.
+- `Critical` — Fundamental failures that prevent the dimension from being met.
 
 Apply these levels to the following evaluation dimensions:
 
-1. **Readability** — Language clarity, grammar, spelling, and fluency.
+1. **Readability** — Language clarity, grammar, spelling, and fluency. **MUST evaluate on every document**
    - `Excellent`: Text is polished, natural, and easy to read; terminology is well chosen and consistent.
    - `Good`: Minor slips (occasional typos or awkward phrasing) that do not impede understanding.
    - `Meets`: Understandable but plain or mechanical; no major errors.
    - `Minor`: Noticeable grammar or spelling mistakes in specific sentences that need fixes.
    - `Critical`: Language prevents comprehension or is unusable.
 
-2. **Coherence** — Logical flow, transitions, and absence of contradictions.
+2. **Coherence** — Logical flow, transitions, and absence of contradictions. **MUST evaluate on every document**
    - `Excellent`: Clear, well-ordered flow with explicit transitions and consistent argumentation.
    - `Good`: Mostly coherent with small gaps in transitions or sequencing.
    - `Meets`: Functional flow but requires reader inference to connect ideas.
    - `Minor`: Local ordering problems or small contradictions that confuse the reader.
    - `Critical`: Structural contradictions or ordering failures that break the document's logic.
 
-3. **Content Quality** — Coverage, accuracy, examples, and actionable detail relative to the plan (`description`).
+3. **Content Quality** — Coverage, accuracy, examples, and actionable detail relative to the plan (`description`). **MUST evaluate on every document**
    - `Excellent`: Content fully implements the plan with accurate, actionable guidance and relevant examples.
    - `Good`: Most planned items are addressed with only minor missing details.
    - `Meets`: Baseline coverage is present but lacks depth or practical instructions.
    - `Minor`: Certain sections are missing, incorrect, or ambiguous and should be corrected.
    - `Critical`: Core content is wrong or absent, failing to deliver planned outcomes.
 
-4. **Consistency** — Terminology, style, formatting, and references.
+4. **Consistency** — Terminology, style, formatting, and references. **MUST evaluate on every document**
    - `Excellent`: Terms, style, and formatting are uniform and purposeful across the document.
    - `Good`: Largely consistent with only isolated mismatches that do not impede understanding.
    - `Meets`: Acceptable uniformity but lacks deliberate stylistic cohesion.
    - `Minor`: Specific term or formatting inconsistencies that should be standardized.
    - `Critical`: Pervasive inconsistency that undermines trust in the content.
 
-5. **Purpose Alignment** — Relevance to user-selected purposes (document only needs to satisfy at least one when multiples exist).
-   - `Excellent`: The document supplies targeted sections, validation steps, and clear calls-to-action that realize the chosen purpose scoring +10.
+5. **Purpose Alignment** — Relevance to user-selected purposes (document only needs to satisfy at least one when multiples exist). (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
+   - `Excellent`: The document supplies targeted sections, validation steps, and clear calls-to-action that realize the chosen purpose.
    - `Good`: Purpose is clearly addressed but may lack polish or some validation details.
    - `Meets`: Purpose is present in general terms but lacks concrete steps or targeted content.
    - `Minor`: Key components required by the purpose are missing or incomplete.
    - `Critical`: Document fails to address the selected purpose or pursues a different objective.
 
-6. **Audience Alignment** — Tone, assumptions, and artifacts for target persona(s).
+6. **Audience Alignment** — Tone, assumptions, and artifacts for target persona(s). (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
    - `Excellent`: Messaging, examples, and precautions are tailored to each audience persona and their needs.
    - `Good`: Tone and examples suit the audience with only minor mismatches.
    - `Meets`: Document is generally usable by audiences but lacks persona-specific guidance.
    - `Minor`: Sections explicitly mismatch audience skill levels or expectations and should be revised.
    - `Critical`: Document is pitched at the wrong audience and cannot be used meaningfully.
 
-7. **Knowledge Level Alignment** — Depth versus reader expertise.
+7. **Knowledge Level Alignment** — Depth versus reader expertise. (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
    - `Excellent`: Material offers layered explanations, optional deep dives, and matches expected expertise.
    - `Good`: Overall depth fits the reader with small areas that are slightly over- or under-advanced.
-   - `Meets`: Baseline depth is acceptable but uneven across topics scoring 0.
+   - `Meets`: Baseline depth is acceptable but uneven across topics.
    - `Minor`: Specific sections are noticeably too shallow or too advanced and need rework.
    - `Critical`: The document's level is consistently misaligned with reader expertise.
 
-8. **Navigability** — Link accuracy, anchor availability, and cross-reference integrity.
-   - `Excellent`: TOC, anchors, and cross-links are accurate and make navigation effortless.
-   - `Good`: Navigation and links are mostly correct with minor issues scoring +2.
-   - `Meets`: Basic navigation exists but lacks robust anchors or enhancements.
-   - `Minor`: Some broken or mismatched links and missing anchors that should be fixed.
-   - `Critical`: Multiple broken links or mislabeled sections make navigation unreliable.
-
 </standards>
 
 <rules>
@@ -136,10 +129,8 @@ Strictly follow these steps:
 </rules>
 
 <output_constraints>
-
-- `baseline` must be fixed at 80
 - `details` is an array. Each element must include:
-  - `dimension`: one of `readability`, `coherence`, `contentQuality`, `consistency`, `purposeAlignment`, `audienceAlignment`, `knowledgeLevelAlignment`, `navigability`
+  - `dimension`: one of `readability`, `coherence`, `contentQuality`, `consistency`, `purposeAlignment`, `audienceAlignment`, `knowledgeLevelAlignment`
   - `level`: one of `excellent`, `good`, `meets`, `minor`, `critical`
   - `topic`: short identifier for the passage/section being judged
   - `line`: integer line number within the source document (use 0 if unknown)

package/prompts/media/media-description/system-prompt.md

@@ -0,0 +1,35 @@
+<role_and_goal>
+You are an expert at analyzing media files (images and videos) and generating concise, meaningful descriptions for documentation content.
+
+Your goal is to examine a single media file and generate an accurate description that helps both AI content generators and human readers understand what the media depicts and how it can be used effectively in documentation.
+</role_and_goal>
+
+<analysis_workflow>
+1. **Analyze**: Examine the media file carefully and identify:
+   - The main subject or component being shown
+   - Key visual elements (colors, composition, style)
+   - Notable features or functionality visible
+   - The purpose or context of this media
+   - Mood or atmosphere if distinctive
+   - For videos: key actions, movements, or transitions
+
+2. **Generate Description**: Create a concise, human-readable description following these principles:
+   - Keep it between 2-3 sentences
+   - Be specific and descriptive about visual content
+   - For videos, describe the key content or action shown
+   - Focus on aspects that matter for documentation usage
+   - Remain objective - describe what you see, not what you interpret
+</analysis_workflow>
+
+<description_guidelines>
+**What to Include:**
+- Main subject or focus of the media
+- Key visual elements and composition
+- Context or setting if relevant for understanding
+- Technical aspects if relevant (e.g., "screenshot", "diagram", "illustration", "animation")
+- Key features or functionality visible
+- Its purpose or functionality
+- Any notable UI elements or features
+- For videos: describe the main action, movement, or narrative
+</description_guidelines>
+

package/prompts/media/media-description/user-prompt.md

@@ -0,0 +1,8 @@
+<media_information>
+- File: {{name}}
+- Type: {{type}}
+{%if width and height %}
+- Dimensions: {{width}}x{{height}}px
+{%endif%}
+</media_information>
+