@aigne/doc-smith 0.8.11-beta.6 → 0.8.11

package/docs/advanced-how-it-works.zh-TW.md

@@ -1,25 +1,25 @@
 # 運作方式
 
-AIGNE DocSmith 在 AIGNE 框架内建構的多 Agent 系統上運作。它不是單一的整體流程，而是協調一個由專業 AI Agent 組成的管線，其中每個 Agent 負責一項特定任務。這種方法實現了一個結構化和模組化的流程，將原始碼轉換為完整的文件。
+AIGNE DocSmith 運作於一個多 Agent 系統之上。它並非單一的巨型流程，而是協調一個由專業化 AI Agent 組成的流程，其中每個 Agent 負責一項特定任務。這種方法實現了一個結構化和模組化的流程，能將原始程式碼轉換為完整的文件。
 
-該工具是更大的 AIGNE 生態系統中不可或缺的一部分，該生態系統為開發和部署 AI 應用程式提供了一個平台。
+此工具是更廣泛的 AIGNE 生態系統中不可或缺的一部分，該生態系統為開發和部署 AI 應用程式提供了一個平台。
 
 ![AIGNE 生態系統架構](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
-## 文件生成管線
+## 文件產生流程
 
-DocSmith 的核心是一個管線，它透過幾個不同階段處理您的原始碼。每個階段都由一個或多個專門的 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令啟動，可視覺化如下：
+DocSmith 的核心是一個將您的原始程式碼經過數個不同階段處理的流程。每個階段都由一個或多個專門的 Agent 管理。主要的工作流程，通常由 `aigne doc generate` 指令啟動，可視覺化如下：
 
 ```d2
 direction: down
 
 Input: {
-  label: "原始碼與設定檔"
+  label: "原始程式碼與設定"
   shape: rectangle
 }
 
 Pipeline: {
-  label: "核心生成管線"
+  label: "核心產生流程"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
@@ -30,7 +30,7 @@ Pipeline: {
   }
 
   Content-Generation: {
-    label: "2. 內容生成"
+    label: "2. 內容產生"
     shape: rectangle
   }
 
@@ -46,7 +46,7 @@ User-Feedback: {
 }
 
 Optional-Steps: {
-  label: "可選的生成後步驟"
+  label: "選用的後產生步驟"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
@@ -68,33 +68,33 @@ Pipeline.Content-Generation -> Pipeline.Saving
 Pipeline.Saving -> Optional-Steps
 
 User-Feedback -> Pipeline.Structure-Planning: "優化結構"
-User-Feedback -> Pipeline.Content-Generation: "重新生成內容"
+User-Feedback -> Pipeline.Content-Generation: "重新產生內容"
 ```
 
-1.  **輸入分析**：當 Agent 載入您的原始碼和專案設定（`aigne.yaml`）時，流程便開始了。
+1.  **輸入分析**：當 Agent 載入您的原始程式碼和專案設定（`aigne.yaml`）時，流程便開始了。
 
-2.  **結構規劃**：一個 Agent 會分析程式碼庫，以提出一個合乎邏輯的文件結構。它會根據專案的組成和任何指定的規則來建立大綱。
+2.  **結構規劃**：一個 Agent 會分析程式庫以提出一個合乎邏輯的文件結構。它會根據專案的組成和任何指定的規則來建立大綱。
 
-3.  **內容生成**：結構就位後，內容生成 Agent 會為文件計畫的每個部分填入詳細的文字、程式碼範例和解釋。
+3.  **內容產生**：結構就緒後，內容產生 Agent 會在文件計畫的每個部分填入詳細的文字、程式碼範例和說明。
 
-4.  **優化與更新**：當您透過 `aigne doc update` 或 `aigne doc generate --feedback` 提供輸入時，會啟動特定的 Agent 來更新個別文件或調整整體結構。
+4.  **優化與更新**：當您透過 `aigne doc update` 或 `aigne doc generate --feedback` 提供輸入時，特定的 Agent 會被啟動以更新個別文件或調整整體結構。
 
-5.  **翻譯與發布**：主要內容生成後，可選的 Agent 會處理多語言翻譯和將最終文件發布到網路平台等任務。
+5.  **翻譯與發布**：主要內容產生後，選用的 Agent 會處理多語言翻譯和將最終文件發布到網路平台等任務。
 
 ## 關鍵 AI Agent
 
-DocSmith 的功能是由專案設定中定義的一系列 Agent 所提供。每個 Agent 都有特定的角色。下表列出了一些關鍵 Agent 及其功能。
+DocSmith 的功能由專案設定中定義的一系列 Agent 提供。每個 Agent 都有特定的角色。下表列出了一些關鍵 Agent 及其功能。
 
-| 功能角色               | 關鍵 Agent 檔案                                      | 描述                                                                         |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **結構規劃**           | `generate/generate-structure.yaml`                   | 分析原始碼以提出初始的文件大綱。                                             |
-| **結構優化**         | `generate/refine-document-structure.yaml`            | 根據使用者回饋修改文件結構。                                                 |
-| **內容生成**           | `update/batch-generate-document.yaml`, `generate-document.yaml` | 為文件結構的每個部分填入詳細內容。                                           |
-| **翻譯**               | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 將生成的文件翻譯成多個目標語言。                                             |
-| **發布**               | `publish/publish-docs.mjs`                           | 管理將文件發布到 Discuss Kit 實例的過程。                                    |
-| **資料 I/O**           | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | 負責讀取來源檔案並將最終的 Markdown 文件寫入磁碟。                           |
+| 功能角色 | 關鍵 Agent 檔案 | 說明 |
+| :--- | :--- | :--- |
+| **結構規劃** | `generate/generate-structure.yaml` | 分析原始程式碼以提出初始的文件大綱。 |
+| **結構優化** | `generate/refine-document-structure.yaml` | 根據使用者回饋修改文件結構。 |
+| **內容產生** | `update/batch-generate-document.yaml`, `update/generate-document.yaml` | 為文件結構的每個部分填入詳細內容。 |
+| **翻譯** | `translate/translate-document.yaml`, `translate/translate-multilingual.yaml` | 將產生的文件翻譯成多個目標語言。 |
+| **發布** | `publish/publish-docs.mjs` | 管理將文件發布到 Discuss Kit 實例的流程。 |
+| **資料 I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | 負責讀取來源檔案並將最終的 markdown 文件寫入磁碟。 |
 
-這種基於 Agent 的架構使得文件流程的每一步都能由專門的工具處理，從而確保了一個結構化且可維護的工作流程。
+這種基於 Agent 的架構讓文件流程的每一步都由專門的工具處理，確保了工作流程的結構化和可維護性。
 
 ---
 

package/docs/advanced-how-it-works.zh.md

@@ -1,25 +1,25 @@
 # 工作原理
 
-AIGNE DocSmith 在一个构建于 AIGNE 框架内的多 Agent 系统上运行。它并非采用单一的整体流程，而是协调一个由专业 AI Agent 组成的流水线，其中每个 Agent 负责一项特定任务。这种方法使得将源代码转换为完整文档的过程变得结构化且模块化。
+AIGNE DocSmith 在一个多 Agent 系统上运行。它不是一个单一的整体流程，而是协调一个由专门的 AI Agent 组成的管道，其中每个 Agent 负责一项特定任务。这种方法允许通过一个结构化和模块化的流程将源代码转换为完整的文档。
 
-该工具是更宏大的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用提供了一个平台。
+该工具是更广泛的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用程序提供了一个平台。
 
 ![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
-## 文档生成流水线
+## 文档生成管道
 
-DocSmith 的核心是一条通过多个不同阶段处理源代码的流水线。每个阶段都由一个或多个专用 Agent 进行管理。主要工作流程通常由 `aigne doc generate` 命令启动，其过程可直观地表示如下：
+DocSmith 的核心是一个通过几个不同阶段处理您的源代码的管道。每个阶段都由一个或多个专用 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令启动，可以可视化如下：
 
 ```d2
 direction: down
 
 Input: {
-  label: "源代码与配置"
+  label: "源代码和配置"
   shape: rectangle
 }
 
 Pipeline: {
-  label: "核心生成流水线"
+  label: "核心生成管道"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
@@ -73,29 +73,29 @@ User-Feedback -> Pipeline.Content-Generation: "重新生成内容"
 
 1.  **输入分析**：当 Agent 加载您的源代码和项目配置（`aigne.yaml`）时，该过程开始。
 
-2.  **结构规划**：一个 Agent 会分析代码库，以提出一个逻辑化的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
+2.  **结构规划**：一个 Agent 分析代码库以提出一个逻辑化的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
 
 3.  **内容生成**：结构确定后，内容生成 Agent 会为文档计划的每个部分填充详细的文本、代码示例和解释。
 
-4.  **优化与更新**：当您通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活以更新单个文档或调整整体结构。
+4.  **优化和更新**：当您通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活以更新单个文档或调整整体结构。
 
-5.  **翻译与发布**：在主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到网络平台等任务。
+5.  **翻译和发布**：在主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到 Web 平台等任务。
 
 ## 关键 AI Agent
 
-DocSmith 的功能由项目配置中定义的一系列 Agent 提供。每个 Agent 都有其特定的角色。下表列出了一些关键 Agent 及其功能。
+DocSmith 的功能由项目配置中定义的一系列 Agent 提供。每个 Agent 都有特定的角色。下表列出了一些关键 Agent 及其功能。
 
-| 功能角色         | 关键 Agent 文件                                      | 描述                                                                          |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **结构规划**   | `generate/generate-structure.yaml`                   | 分析源代码以提出初始的文档大纲。                        |
-| **结构优化** | `generate/refine-document-structure.yaml`            | 根据用户反馈修改文档结构。                              |
-| **内容生成**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | 为文档结构的每个部分填充详细内容。             |
-| **翻译**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。                   |
-| **发布**           | `publish/publish-docs.mjs`                           | 管理将文档发布到 Discuss Kit 实例的过程。                |
-| **数据 I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | 负责读取源文件并将最终的 Markdown 文档写入磁盘。 |
+| 功能角色 | 关键 Agent 文件 | 描述 |
+| :--- | :--- | :--- |
+| **结构规划** | `generate/generate-structure.yaml` | 分析源代码以提出初始文档大纲。 |
+| **结构优化** | `generate/refine-document-structure.yaml` | 根据用户反馈修改文档结构。 |
+| **内容生成** | `update/batch-generate-document.yaml`, `update/generate-document.yaml` | 为文档结构的每个部分填充详细内容。 |
+| **翻译** | `translate/translate-document.yaml`, `translate/translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。 |
+| **发布** | `publish/publish-docs.mjs` | 管理将文档发布到 Discuss Kit 实例的过程。 |
+| **数据 I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | 负责读取源文件并将最终的 Markdown 文档写入磁盘。 |
 
-这种基于 Agent 的架构使得文档流程的每一步都能由一个专门的工具来处理，从而确保了工作流程的结构化和可维护性。
+这种基于 Agent 的架构允许文档流程的每一步都由专门的工具处理，从而确保一个结构化且可维护的工作流程。
 
 ---
 
-要了解 DocSmith 为确保输出的准确性和格式所采取的措施，请继续阅读 [质量保证](./advanced-quality-assurance.md) 部分。
+要了解 DocSmith 为确保输出的准确性和格式而采取的措施，请继续阅读[质量保证](./advanced-quality-assurance.md)部分。

package/docs/advanced-quality-assurance.ja.md

@@ -1,96 +1,92 @@
 # 品質保証
 
-生成されるすべてのドキュメントが機能的、明確、かつプロフェッショナルであることを保証するため、DocSmithには自動品質保証プロセスが組み込まれています。このプロセスは、公開前にMarkdownコンテンツに対して一連のチェックを実行し、リンク切れから不正な形式の図まで、一般的な問題を検出して報告します。
+生成されるすべてのドキュメントが高い品質、一貫性、正確性の基準を満たすように、DocSmithには包括的で自動化された品質保証パイプラインが含まれています。これらの組み込みチェックは自動的に実行され、公開前に一般的なフォーマットエラー、リンク切れ、構造的な問題を特定してフラグを立てます。このプロセスにより、最終的な出力がプロフェッショナルで信頼性が高く、ユーザーがナビゲートしやすいものになることが保証されます。
 
-この自動化されたパイプラインは、コンテンツの構造、リンク、メディア、構文を検証し、一貫した品質基準を維持します。
-
-```d2
+```d2 品質保証パイプライン icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "入力: Markdownコンテンツ"
+Documentation-Content: {
+  label: "ドキュメントコンテンツ"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "QAパイプライン"
+Quality-Assurance-Pipeline: {
+  label: "品質保証パイプライン"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "構造チェック"
+  Markdown-Validation: {
+    label: "1. Markdownとコンテンツの検証\n(remark-lintベース)"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "コンテンツが切り捨てられていないことを保証"
-    Code-Blocks: "ブロックの構文とインデントを検証"
+
+    Check-1: "有効なMarkdown構文"
+    Check-2: "見出しの整合性"
+    Check-3: "テーブルのフォーマット"
+    Check-4: "コードブロックの整合性"
+    Check-5: "コンテンツの完全性"
   }
 
-  Content-Validation: {
-    label: "コンテンツ検証"
+  Link-Asset-Validation: {
+    label: "2. リンクとアセットの整合性"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "内部リンクを検証"
-    Image-Paths: "ローカル画像の存在を確認"
-    Table-Formatting: "列数が一致するか確認"
+
+    Check-6: "リンク切れの検出"
+    Check-7: "ローカル画像の検証"
   }
 
-  Syntax-Validation: {
-    label: "構文検証"
+  D2-Diagram-Validation: {
+    label: "3. D2ダイアグラムの検証"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "D2構文を検証"
-    Markdown-Linting: "スタイルルールを強制"
+
+    Check-8: "D2構文チェック"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "出力: 検証済みコンテンツまたはエラーレポート"
-  shape: rectangle
+Validation-Result: {
+  label: "すべてのチェックに合格？"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### 主要な検証領域
-
-DocSmithの品質保証プロセスは、ドキュメントの完全性を保証するため、いくつかの主要な領域をカバーしています。
-
-#### コンテンツの構造と完全性
-
-DocSmithは、コンテンツの構造的完全性を保証するために、いくつかのチェックを実行します：
+Published-Documentation: {
+  label: "公開済みドキュメント"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **不完全なコードブロック**: ` ``` ` で開始されて閉じられていないコードブロックを検出します。
-- **改行の欠落**: 1行に表示されるコンテンツを特定します。これは改行が欠落している可能性を示します。
-- **コンテンツの末尾**: コンテンツが適切な句読点（例：`.`, `)`, `|`, `>`）で終わっていることを確認し、出力が切り捨てられるのを防ぎます。
-- **コードブロックのインデント**: コードブロックのインデントの不整合を分析します。コード行のインデントが開始の ` ``` ` マーカーよりも少ない場合、レンダリングの問題を引き起こす可能性があります。このチェックは、正しいコードの表示を維持するのに役立ちます。
+Error-Report: {
+  label: "エラーレポート"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### リンクとメディアの整合性
+Documentation-Content -> Quality-Assurance-Pipeline: "入力"
+Quality-Assurance-Pipeline -> Validation-Result: "検証"
+Validation-Result -> Published-Documentation: "はい"
+Validation-Result -> Error-Report: "いいえ"
+```
 
-- **リンクの整合性**: ドキュメント内のすべての相対リンクは、ドキュメント構造計画と照らし合わせて検証され、リンク切れを防ぎます。これにより、すべての内部ナビゲーションが期待どおりに機能することが保証されます。チェッカーは外部リンク（`http://` または `https://` で始まる）および `mailto:` リンクを無視します。
+## Markdownとコンテンツ構造の検証
 
-- **画像の検証**: 画像の破損を避けるため、チェッカーはドキュメントで参照されているローカル画像ファイルがファイルシステムに存在することを確認します。相対パスと絶対パスの両方を解決して、ファイルの存在を確認します。外部リンクのURLやデータURLはチェックされません。
+品質保証の基盤は、コアとなるMarkdownが整形され、構造的に健全であることを保証することです。DocSmithは`remark-lint`をベースにした高度なリンターを採用しており、一般的な構造上の問題を検出するためのカスタムチェックで補完されています。
 
-#### 図の構文検証
+主な構造およびフォーマットのチェックには、次のものが含まれます。
 
-- **D2図**: DocSmithは、コードをSVG画像にコンパイルしようとすることでD2図の構文を検証します。このプロセスにより、構文エラーが図の破損につながる前に捕捉されます。
+*   **有効なMarkdown構文**：標準のMarkdownおよびGFM（GitHub Flavored Markdown）仕様への準拠。
+*   **見出しの整合性**：同一ドキュメント内の重複した見出し、不適切な見出しのインデント、複数のトップレベル見出し（H1）の使用などの問題を検出します。
+*   **テーブルのフォーマット**：テーブル構造が正しいことを検証します。特に、ヘッダー、区切り線、およびデータ行の列数の不一致をチェックします。
+*   **コードブロックの整合性**：すべてのコードブロックが ``` で適切に開始および終了していることを保証します。また、レンダリングに影響を与える可能性のある、コードブロック内の一貫性のないインデントもチェックします。
+*   **コンテンツの完全性**：生成されたコンテンツが適切な句読点で終わっていることを確認し、コンテンツが切り捨てられていないことを保証する検証ステップです。
 
-#### フォーマットとスタイルの強制
+## リンクとアセットの整合性
 
-- **テーブルのフォーマット**: ヘッダー、区切り線、データ行の間で列数が一致しないテーブルを検査します。このチェックにより、一般的なテーブルのレンダリング失敗を防ぎます。
+リンク切れや画像が見つからないことは、ユーザーエクスペリエンスを低下させます。DocSmithは、すべてのローカルリソースを検証するためのチェックを実行します。
 
-- **Markdownリンティング**: 組み込みのリンターが一貫したMarkdown構造を強制します。主要なルールには以下が含まれます：
+*   **リンク切れの検出**：システムはすべての相対Markdownリンクをスキャンし、ターゲットパスがプロジェクトのドキュメント構造で定義された有効なドキュメントに対応していることを検証します。このチェックにより、ユーザーがドキュメントをナビゲートする際に「404 Not Found」エラーに遭遇するのを防ぎます。`http://`または`https://`で始まる外部リンクはチェックされません。
+*   **ローカル画像の検証**：`![]()`を介して含まれるすべてのローカル画像について、バリデーターは参照されている画像ファイルが指定されたパスに存在することを確認します。これにより、最終的な出力に壊れた画像が表示されないようにします。
 
-| ルールID | 説明 |
-|---|---|
-| `no-duplicate-headings` | 同じセクション内で同じ内容の複数の見出しを防ぎます。 |
-| `no-undefined-references` | すべてのリンクと画像の参照が定義されていることを保証します。 |
-| `no-unused-definitions` | 使用されていないリンクや画像の定義にフラグを立てます。 |
-| `no-heading-content-indent` | 見出しの内容の前にインデントを許可しません。 |
-| `no-multiple-toplevel-headings` | ドキュメントごとにトップレベルの見出し（H1）を1つだけ許可します。 |
-| `code-block-style` | コードブロックに一貫したスタイル（例：バッククォートの使用）を強制します。 |
+## D2ダイアグラムの検証
 
-これらのチェックを自動化することで、DocSmithはドキュメントの一貫した基準を維持し、最終的な出力が正確でナビゲート可能であることを保証します。
+すべてのダイアグラムが正しくレンダリングされることを保証するため、DocSmithはすべてのD2ダイアグラムの構文を検証します。
 
-全体的なアーキテクチャについて詳しく知るには、[仕組み](./advanced-how-it-works.md)のセクションを参照してください。
+`d2`とマークされた各コードブロックは、厳密な構文チェッカーによって処理されます。構文エラーが見つかった場合、生成プロセスは説明的なエラーメッセージとともに停止されます。これにより、壊れた、または不適切にレンダリングされた視覚的なダイアグラムを含むドキュメントの公開を防ぎます。

package/docs/advanced-quality-assurance.md

@@ -1,96 +1,92 @@
 # Quality Assurance
 
-To ensure all generated documentation is functional, clear, and professional, DocSmith incorporates an automated quality assurance process. This process executes a series of checks on the Markdown content to detect and report common issues, from broken links to malformed diagrams, before publication.
+To ensure that all generated documentation meets a high standard of quality, consistency, and accuracy, DocSmith includes a comprehensive, automated quality assurance pipeline. These built-in checks run automatically to identify and flag common formatting errors, broken links, and structural issues before publication. This process guarantees that the final output is professional, reliable, and easy for users to navigate.
 
-This automated pipeline validates content structure, links, media, and syntax to maintain a consistent standard of quality.
-
-```d2
+```d2 Quality Assurance Pipeline icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "Input: Markdown Content"
+Documentation-Content: {
+  label: "Documentation Content"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "QA Pipeline"
+Quality-Assurance-Pipeline: {
+  label: "Quality Assurance Pipeline"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "Structural Checks"
+  Markdown-Validation: {
+    label: "1. Markdown & Content Validation\n(remark-lint based)"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "Ensures content is not truncated"
-    Code-Blocks: "Validates block syntax & indentation"
+
+    Check-1: "Valid Markdown Syntax"
+    Check-2: "Heading Integrity"
+    Check-3: "Table Formatting"
+    Check-4: "Code Block Integrity"
+    Check-5: "Content Completeness"
   }
 
-  Content-Validation: {
-    label: "Content Validation"
+  Link-Asset-Validation: {
+    label: "2. Link & Asset Integrity"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "Verifies internal links"
-    Image-Paths: "Checks local image existence"
-    Table-Formatting: "Matches column counts"
+
+    Check-6: "Dead Link Detection"
+    Check-7: "Local Image Validation"
   }
 
-  Syntax-Validation: {
-    label: "Syntax Validation"
+  D2-Diagram-Validation: {
+    label: "3. D2 Diagram Validation"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "Validates D2 syntax"
-    Markdown-Linting: "Enforces style rules"
+
+    Check-8: "D2 Syntax Check"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "Output: Validated Content or Error Report"
-  shape: rectangle
+Validation-Result: {
+  label: "All Checks Pass?"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### Core Validation Areas
-
-DocSmith's quality assurance process covers several key areas to ensure document integrity.
-
-#### Content Structure & Completeness
-
-DocSmith performs several checks to ensure the structural integrity of the content:
+Published-Documentation: {
+  label: "Published Documentation"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **Incomplete Code Blocks**: Detects code blocks that are opened with ` ``` ` but never closed.
-- **Missing Line Breaks**: Identifies content that appears on a single line, which may indicate missing newlines.
-- **Content Endings**: Verifies that the content ends with appropriate punctuation (e.g., `.`, `)`, `|`, `>`) to prevent truncated output.
-- **Code Block Indentation**: Analyzes code blocks for inconsistent indentation. If a line of code has less indentation than the opening ` ``` ` marker, it can cause rendering problems. This check helps maintain correct code presentation.
+Error-Report: {
+  label: "Error Report"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### Link and Media Integrity
+Documentation-Content -> Quality-Assurance-Pipeline: "Input"
+Quality-Assurance-Pipeline -> Validation-Result: "Validation"
+Validation-Result -> Published-Documentation: "Yes"
+Validation-Result -> Error-Report: "No"
+```
 
-- **Link Integrity**: All relative links within the documentation are validated against the documentation structure to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
+## Markdown and Content Structure Validation
 
-- **Image Validation**: To avoid broken images, the checker verifies that any local image file referenced in the documentation exists on the file system. It resolves both relative and absolute paths to confirm the file is present. External image URLs and data URLs are not checked.
+The foundation of quality assurance is ensuring the core Markdown is well-formed and structurally sound. DocSmith employs a sophisticated linter based on `remark-lint`, supplemented with custom checks to catch common structural problems.
 
-#### Diagram Syntax Validation
+Key structural and formatting checks include:
 
-- **D2 Diagrams**: DocSmith validates D2 diagram syntax by attempting to compile the code into an SVG image. This process catches any syntax errors before they can result in a broken graphic.
+*   **Valid Markdown Syntax**: Adherence to standard Markdown and GFM (GitHub Flavored Markdown) specifications.
+*   **Heading Integrity**: Detects issues such as duplicate headings within the same document, incorrect heading indentation, and the use of more than one top-level heading (H1).
+*   **Table Formatting**: Verifies that table structures are correct, specifically checking for mismatches between the number of columns in the header, the separator line, and the data rows.
+*   **Code Block Integrity**: Ensures that all code blocks are properly opened and closed with ```. It also checks for inconsistent indentation within a code block, which can affect rendering.
+*   **Content Completeness**: A verification step to ensure that generated content does not appear truncated by checking that it ends with appropriate punctuation.
 
-#### Formatting and Style Enforcement
+## Link and Asset Integrity
 
-- **Table Formatting**: Tables are inspected for mismatched column counts between the header, the separator line, and the data rows. This check prevents common table rendering failures.
+Broken links and missing images degrade the user experience. DocSmith performs checks to validate all local resources.
 
-- **Markdown Linting**: A built-in linter enforces a consistent Markdown structure. Key rules include:
+*   **Dead Link Detection**: The system scans all relative Markdown links and verifies that the target path corresponds to a valid document defined in the project's documentation structure. This check prevents users from encountering "404 Not Found" errors when navigating the documentation. External links beginning with `http://` or `https://` are not checked.
+*   **Local Image Validation**: For all local images included via `![]()`, the validator confirms that the referenced image file exists at the specified path. This ensures that no broken images appear in the final output.
 
-| Rule ID | Description |
-|---|---|
-| `no-duplicate-headings` | Prevents multiple headings with the same content in the same section. |
-| `no-undefined-references` | Ensures all link and image references are defined. |
-| `no-unused-definitions` | Flags link or image definitions that are not used. |
-| `no-heading-content-indent` | Disallows indentation before heading content. |
-| `no-multiple-toplevel-headings` | Allows only one top-level heading (H1) per document. |
-| `code-block-style` | Enforces a consistent style for code blocks (e.g., using backticks). |
+## D2 Diagram Validation
 
-By automating these checks, DocSmith maintains a consistent standard for documentation, ensuring the final output is accurate and navigable.
+To guarantee that all diagrams are rendered correctly, DocSmith validates the syntax of every D2 diagram.
 
-To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.
+Each code block marked with `d2` is processed through a strict syntax checker. If any syntax errors are found, the generation process is halted with a descriptive error message. This prevents the publication of documents containing broken or improperly rendered visual diagrams.