docs(readme): rewrite with clearer examples and structure

Author: zigai

README.md

@@ -6,18 +6,16 @@
 [![Downloads](https://static.pepy.tech/badge/interfacy)](https://pepy.tech/project/interfacy)
 [![license](https://img.shields.io/github/license/zigai/interfacy.svg)](https://github.com/zigai/interfacy/blob/main/LICENSE)
 
-Interfacy is a CLI framework for building command-line interfaces from Python functions, classes, and class instances using type annotations and docstrings.
+Interfacy is a CLI framework that turns Python functions, classes, and class instances into command-line interfaces. It derives the CLI from signatures, type annotations, and docstrings instead of making you define it twice.
 
 ## Features
 
-- Generate CLIs from functions, class methods, or class instances.
-- Nested subcommands and command groups with aliases.
-- Type inference from annotations, with support for custom parsers.
+- Generate CLIs from functions, classes, class methods, and class instances.
+- Nested subcommands and manual command groups with aliases.
+- Type-driven parsing from annotations, with support for custom parsers.
+- Model expansion for dataclasses, Pydantic models, and plain classes.
 - `--help` text generated from docstrings.
-- Run a target function, class, or class instance directly from the CLI (e.g. `interfacy path.py:main`).
-- Multiple help layouts and color themes.
-- Optional class initializer arguments exposed as CLI options.
-- Argparse-compatible backend, including a drop-in `ArgumentParser` replacement.
+- Highly customizable help output with multiple layouts, color themes, and configurable ordering.
 - Stdin piping support with configurable routing to parameters.
 - Optional tab completion via `argcomplete`.
 
@@ -43,114 +41,119 @@ pip install git+https://github.com/zigai/interfacy.git
 uv add "git+https://github.com/zigai/interfacy.git"
 ```
 
-## Quick start
+## First CLI
 
 ```python
 from interfacy import Argparser
 
-def greet(name: str, times: int = 1) -> None:
-    for _ in range(times):
-        print(f"Hello, {name}!")
+def greet(name: str, times: int = 1) -> str:
+    """Return a greeting."""
+    return " ".join([f"Hello, {name}!" for _ in range(times)])
 
 if __name__ == "__main__":
-    Argparser().run(greet)
+    Argparser(print_result=True).run(greet)
+```
+
+```text
+$ python app.py Ada
+Hello, Ada!
+
+$ python app.py Ada --times 2
+Hello, Ada! Hello, Ada!
+```
+
+By default, required non-boolean parameters become positional arguments and optional parameters become flags.
+
+## Class-Based Commands
+
+Classes become command namespaces. `__init__` parameters live at the command level and public methods become subcommands.
+
+```python
+from interfacy import Argparser
+
+class Calculator:
+    def __init__(self, precision: int = 2) -> None:
+        self.precision = precision
+
+    def add(self, a: float, b: float) -> float:
+        return round(a + b, self.precision)
+
+    def mul(self, a: float, b: float) -> float:
+        return round(a * b, self.precision)
+
+if __name__ == "__main__":
+    Argparser(print_result=True).run(Calculator)
+```
+
+```text
+$ python app.py --precision 3 add 1.25 2.75
+4.0
 ```
 
-## Classes as flags
+## Structured Parameters
+
+Dataclasses, Pydantic models, and plain classes with typed `__init__` parameters can be expanded into nested flags and reconstructed before execution.
 
 ```python
 from dataclasses import dataclass
 from interfacy import Argparser
 
 @dataclass
 class Address:
-    """Mailing address data for a user.
-
-    Args:
-        city: City name.
-        zip: Postal or ZIP code.
-    """
     city: str
-    zip: int
+    postal_code: int
 
 @dataclass
 class User:
-    """User profile information for the CLI.
-
-    Args:
-        name: Display name.
-        age: Age in years.
-        address: Optional mailing address details.
-    """
     name: str
     age: int
     address: Address | None = None
 
 def greet(user: User) -> str:
-    if user.address is None:
-        return f"Hello {user.name}, age {user.age}"
-    return f"Hello {user.name}, age {user.age} from {user.address.city} {user.address.zip}"
+    return f"Hello {user.name}, age {user.age}"
 
 if __name__ == "__main__":
     Argparser(print_result=True).run(greet)
 ```
 
-Help output:
-
 ```text
-usage: app.py greet [--help] --user.name USER.NAME --user.age USER.AGE
-                    [--user.address.city] [--user.address.zip]
-
-options:
-  --help                      show this help message and exit
-  --user.name                 Display name. [type: str] (*)
-  --user.age                  Age in years. [type: int] (*)
-  --user.address.city         City name. [type: str]
-  --user.address.zip          Postal or ZIP code. [type: int]
+$ python app.py --user.name Ada --user.age 32
+Hello Ada, age 32
 ```
 
-## Class-based commands
+## Manual Groups
+
+Use `CommandGroup` when your command tree is not naturally rooted in one callable:
 
 ```python
-from interfacy import Argparser
+from interfacy import Argparser, CommandGroup
 
-class Calculator:
-    def add(self, a: int, b: int) -> int:
-        return a + b
+def clone(url: str) -> str:
+    return f"clone:{url}"
+
+class Releases:
+    def cut(self, version: str) -> str:
+        return f"cut:{version}"
 
-    def mul(self, a: int, b: int) -> int:
-        return a * b
+ops = CommandGroup("ops", description="Operational commands")
+ops.add_command(clone)
+ops.add_command(Releases)
 
 if __name__ == "__main__":
-    Argparser(print_result=True).run(Calculator)
+    Argparser(print_result=True).run(ops)
 ```
 
-## Decorator-based commands
-
-```python
-from interfacy import Argparser
-
-parser = Argparser()
+## Interfacy CLI Entrypoint
 
-@parser.command()
-def greet(name: str) -> str:
-    return f"Hello, {name}!"
+Interfacy also ships a CLI that can run an existing function, class, or class instance directly from a module or Python file:
 
-@parser.command(name="calc", aliases=["c"])
-class Calculator:
-    def add(self, a: int, b: int) -> int:
-        return a + b
-
-    def mul(self, a: int, b: int) -> int:
-        return a * b
-
-if __name__ == "__main__":
-    parser.run()
+```text
+$ interfacy app.py:greet Ada
+$ interfacy app.py:greet --help
+$ interfacy package.cli:Calculator add 1 2
 ```
 
-## CLI entrypoint
-
-Use the CLI entrypoint to run a target function, class, or class instance from a module or file, or to inspect its help:
+The entrypoint supports configuration via TOML, loaded from `~/.config/interfacy/config.toml` or `INTERFACY_CONFIG`.
 
 ```text
 usage: interfacy [--help] [--version] [--config-paths] [TARGET] ...