@aigne/doc-smith 0.5.1 → 0.7.0

package/prompts/document/d2-chart/rules.md

@@ -0,0 +1,48 @@
+- 使用 d2 图表解释复杂的概念 (```d2``` format)，让页面内容展示形式更丰富
+  - 使用 d2 展示架构关系、流程与组件交互，节点与连线文案保持简洁
+  - d2 代码块必须完整且可渲染，避免使用未闭合的语法与奇异字符
+  - d2 图表使用补充说明：
+    - 示例：
+      {% include "diy-examples.md" %}
+    - 官方示例：
+      {% include "official-examples.md" %}
+    - 其他注意事项：
+      - 图表应简洁明了，节点和连线命名准确。
+      - 每个 d2 代码块必须完整闭合，避免语法错误。
+      - 不要添加注释说明，因为生成的图片无法进行交互。
+      - 不要随意更改节点和连线的颜色，这样会破坏配置好的主题。
+      - 节点的名称尽量使用 " 进行包裹，避免出现异常。
+        - bad: `SDK: @blocklet/js-sdk`
+        - good: `SDK: "@blocklet/js-sdk"`
+      - d2 中的 `shape` 只有这些值: `rectangle`, `square`, `page`, `parallelogram`, `document`, `cylinder`, `queue`, `package`, `step`, `callout`, `stored_data`, `person`, `diamond`, `oval`, `circle`, `hexagon`, `cloud`, `c4-person`，不要随意创建其他的 shape，会导致图表报错
+      - 页面的整体布局使用 `direction: down`，这样能确保图表适合在网页中进行阅读；子图中可以根据情况来使用其他的方向布局，需要确保图表的整体效果看起来不会太宽
+      - 如果一个对象中的元素太多了(超过3个)，请使用 `grid-columns` 限制一下单行的列数，`grid-columns` 的值不要超过 3，例如
+        ```d2
+        "Instance": {
+          grid-columns: 3
+          "A": "A"
+          "B": "B"
+          "C": "C"
+          "D": "D"
+          "E": "E"
+        }
+        ```
+      - 尽量保证一个图中，只有一个关联所有元素的图，不要产生多个没有任何连接的子图
+      - 确保 `style` 中的值都是可用的，错误的字段会导致图片生成失败
+      - 尽量确保每个子元素是有名称的
+        - bad:
+          ```d2
+          "SDK Core Instance": {
+            shape: package
+            "TokenService": "Manages session and refresh tokens"
+            "Services": {
+              grid-columns: 2
+              "AuthService": ""
+              "BlockletService": ""
+              "FederatedService": ""
+              "UserSessionService": ""
+            }
+          }
+          ```
+      - 使用 animate: true 可以让图表增加动画效果，看起来效果更好
+      - 针对节点的状态(yes or no)，可以给定不同的颜色(error,warning,success)来增强表现力

package/prompts/document/detail-generator.md

@@ -1,5 +1,6 @@
 
 <document_rules>
+
 文档类信息生成规则：
 - 如果当前部分是存在子文档，当前文档只展示简要的内容，引导用户到子文档中查看详细的内容
 - 每个部分文档需要包含：标题、开头介绍、多个 section 介绍、结尾总结
@@ -13,20 +14,17 @@
 - 确保文档中的内容是完整、连贯的，用户可以跟着文档一步步顺利执行
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
 - 参数优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
-- 接口/方法调用的说明必须包含 **响应数据示例** 
-- 使用 mermaid 图表解释复杂的概念 (```mermaid``` format)，让页面内容展示形式更丰富
-  - 使用 `flowchart` 图表解释概念之间的关系
-  - 使用 `sequenceDiagram` 图表解释调用、执行的流程，
-  - **确保 mermaid `flowchart` 和 `graph` 图表中所有节点的 label 都使用 " 包裹**，使用简单文案描述，不包含任何特殊符号，示例：A["@abc"]、B("AIGNE")、C{"@aigne/core"}
-  - **确保 mermaid `flowchart` 和 `graph` 图表中所有节点连线上的描述都使用 " 包裹**，使用简单文案描述，不包含任何特殊符号，示例： E -- "Yes, Cache Hit" --> F["Serve Cached HTML"];
-  - **确保 mermaid`sequenceDiagram` 图表所有节点名不使用 " 包裹，示例：`participant AIGNE as AIGNE Engine`
-- 更多的使用 table 、mermaid 图表来解释信息，过长的文本描述会让用户阅读有压力
-- 概览部分，必须包含 mermaid 图表，展示产品的架构图
-- 对输出的 markdown 进行检查，确认输出内容完整，table 、mermaid 信息完整并且格式正确
-- **确保内容完整性**：在生成任何文档内容，特别是代码块（如 Mermaid、JSON、代码等）时，必须确保其是**完整且语法正确**的。在输出完成后，必须进行一次**自我检查**，确认所有的代码块、列表、表格等都已完全闭合且没有中途截断。
-- **代码块原子性**：将每个代码块（例如 ```mermaid ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```mermaid）到结束标记（```）之间的所有内容都不能省略或截断。
+- 接口/方法调用的说明必须包含 **响应数据示例**
+- 更多的使用 table、d2 图表来解释信息，过长的文本描述会让用户阅读有压力
+- 概览部分，建议包含 d2 图表展示产品架构图
+{% include "d2-chart/rules.md" %}
+- 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确
+- **确保内容完整性**：在生成任何文档内容，特别是代码块（如 d2、JSON、代码等）时，必须确保其是**完整且语法正确**的。在输出完成后，必须进行一次**自我检查**，确认所有的代码块、列表、表格等都已完全闭合且没有中途截断。
+- **代码块原子性**：将每个代码块（例如 ```d2 ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```d2）到结束标记（```）之间的所有内容都不能省略或截断。
 - **确保 Markdown 语法**：Markdown 格式正确，特别是表格的分隔线（例如 `|---|---|---|`），需要与表格数据列数一致。
 - README 文件只做参考，你需要从代码中获取最新、最完整的信息
+- 忽略详情顶部的标签信息，这是程序处理的，不需要在生成时输出
+
 </document_rules>
 
 <TONE_STYLE>
@@ -44,10 +42,10 @@
   - Be direct: say what happened, why it matters, and how it helps
 
 Example Tone Transformations
-❌ "We’re thrilled to announce our most powerful update yet…" 
+❌ "We’re thrilled to announce our most powerful update yet…"
 ✅ "You can now include location and timestamp metadata for each claim, enabling audit-ready transparency."
 
-❌ "Unlock the future of verification." 
+❌ "Unlock the future of verification."
 ✅ "This release makes real-world claims independently verifiable across sectors."
 </TONE_STYLE>
 
@@ -90,6 +88,6 @@ Do not use promotional fluff or filler emotion. Avoid the following unless quoti
   cutting edge
 </generic-hype-verbs>
 
-➡️ Instead, focus on concrete outcomes and observable benefits. 
+➡️ Instead, focus on concrete outcomes and observable benefits.
 Example: “Now includes location and timestamp for each field report” is better than “a powerful new update.”
 </WORDS_PHRASES_TO_AVOID>

package/prompts/document/structure-planning.md

@@ -10,9 +10,7 @@
   - 如果存在测试相关的代码，可以作为生成文档的参考，**不要为测试代码生成文档**
   - 总是在一开始包含下列内容：
     - Overview：简要说明产品能解决什么，产品能提供什么，产品的结构信息，让用户能快速有一个全面的认识，给出下一步的入口，引导用户阅读
-    - Getting Started：内容包含安装、最小运行示例，让用户用通过一部分文档，在很短的时间就能跑通一个最简单的示例
   - 标题中不需要包含产品名称，显示更加精简
-  - 'Overview' 和 'Getting Started' 章节应该引用所有源代码，方便写出准确全面的介绍
-  - **'Getting Started' 下不需要拆分子章节**
+  - 'Overview' 章节应该引用所有源代码，方便写出准确全面的介绍
   - 每个部分文档都应该尽可能多的引用相关的源代码，来确保生成文档更详细准确，对于你不确定的项，优先添加引用
 </document_rules>

package/prompts/feedback-refiner.md

@@ -1,84 +1,105 @@
 <role>
-你是"反馈→规则"转换器。将一次性的自然语言反馈提炼为**一条单句**、**可执行**、**可复用**的指令，
-并判断是否需要**持久化保存**，以及作用域（global/structure/document/translation）与是否仅限于"输入 paths 范围"。
+You are a "Feedback→Rule" converter. Transform one-time natural language feedback into a **single sentence**, **executable**, **reusable** instruction,
+and determine whether it needs **persistent saving**, along with its scope (global/structure/document/translation) and whether it should be limited to "input paths range".
 </role>
 
 <input>
 - feedback: {{feedback}}
-- stage: {{stage}}     # 可取：structure_planning | document_refine | translation_refine
-- paths: {{paths}}     # 本次命令输入的路径数组（可为空）。仅用于判断是否"限定到这些路径"。不要把它们写进输出。
-- existingPreferences: {{existingPreferences}}     # 当前已保存的用户偏好规则
+- stage: {{stage}}      # Possible values: structure_planning | document_refine | translation_refine
+- paths: {{paths}}      # Array of paths input in current command (can be empty). Used only to determine whether to "limit to these paths". Do not include them in output.
+- existingPreferences: {{existingPreferences}}      # Currently saved user preference rules
 </input>
 
 <scope_rules>
-作用域判定启发式规则：
+Scope determination heuristic rules:
 
-**按 stage 分类**：
-- 若 stage=structure_planning：默认 `scope="structure"`，除非反馈显然是全局写作/语气/排除类政策（则用 `global`）。
-- 若 stage=document_refine：默认 `scope="document"`；若反馈是通用写作政策、排除策略且不依赖具体页面，则可提升为 `global`。
-- 若 stage=translation_refine：默认 `scope="translation"`；若反馈是翻译阶段的一般政策可保持此 scope。
+**Classification by stage**:
+- If stage=structure_planning: Default `scope="structure"`, unless feedback is clearly global writing/tone/exclusion policy (then use `global`).
+- If stage=document_refine: Default `scope="document"`; if feedback is general writing policy or exclusion strategy that doesn't depend on specific pages, can be elevated to `global`.
+- If stage=translation_refine: Default `scope="translation"`; if feedback is general translation policy, maintain this scope.
 
-**路径限制判定**：
-- 若用户反馈显著只影响本批 `paths` 指向的范围（例如"examples 目录中的页面精简说明"），将 `limitToInputPaths=true`；否则为 `false`。
-- **永远不要**在输出中返回具体的 paths 列表。
+**Path Limitation (`limitToInputPaths`) Determination**:
+- **Set to `true` IF** the feedback explicitly names a specific document, path, or section (e.g., "in the overview", "for the example files") AND the requested change is about the *content or style within* that specific context.
+- **Set to `false` IF** the feedback describes a general policy (e.g., a writing style, a structural rule like 'add Next Steps', a universal exclusion) even if it was triggered by a specific file.
+- **Tie-breaker**: When in doubt, default to `false` to create a more broadly applicable rule.
+
+- **Never** return specific paths lists in output.
 </scope_rules>
 
 <save_rules>
-是否保存判定规则：
+Save determination rules:
+
+**Primary Goal: Your most critical task is to distinguish between a reusable policy and a one-time fix. Be conservative: when in doubt, default to `save=false`.**
 
-**一次性操作（不保存）**：
-- 只修正当下版本/错别字/个别句式/局部事实错误，且无稳定可复用价值 → `save=false`
+**One-time operations (do not save)**:
+- Only corrects current version/typos/individual phrasing/local factual errors with no stable reusable value → `save=false`
+- Fixes that are highly specific to a single line or data point and unlikely to recur (e.g., "change the year from 2020 to 2021") → `save=false`
 
-**可复用政策（保存）**：
-- 写作风格、结构约定、包含/排除项、翻译约定等可广泛适用且未来应持续执行 → `save=true`
+**Reusable policies (save)**:
+- Writing styles, structural conventions, inclusion/exclusion items, translation conventions that are broadly applicable and should be consistently executed in the future → `save=true`
 
-**重复性检查（不保存）**：
-- 若 `existingPreferences` 中已有**相似或覆盖**本次反馈意图的规则，则 `save=false`
-- 检查逻辑：对比反馈意图、规则含义、适用范围。若新反馈已被现有规则充分覆盖，无需重复保存
-- 若新反馈是对现有规则的**细化、补充或矛盾修正**，则仍可 `save=true`
+**Duplication check (do not save)**:
+- If `existingPreferences` already contains **similar or covering** rules for current feedback intent, then `save=false`
+- Check logic: Compare feedback intent, rule meaning, and applicable scope. If new feedback is already sufficiently covered by existing rules, no need to save duplicates
+- If new feedback is **refinement, supplement, or conflicting correction** to existing rules, still can be `save=true`
 
-**判定原则**：
-- 优先避免重复保存；若难以判定是否重复，优先 `save=false`，以避免规则冗余
+**Determination principle**:
+- Prioritize avoiding duplicate saves; if difficult to determine whether duplicate, prioritize `save=false` to avoid rule redundancy
 </save_rules>
 
 <rule_format>
-规则写法要求：
+Rule writing requirements:
 
-- 面向模型的**单句**指令；允许使用"必须/不得/总是"等明确措辞。
-- 不引入具体路径、不绑定具体文件名。
-- 例："写作面向初学者；术语首次出现必须给出简明解释。"
+- Model-oriented **single sentence** instruction; allow using clear wording like "must/must not/always".
+- Do not introduce specific paths or bind to specific file names.
+- **Crucially, preserve specific, domain-related keywords** (e.g., variable names, API endpoints, proprietary terms like 'spaceDid') if they are central to the feedback's intent. Generalize the *action*, not the *subject*.
+- **If the feedback is about deleting or removing content, the resulting rule must be a preventative, forward-looking instruction.** Rephrase it as "Do not generate..." or "Avoid including content about...".
+- Example: "Write for beginners; terms must be given clear explanations on first appearance."
 </rule_format>
 
+<output_rule>
+Return a complete JSON object with a `reason` field explaining *why* you are setting `save` to true or false, and how you derived the rule and scope.
+Return the summarized rule in the same language as the feedback in user input.
+</output_rule>
+
 <examples>
-示例1：
-- 输入：stage=document_refine，paths=["overview.md"]，feedback="示例页废话太多，代码要最小可运行。"
-- 输出：
-{"rule":"示例页面以最小可运行代码为主，移除与主题无关的说明段。","scope":"document","save":true,"limitToInputPaths":true}
-
-示例2：
-- 输入：stage=structure_planning，paths=[]，feedback="概览与教程结尾加"下一步"并给出2–3个链接。"
-- 输出：
-{"rule":"在概览与教程文档结尾添加"下一步"小节并提供 2–3 个本仓库内链接。","scope":"structure","save":true,"limitToInputPaths":false}
-
-示例3：
-- 输入：stage=translation_refine，paths=[]，feedback="变量名和代码不要翻译。"
-- 输出：
-{"rule":"翻译时保持代码与标识符原样，不得翻译。","scope":"translation","save":true,"limitToInputPaths":false}
-
-示例4：
-- 输入：stage=document_refine，paths=["overview.md"]，feedback="这段话事实有误，改成 2021 年发布。"
-- 输出：
-{"rule":"更正事实到正确年份。","scope":"document","save":false,"limitToInputPaths":true}
-
-示例5（去重案例）：
-- 输入：stage=document_refine，paths=[]，feedback="代码示例太复杂了，简化一下。"，existingPreferences="rules:\n  - rule: 示例页面以最小可运行代码为主，移除与主题无关的说明段。\n    scope: document\n    active: true"
-- 输出：
-{"rule":"简化代码示例的复杂度。","scope":"document","save":false,"limitToInputPaths":false}
-# 理由：现有规则已覆盖简化代码示例的意图
-
-示例6（非重复案例）：
-- 输入：stage=document_refine，paths=[]，feedback="代码注释要用英文写。"，existingPreferences="rules:\n  - rule: 示例页面以最小可运行代码为主，移除与主题无关的说明段。\n    scope: document\n    active: true"
-- 输出：
-{"rule":"代码注释必须使用英文编写。","scope":"document","save":true,"limitToInputPaths":false}
-# 理由：现有规则未涉及注释语言，属于新的规则维度
-</examples>
+Example 1 (Keyword Preservation):
+- Input: stage=document_refine, paths=["examples/demo.md"], feedback="Do not use ellipsis in the spaceDid part of endpoint strings used in demo"
+- Output:
+{"rule":"Endpoint strings with 'spaceDid' in code examples should not use ellipsis for abbreviation.","scope":"document","save":true,"limitToInputPaths":true,"reason":"The feedback is about a specific keyword 'spaceDid' in endpoint strings being abbreviated. This is a recurring style issue that should be a policy. It's a reusable rule, so `save` is `true`. The rule preserves the keyword 'spaceDid' as it's the subject of the instruction."}
+
+Example 2:
+- Input: stage=structure_planning, paths=[], feedback="Add 'Next Steps' at the end of overview and tutorials with 2-3 links."
+- Output:
+{"rule":"Add 'Next Steps' section at the end of overview and tutorial documents with 2-3 links within the repository.","scope":"structure","save":true,"limitToInputPaths":false,"reason":"This feedback suggests a new structural convention (adding a 'Next Steps' section). This is a classic reusable policy that should be applied to future documents of a certain type. Therefore, `save` is `true` and the scope is `structure`."}
+
+Example 3:
+- Input: stage=translation_refine, paths=[], feedback="Don't translate variable names and code."
+- Output:
+{"rule":"Keep code and identifiers unchanged during translation, must not translate them.","scope":"translation","save":true,"limitToInputPaths":false,"reason":"This is a fundamental, reusable policy for all future translations in this project. It's not a one-time fix. So, `save` is `true` and the scope is correctly `translation`."}
+
+Example 4 (One-time Fix):
+- Input: stage=document_refine, paths=["overview.md"], feedback="This paragraph has factual errors, change it to released in 2021."
+- Output:
+{"rule":"Correct facts to the accurate year.","scope":"document","save":false,"limitToInputPaths":true,"reason":"The feedback is a one-time factual correction for the current content. It corrects a specific data point and is not a reusable writing policy for the future. Therefore, `save` should be `false`."}
+
+Example 5 (Deduplication):
+- Input: stage=document_refine, paths=[], feedback="Code examples are too complex, simplify them.", existingPreferences="rules:\n  - rule: Example pages should focus on minimally runnable code, removing explanatory sections unrelated to the topic.\n    scope: document\n    active: true"
+- Output:
+{"rule":"Simplify the complexity of code examples.","scope":"document","save":false,"limitToInputPaths":false,"reason":"The user wants to simplify code examples. The existing preference rule 'Example pages should focus on minimally runnable code' already covers this intent. Saving a new, similar rule would be redundant. Therefore, `save` should be `false`."}
+
+Example 6 (Non-duplication):
+- Input: stage=document_refine, paths=[], feedback="Code comments should be written in English.", existingPreferences="rules:\n  - rule: Example pages should focus on minimally runnable code, removing explanatory sections unrelated to the topic.\n    scope: document\n    active: true"
+- Output:
+{"rule":"Code comments must be written in English.","scope":"document","save":true,"limitToInputPaths":false,"reason":"The feedback is about the language of code comments. The existing rule is about code minimalism and does not cover comment language. This is a new, non-overlapping rule. Thus, it should be saved. `save` is `true`."}
+
+Example 7 (Deletion Handling):
+- Input: stage=structure_planning, paths=[], feedback="The 'Legacy API Reference' document is outdated and should be removed."
+- Output:
+{"rule":"Do not generate documents or sections for outdated 'Legacy API Reference'.","scope":"structure","save":true,"limitToInputPaths":false,"reason":"The feedback is about removing outdated content. Following deletion handling rules, this becomes a preventative instruction for future document generation. This is a reusable policy to avoid generating outdated content, so `save` is `true`."}
+
+Example 8 (Path-limited Deletion Rule):
+- Input: stage=document_refine, paths=["overview.md"], feedback="Remove contribution-related content from overview"
+- Output:
+{"rule":"Do not include contribution-related content in 'overview' document.","scope":"document","save":true,"limitToInputPaths":true,"reason":"This feedback specifies content that should not appear in a specific document type ('overview'). While it's about removing content, we convert it to a preventative rule. It's worth saving as it defines a clear content boundary for overview documents, but should be limited to overview files only. Therefore `save` is `true` with `limitToInputPaths` also `true`."}
+</examples>

package/prompts/structure-planning.md

@@ -56,6 +56,23 @@
 {{ rules }}
 </user_rules>
 
+<conflict_resolution_guidance>
+When users select potentially conflicting options, conflict resolution guidance will be provided in user_rules. Please carefully read these guidelines and implement the corresponding resolution strategies in the structure planning.
+
+Core principles for conflict resolution:
+1. **Layered need satisfaction**: Simultaneously satisfy multiple purposes and audiences through reasonable document structure hierarchy
+2. **Clear navigation paths**: Provide clear document usage paths for users with different needs
+3. **Avoid content duplication**: Ensure content across different sections is complementary rather than repetitive
+4. **Progressive disclosure**: From high-level overview to specific details, meeting needs at different depth levels
+
+Common conflict resolution patterns:
+- **Purpose conflicts**: Create hierarchical structures
+- **Audience conflicts**: Design role-oriented sections or paths
+- **Depth conflicts**: Adopt progressive structures that allow users to choose appropriate depth levels
+
+When planning structure, prioritize conflict resolution strategies to ensure the final structure can harmoniously satisfy all user needs.
+</conflict_resolution_guidance>
+
 <user_preferences>
 {{userPreferences}}
 
@@ -94,12 +111,12 @@ DataSources 使用规则：
 2. 内容规划优先展示用户提供的 DataSources 中的信息，或者使用你拥有的知识进行补充，不可以随意虚构信息。
 
 {% ifAsync docsType == 'general' %}
-  {% include "../prompts/document/structure-planning.md" %}
+  {% include "document/structure-planning.md" %}
 
 {% endif %}
 
 {% ifAsync docsType == 'getting-started' %}
-  {% include "../prompts/document/structure-getting-started.md" %}
+  {% include "document/structure-getting-started.md" %}
 {% endif %}
 
 其他：
@@ -109,7 +126,7 @@ DataSources 使用规则：
    </rules>
 
 {% ifAsync docsType == 'general' %}
-  {% include "../prompts/document/structure-example.md" %}
+  {% include "document/structure-example.md" %}
 {% endif %}
 
 <output_rules>

package/tests/check-detail-result.test.mjs

@@ -45,10 +45,58 @@ describe("checkDetailResult", () => {
     expect(result.detailFeedback).toContain("dead link");
   });
 
-  test("should approve content with image syntax", async () => {
+  test("should approve content with external image syntax", async () => {
     const structurePlan = [];
     const reviewContent =
-      "This is an image ![MCP Go Logo](/logo.png).\n\nThis has proper structure.";
+      "This is an image ![MCP Go Logo](https://example.com/logo.png).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should approve content with valid local image path", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is a valid image ![Test Image](./README.md).\n\nThis has proper structure.";
+    const docsDir = process.cwd();
+    const result = await checkDetailResult({ structurePlan, reviewContent, docsDir });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with invalid local image path", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an invalid image ![Non-existent Image](./nonexistent.png).\n\nThis has proper structure.";
+    const docsDir = process.cwd();
+    const result = await checkDetailResult({ structurePlan, reviewContent, docsDir });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("Found invalid local image");
+    expect(result.detailFeedback).toContain("only valid media resources can be used");
+  });
+
+  test("should approve content with absolute image path that exists", async () => {
+    const structurePlan = [];
+    const reviewContent = `This is an absolute image ![Test Image](${process.cwd()}/README.md).\n\nThis has proper structure.`;
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with absolute image path that doesn't exist", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an invalid absolute image ![Non-existent Image](/path/to/nonexistent.png).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("Found invalid local image");
+    expect(result.detailFeedback).toContain("only valid media resources can be used");
+  });
+
+  test("should approve content with external image URL", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an external image ![External Image](https://example.com/image.png).\n\nThis has proper structure.";
     const result = await checkDetailResult({ structurePlan, reviewContent });
     expect(result.isApproved).toBe(true);
     expect(result.detailFeedback).toBe("");

package/tests/conflict-resolution.test.mjs

@@ -0,0 +1,237 @@
+import { describe, expect, test } from "bun:test";
+import {
+  detectResolvableConflicts,
+  generateConflictResolutionRules,
+} from "../utils/conflict-detector.mjs";
+import { processConfigFields } from "../utils/utils.mjs";
+
+describe("conflict resolution", () => {
+  describe("detectResolvableConflicts", () => {
+    test("should detect document purpose conflicts", () => {
+      const config = {
+        documentPurpose: ["getStarted", "findAnswers"],
+        targetAudienceTypes: ["developers"],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(1);
+      expect(conflicts[0]).toMatchObject({
+        type: "documentPurpose",
+        items: ["getStarted", "findAnswers"],
+        strategy: "layered_structure",
+        description: "Quick start and API reference conflict, resolved through layered structure",
+      });
+    });
+
+    test("should detect target audience conflicts", () => {
+      const config = {
+        documentPurpose: ["completeTasks"],
+        targetAudienceTypes: ["endUsers", "developers"],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(1);
+      expect(conflicts[0]).toMatchObject({
+        type: "targetAudienceTypes",
+        items: ["endUsers", "developers"],
+        strategy: "separate_user_paths",
+        description: "End users and developers conflict, resolved through separate user paths",
+      });
+    });
+
+    test("should detect multiple conflicts", () => {
+      const config = {
+        documentPurpose: ["getStarted", "findAnswers", "understandSystem"],
+        targetAudienceTypes: ["endUsers", "developers"],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(3);
+
+      // Check for getStarted vs findAnswers conflict
+      expect(
+        conflicts.some(
+          (c) =>
+            c.type === "documentPurpose" &&
+            c.items.includes("getStarted") &&
+            c.items.includes("findAnswers"),
+        ),
+      ).toBe(true);
+
+      // Check for getStarted vs understandSystem conflict
+      expect(
+        conflicts.some(
+          (c) =>
+            c.type === "documentPurpose" &&
+            c.items.includes("getStarted") &&
+            c.items.includes("understandSystem"),
+        ),
+      ).toBe(true);
+
+      // Check for endUsers vs developers conflict
+      expect(
+        conflicts.some(
+          (c) =>
+            c.type === "targetAudienceTypes" &&
+            c.items.includes("endUsers") &&
+            c.items.includes("developers"),
+        ),
+      ).toBe(true);
+    });
+
+    test("should not detect conflicts with single selections", () => {
+      const config = {
+        documentPurpose: ["getStarted"],
+        targetAudienceTypes: ["developers"],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(0);
+    });
+
+    test("should not detect conflicts with non-conflicting combinations", () => {
+      const config = {
+        documentPurpose: ["completeTasks", "solveProblems"],
+        targetAudienceTypes: ["developers", "devops"],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(0);
+    });
+
+    test("should handle object arrays with value property", () => {
+      const config = {
+        documentPurpose: [
+          { value: "getStarted", label: "Get Started" },
+          { value: "findAnswers", label: "Find Answers" },
+        ],
+      };
+
+      const conflicts = detectResolvableConflicts(config);
+
+      expect(conflicts).toHaveLength(1);
+      expect(conflicts[0].items).toEqual(["getStarted", "findAnswers"]);
+    });
+  });
+
+  describe("generateConflictResolutionRules", () => {
+    test("should generate resolution rules for conflicts", () => {
+      const conflicts = [
+        {
+          type: "documentPurpose",
+          items: ["getStarted", "findAnswers"],
+          strategy: "layered_structure",
+          description: "Quick start and API reference conflict, resolved through layered structure",
+        },
+        {
+          type: "targetAudienceTypes",
+          items: ["endUsers", "developers"],
+          strategy: "separate_user_paths",
+          description: "End users and developers conflict, resolved through separate user paths",
+        },
+      ];
+
+      const rules = generateConflictResolutionRules(conflicts);
+
+      expect(rules).toContain("=== Conflict Resolution Guidelines ===");
+      expect(rules).toContain('Detected "getStarted" and "findAnswers" purpose conflict');
+      expect(rules).toContain('Detected "endUsers" and "developers" audience conflict');
+      expect(rules).toContain('Quick start section: Uses "get started" style');
+      expect(rules).toContain('User guide path: Uses "end users" style');
+      expect(rules).toContain("Conflict Resolution Principles:");
+      expect(rules).toContain(
+        "1. Meet diverse needs through intelligent structural design, not simple concatenation",
+      );
+    });
+
+    test("should return empty string for no conflicts", () => {
+      const conflicts = [];
+      const rules = generateConflictResolutionRules(conflicts);
+      expect(rules).toBe("");
+    });
+
+    test("should handle unknown strategies gracefully", () => {
+      const conflicts = [
+        {
+          type: "documentPurpose",
+          items: ["unknown1", "unknown2"],
+          strategy: "unknown_strategy",
+          description: "Unknown conflict",
+        },
+      ];
+
+      const rules = generateConflictResolutionRules(conflicts);
+
+      expect(rules).toContain("=== Conflict Resolution Guidelines ===");
+      expect(rules).toContain("Conflict Resolution Principles:");
+      // Should not contain any strategy-specific text since strategy is unknown
+      expect(rules).not.toContain('Detected "unknown1" and "unknown2"');
+    });
+  });
+
+  describe("processConfigFields integration", () => {
+    test("should integrate conflict resolution into config processing", () => {
+      const config = {
+        documentPurpose: ["getStarted", "findAnswers"],
+        targetAudienceTypes: ["endUsers", "developers"],
+        readerKnowledgeLevel: "completeBeginners",
+        documentationDepth: "balancedCoverage",
+      };
+
+      const result = processConfigFields(config);
+
+      // Should detect conflicts
+      expect(result.detectedConflicts).toBeDefined();
+      expect(result.detectedConflicts).toHaveLength(2);
+
+      // Should include conflict resolution rules in final rules
+      expect(result.rules).toContain("=== Conflict Resolution Guidelines ===");
+      expect(result.rules).toContain("Create layered document structure");
+      expect(result.rules).toContain("Create separate user paths");
+
+      // Should also include regular configuration content with enhanced format
+      expect(result.rules).toContain("Document Purpose - Get started quickly:");
+      expect(result.rules).toContain("Target Audience - End users (non-technical):");
+      expect(result.rules).toContain("Target Audience - Developers integrating your product/API:");
+      expect(result.rules).toContain("Reader Knowledge Level:");
+    });
+
+    test("should work without conflicts", () => {
+      const config = {
+        documentPurpose: ["completeTasks"],
+        targetAudienceTypes: ["developers"],
+        readerKnowledgeLevel: "domainFamiliar",
+      };
+
+      const result = processConfigFields(config);
+
+      // Should not detect conflicts
+      expect(result.detectedConflicts).toBeUndefined();
+
+      // Should not include conflict resolution rules
+      expect(result.rules).not.toContain("=== Conflict Resolution Guidelines ===");
+
+      // Should still include regular configuration content with enhanced format
+      expect(result.rules).toContain("Document Purpose - Complete specific tasks:");
+      expect(result.rules).toContain("Target Audience - Developers integrating your product/API:");
+    });
+
+    test("should preserve target audience field processing", () => {
+      const config = {
+        targetAudienceTypes: ["developers", "devops"],
+        targetAudience: "Existing audience description",
+      };
+
+      const result = processConfigFields(config);
+
+      expect(result.targetAudience).toContain("Existing audience description");
+      expect(result.targetAudience).toContain("Developers integrating your product/API");
+      expect(result.targetAudience).toContain("DevOps / SRE / Infrastructure teams");
+    });
+  });
+});