- Internal development documentation for the Mingling codebase — design notes, issue discussions, and architectural decisions.
-
-
-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-docs/_sidebar.md b/docs/dev-docs/_sidebar.md
deleted file mode 100644
index dd735c4..0000000
--- a/docs/dev-docs/_sidebar.md
+++ /dev/null
@@ -1,10 +0,0 @@
-- [Welcome!](README)
-* Abouts
- * [AI Translation Rule](pages/abouts/ai-translation-rule)
- * [Markdown Code Verification System](pages/abouts/code-verify-system)
-* Issues
- * [remove-r-print-macro](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-docs/index.html b/docs/dev-docs/index.html
deleted file mode 100644
index e62268d..0000000
--- a/docs/dev-docs/index.html
+++ /dev/null
@@ -1,187 +0,0 @@
-
-
-
-
-
-
- Mingling Dev Docs
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/dev-docs/pages/abouts/.name b/docs/dev-docs/pages/abouts/.name
deleted file mode 100644
index d5a4a33..0000000
--- a/docs/dev-docs/pages/abouts/.name
+++ /dev/null
@@ -1 +0,0 @@
-Abouts
diff --git a/docs/dev-docs/pages/abouts/ai-translation-rule.md b/docs/dev-docs/pages/abouts/ai-translation-rule.md
deleted file mode 100644
index b1f93f6..0000000
--- a/docs/dev-docs/pages/abouts/ai-translation-rule.md
+++ /dev/null
@@ -1,116 +0,0 @@
-
AI Translation Rule
-
- Translation prompt for your AI Agent
-
-
-# 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.
-```
-
-
- A system that verifies every identified code block can be compiled
-
-
-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//
-├── 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-docs/pages/issues/.name b/docs/dev-docs/pages/issues/.name
deleted file mode 100644
index f99478d..0000000
--- a/docs/dev-docs/pages/issues/.name
+++ /dev/null
@@ -1 +0,0 @@
-Issues
diff --git a/docs/dev-docs/pages/issues/remove-r-print-macro.md b/docs/dev-docs/pages/issues/remove-r-print-macro.md
deleted file mode 100644
index e5ef4a6..0000000
--- a/docs/dev-docs/pages/issues/remove-r-print-macro.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Remove `r_print!` and `r_println!` Macros
-
-`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-docs/pages/issues/the-mod-pathfinder.md b/docs/dev-docs/pages/issues/the-mod-pathfinder.md
deleted file mode 100644
index 676251d..0000000
--- a/docs/dev-docs/pages/issues/the-mod-pathfinder.md
+++ /dev/null
@@ -1,64 +0,0 @@
-
The Mod Pathfinder
-
- A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros.
-
-
-## 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) {
- 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-docs/pages/issues/the-shit-time.md b/docs/dev-docs/pages/issues/the-shit-time.md
deleted file mode 100644
index f524f42..0000000
--- a/docs/dev-docs/pages/issues/the-shit-time.md
+++ /dev/null
@@ -1,90 +0,0 @@
-
Some Situations Where You'd Be Like "Shit!"
-
- This document collects the discomforts currently experienced while using Mingling.
-
-
-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
-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
-completion:
-add rm list <--- You cannot register descriptions for commands
-```
-
-Expected behavior:
-
-```
-mycmd
-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-docs/pages/templates/.name b/docs/dev-docs/pages/templates/.name
deleted file mode 100644
index 1e1408c..0000000
--- a/docs/dev-docs/pages/templates/.name
+++ /dev/null
@@ -1 +0,0 @@
-Templates
diff --git a/docs/dev-docs/pages/templates/doc.md b/docs/dev-docs/pages/templates/doc.md
deleted file mode 100644
index e8a9308..0000000
--- a/docs/dev-docs/pages/templates/doc.md
+++ /dev/null
@@ -1,28 +0,0 @@
-
Helpdoc Template
-
- A template for writing documentation
-
-
-When writing a Helpdoc, you can use the following template to draft
-
-```markdown
-