chore(docs): rename dev-docs directory to dev

Update sidebar link for remove-r-print-macro to use full description
author: 魏曹先生 <1992414357@qq.com> 2026-07-10 16:23:18 +0800
committer: 魏曹先生 <1992414357@qq.com> 2026-07-10 16:26:13 +0800
commit: abbabd9c55daa79b07cd9ba81037568958794a91 (patch)
tree: 6bed622d2b500473669f64d6b73c75ba51668946 /docs/dev
parent: 73d0f0185f94a8733dfb5eb538298447ab8977b3 (diff)
12 files changed, 842 insertions, 0 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
new file mode 100644
index 0000000..a2eede9
--- /dev/null
+++ b/docs/dev/README.md
@@ -0,0 +1,15 @@
+<h1 align="center">Mingling Dev Docs</h1>
+
+<p align="center">
+    Internal development documentation for the <b>Mingling</b> codebase — design notes, issue discussions, and architectural decisions.
+</p>
+
+This site is separate from the [main helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html). The helpdoc is user-facing: tutorials, feature guides, and how-to content for developers _using_ Mingling to build CLI applications. This dev-docs site is for developers _working on_ Mingling itself — understanding internal mechanisms, tracking unresolved problems, and recording design rationale.
+
+## What's here
+
+- **Issues** — Collected notes on known pain points, unresolved trade-offs, and feature gaps in the current implementation.
+
+## How this is different from GitHub Issues
+
+Mingling is hosted on [GitHub](https://github.com/mingling-rs/mingling), and the [Issues page](https://github.com/mingling-rs/mingling/issues) there is primarily for discussion. In contrast, an issue in this document exists only when it is being planned or actively worked on.
diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md
new file mode 100644
index 0000000..0c49615
--- /dev/null
+++ b/docs/dev/_sidebar.md
@@ -0,0 +1,10 @@
+- [Welcome!](README)
+* Abouts
+  * [AI Translation Rule](pages/abouts/ai-translation-rule)
+  * [Markdown Code Verification System](pages/abouts/code-verify-system)
+* Issues
+  * [Remove r_print! and r_println! Macros](pages/issues/remove-r-print-macro)
+  * [The Mod Pathfinder](pages/issues/the-mod-pathfinder)
+  * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time)
+* Templates
+  * [Helpdoc Template](pages/templates/doc)
diff --git a/docs/dev/index.html b/docs/dev/index.html
new file mode 100644
index 0000000..e62268d
--- /dev/null
+++ b/docs/dev/index.html
@@ -0,0 +1,187 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta
+            name="viewport"
+            content="width=device-width, initial-scale=1, minimum-scale=1.0, shrink-to-fit=no, viewport-fit=cover"
+        />
+
+        <title>Mingling Dev Docs</title>
+        <meta
+            name="Mingling Dev Docs"
+            content="Internal design docs, issue discussions, and development notes for Mingling."
+        />
+
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="icon" type="image/png" href="../res/favicon_small.png" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+        <link
+            href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap"
+            rel="stylesheet"
+        />
+
+        <link rel="stylesheet" href="../css/dev-light.css" />
+        <link
+            id="dark-style"
+            rel="stylesheet"
+            href="../css/dev-dark.css"
+            disabled
+        />
+
+        <style>
+            /* ── No sidebar header image override ── */
+            .sidebar > h1 .app-name-link {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 16px;
+                font-weight: 600;
+                letter-spacing: -0.3px;
+            }
+            .sidebar > h1 .app-name-link::before {
+                content: "⚙ ";
+                font-family:
+                    system-ui,
+                    -apple-system,
+                    sans-serif;
+                letter-spacing: 0;
+            }
+            .markdown-section h1,
+            .markdown-section h2,
+            .markdown-section h3,
+            .markdown-section h4 {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-weight: 600;
+                letter-spacing: -0.5px;
+            }
+            .markdown-section h1 {
+                font-size: 24px;
+            }
+            .markdown-section h2 {
+                font-size: 19px;
+            }
+            .markdown-section h3 {
+                font-size: 16px;
+            }
+            .markdown-section p,
+            .markdown-section li {
+                font-family:
+                    system-ui,
+                    -apple-system,
+                    "Segoe UI",
+                    "Noto Sans",
+                    Helvetica,
+                    Arial,
+                    sans-serif;
+            }
+            .sidebar ul li a {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 13px;
+                letter-spacing: -0.2px;
+            }
+            .sidebar ul li ul li a {
+                font-size: 12px;
+            }
+            /* ── Top nav bar ── */
+            .dev-nav {
+                position: fixed;
+                top: 12px;
+                right: 30px;
+                z-index: 20;
+                display: flex;
+                gap: 4px;
+                align-items: center;
+            }
+            .dev-nav a {
+                font-family:
+                    "JetBrains Mono", "SF Mono", "Fira Code", "Cascadia Code",
+                    monospace;
+                font-size: 12px;
+                text-transform: uppercase;
+                letter-spacing: 0.5px;
+                color: #656d76;
+                text-decoration: none;
+                padding: 4px 10px;
+                transition: color 0.15s;
+            }
+            .dev-nav a:hover {
+                color: #0969da;
+            }
+        </style>
+    </head>
+
+    <body>
+        <nav class="dev-nav">
+            <a
+                href="#"
+                onclick="
+                    toggleTheme();
+                    return false;
+                "
+                >🌓 Theme</a
+            >
+            <a href="../doc.html">📖 Helpdoc</a>
+        </nav>
+
+        <div id="app"></div>
+
+        <script>
+            window.$docsify = {
+                name: "dev-docs",
+                repo: "true",
+                corner: {
+                    url: "https://github.com/mingling-rs/mingling",
+                    icon: "github",
+                },
+                auto2top: true,
+                loadSidebar: true,
+                maxLevel: 0,
+                subMaxLevel: 3,
+                search: {
+                    placeholder: "Search dev docs…",
+                    noData: "No matches found.",
+                    depth: 2,
+                },
+                plugins: [
+                    function (hook) {
+                        hook.beforeEach(function (content) {
+                            return content
+                                .split("\n")
+                                .filter(function (line) {
+                                    return !line.startsWith("@@@");
+                                })
+                                .join("\n");
+                        });
+                    },
+                    [
+                        "flexible-alerts",
+                        {
+                            style: "flat",
+                            labels: {
+                                NOTE: "Note",
+                                TIP: "Tip",
+                                IMPORTANT: "Important",
+                                WARNING: "Warning",
+                                CAUTION: "Caution",
+                            },
+                        },
+                    ],
+                ],
+            };
+        </script>
+
+        <script src="../scripts/docsify.min.js"></script>
+        <script src="../scripts/search.js"></script>
+        <script src="../scripts/prism-bash.min.js"></script>
+        <script src="../scripts/prism-toml.min.js"></script>
+        <script src="../scripts/prism-rust.js"></script>
+        <script src="../scripts/docsify-corner.js"></script>
+        <script src="../scripts/docsify-plugin-flexible-alerts.js"></script>
+        <script src="../scripts/day-night-switch.js"></script>
+    </body>
+</html>
diff --git a/docs/dev/pages/abouts/.name b/docs/dev/pages/abouts/.name
new file mode 100644
index 0000000..d5a4a33
--- /dev/null
+++ b/docs/dev/pages/abouts/.name
@@ -0,0 +1 @@
+Abouts
diff --git a/docs/dev/pages/abouts/ai-translation-rule.md b/docs/dev/pages/abouts/ai-translation-rule.md
new file mode 100644
index 0000000..b1f93f6
--- /dev/null
+++ b/docs/dev/pages/abouts/ai-translation-rule.md
@@ -0,0 +1,116 @@
+<h1 align="center">AI Translation Rule</h1>
+<p align="center">
+    Translation prompt for your AI Agent
+</p>
+
+# Translation Style Guide
+
+## 1. Tone & Voice
+
+### Preserve original tone
+
+Maintain the author's attitude, formality, and emotional register exactly as in the source.
+
+### Synonymous substitution
+
+Use words with close or equivalent meaning where direct translation is awkward or unnatural.
+
+## 2. Vocabulary & Abbreviation
+
+### Abbreviation
+
+Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department)
+to avoid overlong words,
+but only when clarity is not sacrificed.
+
+### Concise expression
+
+Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_)
+unless the original tone demands formality.
+
+## 3. Structural Rules
+
+### Paragraph integrity
+
+Keep the original paragraph breaks and line spacing.
+
+### Tag preservation
+
+Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation.
+
+### Example
+
+- Before: “请保持专业语气，但避免使用过长的学术词汇。”
+- After: “Keep a prof. tone, but avoid long academic words.”
+
+### Minimal diff
+
+When translating or syncing English content against a known Chinese original,
+if the Chinese original's meaning is extremely close to the current English meaning,
+do not modify the English text.
+This is to keep git diffs friendly _(only modify parts that have truly changed)_.
+
+## 4. Exceptions
+
+- If a term has no common abbreviation, use the full word.
+- If preserving tone requires a longer phrase, prioritize tone over brevity.
+
+## 5. Original Text
+
+```markdown
+# Translation Style Guide
+ 
+## 1. Tone & Voice
+ 
+### Preserve original tone
+ 
+Maintain the author's attitude, formality, and emotional register exactly as in the source.
+ 
+### Synonymous substitution
+ 
+Use words with close or equivalent meaning where direct translation is awkward or unnatural.
+ 
+## 2. Vocabulary & Abbreviation
+ 
+### Abbreviation
+ 
+Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department)
+to avoid overlong words,
+but only when clarity is not sacrificed.
+ 
+### Concise expression
+ 
+Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_)
+unless the original tone demands formality.
+ 
+## 3. Structural Rules
+ 
+### Paragraph integrity
+ 
+Keep the original paragraph breaks and line spacing.
+ 
+### Tag preservation
+ 
+Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation.
+ 
+### Example
+ 
+- Before: “请保持专业语气，但避免使用过长的学术词汇。”
+- After: “Keep a prof. tone, but avoid long academic words.”
+ 
+### Minimal diff
+ 
+When translating or syncing English content against a known Chinese original,
+if the Chinese original's meaning is extremely close to the current English meaning,
+do not modify the English text.
+This is to keep git diffs friendly _(only modify parts that have truly changed)_.
+ 
+## 4. Exceptions
+ 
+- If a term has no common abbreviation, use the full word.
+- If preserving tone requires a longer phrase, prioritize tone over brevity.
+```
+ 
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md
new file mode 100644
index 0000000..61b66e8
--- /dev/null
+++ b/docs/dev/pages/abouts/code-verify-system.md
@@ -0,0 +1,242 @@
+<h1 align="center">Markdown Code Verification System</h1>
+<p align="center">
+    A system that verifies every identified code block can be compiled
+</p>
+
+This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI.
+
+## Config
+
+Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root.
+
+You can also test a single file via command-line arg:
+
+```sh
+./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md
+```
+ 
+```powershell
+.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md
+```
+ 
+## Default Rules
+
+Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block:
+
+### 1. `#![allow(dead_code)]` and `#![allow(unused)]`
+
+Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets.
+
+### 2. `use mingling::prelude::*;`
+
+If the block already has `use mingling::prelude::*;`, it won't be inserted again.
+
+Otherwise it's inserted automatically (with `#[allow(unused_imports)]`).
+
+### 3. `fn main() {}`
+
+If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended,
+
+so the block can compile as a standalone binary project.
+
+### 4. `mingling::macros::gen_program!();`
+
+If the block **does not contain** a `gen_program!()` call,
+
+`mingling::macros::gen_program!();` is appended automatically.
+
+This call is required by the mingling framework.
+
+### 5. Build Cache Dedup — Shared Dep Hash
+
+Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations.
+
+> [!NOTE]
+>
+> Hash input (all sorted):
+>
+> 1. Feature list
+> 2. External dep name list
+> 3. External dep version list
+> 4. `name=version` pairs
+>
+> Uses FNV-1a 64-bit hash, stable across runs.
+
+## Verification Steps
+
+After the **default rules** are applied, each block goes through:
+
+### 1. Block Extraction
+
+- Only ` ```rust ` fenced code blocks are extracted.
+- Empty blocks (no code lines) are skipped.
+- Blocks with `// NOT VERIFIED` alone are skipped.
+
+### 2. Temp Project Generation
+
+Each block (or each dedup-hash group) gets its own Cargo project:
+
+```
+.temp/doc-test/<hash>/
+├── Cargo.toml
+└── src/
+    └── main.rs
+```
+ 
+### 3. Build Verification
+
+Compiled with `cargo build --release`, stderr inherited to the terminal for real-time progress.
+
+- **Build OK** → **PASS**
+- **Build FAIL** → **FAIL**, last 20 lines of error captured.
+
+### 4. Report
+
+After all tests, a report is written to `.temp/DOCS-TEST-RESULT.md`, containing:
+
+- Total tests, passed, failed
+- Table of results per block (block #, file, line, status)
+- Detailed errors for failed blocks
+
+### 5. Exit Code
+
+- Any block fails → non-zero exit code (blocks CI pipeline).
+- All pass → zero exit code.
+
+---
+
+## Metadata Tag Rules
+
+At the start of a ` ```rust ` block (before code content), use these comment headers to declare metadata. Headers are parsed in order; everything after them is treated as code:
+
+### `// NOT VERIFIED`
+
+Marks the block **not to be compiled**. Use for illustrative snippets that can't compile on their own.
+
+```rust
+// NOT VERIFIED
+// This block is illustrative only, won't be compiled
+fn placeholder() {}
+```
+ 
+### `// BUILD TIME`
+
+Marks the block as a `build.rs` script instead of `src/main.rs`. The block code is wrapped in `fn main() { }` and written to `build.rs`. A stub `fn main() {}` is generated for `src/main.rs`.
+
+```rust
+// BUILD TIME
+// Features: ["builds", "pathf"]
+analyze_and_build_type_mapping().unwrap();
+```
+ 
+### `// Features: [...]`
+
+Declares the mingling crate features needed by this block, as a JSON string array. These features are written into `Cargo.toml`'s `[dependencies]`.
+
+```rust
+// Features: ["full", "serde"]
+```
+ 
+### `// Dependencies:`
+
+Declares external crate deps needed by the block. After `// Dependencies:`, each dep goes on one line: `// crate_name = "version"`.
+
+```rust
+// Dependencies:
+// serde = "1"
+// clap = "4"
+```
+ 
+> [!TIP]
+>
+> **Special handling**:
+>
+> For deps named `serde` or `clap` with a plain string version,
+>
+> `features = ["derive"]` is auto-added.
+>
+> If the version uses a TOML inline table (e.g. `{ version = "1", features = ["derive"] }`),
+>
+> it's kept as-is.
+
+---
+
+## `@@@` Lines (Hidden Compilation)
+
+Lines starting with `@@@` are **hidden from the rendered documentation** but still included in compilation.
+
+This is useful when you want to show only the core logic while keeping the block fully compilable:
+
+```rust
+// This line is visible in docs
+@@@// This line is hidden but still compiled
+@@@fn setup() { /* hidden boilerplate */ }
+```
+ 
+### How it works
+
+| Stage                 | Handling                                                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------------ |
+| **docsify rendering** | `@@@` lines are stripped before markdown is rendered (via `beforeEach` plugin)                   |
+| **CI verification**   | `@@@` prefix is stripped during block parsing, remaining content is treated as regular Rust code |
+
+### Convention
+
+Use `@@@` for:
+
+- `fn main() {}` / `gen_program!()` when the block doesn't need to show them
+- Common `use` imports that would distract from the example
+- Type definitions (`pack!`, `#[derive]`) that are necessary for compilation but not the focus
+- Helper functions that the reader doesn't need to see
+
+> [!TIP]
+> `@@@` is the replacement for `// NOT VERIFIED` — instead of marking a block as uncompilable,
+> hide the boilerplate and keep everything compiling.
+
+---
+
+## Structure Overview
+
+| Module                                        | Responsibility                                                                      |
+| --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `dev_tools/src/verify.rs`                     | Block parsing, Cargo.toml/main.rs generation, build exec, hash dedup, report output |
+| `dev_tools/src/bin/test-all-markdown-code.rs` | Entry point: read config, collect files, orchestrate tests, aggregate results       |
+| `verified-docs.toml`                          | Specifies which doc files to verify                                                 |
+
+---
+
+## Full Example
+
+````markdown
+```rust
+// Features: ["parser"]
+// Dependencies:
+// serde = "1"
+
+// Example code ...
+```
+````
+ 
+The above block compiles equivalently to:
+
+```rust
+#![allow(dead_code)]
+#![allow(unused)]
+ 
+#[allow(unused_imports)]
+use mingling::prelude::*;
+ 
+// Example code ...
+ 
+fn main() {}
+ 
+mingling::macros::gen_program!();
+```
+ 
+`Cargo.toml` will contain:
+
+```toml
+[dependencies]
+mingling = { path = "../../mingling", features = ["parser"] }
+serde = { version = "1", features = ["derive"] }
+```
diff --git a/docs/dev/pages/issues/.name b/docs/dev/pages/issues/.name
new file mode 100644
index 0000000..f99478d
--- /dev/null
+++ b/docs/dev/pages/issues/.name
@@ -0,0 +1 @@
+Issues
diff --git a/docs/dev/pages/issues/remove-r-print-macro.md b/docs/dev/pages/issues/remove-r-print-macro.md
new file mode 100644
index 0000000..3de8f61
--- /dev/null
+++ b/docs/dev/pages/issues/remove-r-print-macro.md
@@ -0,0 +1,87 @@
+<h1 align="center">Remove r_print! and r_println! Macros</h1>
+
+`r_print!` and `r_println!` are important macros in Mingling for use inside `#[help]` and `#[renderer]` functions, but their implementation is not clean: they implicitly introduce a `__renderer_inner_result` field. While this might look elegant at the API level, it is **incorrect** and even **objectionable**.
+
+## Why **Objectionable**?
+
+Because you can't define declarative macros with `macro_rules` that wrap them.
+
+This is because `r_println!` depends on the implicit variable `__renderer_inner_result` injected by the `#[renderer]` proc macro into the function body. However, when a `macro_rules` declarative macro expands, **its internal code is placed in the caller's context**, which does not contain `__renderer_inner_result` — that variable only exists within the direct scope of the function body processed by `#[renderer]`.
+
+Let's look at some code to see why:
+
+```rust
+// Suppose you want to write a wrapper macro:
+macro_rules! my_println {
+    ($($arg:tt)*) => {
+        // When expanded here, the context is the call site of my_println!,
+        // not the location where the renderer function's injected variables live.
+        // So __renderer_inner_result is NOT visible here!
+        r_println!("Custom: {}", format!($($arg)*));
+    };
+}
+
+#[renderer]
+fn render_something(_p: ResultSomething) {
+    // Although this function body has __renderer_inner_result injected,
+    // the code from my_println! does NOT expand "inside this function body" —
+    // macro_rules expansion is essentially text replacement. The replaced code
+    // lives at the line where my_println! is called, and any variables referenced
+    // inside that macro must resolve to identifiers accessible at the call site.
+    // __renderer_inner_result is not a public, path-accessible variable;
+    // it's a hygienic local variable generated by the `#[renderer]` macro,
+    // and external macros cannot directly access it by name.
+    my_println!("{}", box_val); // Compile error: cannot find __renderer_inner_result
+}
+```
+
+## Deeper Issues
+
+I have to admit, this is an early design flaw. After re-examining the code, I found the problem goes beyond "can't be wrapped".
+
+This isn't just a "can't wrap" issue — it reflects that `r_println!`'s design fundamentally violates Rust's macro hygiene principles:
+
+- **Implicit dependency**: Users of the macro must know that a variable named `__renderer_inner_result` exists — but this variable is neither part of the public API nor explicitly documented anywhere.
+- **Scope leakage**: Variables injected by a proc macro should be confined to the scope processed by that macro. But `r_println!` attempts to make that variable accessible across macro calls, which effectively breaks Rust's identifier hygiene.
+- **Non-composable**: Any attempt to wrap `r_println!` will fail, because declarative macros cannot "pass through" access to implicit variables. Even using a proc macro to wrap it would encounter similar hygiene issues.
+
+## Desired New Syntax
+
+I've designed two alternative approaches and will choose based on actual needs.
+
+### Option 1: Explicit Return
+
+```rust
+#[renderer]
+fn render_something(prev: ResultSomething) -> RenderResult {
+    let mut result = RenderResult::new();
+    result.println(prev.to_string());
+    // or
+    write!(result, "{}", prev.to_string());
+
+    result // return here
+}
+```
+
+Clear boundaries — the entire rendering process is confined within the function body decorated by `#[help]` or `#[renderer]`, without introducing extra out-of-scope dependencies. The trade-off is slightly more boilerplate compared to the original approach.
+
+### Option 2: Resource Injection
+
+```rust
+#[renderer]
+fn render_something(prev: ResultSomething, result: &mut ResRenderResult) {
+    result.println(prev.to_string());
+    // or
+    write!(result, "{}", prev.to_string());
+
+    result // return here
+}
+```
+
+More flexible, but blurs the boundary between logic functions like `#[chain]` and rendering functions like `#[help]`.
+
+### Preferred Direction
+
+I lean toward **Option 1 (Explicit Return)**. There's no need to turn `RenderResult` into `ResRenderResult` as a global resource.
+
+As for rendering in logic functions like `#[chain]`, that should be handled by a separate system — not discussed here.
diff --git a/docs/dev/pages/issues/the-mod-pathfinder.md b/docs/dev/pages/issues/the-mod-pathfinder.md
new file mode 100644
index 0000000..676251d
--- /dev/null
+++ b/docs/dev/pages/issues/the-mod-pathfinder.md
@@ -0,0 +1,64 @@
+<h1 align="center">The Mod Pathfinder</h1>
+<p align="center">
+    A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros.
+</p>
+
+## Background
+
+Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed.
+
+## Solution
+
+We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types.
+
+### Behavior When Enabled
+
+**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time)
+
+**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time)
+
+## Challenges
+
+`mingling-mod-pathf` needs to understand **all** Mingling syntax features.
+Fortunately, Mingling's type creation is almost always explicit:
+
+```rust
+mod sub {
+    mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName
+}
+```
+ 
+There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name:
+
+```rust
+dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd
+```
+ 
+And also `#[program_setup]`:
+
+```rust
+#[program_setup] // can infer CustomSetup from the function name `custom_setup`
+fn custom_setup(program: &mut Program<ThisProgram>) {
+    program.with_dispatchers((CMD1, CMD2, CMD3, CMD4, CMD5));
+}
+```
+ 
+## Pathf Output Format
+
+Uses TOML key-value pairs, formatted as follows:
+
+```toml
+ResultRemoteAdd = "crate::mymod::ResultRemoteAdd"
+```
+ 
+Recommended storage location is under the target directory:
+
+```
+/target/{target}/{crate-name}/type-mapping.toml
+```
+ 
+## Other Issues
+
+This solution is limited to Mingling's own syntax system. If types like `dispatcher!`, `pack!` are indirectly expanded through macros, the analyzer will not be able to discover them.
+
+However, this approach solves the current main pain points, so this issue can be set aside for now and addressed later.
diff --git a/docs/dev/pages/issues/the-shit-time.md b/docs/dev/pages/issues/the-shit-time.md
new file mode 100644
index 0000000..f524f42
--- /dev/null
+++ b/docs/dev/pages/issues/the-shit-time.md
@@ -0,0 +1,90 @@
+<h1 align="center">Some Situations Where You'd Be Like "Shit!"</h1>
+<p align="center">
+    This document collects the discomforts currently experienced while using Mingling.
+</p>
+
+This document collects the discomforts currently experienced while using Mingling.
+
+Of course, you can also contribute to this document.
+
+---
+
+## Why is there no fallback completion logic?
+
+(completion) (fallback)
+
+Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion.
+
+For example:
+
+```
+mycmd <tab>
+completion:
+--help    -h  --- Display helps
+--version -V  --- Display versions
+```
+ 
+Currently, there is no workaround.
+
+Ideal solution:
+
+```rust
+#[completion(EntryGlobal)]
+fn complete(ctx: &ShellContext) -> Suggest {
+    // ...
+}
+```
+ 
+---
+
+## Why can't I register descriptions for commands?
+
+(completion) (dispatcher)
+
+Currently, Mingling's Completion cannot register a description for each subcommand.
+
+For example:
+
+```
+mycmd <tab>
+completion:
+add rm list <--- You cannot register descriptions for commands
+```
+ 
+Expected behavior:
+
+```
+mycmd <tab>
+completion:
+add  --- Add something
+rm   --- Remove something
+list --- List something
+```
+ 
+Ideal solution:
+
+```rust
+// It should be able to freely integrate with crates that provide i18n functionality,
+// so the following approach cannot be used as a data source for descriptions.
+dispatcher! {
+    /// Add Something <--- How to i18n?
+    "add", CMDAdd => EntryAdd
+}
+ 
+// Ideally, it should satisfy the following two conditions:
+// 1. No need to use `with_dispatcher`, because `with_dispatcher` is disabled in `dispatch_tree` mode
+// 2. Must be able to accept String or &str at runtime
+ 
+// Current idea
+#[inline(always)]
+#[dispatcher_desc(EntryAdd)]
+fn desc_add() -> String {
+    // If using rust_i18n
+    t!("cmd.add.desc")
+}
+ 
+// Collected and generated by `gen_program!()`
+// Generate something like get_dispatcher_desc(id: &ThisProgram) -> String
+// Match the corresponding function using enum values inside ThisProgram
+gen_program!()
+```
diff --git a/docs/dev/pages/templates/.name b/docs/dev/pages/templates/.name
new file mode 100644
index 0000000..1e1408c
--- /dev/null
+++ b/docs/dev/pages/templates/.name
@@ -0,0 +1 @@
+Templates
diff --git a/docs/dev/pages/templates/doc.md b/docs/dev/pages/templates/doc.md
new file mode 100644
index 0000000..e8a9308
--- /dev/null
+++ b/docs/dev/pages/templates/doc.md
@@ -0,0 +1,28 @@
+<h1 align="center">Helpdoc Template</h1>
+<p align="center">
+    A template for writing documentation
+</p>
+
+When writing a Helpdoc, you can use the following template to draft
+
+```markdown
+<h1 align="center">Title</h1>
+<p align="center">
+    Description
+</p>
+ 
+Content here
+ 
+<!-- To display playable code if needed -->
+<!--<iframe
+    src="../play/play.html?tur=default.md&amp;title=Title"
+    height="600px"/>-->
+ 
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Your-Name
+</p>
+```
+ 
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
author	魏曹先生 <1992414357@qq.com>	2026-07-10 16:23:18 +0800
committer	魏曹先生 <1992414357@qq.com>	2026-07-10 16:26:13 +0800
commit	abbabd9c55daa79b07cd9ba81037568958794a91 (patch)
tree	6bed622d2b500473669f64d6b73c75ba51668946 /docs/dev
parent	73d0f0185f94a8733dfb5eb538298447ab8977b3 (diff)