@aigne/doc-smith 0.8.15 → 0.8.16-beta.1

package/prompts/common/document/openapi-usage-rules.md

@@ -1,36 +1,189 @@
 {% if openAPISpec %}
 <openapi_usage_rules>
+## OpenAPI Usage Rules
 
-**Goal:** Use the provided OpenAPI (Swagger) specification, align it with the current page objective, and leverage it to refine this document.
+Use the provided OpenAPI (Swagger) specification in `<openapi_usage_rules>`, align it with the current page objective, and leverage it to refine this document.
 
-**OpenAPI File Content:** 
-<openapi_doc>
+### Documentation Requirements and Constraints
 
-{{ openAPISpec }}
+- Extract the core content
+  - Organize the document by functional modules.
+  - For each path item, include the following elements:
+    - HTTP method and path.
+    - Concise summary.
+    - Detailed description.
+    - Request parameters: name, location (`in`), type, required flag, description.
+    - Request body: describe its structure when present.
+    - Response body: describe its structure, ignore status code layer.
+    - Response Example: provide example responses for common scenarios
 
-</openapi_doc>
+- Mandatory API description constraints (deduplication rule):
+  - **Ensure** that throughout the document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.
+  - **Never** repeat or expand the interface list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
 
----
+### Expected Output Format
+- A concise, clear, and easy-to-scan Markdown document.
 
-### **Documentation Requirements and Constraints**
+### Examples
+#### OpenAPI Spec Content
+```yml
+openapi: 3.0.1
+info:
+  title: DISCUSS KIT
+  description: ''
+  version: 1.0.0
+paths:
+  /api/v1/sdk/posts:
+    get:
+      summary: List posts
+      deprecated: false
+      description: 'List posts'
+      parameters:
+        - name: type
+          in: query
+          description: 'The type of the posts'
+          required: false
+          example: blog
+          schema:
+            type: string
+            enum:
+              - discussion
+              - blog
+              - doc
+        - name: locale
+          in: query
+          description: 'The locale of the posts'
+          required: false
+          example: en
+          schema:
+            type: string
+            default: en
+            examples:
+              - en
+              - zh
+        - name: page
+          in: query
+          description: 'The page number'
+          required: false
+          example: 1
+          schema:
+            type: integer
+        - name: size
+          in: query
+          description: 'The number of posts per page'
+          required: false
+          example: 20
+          schema:
+            type: integer
+        - name: sort
+          in: query
+          description: 'The sort order of the posts'
+          required: false
+          example: '-createdAt'
+          schema:
+            type: string
+            enum:
+              - createdAt
+              - '-createdAt'
+        - name: labels
+          in: query
+          description: 'The labels of the posts'
+          required: false
+          example:
+            - did
+          schema:
+            type: array
+            items:
+              type: string
+            nullable: true
+      responses:
+        '200':
+          description: succeed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties: {}
+                  meta:
+                    type: object
+                    properties:
+                      total:
+                        type: integer
+                    required:
+                      - total
+                required:
+                  - data
+                  - meta
+```
 
-1.  **Extract the core content:**
-    * Organize the document by functional modules.
-    * For each path item, include the following elements:
-        * HTTP method and path.
-        * Concise summary.
-        * Detailed description.
-        * Request parameters: name, location (`in`), type, required flag, description.
-        * Request body: describe its structure when present.
-        * Responses: at least the key status codes (e.g., 200, 201, 400, 500) and their schemas.
+#### Generate Output
+````md
+### Posts
 
-2.  **Mandatory API description constraints (deduplication rule):**
-    * **Ensure that throughout the document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.**
-    * **Never** repeat or expand the interface list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
+### List posts
 
----
+Retrieves a list of posts, which can be filtered by type, locale, and other criteria. This endpoint supports pagination.
 
-**Expected output format:** A concise, clear, and easy-to-scan Markdown document.
+`GET` `/api/v1/sdk/posts`
+
+#### Parameters
+
+<x-field-group>
+  <x-field data-name="type" data-type="string" data-required="false" data-default="blog">
+    <x-field-desc markdown>The type of posts to retrieve. Can be `discussion`, `blog`, or `doc`.</x-field-desc>
+  </x-field>
+  <x-field data-name="locale" data-type="string" data-required="false" data-default="en">
+    <x-field-desc markdown>The locale of the posts, e.g., `en` or `zh`.</x-field-desc>
+  </x-field>
+  <x-field data-name="page" data-type="integer" data-required="false">
+    <x-field-desc markdown>The page number for pagination.</x-field-desc>
+  </x-field>
+  <x-field data-name="size" data-type="integer" data-required="false" data-default="20">
+    <x-field-desc markdown>The number of posts to return per page.</x-field-desc>
+  </x-field>
+  <x-field data-name="sort" data-type="string" data-required="false" data-default="-createdAt">
+    <x-field-desc markdown>The sort order for the posts. Use `createdAt` for ascending or `-createdAt` for descending.</x-field-desc>
+  </x-field>
+  <x-field data-name="labels" data-type="array" data-required="false">
+    <x-field-desc markdown>An array of label strings to filter posts by.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+#### Responses
+
+<x-field-group>
+  <x-field data-name="data" data-type="array" data-required="true">
+    <x-field-desc markdown>An array of post objects.</x-field-desc>
+  </x-field>
+  <x-field data-name="meta" data-type="object" data-required="true">
+    <x-field-desc markdown>Metadata for pagination.</x-field-desc>
+    <x-field data-name="total" data-type="integer" data-required="true" data-desc="The total number of posts available."></x-field>
+  </x-field>
+</x-field-group>
+
+#### Response Example
+
+```json posts result
+{
+  "data": [
+    {
+      "id": "15bcb4e7-8bd9-4759-b60b-ae826534057a",
+      "title": "Example Blog Post",
+      "content": "This is the content of the blog post.",
+      "createdAt": "2023-10-27T10:00:00Z"
+    }
+  ],
+  "meta": {
+    "total": 1
+  }
+}
+```
+````
 
 </openapi_usage_rules>
 {% endif %}

package/prompts/common/document-structure/document-icon-generate.md

@@ -0,0 +1,116 @@
+# Document Icon Generation
+
+<role>
+You are an icon selection specialist. Your task is to generate appropriate Iconify icon names for document structure root nodes based on their title and description. The icon should semantically match the document's purpose and content to provide better visual identification.
+</role>
+
+<input>
+
+- documentList: {{documentList}}
+
+</input>
+
+<icon_generation_rules>
+
+**Core Requirements:**
+
+1. **Icon Format:**
+   - Must be a valid **Lucide icon name** in the format: `lucide:icon-name`
+   - Examples: `lucide:book`, `lucide:rocket`, `lucide:code`, `lucide:settings`
+   - **Only Lucide icons are supported** - do not use other icon collections
+
+3. **Icon Selection Guidelines:**
+   - Choose icons that **semantically match** the document's purpose and content based on both title and description
+   - Analyze the combined meaning of title and description to understand the document's purpose
+   - Consider the **target audience** and **document type** when selecting icons
+
+4. **Icon Categories and Suggestions:**
+
+   **General Documentation:**
+   - `lucide:book` - General documentation, guides
+   - `lucide:file-text` - Text documents, articles
+   - `lucide:book-open` - Reading materials, tutorials
+   - `lucide:library` - Reference materials
+
+   **Getting Started & Quick Start:**
+   - `lucide:rocket` - Quick start, getting started guides
+   - `lucide:play-circle` - Getting started, tutorials
+   - `lucide:zap` - Quick start, fast setup
+   - `lucide:sparkles` - Quick start, new features
+
+   **API & Code References:**
+   - `lucide:code` - API documentation, code references
+   - `lucide:file-code-2` - Code files, programming guides
+   - `lucide:terminal` - Command-line interfaces, CLI tools
+   - `lucide:git-branch` - Version control, development
+   - `lucide:brackets` - Code syntax, programming
+
+   **Configuration & Settings:**
+   - `lucide:settings` - Configuration guides, settings
+   - `lucide:cog` - Configuration, setup
+   - `lucide:wrench` - Tools, configuration
+   - `lucide:sliders` - Settings, preferences
+
+   **Tutorials & Learning:**
+   - `lucide:graduation-cap` - Learning materials, tutorials
+   - `lucide:lightbulb` - Tips, tutorials, guides
+   - `lucide:book-open` - Learning, reading
+   - `lucide:school` - Educational content
+
+   **Project & Overview:**
+   - `lucide:folder-open` - Project overview, structure
+   - `lucide:layers` - Architecture, structure
+   - `lucide:package` - Packages, modules
+   - `lucide:box` - Components, modules
+
+   **User & Community:**
+   - `lucide:users` - User guides, community
+   - `lucide:user` - User documentation
+   - `lucide:help-circle` - Help, FAQ
+   - `lucide:message-circle` - Communication, chat
+
+   **Security & Admin:**
+   - `lucide:shield` - Security, protection
+   - `lucide:key` - Authentication, access
+   - `lucide:lock` - Security, privacy
+   - `lucide:shield-check` - Security verification
+
+   **Deployment & Operations:**
+   - `lucide:cloud` - Cloud services, deployment
+   - `lucide:server` - Server, infrastructure
+   - `lucide:database` - Database, data
+   - `lucide:network` - Networking, connections
+
+5. **Selection Process:**
+   - Read both title and description carefully
+   - Identify the primary purpose and content type
+   - Match to the most appropriate icon category
+   - Select the most semantically relevant Lucide icon from that category
+   - Ensure the icon clearly represents the document's purpose
+   - **Only use Lucide icons** - format must be `lucide:icon-name`
+
+6. **Important Notes:**
+   - Only generate icons for root-level documents (where parentId is null or empty)
+   - Each document should have exactly one icon
+   - Icons should be immediately recognizable and semantically clear
+   - Avoid overly generic icons when a more specific one is available
+   - Consider cultural and language context when appropriate
+
+</icon_generation_rules>
+
+<output_rules>
+
+Return a JSON object with:
+
+- `documentList`: array of document items with generated icons, each containing:
+  - `path`: the same path from input (for mapping purposes)
+  - `icon`: Lucide icon name in the format `lucide:icon-name` (e.g., `lucide:book`)
+
+Ensure each item:
+- Preserves the exact `path` value from the corresponding input item
+- Has an `icon` field with a valid Lucide icon name (format: `lucide:icon-name`)
+- The icon semantically matches the document's title and description
+- **Only uses Lucide icons** - do not use other icon collections
+
+</output_rules>
+

package/prompts/common/document-structure/document-structure-rules.md

@@ -28,13 +28,18 @@ Structural planning rules:
 
 2. Content planning should prioritize displaying information from user-provided `<data_sources>` or supplement with your existing knowledge. Do not arbitrarily fabricate information.
 
-{% ifAsync docsType == 'general' %}
-  {% include "../../structure/document-rules.md" %}
+3. **Document Icon Generation:**
+   - For root-level nodes (where `parentPath` is null or empty), add an `icon` attribute
+   - Format: `lucide:icon-name` (only Lucide icons supported)
+   - Choose icons that semantically match the document's purpose based on title and description
+   - Common icons: `lucide:book` (documentation), `lucide:rocket` (quick start), `lucide:code` (API), `lucide:settings` (configuration), `lucide:graduation-cap` (tutorials), `lucide:folder-open` (overview), `lucide:users` (user guides), `lucide:shield` (security), `lucide:cloud` (deployment)
 
+{% ifAsync docsType == 'general' %}
+{% include "../../structure/document-rules.md" %}
 {% endif %}
 
 {% ifAsync docsType == 'getting-started' %}
-  {% include "../../structure/structure-getting-started.md" %}
+{% include "../../structure/structure-getting-started.md" %}
 {% endif %}
 
 Other requirements:

package/prompts/common/document-structure/document-title-streamline.md

@@ -0,0 +1,86 @@
+# Document Title Streamline
+
+<role>
+You are a document title optimizer. Your task is to streamline document titles by shortening them while preserving their original meaning and clarity. The primary goal is to make sidebar navigation less crowded and easier to scan at a glance.
+</role>
+
+<input>
+
+- documentList: {{documentList}}
+
+</input>
+
+<streamlining_rules>
+
+**Core Requirements:**
+
+1. **Title Constraints (Optimized for Sidebar Display):**
+
+   - **Character-based limits** (not word-based, as character count determines visual width):
+     - **For English titles: Maximum 24 characters**
+     - **For character-based languages (Chinese, Japanese, etc.): Maximum 12 characters** (half of English limit)
+   - **Purpose**: These limits are specifically designed for sidebar navigation display to prevent crowding and improve readability
+   - **Why character count, not word count**:
+     - Character width is what determines visual space in sidebar navigation
+     - English words vary greatly in length (e.g., "API" = 3 chars, "Configuration" = 13 chars)
+     - Character count provides more accurate control over sidebar display width
+     - Ensures consistent visual width across different languages
+   - Must capture the core concept
+   - Use concise, clear terminology
+   - Preserve key technical terms or proper nouns when essential
+   - Remove unnecessary articles (a, an, the) and filler words
+   - Keep titles scannable and user-friendly
+   - Optimize specifically for sidebar navigation display
+
+2. **General Guidelines:**
+
+   - Maintain consistency in terminology across all items
+   - Prioritize clarity over brevity when there's a conflict
+   - Keep technical accuracy intact
+   - Preserve brand names, product names, and critical keywords
+   - Use title case for document titles
+   - Consider the document's context and hierarchy when streamlining
+   - Focus on making titles easy to scan in a sidebar navigation menu
+
+**Optimization Strategies:**
+
+- Replace long phrases with shorter equivalents
+- Use common abbreviations when widely understood
+- Remove redundant modifiers
+- Combine related concepts when possible
+- Focus on the most important information
+- Remove unnecessary words that don't add meaning
+
+**Important Notes:**
+
+- Only streamline the title, descriptions are not modified
+- **Sidebar Display Consideration**: Character-based limits (24 for English, 12 for other languages) are specifically chosen to optimize sidebar navigation display
+  - Sidebar navigation typically has limited horizontal space
+  - Character count determines visual width, not word count
+  - English: 24 characters ≈ 4-5 average words, fits standard sidebar width (250-300px)
+  - Character-based languages: 12 characters ≈ same visual width as 24 English characters
+  - Shorter titles prevent text wrapping and improve visual scanning
+  - These limits ensure titles remain readable and don't crowd the navigation menu
+- The goal is to make sidebar navigation less crowded and more readable
+- Titles should be immediately understandable without reading the full description
+- **Language detection**: Determine the primary language of the title and apply the appropriate character limit
+
+</streamlining_rules>
+
+<output_rules>
+
+Return a JSON object with:
+
+- `documentList`: array of streamlined document items, each containing:
+  - `path`: the same path from input (for mapping purposes)
+  - `title`: shortened title (maximum 24 characters for English, 12 characters for character-based languages, optimized for sidebar display)
+
+Ensure each streamlined item:
+- Preserves the exact `path` value from the corresponding input item
+- Maintains the original intent and meaning
+- Uses clear, scannable language
+- Fits within the word/character count constraints
+- Provides enough context for users to understand the document's purpose at a glance
+- Is optimized for sidebar navigation display
+
+</output_rules>

package/prompts/common/document-structure/openapi-usage-rules.md

@@ -0,0 +1,28 @@
+{% if userContext.openAPISpec %}
+
+<openapi_usage_rules>
+## OpenAPI Usage Rules
+
+Use the provided OpenAPI (Swagger) specification in `<openapi_spec_content>` to design how the OpenAPI content and the overall document should be structured together.
+
+### Documentation Requirements and Constraints
+
+- Section structure and titles
+  - Create a dedicated top-level section for the OpenAPI content.
+  - The section title must be professional and user friendly
+    - **Never** include terms such as OpenAPI, Swagger, or file formats.
+    - Recommended titles include **"API Interface Reference"** or **"Interface Reference"**.
+
+- Content hierarchy and presentation:
+  - **Ideal state (single-level page):** Prefer to present all API endpoints within **one Markdown file (one page)**.
+  - **Split criteria (two-level pages):** Only when the number of endpoints is too large for a single file should you split by OpenAPI tags or logical modules, creating individual Markdown files per module.
+  - **Forced file hierarchy constraint:** Whether using one or two levels, the generated API reference files (Markdown) may contain **no more than two levels.**
+    - **Example (two-level structure):** `/api-reference.md` (index) -> `/api/user.md`, `/api/order.md` (module pages)
+    - **Disallow any third level or deeper structure:** for example, `/api/v1/user/get.md`.
+
+- Mandatory API description constraints (deduplication rule):
+  - Ensure that for the entire document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.
+  - **Never** repeat or extend the API list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
+
+</openapi_usage_rules>
+{% endif %}

package/prompts/common/document-structure/output-constraints.md

@@ -6,4 +6,13 @@
   - For referenced files, analyze another layer of source code files referenced within them and add to sourceIds to ensure complete context for detail generation
 2. **Ensure sourceIds are never empty**. Do not plan {{nodeName}} items without related data sources
 
+3. **Project Information Length Constraints:**
+   - `projectName`: Must not exceed **40 characters** (counted as character length, regardless of language - Chinese, English, Russian, etc.). Keep it concise and clear. Generate a complete, meaningful name within this limit.
+   - `projectDesc`: Must not exceed **160 characters** (counted as character length, regardless of language - Chinese, English, Russian, etc.). Provide a brief, informative description. Generate a complete, coherent description within this limit.
+   - **Character counting rules:**
+     - Count all characters equally (Chinese, English, Russian, etc. - each character counts as 1)
+     - Spaces in the middle of the text count toward the character limit
+     - Leading and trailing spaces will be automatically removed, so do not include them
+   - **Important**: These are hard limits. Ensure your generated content is complete and grammatically correct within these character constraints. Do not generate content that would need truncation.
+
 </output_constraints>

package/prompts/detail/custom/{custom-code-block.md → code-block-usage-rules.md}

@@ -1,36 +1,42 @@
-<enhanced_code_block_rules>
+<code_block_usage_rules>
+
 ## Enhanced Attributes for Markdown Code Blocks
 
 When generating Markdown, you can add enhanced attributes to code blocks to provide richer functionality and better display effects. These attributes allow you to specify **titles**, **icons**, and more for code blocks.
 
-**Please use these enhanced attributes as much as possible to improve display effects**
-
 ### Attribute Definition
 
 The following are the available enhanced attributes and their descriptions:
 
-  * `language`: The language of the code block (e.g., `javascript`, `python`, `html`). This attribute is placed directly after the three backticks (\`\`\`).
-  * `title`: The title of the code block, which is optional.
-  * `icon`: The icon displayed next to the code block, which is optional. This value must be a valid **Iconify icon name** (e.g., `logos:javascript`, `mdi:folder-open`).
+- `language`: The language of the code block (e.g., `javascript`, `python`, `html`). This attribute is placed directly after the three backticks (\`\`\`).
+- `title`: The title of the code block (optional)
+- `icon`: The icon displayed next to the code block, which is optional. This value must be a valid **Iconify icon name** (e.g., `logos:javascript`, `mdi:folder-open`).
 
 ### Attribute Usage
 
-  * `language` and `title` are written directly after \`\`\`, separated by spaces.
-  * Other attributes (`icon`) must be provided in **key=value** format, separated by spaces.
+- `language` and `title` are written directly after \`\`\`, separated by spaces.
+  - Do not add quotes around the `title` value.
+- Other attributes (`icon`) must be provided in **key=value** format, separated by spaces.
 
-### Special Rules
+### Usage Requirements
+- Use these enhanced attributes as much as possible to improve display effects.
 - If the language is a shell (includes `sh`, `bash`, `zsh`, etc.):
   - Executable shell code blocks must be a single-line command to make copying and running easier.
   - Do not include comments inside executable shell code blocks; place explanatory comments outside the code block.
+- Prefer use filename as title:
+  - If the code block content demonstrates usage of a component or library (for example a React component file, a Vue component, or a util module), the `title` should be the filename used in real usage (for example `MyComponent.jsx`, `index.ts`, `utils.js`). Using the filename as the title makes the example clearer and helps standardize code-block titles across the docs.
+  - If the content is not a usage example, prefer a short descriptive title that summarizes the snippet's purpose.
+- Ensure readability of the document:
+  - After inserting a code block, update the surrounding document text to introduce, reference, or explain the code block.
 
 ### Examples
 
-<code_block_good_examples>
+#### Good Examples
 The following are some examples of Markdown code blocks using enhanced attributes:
 
 **Example 1: Code block with title and icon**
 
-```javascript Shopping Cart Class icon=logos:javascript
+```javascript shopping-cart.js icon=logos:javascript
 class ShoppingCart {
   constructor() {
     this.items = [];
@@ -54,7 +60,7 @@ class ShoppingCart {
 
 **Example 3: Code block with title only**
 
-```javascript Shopping Cart Class
+```javascript shopping-cart.js
 class ShoppingCart {
   constructor() {
     this.items = [];
@@ -76,6 +82,29 @@ class ShoppingCart {
 }
 ```
 
+**Example 7: Component usage example with filename title**
+
+```javascript MyComponent.jsx icon=logos:react
+import React from 'react';
+
+export default function MyComponent(props) {
+  return (
+    <div className="my-component">
+      <h1>{props.title}</h1>
+    </div>
+  );
+}
+```
+
+**Example 8: Utility module example with filename title**
+
+```javascript utils.js
+// simple utility function exported from utils.js
+export function formatDate(date) {
+  return new Date(date).toLocaleDateString();
+}
+```
+
 **Example 5: Shell code block should in one line**
 
 ```sh Install aigne deps icon=lucide:terminal
@@ -91,9 +120,8 @@ blocklet deploy . \
   --app-id z2qa9sD2tFAP8gM7C1i8iETg3a1T3A3aT3bQ
 ```
 
-</code_block_good_examples>
 
-<code_block_bad_examples>
+#### Bad Examples
 
 **Example 1**
 
@@ -132,5 +160,4 @@ npm i -g @aigne/websmith-smith
 npm i -g @aigne/cli
 ```
 
-</code_block_bad_examples>
-</enhanced_code_block_rules>
+</code_block_usage_rules>

package/prompts/detail/custom/custom-components/x-card-usage-rules.md

@@ -0,0 +1,62 @@
+<x-card-usage-rules>
+## XCard Usage Rules
+
+XCard is individual link display card, suitable for displaying individual links with a richer and more visually appealing presentation format.
+
+### 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).
+
+### Children
+
+- Must be written within `<x-card>...</x-card>` children.
+- **Plain Text Only**: All markdown formatting is prohibited, including inline formats like `code`, **bold**, _italic_, [links](), and block-level formats like headers (# ##), lists (- \*), code blocks (```), tables (|), and any other markdown syntax. Only plain text content is allowed.
+
+### Good Examples
+
+- Example 1: Basic card with icon and description
+  ```md
+    <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
+  ```md
+  <x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
+  This is an example of a horizontal card.
+  </x-card>
+  ```
+
+### Bad Examples
+
+- Example 1: Inline Markdown formatting in card content
+  ```md
+  <x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired. </x-card>
+  ```
+
+- Example 2: Code block inside card content
+  ````md
+  <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-usage-rules>