docs: add module-level documentation and improve doc comments

27 files changed, 278 insertions, 55 deletions

diff --git a/.run/version-files.toml b/.run/version-files.toml
index f00ae4c..42d9b4d 100644
--- a/.run/version-files.toml
+++ b/.run/version-files.toml
@@ -25,3 +25,7 @@ pattern = "version = \"{VER}\""
 [[file]]
 file = "./mingling_picker/README.md"
 pattern = "mingling_picker = \"{VER}\""
+
+[[file]]
+file = "./mingling_picker_macros/README.md"
+pattern = "version = \"{VER}\""
diff --git a/mingling/src/parser/picker.rs b/mingling/src/parser/picker.rs
index 21ba9a6..601cd3f 100644
--- a/mingling/src/parser/picker.rs
+++ b/mingling/src/parser/picker.rs
@@ -722,6 +722,13 @@ impl_pick_with_route_next! { PickWithRoute9 PickWithRoute10 val_10 T1 val_1, T2
 impl_pick_with_route_next! { PickWithRoute10 PickWithRoute11 val_11 T1 val_1, T2 val_2, T3 val_3, T4 val_4, T5 val_5, T6 val_6, T7 val_7, T8 val_8, T9 val_9, T10 val_10 }
 impl_pick_with_route_next! { PickWithRoute11 PickWithRoute12 val_12 T1 val_1, T2 val_2, T3 val_3, T4 val_4, T5 val_5, T6 val_6, T7 val_7, T8 val_8, T9 val_9, T10 val_10, T11 val_11 }
 
+/// Trait for types that can be used with `Pickable` to extract enum values from command-line arguments.
+///
+/// This trait combines `EnumTag` (for building an enum variant from a string name) and `Default`
+/// (for providing a fallback value when the flag is not present).
+///
+/// Types implementing this trait can be used with `Picker::pick`, `Picker::pick_or_route`, and
+/// the chaining `.pick()` methods to extract and parse enum values from command-line arguments.
 pub trait PickableEnum: EnumTag + Default {}
 
 impl<T> Pickable for T
diff --git a/mingling/src/parser/picker/bools.rs b/mingling/src/parser/picker/bools.rs
index ede8812..0525c52 100644
--- a/mingling/src/parser/picker/bools.rs
+++ b/mingling/src/parser/picker/bools.rs
@@ -1,9 +1,15 @@
 use crate::parser::Pickable;
 
+/// Represents a boolean-like value with `Yes` and `No` variants.
+///
+/// `Yes` can be parsed from command-line arguments using positive keywords such as `"y"` or `"yes"`,
+/// and defaults to `No`.
 #[derive(Debug, Default)]
 #[repr(u8)]
 pub enum Yes {
+    /// The affirmative/positive variant.
     Yes,
+    /// The negative/default variant.
     #[default]
     No,
 }
@@ -57,10 +63,16 @@ impl Pickable for Yes {
     }
 }
 
+/// Represents a boolean-like value with `True` and `False` variants.
+///
+/// `True` can be parsed from command-line arguments using positive keywords such as `"t"` or `"true"`,
+/// and defaults to `False`.
 #[derive(Debug, Default)]
 #[repr(u8)]
 pub enum True {
+    /// The affirmative/positive variant.
     True,
+    /// The negative/default variant.
     #[default]
     False,
 }
diff --git a/mingling_macros/src/lib.rs b/mingling_macros/src/lib.rs
index 0c7aeaf..d0f603a 100644
--- a/mingling_macros/src/lib.rs
+++ b/mingling_macros/src/lib.rs
@@ -2,7 +2,7 @@
 //!
 //! This crate is the **macro layer** of Mingling. Each `#[attribute]` or `!`-callable
 //! macro collects metadata into **compile-time global registries** (`OnceLock<Mutex<BTreeSet>>`).
-//! At the end, [`gen_program!`] reads all registries and generates the final program struct
+//! At the end, `gen_program!` reads all registries and generates the final program struct
 //! with all dispatchers, chains, renderers, and completions wired together.
 //!
 //! # How Macros Work Together
@@ -47,16 +47,16 @@
 //!
 //! | Macro | What it does |
 //! |-------|-------------|
-//! | [`dispatcher!`] | Declares a command entry point and its argument type |
-//! | [`macro@dispatcher_clap`] | Like `dispatcher!` but powered by `clap::Parser` |
-//! | [`node!`] | Builds a [`Node`](https://docs.rs/mingling/latest/mingling/struct.Node.html) from a dot-separated path string |
-//! | [`pack!`] | Creates a newtype wrapper around an inner type for use in Chain/Renderer |
-//! | [`pack_structural!`] | Like `pack!` but also derives `StructuralData` for structured output |
-//! | [`pack_err!`] | Creates an error struct with automatic `name` field |
-//! | [`pack_err_structural!`] | Like `pack_err!` but also derives `StructuralData` for structured output |
-//! | [`entry!`] | Creates a packed entry from string literals |
+//! | `dispatcher!` | Declares a command entry point and its argument type |
+//! | `dispatcher_clap!` | Like `dispatcher!` but powered by `clap::Parser` |
+//! | `node!` | Builds a [`Node`](https://docs.rs/mingling/latest/mingling/struct.Node.html) from a dot-separated path string |
+//! | `pack!` | Creates a newtype wrapper around an inner type for use in Chain/Renderer |
+//! | `pack_structural!` | Like `pack!` but also derives `StructuralData` for structured output |
+//! | `pack_err!` | Creates an error struct with automatic `name` field |
+//! | `pack_err_structural!` | Like `pack_err!` but also derives `StructuralData` for structured output |
+//! | `entry!` | Creates a packed entry from string literals |
 //! | [`#[derive(Groupped)]`](derive@Groupped) | Makes a type recognizable by the framework's type registry |
-//! | [`#[derive(StructuralData)]`](derive@StructuralData) | Marks a type as eligible for structured output (JSON/YAML/etc.) |
+//! | `#[derive(StructuralData)]` | Marks a type as eligible for structured output (JSON/YAML/etc.) |
 //! | [`#[derive(EnumTag)]`](derive@EnumTag) | Adds enum variant metadata (name, description) |
 //!
 //! ## Phase 2: Processing & Rendering Registration
@@ -66,27 +66,27 @@
 //! | [`#[chain]`](attr.chain.html) | Transforms a function into a chain processing step |
 //! | [`#[renderer]`](attr.renderer.html) | Transforms a function into a renderer for a type |
 //! | [`#[help]`](attr.help.html) | Defines help output for a command entry type |
-//! | [`route!`] | Routes execution depending on a condition |
-//! | [`empty_result!`] | Returns an empty result for early termination |
+//! | `route!` | Routes execution depending on a condition |
+//! | `empty_result!` | Returns an empty result for early termination |
 //! | [`#[completion]`](attr.completion.html) | Registers a shell completion handler |
 //!
 //! ## Phase 3: Program Generation
 //!
 //! | Macro | What it does |
 //! |-------|-------------|
-//! | [`gen_program!`] | **Final step**: reads all registries and generates the full program |
-//! | [`suggest!`] | Generates suggestion logic for a dispatcher |
-//! | [`suggest_enum!`] | Generates suggestion logic for an enum dispatcher |
+//! | `gen_program!` | **Final step**: reads all registries and generates the full program |
+//! | `suggest!` | Generates suggestion logic for a dispatcher |
+//! | `suggest_enum!` | Generates suggestion logic for an enum dispatcher |
 //!
 //! ## Internal (used by the macros above)
 //!
 //! | Macro | What it does |
 //! |-------|-------------|
-//! | [`register_type!`] | Registers a type in the packed-type registry |
-//! | [`register_chain!`] | Registers a chain mapping in the chain registry |
-//! | [`register_renderer!`] | Registers a renderer mapping in the renderer registry |
-//! | [`register_dispatcher!`] | Registers a dispatcher for the `dispatch_tree` feature |
-//! | [`register_help!`] | Registers a help request handler |
+//! | `register_type!` | Registers a type in the packed-type registry |
+//! | `register_chain!` | Registers a chain mapping in the chain registry |
+//! | `register_renderer!` | Registers a renderer mapping in the renderer registry |
+//! | `register_dispatcher!` | Registers a dispatcher for the `dispatch_tree` feature |
+//! | `register_help!` | Registers a help request handler |
 //! | `program_fallback_gen!` | Generates fallback error types |
 //! | `program_final_gen!` | Generates the `ProgramCollect` impl and `ThisProgram` struct |
 //! | `program_comp_gen!` | Generates completion logic |
@@ -98,12 +98,12 @@
 //!
 //! | Feature | Macros enabled |
 //! |---------|---------------|
-//! | `clap` | [`macro@dispatcher_clap`] |
-//! | `comp` | [`#[completion]`](attr.completion.html), [`suggest!`], [`suggest_enum!`] |
-//! | `extra_macros` | [`entry!`], [`empty_result!`], [`route!`], [`#[program_setup]`](attr.program_setup.html), [`macro@group`] |
+//! | `clap` | `dispatcher_clap!` |
+//! | `comp` | [`#[completion]`](attr.completion.html), `suggest!`, `suggest_enum!` |
+//! | `extra_macros` | `entry!`, `empty_result!`, `route!`, [`#[program_setup]`](attr.program_setup.html), `group!` |
 //! | `dispatch_tree` | `register_dispatcher!` (enables trie-based command dispatch) |
-//! | `structural_renderer` | [`#[derive(StructuralData)]`](derive@StructuralData), [`pack_structural!`], [`pack_err_structural!`], [`macro@group_structural`] |
-//! | `structural_renderer` + `extra_macros` | [`group_structural!`], [`pack_err_structural!`] |
+//! | `structural_renderer` | `#[derive(StructuralData)]`, `pack_structural!`, `pack_err_structural!`, `group_structural!` |
+//! | `structural_renderer` + `extra_macros` | `group_structural!`, `pack_err_structural!` |
 //! | `async` | Enables async `#[chain]` functions |
 //! | `repl` | Enables REPL execution loop |
 //!
@@ -114,7 +114,7 @@
 //! entries contain the **token-stream representation** of match arms, type mappings,
 //! and struct definitions.
 //!
-//! When [`gen_program!`] is called, it reads all registries, concatenates their
+//! When `gen_program!` is called, it reads all registries, concatenates their
 //! entries, and emits the complete program:
 //!
 //! ```rust,ignore
@@ -599,13 +599,13 @@ pub fn route(input: TokenStream) -> TokenStream {
 /// crate::ResultEmpty::new(()).to_chain()
 /// ```
 ///
-/// This works because [`ResultEmpty`] is automatically generated by [`gen_program!`]
+/// This works because [`ResultEmpty`] is automatically generated by `gen_program!`
 /// and implements the necessary trait conversions into [`ChainProcess`].
 ///
 /// # See also
 ///
 /// - [`ResultEmpty`] — The type that represents an empty result.
-/// - [`route!`] — For early-return from `Result` expressions.
+/// - `route!` — For early-return from `Result` expressions.
 ///
 /// [`ResultEmpty`]: https://docs.rs/mingling/latest/mingling/type.ResultEmpty.html
 /// [`ChainProcess`]: https://docs.rs/mingling/latest/mingling/enum.ChainProcess.html
@@ -690,8 +690,8 @@ pub fn empty_result(_input: TokenStream) -> TokenStream {
 ///
 /// # See also
 ///
-/// - [`macro@dispatcher_clap`] — For clap-powered argument parsing.
-/// - [`node!`] — For building custom [`Node`] paths.
+/// - `dispatcher_clap!` — For clap-powered argument parsing.
+/// - `node!` — For building custom [`Node`] paths.
 /// - [`#[chain]`](attr.chain.html) — For processing the dispatched entry.
 ///
 /// [`ChainProcess`]: https://docs.rs/mingling/latest/mingling/enum.ChainProcess.html
@@ -1088,7 +1088,7 @@ pub fn dispatcher_clap(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// Creates a packed entry value from a list of string literals.
 ///
 /// This is a convenience macro for constructing entry wrapper types (created
-/// via [`pack!`] or [`dispatcher!`]) with test data, typically used in unit tests
+/// via `pack!` or `dispatcher!`) with test data, typically used in unit tests
 /// or quick prototypes.
 ///
 /// # Syntax
@@ -1119,8 +1119,8 @@ pub fn dispatcher_clap(attr: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// # See also
 ///
-/// - [`pack!`] — For creating the wrapper types used with `entry!`.
-/// - [`dispatcher!`] — Which implicitly creates entry types via `pack!`.
+/// - `pack!` — For creating the wrapper types used with `entry!`.
+/// - `dispatcher!` — Which implicitly creates entry types via `pack!`.
 #[cfg(feature = "extra_macros")]
 #[proc_macro]
 pub fn entry(input: TokenStream) -> TokenStream {
@@ -1147,10 +1147,10 @@ pub fn register_help(input: TokenStream) -> TokenStream {
 
 /// Registers a dispatcher at compile time for the `dispatch_tree` feature.
 ///
-/// This macro is called internally by [`dispatcher!`] when the `dispatch_tree`
+/// This macro is called internally by `dispatcher!` when the `dispatch_tree`
 /// feature is enabled. Each call stores the node name into the global
 /// `COMPILE_TIME_DISPATCHERS` registry and generates a static variable for the
-/// dispatcher instance. This data is later consumed by [`gen_program!`] to
+/// dispatcher instance. This data is later consumed by `gen_program!` to
 /// generate a character-level **Trie** for efficient command dispatch.
 ///
 /// The trie dispatch works by grouping commands by their character prefix,
@@ -1167,7 +1167,7 @@ pub fn register_help(input: TokenStream) -> TokenStream {
 ///
 /// # See also
 ///
-/// - [`dispatcher!`] — The primary way to declare dispatchers (calls this internally).
+/// - `dispatcher!` — The primary way to declare dispatchers (calls this internally).
 /// - `dispatch_tree_gen` module — The trie generation logic.
 #[proc_macro]
 pub fn register_dispatcher(input: TokenStream) -> TokenStream {
@@ -1190,7 +1190,7 @@ pub fn register_dispatcher(input: TokenStream) -> TokenStream {
 /// 3. Keeping the original function for direct calls.
 ///
 /// Inside a `#[help]` function, you must manually create a `RenderResult`
-/// and return it. Use [`writeln!`](std::fmt::writeln) on the result to
+/// and return it. Use `writeln!` on the result to
 /// write help text.
 ///
 /// # Syntax
@@ -1234,13 +1234,13 @@ pub fn register_dispatcher(input: TokenStream) -> TokenStream {
 ///
 /// - The function must have exactly one parameter (the entry type to provide help for).
 /// - The parameter type must be a single-segment type path (e.g., `MyEntry`, not `other::MyEntry`).
-/// - The function must return [`RenderResult`].
+/// - The function must return `RenderResult`.
 /// - The function cannot be async.
 ///
 /// # See also
 ///
 /// - [`BasicProgramSetup`] — The setup that enables `--help` and `-h` flag processing.
-/// - [`RenderResult`] — The return type for help functions.
+/// - `RenderResult` — The return type for help functions.
 /// - [`#[chain]`](attr.chain.html) — For processing the dispatched entry after help.
 ///
 /// [`BasicProgramSetup`]: https://docs.rs/mingling/latest/mingling/setup/struct.BasicProgramSetup.html
@@ -1326,7 +1326,7 @@ pub fn derive_enum_tag(input: TokenStream) -> TokenStream {
     enum_tag::derive_enum_tag(input)
 }
 
-/// Derive macro for [`StructuralData`], marking a type as eligible for structured
+/// Derive macro for `StructuralData`, marking a type as eligible for structured
 /// structured output (JSON / YAML / TOML / RON).
 ///
 /// The type must also implement `serde::Serialize` — the generated
diff --git a/mingling_pathf/src/config.rs b/mingling_pathf/src/config.rs
index 6758264..1199b2c 100644
--- a/mingling_pathf/src/config.rs
+++ b/mingling_pathf/src/config.rs
@@ -1,3 +1,9 @@
+//! Configuration for the module pathfinder analysis.
+//!
+//! This module defines [`PathfinderConfig`], which controls behavior such as
+//! whether dispatch-tree related types (`__internal_dispatcher_*`) should be
+//! extracted.
+
 /// Configuration for the module pathfinder analysis.
 ///
 /// Controls behavior such as whether dispatch-tree related types
diff --git a/mingling_pathf/src/error.rs b/mingling_pathf/src/error.rs
index 513ec23..70a8f6e 100644
--- a/mingling_pathf/src/error.rs
+++ b/mingling_pathf/src/error.rs
@@ -1,3 +1,9 @@
+//! Errors that can occur during the pathfinding process for Rust module resolution.
+//!
+//! This module defines all possible failure modes when traversing the module graph
+//! of a Rust project, including I/O failures, missing modules, invalid path
+//! attributes, missing entry points, and syntax parsing errors.
+
 use std::fmt;
 use std::path::PathBuf;
 
diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs
index 81b2df6..557ae45 100644
--- a/mingling_pathf/src/lib.rs
+++ b/mingling_pathf/src/lib.rs
@@ -1,3 +1,6 @@
+#![allow(clippy::needless_doctest_main)]
+#![doc = include_str!("../README.md")]
+
 pub mod config;
 pub mod error;
 pub mod module_pathf;
diff --git a/mingling_pathf/src/module_pathf.rs b/mingling_pathf/src/module_pathf.rs
index c20fd82..f0a06d1 100644
--- a/mingling_pathf/src/module_pathf.rs
+++ b/mingling_pathf/src/module_pathf.rs
@@ -1,3 +1,9 @@
+//! A module for mapping Rust module paths to source files.
+//!
+//! This module provides functionality to analyze the module structure of a Rust crate
+//! and determine the effective module path for each source file, taking into account
+//! `pub use` re-exports that can cause modules to be hoisted to parent paths.
+
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use syn::{Item, UseTree};
diff --git a/mingling_pathf/src/pattern_analyzer.rs b/mingling_pathf/src/pattern_analyzer.rs
index c4b1971..3765971 100644
--- a/mingling_pathf/src/pattern_analyzer.rs
+++ b/mingling_pathf/src/pattern_analyzer.rs
@@ -1,3 +1,17 @@
+//! This module defines the core pattern analysis system used to parse and extract
+//! importable/referenceable items (like structs, enums, functions, etc.) from Rust source files.
+//!
+//! It provides a pluggable architecture via the `AnalyzePattern` trait, allowing different
+//! syntactic patterns to be registered and applied. Built-in patterns cover common structures
+//! such as basic structs, packs, groups, derives, chains, renderers, help, completion, and
+//! dispatch patterns (both standard and clap-based).
+//!
+//! The entry points are:
+//! - [`init()`] — creates a default `PatternAnalyzer` with all built-in patterns.
+//! - [`init_with_config()`] — creates a `PatternAnalyzer` with a given `PathfinderConfig`.
+//! - [`PatternAnalyzer::analyze_file()`] / [`PatternAnalyzer::analyze_file_items()`] — run
+//!   analysis on a single file.
+
 use std::collections::HashSet;
 use std::path::Path;
 
diff --git a/mingling_pathf/src/patterns.rs b/mingling_pathf/src/patterns.rs
index d0bda5d..9801e9b 100644
--- a/mingling_pathf/src/patterns.rs
+++ b/mingling_pathf/src/patterns.rs
@@ -1,3 +1,5 @@
+//! Mingling path matching patterns for command routing and field mapping.
+
 pub use basic_struct::*;
 pub use chain::*;
 pub use completion::*;
diff --git a/mingling_pathf/src/patterns/basic_struct.rs b/mingling_pathf/src/patterns/basic_struct.rs
index eeb665a..09e8e70 100644
--- a/mingling_pathf/src/patterns/basic_struct.rs
+++ b/mingling_pathf/src/patterns/basic_struct.rs
@@ -1,3 +1,7 @@
+//! The `BasicStructPattern` matches `struct` definitions in Rust source code.
+//! It identifies root-level structs and structs nested inside inline modules,
+//! returning their names and optional module path for analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/chain.rs b/mingling_pathf/src/patterns/chain.rs
index d64ed3b..6393440 100644
--- a/mingling_pathf/src/patterns/chain.rs
+++ b/mingling_pathf/src/patterns/chain.rs
@@ -1,3 +1,7 @@
+//! The `ChainPattern` matches functions annotated with `#[chain]` and
+//! extracts the generated internal struct name (e.g., `__internal_chain_<fn_name>`).
+//! This is used to track chained handler functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/completion.rs b/mingling_pathf/src/patterns/completion.rs
index ff20e0f..5427b93 100644
--- a/mingling_pathf/src/patterns/completion.rs
+++ b/mingling_pathf/src/patterns/completion.rs
@@ -1,3 +1,7 @@
+//! The `CompletionPattern` matches functions annotated with `#[completion(T)]` and
+//! extracts the generated internal struct name (e.g., `__internal_completion_<fn_name>`).
+//! This is used to track completion handler functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/dispatcher.rs b/mingling_pathf/src/patterns/dispatcher.rs
index b9f147d..6796a2c 100644
--- a/mingling_pathf/src/patterns/dispatcher.rs
+++ b/mingling_pathf/src/patterns/dispatcher.rs
@@ -1,3 +1,16 @@
+//! The `DispatcherPattern` matches invocations of the `dispatcher!` macro and
+//! extracts the generated type names from its arguments. It supports:
+//! - `Entry*` — the entry type (always generated)
+//! - `CMD*` — the dispatcher struct (always generated)
+//! - `__internal_dispatcher_*` — the dispatch tree static (when `use_dispatch_tree` is `true`)
+//!
+//! Supported forms:
+//! - Explicit: `dispatcher!("greet", CMDGreet => EntryGreet)`
+//! - Implicit: `dispatcher!("greet")` — infers `CMDGreet` and `EntryGreet`
+//! - With braces: `dispatcher! { ... }`
+//!
+//! This pattern is used to track dispatcher types for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/dispatcher_clap.rs b/mingling_pathf/src/patterns/dispatcher_clap.rs
index 2e1ec6c..1a86ad5 100644
--- a/mingling_pathf/src/patterns/dispatcher_clap.rs
+++ b/mingling_pathf/src/patterns/dispatcher_clap.rs
@@ -1,3 +1,17 @@
+//! The `DispatcherClapPattern` matches structs annotated with `#[dispatcher_clap(...)]` and
+//! extracts key items for code generation or analysis:
+//! - The entry struct name (always)
+//! - The dispatcher command struct (`CMD*`, always)
+//! - The error type, if `error = ErrorType` is specified
+//! - The help internal struct, if `help = true` is specified
+//! - The `__internal_dispatcher_*` dispatch tree static, if `use_dispatch_tree` is enabled
+//!
+//! Supported forms:
+//! - `#[dispatcher_clap("greet", CMDGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, help = true)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet, help = true)] struct EntryGreet { ... }`
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/group.rs b/mingling_pathf/src/patterns/group.rs
index 99d1137..0e4b50d 100644
--- a/mingling_pathf/src/patterns/group.rs
+++ b/mingling_pathf/src/patterns/group.rs
@@ -1,3 +1,7 @@
+//! The `GroupPattern` matches the `group!` and `group_structural!` macros and
+//! extracts the type name or alias defined within them.
+//! This is used to track type groups for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/groupped_derive.rs b/mingling_pathf/src/patterns/groupped_derive.rs
index 8491121..91daaef 100644
--- a/mingling_pathf/src/patterns/groupped_derive.rs
+++ b/mingling_pathf/src/patterns/groupped_derive.rs
@@ -1,3 +1,8 @@
+//! The `GrouppedDerivePattern` matches structs, enums, and unions annotated with
+//! `#[derive(Groupped)]` or `#[derive(GrouppedSerialize)]` (or any combination
+//! with other derives). It also recurses into `mod` items to find nested types.
+//! This is used to track grouped items for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/help.rs b/mingling_pathf/src/patterns/help.rs
index 02bfa4f..628f4ac 100644
--- a/mingling_pathf/src/patterns/help.rs
+++ b/mingling_pathf/src/patterns/help.rs
@@ -1,3 +1,7 @@
+//! The `HelpPattern` matches functions annotated with `#[help]` and
+//! extracts the generated internal struct name (e.g., `__internal_help_<fn_name>`).
+//! This is used to track help functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/pack.rs b/mingling_pathf/src/patterns/pack.rs
index 83c1cee..c80fb65 100644
--- a/mingling_pathf/src/patterns/pack.rs
+++ b/mingling_pathf/src/patterns/pack.rs
@@ -1,3 +1,7 @@
+//! The `PackPattern` matches types defined by `pack!`, `pack_err!`, `pack_structural!`, and `pack_err_structural!` macros.
+//! It extracts the registered type name (e.g., `TypeName` from `pack!(TypeName = InnerType)`).
+//! This is used to track packed type definitions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/renderer.rs b/mingling_pathf/src/patterns/renderer.rs
index 054769e..c2e9ca9 100644
--- a/mingling_pathf/src/patterns/renderer.rs
+++ b/mingling_pathf/src/patterns/renderer.rs
@@ -1,3 +1,7 @@
+//! The `RendererPattern` matches functions annotated with `#[renderer]` and
+//! extracts the generated internal struct name (e.g., `__internal_renderer_<fn_name>`).
+//! This is used to track rendering functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/type_mapping_builder.rs b/mingling_pathf/src/type_mapping_builder.rs
index 3422af8..0965b47 100644
--- a/mingling_pathf/src/type_mapping_builder.rs
+++ b/mingling_pathf/src/type_mapping_builder.rs
@@ -1,3 +1,7 @@
+//! This module contains the matching patterns for `mingling_pathf`.
+//! It provides the core logic for analyzing crate types and generating
+//! type mapping files used by the pathfinder system.
+
 use std::collections::HashSet;
 use std::path::Path;
 
diff --git a/mingling_picker/README.md b/mingling_picker/README.md
index c83bff4..db67825 100644
--- a/mingling_picker/README.md
+++ b/mingling_picker/README.md
@@ -22,15 +22,20 @@ mingling_picker = "0.3.0"
 Provides a clean chained-call API for declaring arguments to parse:
 
 ```rust
+use mingling_picker::prelude::*;
+
 let args: Vec<&str> = vec!["--name", "Bob", "--age", "24"];
-let result = args
-    .pick(&flag![name: String])
+
+let (name, age) = args
+    .pick(&arg![name: String])
     .or(|| "Alice".to_string())
-    .pick(&flag![age: i32])
+    .pick(&arg![age: i32])
     .or(|| 24)
     .post(|num| num.clamp(0, 120))
-    .parse();
-let (name, age): (String, i32) = a.unwrap();
+    .unwrap();
+
+assert_eq!(name, "Bob".to_string());
+assert_eq!(age, 24);
 ```
 
 ## Parsing Function Library
@@ -38,5 +43,5 @@ let (name, age): (String, i32) = a.unwrap();
 Provides a pure function library `parselib` for analyzing the structure of command-line arguments.
 
 ```rust
-use mingling::picker::parselib::*;
+use mingling_picker::parselib::*;
 ```
diff --git a/mingling_picker/src/lib.rs b/mingling_picker/src/lib.rs
index afc7aca..ffa6e13 100644
--- a/mingling_picker/src/lib.rs
+++ b/mingling_picker/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod builtin;
 
 mod picker;
@@ -12,16 +14,28 @@ pub use arg::*;
 mod infos;
 pub use infos::*;
 
+/// Provides the specific parsing logic for command-line arguments and common utilities,
+/// as well as customization of command-line argument styles.
 pub mod parselib;
 
+/// Parser-provided parseable command-line types
 pub mod value;
 
+/// The prelude module, which re-exports the most commonly used traits and types.
+///
+/// This module is intended to be imported with a wildcard import:
+///
+/// ```ignore
+/// use mingling_picker::prelude::*;
+/// ```
 pub mod prelude {
     pub use crate::IntoPicker;
+    pub use crate::macros::arg;
 }
 
+/// Re-export of the `mingling_picker_macros` crate
 pub mod macros {
-    pub use mingling_picker_macros::*;
+    pub use mingling_picker_macros::arg;
 }
 
 /// Provides the types necessary for implementing the `Pickable` trait
diff --git a/mingling_picker/src/parselib/style.rs b/mingling_picker/src/parselib/style.rs
index 4ea161f..3c37b2d 100644
--- a/mingling_picker/src/parselib/style.rs
+++ b/mingling_picker/src/parselib/style.rs
@@ -109,25 +109,58 @@ impl<'a> From<&'a String> for FlagStr<'a> {
     }
 }
 
+/// Defines the naming convention for command-line option names.
+///
+/// Each variant represents a different case format that can be applied
+/// to option names (e.g., long option names) during parsing or generation.
+///
+/// # Examples
+///
+/// ```
+/// # use mingling_picker::IntoPicker;
+/// use mingling_picker::parselib::ParserStyleNamingCase;
+///
+/// let case = ParserStyleNamingCase::Kebab;
+/// assert_eq!(
+///     case.convert("brew_coffee".to_string()),
+///     "brew-coffee".to_string()
+/// );
+/// ```
 #[repr(u8)]
 #[derive(Default, Clone, Copy, PartialEq, Eq)]
 pub enum ParserStyleNamingCase {
-    /// snake_case format (e.g., `brew_coffee`)
+    /// snake_case format: words are separated by underscores, all lowercase.
+    ///
+    /// Example: `brew_coffee`
     #[default]
     Snake,
-    /// camelCase format (e.g., `brewCoffee`)
+    /// camelCase format: first word is lowercase, subsequent words are capitalized.
+    ///
+    /// Example: `brewCoffee`
     Camel,
-    /// PascalCase format (e.g., `BrewCoffee`)
+    /// PascalCase format: every word starts with an uppercase letter.
+    ///
+    /// Example: `BrewCoffee`
     Pascal,
-    /// kebab-case format (e.g., `brew-coffee`)
+    /// kebab-case format: words are separated by hyphens, all lowercase.
+    ///
+    /// Example: `brew-coffee`
     Kebab,
-    /// dot.case format (e.g., `brew.coffee`)
+    /// dot.case format: words are separated by dots, all lowercase.
+    ///
+    /// Example: `brew.coffee`
     Dot,
-    /// Title Case format (e.g., `Brew Coffee`)
+    /// Title Case format: words are separated by spaces, each word capitalized.
+    ///
+    /// Example: `Brew Coffee`
     Title,
-    /// lower case format (e.g., `brew coffee`)
+    /// lower case format: words are separated by spaces, all lowercase.
+    ///
+    /// Example: `brew coffee`
     Lower,
-    /// UPPER CASE format (e.g., `BREW COFFEE`)
+    /// UPPER CASE format: words are separated by spaces, all uppercase.
+    ///
+    /// Example: `BREW COFFEE`
     Upper,
 }
 
diff --git a/mingling_picker/src/parselib/utils.rs b/mingling_picker/src/parselib/utils.rs
index 726346c..47c5b55 100644
--- a/mingling_picker/src/parselib/utils.rs
+++ b/mingling_picker/src/parselib/utils.rs
@@ -3,6 +3,11 @@ use crate::{
     parselib::{MaskedArg, ParserStyle},
 };
 
+/// Builds a list of possible flag strings for the given argument info
+///
+/// This function generates formatted flag strings (e.g., `-h`, `--help`) from the short flag,
+/// long flag, and any aliases defined in the argument info. The long flag and alias names
+/// are converted according to the style's naming case convention before being formatted.
 #[inline(always)]
 pub fn build_possible_flags(style: &ParserStyle, arg_info: &PickerArgInfo) -> Vec<String> {
     let mut possible_flags = vec![];
diff --git a/mingling_picker_macros/README.md b/mingling_picker_macros/README.md
index e69de29..5a3f220 100644
--- a/mingling_picker_macros/README.md
+++ b/mingling_picker_macros/README.md
@@ -0,0 +1,40 @@
+# Mingling Picker Macros
+
+Procedural macros for [Mingling Picker](https://github.com/mingling-rs/mingling/tree/main/mingling_picker), enabled by the `mingling/picker` feature.
+
+```toml
+[dependencies.mingling]
+version = "0.3.0"
+features = [
+    "picker"
+]
+```
+
+## Provided Macros
+
+### Macro `arg!`
+
+Declares a parameter definition for use with `Picker`'s `.pick()` method:
+
+```rust,ignore
+use mingling_picker_macros::arg;
+
+// Named flag with a value
+let flag = arg![name: String];
+
+// Named flag with short form
+let flag = arg![name: String, 'n'];
+
+// Named flag with alias
+let flag = arg![name: String, 'n', "nickname"];
+
+// Positional parameter
+let flag = arg![String];
+
+// Flag-only parameter (boolean)
+let flag = arg![verbose: Flag];
+```
+
+### Macro `internal_repeat!` (Internal)
+
+Internal macro used by Picker to generate `PickerPattern1..=32` and their parsing logic. Not intended for direct use.
diff --git a/mingling_picker_macros/src/lib.rs b/mingling_picker_macros/src/lib.rs
index 33bb67d..a12e3ed 100644
--- a/mingling_picker_macros/src/lib.rs
+++ b/mingling_picker_macros/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 use proc_macro::TokenStream;
 
 mod arg;