1 files changed, 83 insertions, 0 deletions
diff --git a/docs/pages/advanced/1-completion.md b/docs/pages/advanced/1-completion.md
new file mode 100644
index 0000000..a90c3ce
--- /dev/null
+++ b/docs/pages/advanced/1-completion.md
@@ -0,0 +1,83 @@
+<h1 align="center">Completion</h1>
+<p align="center">
+    Fully dynamic completion system via the `comp` feature
+</p>
+
+Mingling's completion is **fully dynamic** — no static completion files, suggestions are computed at runtime based on the user's current input.
+
+## Enable `comp`
+
+```toml
+# Cargo.toml
+[dependencies.mingling]
+features = ["comp"]
+ 
+[build-dependencies.mingling]
+features = [
+    "comp",
+    # Enable `builds` for build-time support
+    "builds"
+]
+```
+ 
+## How it works
+
+When the user presses `TAB`, the completion script calls the program's hidden subcommand `__comp`, which dynamically queries the best suggestions based on the provided `ShellContext`.
+
+This hidden subcommand is auto-generated by `gen_program!()` when the `comp` feature is enabled. Its dispatcher is `CMDCompletion` — you need to add it to your program via `with_dispatcher`.
+
+Completion flow:
+
+1. Re-match the user's current input to a `Dispatcher`
+2. Call the corresponding `#[completion]` function
+3. The function returns a `Suggest` (file completion or a list of suggestions)
+4. Notify the shell to display the suggestions
+
+## Define completions
+
+Use `#[completion(EntryType)]` to define completion logic for an Entry:
+
+```rust
+// Features: ["comp"]
+@@@use mingling::prelude::*;
+@@@use mingling::{ShellContext, Suggest, SuggestItem};
+@@@use std::collections::BTreeSet;
+@@@dispatcher!("greet", CMDGreet => EntryGreet);
+ 
+#[completion(EntryGreet)]
+fn complete_greet(ctx: &ShellContext) -> Suggest {
+    if ctx.previous_word == "greet" {
+        let mut items = BTreeSet::new();
+        items.insert(SuggestItem::new_with_desc("Alice".into(), "Likes to receive messages".into()));
+        items.insert(SuggestItem::new("World".into()));
+        Suggest::Suggest(items)
+    } else {
+        Suggest::FileCompletion
+    }
+}
+```
+ 
+The `suggest!` macro is a more concise way to write the same thing:
+
+```rust
+// Features: ["comp"]
+@@@use mingling::macros::suggest;
+@@@fn example() {
+suggest! {
+    "Alice": "Likes to receive messages",
+    "World"
+};
+@@@}
+```
+ 
+`ShellContext` holds the user's current input state (`previous_word`, `current_word`, `all_words`, etc.). `Suggest` has two variants: `Suggest::Suggest(list)` returns a suggestion list, `Suggest::FileCompletion` delegates file completion to the shell.
+
+## Generate completion scripts
+
+Call `build_comp_scripts` in `build.rs` to generate completion scripts (requires `builds` + `comp` features).
+
+See [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion).
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>