5 files changed, 448 insertions, 0 deletions
diff --git a/docs/dev/pages/abouts/.name b/docs/dev/pages/abouts/.name
new file mode 100644
index 0000000..f2b936c
--- /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/ci.md b/docs/dev/pages/abouts/ci.md
new file mode 100644
index 0000000..3a93c1c
--- /dev/null
+++ b/docs/dev/pages/abouts/ci.md
@@ -0,0 +1,71 @@
+<h1 align="center">About Mingling CI Process</h1>
+<p align="center">
+    CI workflow and local execution guide for Mingling
+</p>
+
+Mingling's CI process is built into the project, with its execution logic located in `.run/src/bin/ci.rs`. You can run it locally via the `cargo ci` command, which produces the same results as the `CI` workflow in GitHub Actions.
+
+During development, you can run `cargo ci` at any time to verify that your code hasn't introduced regressions.
+
+## Running Locally
+
+An alias is defined in `.cargo/config.toml` at the project root:
+
+```toml
+[alias]
+ci = "run --manifest-path .run/Cargo.toml --bin ci --quiet --"
+```
+ 
+Simply execute:
+
+```bash
+cargo ci
+```
+ 
+## CI Execution Flow
+
+`cargo ci` runs the following stages in order:
+
+### 1. Code Checking Stage (run by default, or individually via `--test-codes`)
+
+- **Scan and build all crates**: Recursively finds all `Cargo.toml` files in the project and runs `cargo build` for each crate in parallel.
+- **Run Clippy on all crates**: Executes `cargo clippy ... -- -D warnings` in parallel; any warning will cause a failure.
+- **Run unit tests for all crates**: Executes `cargo test` in parallel.
+
+### 2. Documentation and Example Checking Stage (run by default, or individually via `--test-docs`)
+
+- **Test all examples**: Runs the `test-examples` tool.
+- **Verify Markdown code blocks compile**: Runs the `test-all-markdown-code` tool to check code blocks in all `*.md` files. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md) for details.
+- **Check if documentation is up to date**: Runs the following documentation refresh tools in sequence:
+  - `docs-code-box-fix`
+  - `docsify-sidebar-gen`
+  - `refresh-docs`
+  - `refresh-feature-mod`
+  - `sync-examples`
+- Finally, runs `cargo fmt` to unify code formatting.
+
+### 3. File Normalization
+
+Runs `git add --renormalize .` to ensure file attributes such as line endings conform to the repository configuration.
+
+## Workspace Cleanliness and Temporary Commits
+
+To ensure reproducible CI results, `ci.rs` imposes strict requirements on the workspace state:
+
+- If the current workspace is not clean and `--dirty` has not been specified, the script will prompt whether to create a temporary commit:
+  - The commit message is `[DO NOT PUSH] CI TEMP [DO NOT PUSH]`.
+  - Use `-y` to auto-confirm without interaction.
+- After CI finishes, the script automatically restores the workspace:
+  - First, `git reset --hard` discards all changes.
+  - If a temporary commit was created, it then runs `git reset --soft HEAD~1` and unstages everything, restoring the state to before CI started.
+- If `--dirty` is specified, the temporary commit and the final cleanliness check are skipped.
+
+> **Warning**: `git reset --hard` is executed at the end of CI. If you use `--dirty`, ensure you have no unsaved important changes.
+
+## GitHub Actions Workflow
+
+`.github/workflows/ci.yml` defines the project's CI:
+
+- Triggered on `push` to the `main` branch.
+- Runs `cargo ci` in parallel on `ubuntu-latest` and `windows-latest`.
+- After CI passes, the `unreleased` tag is automatically moved to the latest commit on `main`.
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/abouts/nightly-features.md b/docs/dev/pages/abouts/nightly-features.md
new file mode 100644
index 0000000..13b666e
--- /dev/null
+++ b/docs/dev/pages/abouts/nightly-features.md
@@ -0,0 +1,18 @@
+<h1 align="center">About Nightly Features</h1>
+<p align="center">
+    Using nightly Rust features in Mingling
+</p>
+
+**Mingling** uses some features that are only available in the `nightly` toolchain. This requires you to enable the `nightly` feature:
+
+```toml
+[dependencies]
+mingling = { version = "...", features = ["nightly"] }
+```
+ 
+## Features
+
+> [!WARNING]
+> The following features can only be used with the nightly toolchain, and are only guaranteed to compile, not to be stable or production-ready.
+>
+> If you need a stable development experience, please **do not use** the `nightly` feature!