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

package/prompts/detail/custom/custom-components.md

@@ -1,275 +1,391 @@
 <custom_components_usage>
 When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
+
 - `<x-card>`
 - `<x-cards>`
 - `<x-field>`
+- `<x-field-desc>`
+- `<x-field-group>`
 
+## `<x-card>` Single Card Component
 
-### 1. <x-card> Single Card Component
 Suitable for displaying individual links with a richer and more visually appealing presentation format.
 
-Example:
+### Syntax Rules
+
+Attributes:
+
+- `data-title` (required): Card title.
+- `data-icon` (optional): Icon identifier (e.g., lucide:icon-name or material-symbols:rocket-outline).
+  - Icons should prioritize Lucide (lucide:icon-name). If not available in Lucide, use Iconify (collection:icon-name, e.g., material-symbols:rocket-outline).
+- `data-image` (optional): Image URL, can coexist with icon.
+  - **Requirement**: At least one of `data-icon` or `data-image` must be provided.
+  - It's recommended to always provide data-icon.
+- `data-href` (optional): Navigation link for clicking the card or button.
+- `data-horizontal` (optional): Whether to use horizontal layout.
+- `data-cta` (optional): Button text (call to action).
+
+Body content:
+
+- Must be written within `<x-card>...</x-card>` children.
+- must be **plain text only**. Any markdown formatting will cause rendering errors and must be avoided.
+
+### Examples
+
+<card_good_examples>
+Example 1: Basic card with icon and description
+
+```
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired. </x-card>
+```
+
+Example 2: Horizontal card layout
 
 ```
-<x-card data-title="Required Title" data-image="Image URL" data-icon="Icon identifier (e.g., lucide:rocket or material-symbols:rocket-outline)" data-href="Navigation link URL" data-horizontal="true/false" data-cta="Button text" >
-  Card body content
+<x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
+This is an example of a horizontal card.
 </x-card>
 ```
 
-Attribute Rules:
+</card_good_examples>
 
--	data-title (required): Card title.
--	data-icon / data-image (choose one, at least one must be provided):
-    -	It's recommended to always provide data-icon.
-    -	Icons should prioritize Lucide (lucide:icon-name). If not available in Lucide, use Iconify (collection:icon-name, e.g., material-symbols:rocket-outline).
--	data-image (optional): Image URL, can coexist with icon.
--	data-href (optional): Navigation link for clicking the card or button.
--	data-horizontal (optional): Whether to use horizontal layout.
--	data-cta (optional): Button text (call to action).
--	Body content: 
-  - Must be written within <x-card>...</x-card> children.
-  - **Markdown format rendering is not supported**
-  - **Code block rendering is not supported**
-  - Only supports plain text format without styling
+<card_bad_examples>
+Example 1: Markdown formatting in card content
 
+```
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired. </x-card>
+```
 
-### 2. `<x-field>` Structured Field Component
+Example 2: Code block inside card content
 
-Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
+```
+<x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
+  Creates a listener for "ctrl-break" events.
+
+  \`\`\`rust
+  use tokio::signal::windows::ctrl_break;
+
+  #[tokio::main]
+  async fn main() -> std::io::Result<()> {
+  let mut stream = ctrl_break()?;
+  stream.recv().await;
+  println!("got ctrl-break");
+  Ok(())
+  }
+  \`\`\`
+</x-card>
+```
 
-### 2.1. `<x-field-group>` Field Group Component
+</card_bad_examples>
 
-Used to group multiple related `<x-field>` elements at the top level, indicating they belong to the same object or context. This provides better organization and visual grouping for related parameters.
+## `<x-cards>` Card List Component
 
-Syntax:
+Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
 
-```
-<x-field-group>
-  <x-field data-name="field1" data-type="string" data-desc="First field description"></x-field>
-  <x-field data-name="field2" data-type="number" data-desc="Second field description"></x-field>
-  <x-field data-name="field3" data-type="boolean" data-desc="Third field description"></x-field>
-</x-field-group>
-```
+### Syntax Rules
 
-Attribute Rules:
+Attributes:
 
-- No attributes required
-- Must contain multiple `<x-field>` elements
-- Only `<x-field>` elements are allowed as children
-- Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
-- Used only at the top level for grouping related fields
+- data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
+  - Must contain multiple <x-card> elements internally.
+
+Body content:
 
-### 2.2. `<x-field>` Individual Field Component
+- Must contain multiple <x-card> elements internally.
+- **Consistency requirement**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+  - It's recommended to always provide data-icon for each card.
+  - Or all cards should have data-image.
+  - Avoid mixing (some with icons, some with only images).
 
-Syntax:
+### Examples
+
+<cards_good_examples>
+Example 1: Three-column cards with icons
 
 ```
-<x-field data-name="field_name" data-type="string" data-default="default_value" data-required="true" data-deprecated="false" data-desc="Field description">
-  <!-- For complex types, children can only be other x-field elements -->
-  <x-field data-name="nested_field" data-type="string" data-desc="Nested field description"></x-field>
-  <!-- Optional: Use x-field-desc for rich text descriptions with inline markdown -->
-  <x-field-desc markdown>This field supports **bold text**, `inline code`, and other inline markdown formatting.</x-field-desc>
-</x-field>
+<x-cards data-columns="3">
+  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+  <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+</x-cards>
+```
+
+Example 2: Two-column cards with images
+
 ```
+<x-cards data-columns="2">
+<x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+<x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+</x-cards>
+```
+
+</cards_good_examples>
+
+## `<x-field>` Individual Field Component
+
+Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
 
-Attribute Rules:
+### Syntax Rules
 
-- `data-name` (required): The name of the field/parameter
-- `data-type` (required): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
+Attributes:
+
+- `data-name` (optional): The name of the field/parameter
+- `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
 - `data-default` (optional): Default value for the field
 - `data-required` (optional): Whether the field is required ("true" or "false")
 - `data-deprecated` (optional): Whether the field is deprecated ("true" or "false")
 - `data-desc` (optional): Simple description of the field (plain text only)
-- Children: For complex types (object, array), children can contain multiple `<x-field>` elements and optionally one `<x-field-desc>` element. For simple types, children can be empty or contain one `<x-field-desc>` element.
-
-Child Elements:
+  - Mutually exclusive with `data-desc`: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
 
-- `<x-field-desc>` (optional): Rich text description supporting inline markdown formatting
-  - `markdown` (required): **MUST** be set to "markdown" - this attribute is mandatory and cannot be omitted
-  - Supports **bold text**, `inline code`, *italic text*, and other inline markdown
-  - Cannot contain block-level elements (no code blocks, headers, lists)
-  - **Mutually exclusive with `data-desc`**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
-  - Only one `<x-field-desc>` element per `<x-field>` is allowed
-  - **Validation**: `<x-field-desc>` without `markdown` attribute will be rejected
+Body content:
 
-Nesting Rules:
-
-- Maximum nesting depth: 5 levels (to avoid overly complex structures)
-- **Top-level organization**: Use `<x-field-group>` to group related `<x-field>` elements at the top level
-- **Field component children**: Children elements must only be `<x-field>` and `<x-field-desc>` components
-- **Group component children**: `<x-field-group>` can only contain `<x-field>` elements
-- **Mutually exclusive descriptions**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
-- **Child element limits**: 
-  - For simple types: children can be empty or contain exactly one `<x-field-desc>` element
-  - For complex types: children can contain multiple `<x-field>` elements and optionally one `<x-field-desc>` element
-- **Always use opening/closing tags format**: `<x-field ...></x-field>` and `<x-field-group>...</x-field-group>` for all types
-- **Mandatory markdown attribute**: Every `<x-field-desc>` element **MUST** include `markdown` attribute - elements without this attribute will be rejected
-- **Grouping rules**:
-  - `<x-field-group>` can only be used at the top level
-  - Cannot be nested inside `<x-field>` or other `<x-field-group>` elements
-  - Must contain multiple `<x-field>` elements
-- For simple types (string, number, boolean), children can be empty or contain one `<x-field-desc>`: `<x-field ...></x-field>` or `<x-field ...><x-field-desc markdown>...</x-field-desc></x-field>`
+- For simple types (string, number, boolean): children can be empty or contain exactly one `<x-field-desc>` element
 - For complex types (object, array), children contain nested `<x-field>` elements and optionally one `<x-field-desc>` element
+  - Maximum nesting depth: 5 levels (to avoid overly complex structures)
+- Only one `<x-field-desc>` element per `<x-field>` is allowed
+- **Always use opening/closing tags format**: `<x-field ...></x-field>` for all types
 
-**Usage Rules:**
+### Examples
 
-- **Context types must use `<x-field>` instead of tables** for consistent formatting
-- **Mandatory markdown attribute**: Every `<x-field-desc>` element must include `markdown` attribute
-- **Description text as child content**: Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+<field_good_examples>
+Example 1: Simple field with all attributes
+
+```
+<x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+```
 
-**Error Examples:**
+Example 2: Field with markdown description
 
-❌ **INCORRECT** - Missing `markdown` attribute:
 ```
 <x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc>Your **API key** for authentication.</x-field-desc>
+  <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
 </x-field>
 ```
 
-❌ **INCORRECT** - Description text as attribute value:
+Example 3: Nested object structure
+
 ```
-<x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown="Your **API key** for authentication."></x-field-desc>
+<x-field data-name="session" data-type="object" data-required="true">
+  <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
+  <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
+    <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
+    <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com">
+        <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
+    </x-field>
+    <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
+  </x-field>
+  <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]'>
+    <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
+  </x-field>
 </x-field>
 ```
 
-✅ **CORRECT** - Includes the required `markdown` attribute, with the description provided as child text:
+</field_good_examples>
+
+<field_bad_examples>
+Example 1: Using multiple `<x-field-desc>` elements
+
 ```
 <x-field data-name="api_key" data-type="string" data-required="true">
   <x-field-desc markdown>Your **API key** for authentication.</x-field-desc>
+  <x-field-desc markdown>Keep it secure and never expose it.</x-field-desc>
 </x-field>
 ```
 
-Example:
+Example 2: Using self-closing tag
 
 ```
-<!-- Single field with simple description (using data-desc) -->
-<x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+<x-field data-name="user_id" data-type="string" data-required="true" data-desc="User identifier" />
+```
+
+Example 3: Using both `data-desc` and `<x-field-desc>`
+
+```
+<x-field data-name="api_key" data-type="string" data-required="true" data-desc="API key for authentication">
+  <x-field-desc markdown>Your **API key** for authentication. Keep it secure and never expose it.</x-field-desc>
+</x-field>
+```
+
+Example 4: Nesting other child elements
+
+```
+<x-field data-name="user" data-type="object" data-required="true">
+  <div>User information</div>
+  <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+</x-field>
+```
+
+</field_bad_examples>
+
+## `<x-field-desc>` Field Description Component
+
+Used to provide rich text descriptions for `<x-field>` elements, supporting inline markdown formatting for enhanced readability.
+
+### Syntax Rules
+
+Attributes:
+
+- `markdown` (required): **MUST** be set to "markdown" . This attribute is mandatory and cannot be omitted
+  - **Validation**: `<x-field-desc>` without `markdown` attribute will be rejected
+
+Body content:
+
+- Supports **bold text**, `inline code`, _italic text_, and other inline markdown
+- Cannot contain block-level elements (no code blocks, headers, lists)
+- **Description text as child content**: Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+
+Structure constraints:
+
+- Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
+
+### Examples
+
+<field_desc_good_examples>
+Example 1: Basic markdown description
 
-<!-- Single field with rich text description (using x-field-desc) -->
+```
+<x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
+```
+
+Example 2: Description with inline code
+
+```
+<x-field-desc markdown>**JWT token** containing user identity and permissions. Expires in `24 hours` by default. Use the `refresh_token` to obtain a new one.</x-field-desc>
+```
+
+</field_desc_good_examples>
+
+<field_desc_bad_examples>
+Example 1: Missing markdown attribute
+
+```
 <x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
+  <x-field-desc>Your **API key** for authentication.</x-field-desc>
 </x-field>
+```
 
-<!-- Multiple related fields grouped together (Props, Parameters, Returns, Context) -->
-<x-field-group>
-  <x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
-  <x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
-  <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
-  <x-field data-name="price" data-type="number" data-required="true" data-default="0">
-    <x-field-desc markdown>Product price in **USD**. Must be a positive number with up to 2 decimal places.</x-field-desc>
-  </x-field>
-</x-field-group>
+Example 2: Incorrect markdown attribute usage
 
-<!-- Multiple field groups for different contexts -->
-<x-field-group>
-  <x-field data-name="username" data-type="string" data-required="true" data-desc="User login name"></x-field>
-  <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
-  <x-field data-name="password" data-type="string" data-required="true" data-desc="User password"></x-field>
-</x-field-group>
+```
+<x-field data-name="api_key" data-type="string" data-required="true">
+  <x-field-desc markdown="Your **API key** for authentication."></x-field-desc>
+</x-field>
+```
 
-<x-field-group>
-  <x-field data-name="host" data-type="string" data-required="true" data-default="localhost" data-desc="Database host address"></x-field>
-  <x-field data-name="port" data-type="number" data-required="true" data-default="5432" data-desc="Database port number"></x-field>
-  <x-field data-name="ssl" data-type="boolean" data-required="false" data-default="false" data-desc="Enable SSL connection"></x-field>
-</x-field-group>
+Example 3: Using self-closing tag
 
-<!-- Complex nested object with rich descriptions -->
-<x-field data-name="session" data-type="object" data-required="true">
-    <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
-    <x-field data-name="auth" data-type="object" data-required="true" data-desc="User authentication information">
-        <x-field data-name="token" data-type="object" data-required="true" data-desc="Access token information">
-            <x-field data-name="access_token" data-type="string" data-required="true" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">
-                <x-field-desc markdown>**JWT token** containing user identity and permissions. Expires in `24 hours` by default. Use the `refresh_token` to obtain a new one.</x-field-desc>
-            </x-field>
-            <x-field data-name="refresh_token" data-type="string" data-required="false" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">
-                <x-field-desc markdown>Used to obtain new `access_token` when the current one expires. Valid for **30 days**.</x-field-desc>
-            </x-field>
-            <x-field data-name="expires_at" data-type="number" data-required="true" data-default="1704067200" data-desc="Token expiration timestamp (Unix timestamp)"></x-field>
-        </x-field>
-        <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
-            <x-field data-name="profile" data-type="object" data-required="true" data-desc="User profile information">
-                <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
-                <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com">
-                    <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
-                </x-field>
-                <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
-            </x-field>
-            <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]'>
-                <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
-            </x-field>
-        </x-field>
-    </x-field>
+```
+<x-field data-name="user_id" data-type="string" data-required="true">
+  <x-field-desc markdown />
 </x-field>
 ```
 
-### 3. `<x-cards>` Card List Component
+Example 4: Containing block-level elements
 
-Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
+```
+<x-field data-name="config" data-type="object" data-required="true">
+  <x-field-desc markdown>
+    Configuration object for the application.
+
+    # Important Notes
+    - Set debug to true for development
+    - Use production database in production
+
+    \`\`\`javascript
+    const config = { debug: true };
+    \`\`\`
+  </x-field-desc>
+</x-field>
+```
 
-Syntax:
+Example 5: Used outside of x-field component
 
 ```
-<x-cards data-columns="Number of columns">
-  <x-card data-title="Title 1" data-icon="lucide:rocket">Content 1</x-card>
-  <x-card data-title="Title 2" data-icon="lucide:bolt">Content 2</x-card>
-  <x-card data-title="Title 3" data-icon="material-symbols:rocket-outline">Content 3</x-card>
-</x-cards>
+<x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
 ```
 
-Attribute Rules:
--	data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
--	Must contain multiple <x-card> elements internally.
--	Consistency requirement: All <x-card> elements within the same <x-cards> must maintain visual consistency:
-    -	It's recommended to always provide data-icon for each card.
-    -	Or all cards should have data-image.
-    -	Avoid mixing (some with icons, some with only images).
+Example 6: Used as child of other components
 
-<custom_components_good_example>
-Use plain text without any styling
-<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired.  </x-card>
+```
+<x-field-group>
+  <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+  <x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
+</x-field-group>
+```
 
-Single card:
-<x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
-  This is an example of a horizontal card.
-</x-card>
+</field_desc_bad_examples>
 
-Card list (all using icons, recommended approach):
-<x-cards data-columns="3">
-  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
-  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
-  <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
-</x-cards>
+## `<x-field-group>` Field Group Component
 
-Card list (all using images):
-<x-cards data-columns="2">
-  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
-  <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
-</x-cards>
-</custom_components_good_example>
+Used to group multiple related `<x-field>` elements at the top level, indicating they belong to the same object or context. This provides better organization and visual grouping for related parameters.
 
-<custom_components_bad_example>
+### Syntax Rules
 
-`x-card` component body does not support markdown formatting inline code block
-<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired.  </x-card>
+Attributes:
 
+- No attributes required
+
+Body content:
+
+- Only `<x-field>` elements are allowed as children
+
+Structure:
+
+- Top-level organization: Used only at the top level for grouping related `<x-field>`
+- Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+
+### Examples
+
+<field_group_good_examples>
+Example 1: Product information fields
 
-`x-card` component body does not support code blocks
-<x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
-Creates a listener for "ctrl-break" events.
-```rust,no_run
-use tokio::signal::windows::ctrl_break;
-
-#[tokio::main]
-async fn main() -> std::io::Result<()> {
-let mut stream = ctrl_break()?;
-stream.recv().await;
-println!("got ctrl-break");
-Ok(())
-}
 ```
-</x-card>
+<x-field-group>
+  <x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
+  <x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
+  <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+  <x-field data-name="price" data-type="number" data-required="true" data-default="0">
+    <x-field-desc markdown>Product price in **USD**. Must be a positive number with up to 2 decimal places.</x-field-desc>
+  </x-field>
+</x-field-group>
+```
+
+</field_group_good_examples>
+
+<field_group_bad_examples>
+Example 1: Nested inside x-field component
+
+```
+<x-field data-name="user" data-type="object" data-required="true">
+  <x-field-group>
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+    <x-field data-name="email" data-type="string" data-required="true" data-desc="User email"></x-field>
+  </x-field-group>
+</x-field>
+```
+
+Example 2: Nested inside another x-field-group
+
+```
+<x-field-group>
+  <x-field data-name="user" data-type="object" data-required="true" data-desc="User information"></x-field>
+  <x-field-group>
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+    <x-field data-name="email" data-type="string" data-required="true" data-desc="User email"></x-field>
+  </x-field-group>
+</x-field-group>
+```
+
+Example 3: Containing non-x-field elements
+
+```
+<x-field-group>
+  <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+  <div>Additional information</div>
+  <x-field data-name="email" data-type="string" data-required="true" data-desc="User email"></x-field>
+</x-field-group>
+```
 
-</custom_components_bad_example>
+</field_group_bad_examples>
 
 </custom_components_usage>

package/prompts/detail/document-rules.md

@@ -13,10 +13,10 @@ Documentation Generation Rules:
 - Structure each section with: title, introduction, code examples, response data samples, and explanatory notes. Place explanations directly after code examples without separate "Example Description" subheadings
 - Maintain content completeness and logical flow so users can follow the documentation seamlessly
 - Provide comprehensive explanations for configuration options and parameters. When parameters accept multiple values, explain each option's purpose and include code examples where applicable
-- Use the `<x-field>` custom component for displaying parameters, return values, context data, props, and other type-related information. Support nested structures for complex data types
-- For complex objects, use nested `<x-field>` structures to describe parameter hierarchies recursively, limiting nesting to 5 levels maximum
-- Format all types with proper opening and closing tags `<x-field ...></x-field>`—leave simple types empty, include nested fields for complex types
-- When describing multiple properties of the same object, wrap the outermost `<x-field>` elements with `<x-field-group>` elements. Note that nested `<x-field>` elements do not need wrapping
+- Use the `<x-field>` custom component only for displaying structured object data such as API parameters, return values, network request body/query/headers, and complex object properties (e.g., ContextType). This component does not exist independently but represents complete object structures
+- Do not use `<x-field>` for individual field descriptions (e.g., name or version in package.json, logo or appUrl in config.yaml) - use regular Markdown text instead
+- Wrap the outermost `<x-field>` elements with `<x-field-group>` when describing multiple properties of the same object, even if there's only one `<x-field>` element
+- Use recursive `<x-field>` structures to fully express complex object type hierarchies, decomposing all nested properties into more fundamental types. Limit nesting to 5 levels maximum
 - All interface and method documentation must include **response data examples**
 - For simple list data, use Markdown tables to present information clearly and improve readability
 - Validate output Markdown for completeness, ensuring tables are properly formatted

package/prompts/detail/generate-document.md

@@ -37,14 +37,6 @@ Custom component generation rules:
 Custom code block generation rules:
 {% include "custom/custom-code-block.md" %}
 
-Diagram generate guide:
-Evaluate for each document whether diagrams are necessary.
-- Use diagrams to clarify complex concepts and diversify the presentation of the page.
-- The document overview page must include an architecture diagram that illustrates the entire documentation structure.
-- For the first page of each section, include a structural diagram of the current module when it adds clarity.
-- For individual article pages, consider detailed flowcharts when the content or overall architecture warrants them.
-- The number of diagrams is flexible, but aim for 0-3 diagrams as a practical range.
-
 </content_generation_rules>
 
 {% if glossary %}
@@ -110,3 +102,24 @@ User feedback on previous generation:
 3. Reference the style from examples only, **output content in {{locale}} language**
 
 </output_constraints>
+
+
+<tool-usage>
+1. generateD2DiagramContent: Generate D2 diagram for the given document content
+  - Use diagrams to clarify complex concepts and diversify the presentation of the page.
+  - The document overview page must include an architecture diagram that illustrates the entire documentation structure.
+  - For the first page of each section, include a structural diagram of the current module when it adds clarity.
+  - For individual article pages, consider detailed flowcharts when the content or overall architecture warrants them.
+  - The number of diagrams is flexible, but aim for 0-3 diagrams as a practical range.
+
+2. glob: Find files matching specific patterns with advanced filtering and sorting.
+
+3. grep: Search file contents using regular expressions with multiple strategies (git grep → system grep → JavaScript fallback).
+
+4. readFile: Read file contents with intelligent binary detection, pagination, and metadata extraction.
+
+When to use Tools:
+- For each document, evaluate whether D2 diagrams are needed. If so, always use generateD2DiagramContent to add diagrams to the document
+- During document generation, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
+- Code examples in generated documents must use APIs and packages defined in the input data sources. Do not generate non-existent code out of thin air. Use glob/grep/readFile to query related code or references
+</tool-usage>