micforge 1.3.0__py3-none-any.whl

micforge/commands/doctor.py

@@ -0,0 +1,127 @@
+"""`doctor`: environment, device and performance checks with fix-it hints."""
+from __future__ import annotations
+
+import platform
+import sys
+import time
+
+import numpy as np
+from rich import box
+from rich.table import Table
+
+from ..audio.backend import get_sd
+from ..audio.devices import detect_virtual_output, find_device, list_devices
+from ..config import AppConfig
+from ..dsp.chain import process_offline
+from ..errors import MicforgeError
+from ..ui.theme import console
+from .common import make_chain
+
+OK, WARN, BAD = "[green]✔[/]", "[yellow]![/]", "[red]✖[/]"
+
+CABLE_HELP = {
+    "win32": "Install VB-CABLE (free): https://vb-audio.com/Cable/ - reboot, then re-run `micforge setup`.",
+    "darwin": "Install BlackHole 2ch: `brew install blackhole-2ch` - then re-run `micforge setup`.",
+    "linux": "Create a virtual sink: `pactl load-module module-null-sink sink_name=micforge` "
+    "- Discord then uses 'Monitor of micforge' as its mic.",
+}
+
+
+def run_doctor(app: AppConfig, export: bool = False, export_path: str | None = None) -> int:
+    t = Table(box=box.SIMPLE_HEAD, header_style="bold cyan", show_lines=False)
+    t.add_column("", width=2)
+    t.add_column("check")
+    t.add_column("result")
+    problems = 0
+
+    def row(mark: str, name: str, result: str) -> None:
+        t.add_row(mark, name, result)
+
+    row(OK if sys.version_info >= (3, 10) else BAD, "python", f"{platform.python_version()} on {platform.system()}")
+    try:
+        import scipy
+        row(OK, "numpy / scipy", f"{np.__version__} / {scipy.__version__}")
+    except ImportError:
+        row(BAD, "scipy", "missing - pip install scipy")
+        problems += 1
+
+    try:
+        sd = get_sd()
+        row(OK, "PortAudio", str(sd.get_portaudio_version()[1]))
+    except MicforgeError as exc:
+        row(BAD, "PortAudio", f"{exc} {exc.hint or ''}")
+        console.print(t)
+        return 1
+
+    pool = list_devices(all_apis=True)
+    try:
+        mic = find_device(app.input_device, "input", pool)
+        row(OK, "microphone", f"{mic.name} [{mic.hostapi}]")
+        try:
+            sd.check_input_settings(device=mic.index, channels=1, samplerate=app.sample_rate)
+            row(OK, f"mic @ {app.sample_rate} Hz", "supported")
+        except Exception as exc:  # noqa: BLE001
+            row(WARN, f"mic @ {app.sample_rate} Hz", f"not accepted ({exc}); WASAPI auto-convert may still work, or try 44100")
+    except MicforgeError as exc:
+        row(BAD, "microphone", str(exc))
+        problems += 1
+
+    cable = detect_virtual_output(pool) if app.output_device is None else None
+    if app.output_device is not None:
+        try:
+            cable = find_device(app.output_device, "output", pool)
+        except MicforgeError as exc:
+            row(BAD, "virtual cable", str(exc))
+            problems += 1
+    if cable:
+        row(OK, "virtual cable", cable.name)
+    elif app.output_device is None:
+        row(BAD, "virtual cable", "none found - " + CABLE_HELP.get(sys.platform if sys.platform in CABLE_HELP else "linux", ""))
+        problems += 1
+
+    try:
+        hp = find_device(app.monitor_device, "output", pool)
+        row(OK, "headphones / monitor", hp.name)
+    except MicforgeError as exc:
+        row(WARN, "headphones / monitor", str(exc))
+
+    from ..dsp.cofilite import find_model_file
+    model_file = find_model_file(app.denoise_model)
+    if model_file:
+        row(OK, "denoise model", f"CoFi-Lite ({model_file.name}, {model_file.stat().st_size / 1024:.0f} KB) [<100MB RAM]")
+    else:
+        row(OK, "denoise model", "Spectral Wiener (classical fallback)")
+
+    chain, _ = make_chain(app, app.preset)
+    x = (np.random.default_rng(0).standard_normal(app.sample_rate * 2) * 0.05).astype(np.float32)
+    process_offline(chain, x[: app.sample_rate // 2], app.block_size)  # warm-up (numpy/FFT plan caches)
+    chain, _ = make_chain(app, app.preset)
+    t0 = time.perf_counter()
+    process_offline(chain, x, app.block_size)
+    rt = (x.shape[0] / app.sample_rate) / (time.perf_counter() - t0)
+    row(OK if rt > 5 else WARN if rt > 2 else BAD, "dsp speed", f"{rt:.0f}x realtime ({100 / rt:.1f}% of one core)")
+    if rt <= 2:
+        problems += 1
+    row(OK, "latency (dsp only)", f"{chain.latency_samples / app.sample_rate * 1000:.1f} ms")
+
+    console.print(t)
+    console.print(
+        "[bold]Discord checklist:[/] Input Device = cable's recording end · Noise Suppression: None · "
+        "Automatic Gain Control: off · Echo Cancellation: off · Input Sensitivity: manual, low."
+    )
+    console.print(
+        "[bold]Windows tip:[/] Sound settings → your mic → Properties → Advanced: turn off 'Audio Enhancements' "
+        "and exclusive mode, or other apps can fight for the mic."
+    )
+    console.print(
+        "[dim]📖 Troubleshooting guide:[/] [bold cyan]docs/TROUBLESHOOTING.md[/]"
+    )
+
+    if export or export_path:
+        from pathlib import Path
+        from ..diagnostics import collect_diagnostics, export_diagnostics_zip
+        report = collect_diagnostics(app)
+        out_zip = export_diagnostics_zip(report, Path(export_path) if export_path else None)
+        console.print(f"\n[bold green]✔ Diagnostics exported to:[/] [white]{out_zip}[/]")
+
+    return 1 if problems else 0

micforge/commands/files.py

@@ -0,0 +1,48 @@
+"""`process` and `analyze`: offline work on WAV files."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from ..analysis.stats import analyze, band_levels_db, diagnose
+from ..audio.fileio import read_wav, write_wav
+from ..config import AppConfig
+from ..dsp.chain import process_offline
+from ..errors import MicforgeError
+from ..ui.report import full_report
+from ..ui.theme import console
+from .common import make_chain
+
+
+def run_process(app: AppConfig, src: str, dst: str, preset: str | None) -> None:
+    preset = preset or app.preset
+    if not Path(src).is_file():
+        raise MicforgeError(f"File not found: {src}")
+    x, sr = read_wav(src, target_rate=app.sample_rate)
+    chain, _ = make_chain(app, preset)
+    dn = chain.stage("denoise")
+    if dn is not None and getattr(dn, "profile", None) is None:
+        try:  # no saved profile: use the quietest 1 s of the file as the noise reference
+            import numpy as np
+            fr = int(0.1 * sr)
+            n = x.shape[0] // fr
+            lv = np.mean(x[: n * fr].reshape(n, fr) ** 2, axis=1)
+            i = int(np.argmin(np.convolve(lv, np.ones(10) / 10, mode="valid")))
+            dn.learn(x[i * fr : i * fr + 10 * fr])  # type: ignore[attr-defined]
+        except (ValueError, IndexError):
+            pass
+    with Progress(SpinnerColumn(), TextColumn("processing…"), console=console, transient=True):
+        y = process_offline(chain, x, app.block_size)
+    write_wav(dst, y, sr)
+    console.print(f"[green]✔ Wrote {dst}[/]  (preset: {preset})")
+    b, a = analyze(x, sr), analyze(y, sr)
+    console.print(full_report(b, a, band_levels_db(x, sr), band_levels_db(y, sr), diagnose(a)))
+
+
+def run_analyze(app: AppConfig, src: str) -> None:
+    if not Path(src).is_file():
+        raise MicforgeError(f"File not found: {src}")
+    x, sr = read_wav(src)
+    s = analyze(x, sr)
+    console.print(full_report(s, None, findings=diagnose(s)))

micforge/commands/help_cmd.py

@@ -0,0 +1,449 @@
+"""Interactive, dynamic command-line help and usage reference for Micforge."""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from rich import box
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .. import __version__
+from ..ui.theme import console
+
+
+# Enhanced metadata enriching argparse introspection with practical examples and tips
+COMMAND_METADATA: dict[str, dict[str, Any]] = {
+    "run": {
+        "category": "🎙️ Live Real-Time Audio",
+        "headline": "Start the real-time DSP rack, virtual cable routing, and live HUD.",
+        "examples": [
+            ("Start streaming with default settings", "micforge run"),
+            ("Use gaming preset with 128-sample low latency", "micforge run -p gaming --block 128"),
+            ("Listen to your processed voice in headphones", "micforge run --monitor"),
+            ("Run silently in system tray without terminal", "micforge run --tray"),
+        ],
+        "tips": [
+            "Press [Tab] anytime during live streaming to toggle the ultra-clean Gamer HUD.",
+            "Press [b] to toggle bypass and [x] to mute your microphone.",
+            "In Discord or OBS, remember to select 'CABLE Output' as your recording mic.",
+        ],
+    },
+    "loopback": {
+        "category": "🎙️ Live Real-Time Audio",
+        "headline": "Hear yourself live with instant A/B raw vs. processed comparison.",
+        "examples": [
+            ("Start loopback monitor on default headphones", "micforge loopback"),
+            ("Test warm broadcast preset", "micforge loopback -p broadcast"),
+            ("Specify headphones device explicitly", "micforge loopback --out \"Headphones\""),
+        ],
+        "tips": [
+            "Use headphones to prevent feedback howling.",
+            "Press [b] to toggle instant A/B comparison between raw mic and processed audio.",
+        ],
+    },
+    "test": {
+        "category": "🎙️ Live Real-Time Audio",
+        "headline": "Record a voice sample, show before/after spectral metrics, and play both.",
+        "examples": [
+            ("Record 8 seconds test sample", "micforge test"),
+            ("Quick 4-second test with podcast preset", "micforge test -p podcast -s 4"),
+        ],
+        "tips": [
+            "Speak naturally with background noise (fans/typing) to judge noise reduction quality.",
+        ],
+    },
+    "setup": {
+        "category": "🛠️ Hardware, Calibration & Latency",
+        "headline": "Interactive setup wizard to select microphone, virtual cable, and headphones.",
+        "examples": [
+            ("Launch interactive device setup", "micforge setup"),
+        ],
+        "tips": [
+            "On Windows, always pick the WASAPI endpoints for the lowest latency and clock stability.",
+        ],
+    },
+    "devices": {
+        "category": "🛠️ Hardware, Calibration & Latency",
+        "headline": "List all detected audio hardware, default endpoints, and host APIs.",
+        "examples": [
+            ("List standard devices", "micforge devices"),
+            ("List all audio host APIs (WASAPI, MME, DirectSound)", "micforge devices --all"),
+        ],
+        "tips": [
+            "Use device index numbers (e.g. --mic 1) or matching substrings (e.g. --mic Realtek).",
+        ],
+    },
+    "calibrate": {
+        "category": "🛠️ Hardware, Calibration & Latency",
+        "headline": "Learn your room silence for 3–5s to configure noise floor and gate threshold.",
+        "examples": [
+            ("Perform standard room calibration", "micforge calibrate"),
+            ("Calibrate for 6 seconds", "micforge calibrate -s 6"),
+            ("Reset calibration back to factory baseline", "micforge calibrate --reset"),
+        ],
+        "tips": [
+            "Stay silent and keep PC fans running normally while calibrating.",
+        ],
+    },
+    "profile": {
+        "category": "🛠️ Hardware, Calibration & Latency",
+        "headline": "Manage voice-aware noise profiles and acoustic environments.",
+        "examples": [
+            ("List all available noise profiles", "micforge profile list"),
+            ("Inspect fan noise profile details", "micforge profile show fan_on"),
+            ("Switch active environment to mechanical keyboard", "micforge profile switch mechanical_keyboard"),
+            ("Trigger immediate quiet-room relearn", "micforge profile relearn"),
+        ],
+        "tips": [
+            "Continuous learning adapts slowly (≤1 dB/s) and never learns when you speak.",
+            "Switch to 'fan_on' during heavy gaming sessions when PC fans ramp up.",
+        ],
+    },
+    "latency": {
+        "category": "🛠️ Hardware, Calibration & Latency",
+        "headline": "Measure physical end-to-end loopback latency with logarithmic chirp.",
+        "examples": [
+            ("Run standard loopback latency benchmark", "micforge latency"),
+            ("Benchmark specific mic and headphones", "micforge latency --mic 1 --out 2"),
+        ],
+        "tips": [
+            "Uses a 60ms acoustic chirp cross-correlation with sub-millisecond precision.",
+            "Provides tailored tuning tips for buffer sizes and Windows WASAPI settings.",
+        ],
+    },
+    "settings": {
+        "category": "🎛️ Tuning, Presets & Studio GUI",
+        "headline": "Open native multi-tab Control Center (Simple/Advanced DSP, Hotkeys, Devices).",
+        "examples": [
+            ("Open Settings GUI", "micforge settings"),
+            ("Alias command", "micforge hotkeys"),
+        ],
+        "tips": [
+            "Features Simple Mode (4 macro knobs: Clarity, Warmth, Noise Removal, Room Cleanup).",
+            "Includes one-click '📦 Export Diagnostics (.zip)' in the Routing & System tab.",
+        ],
+    },
+    "hotkeys": {
+        "category": "🎛️ Tuning, Presets & Studio GUI",
+        "headline": "Alias for 'settings' — configure global hotkeys, audio cues, and startup.",
+        "examples": [
+            ("Open Settings and Hotkeys GUI", "micforge hotkeys"),
+        ],
+        "tips": [
+            "Hotkeys work system-wide even when full-screen games or Discord have focus.",
+        ],
+    },
+    "preset": {
+        "category": "🎛️ Tuning, Presets & Studio GUI",
+        "headline": "List, inspect, clone, export, and manage DSP chain presets.",
+        "examples": [
+            ("List all available presets", "micforge preset list"),
+            ("Inspect 'discord' preset settings", "micforge preset show discord"),
+            ("Clone 'gaming' into a new custom preset", "micforge preset save my_stream --from gaming"),
+            ("Export custom preset to JSON file", "micforge preset export my_stream ~/preset.json"),
+            ("Import preset from JSON file", "micforge preset import ~/preset.json"),
+        ],
+        "tips": [
+            "Built-in presets (discord, gaming, podcast, noisy_room) are immutable and safe.",
+        ],
+    },
+    "presets": {
+        "category": "🎛️ Tuning, Presets & Studio GUI",
+        "headline": "Quick alias to list presets or print preset details.",
+        "examples": [
+            ("List all presets", "micforge presets"),
+            ("Print preset configuration", "micforge presets podcast"),
+        ],
+        "tips": [],
+    },
+    "process": {
+        "category": "📁 Offline File Audio Processing",
+        "headline": "Process an offline WAV audio file through the 11-stage DSP rack.",
+        "examples": [
+            ("Process raw recording", "micforge process raw.wav clean.wav"),
+            ("Process with broadcast preset", "micforge process voice.wav out.wav -p broadcast"),
+        ],
+        "tips": [
+            "Supports 16-bit, 24-bit, and 32-bit float WAV audio at any sample rate.",
+        ],
+    },
+    "analyze": {
+        "category": "📁 Offline File Audio Processing",
+        "headline": "Analyze a WAV audio file (loudness, SNR, clarity, spectral profile).",
+        "examples": [
+            ("Inspect audio quality of recording", "micforge analyze recording.wav"),
+        ],
+        "tips": [
+            "Reports RMS energy, peak ceiling, dynamic crest factor, and acoustic suggestions.",
+        ],
+    },
+    "doctor": {
+        "category": "🩺 Diagnostics, Models & System",
+        "headline": "Health check for audio drivers, buffer speed, and redacted .zip diagnostics.",
+        "examples": [
+            ("Run doctor health assessment", "micforge doctor"),
+            ("Export complete redacted diagnostic .zip bundle", "micforge doctor --export"),
+            ("Export to specific file destination", "micforge doctor --export ~/diag.zip"),
+        ],
+        "tips": [
+            "Automatically sanitizes passwords, tokens, API keys, URLs, and home paths.",
+            "Links directly to docs/TROUBLESHOOTING.md for instant fix instructions.",
+        ],
+    },
+    "model": {
+        "category": "🩺 Diagnostics, Models & System",
+        "headline": "Inspect active CoFi-Lite neural speech model or export PyTorch weights to ONNX.",
+        "examples": [
+            ("Show active neural model status & RAM footprint", "micforge model info"),
+            ("Export PyTorch checkpoint to ONNX", "micforge model export checkpoint.tar model.onnx"),
+        ],
+        "tips": [
+            "Micforge bundles an ultra-compact ~83k parameter CoFi-Lite model requiring <100MB RAM.",
+        ],
+    },
+    "version": {
+        "category": "🩺 Diagnostics, Models & System",
+        "headline": "Display Micforge version, model status, and runtime environment.",
+        "examples": [
+            ("Show version info", "micforge version"),
+        ],
+        "tips": [],
+    },
+    "help": {
+        "category": "🩺 Diagnostics, Models & System",
+        "headline": "Display dynamic, categorized command reference and deep-dive usage guides.",
+        "examples": [
+            ("Show complete categorized command table", "micforge help"),
+            ("Deep dive into a specific command", "micforge help run"),
+            ("Inspect latency test options", "micforge help latency"),
+        ],
+        "tips": [
+            "Type 'micforge help <command>' anytime to see full arguments, flags, and pro tips.",
+        ],
+    },
+}
+
+CATEGORIES_ORDER = [
+    "🎙️ Live Real-Time Audio",
+    "🛠️ Hardware, Calibration & Latency",
+    "🎛️ Tuning, Presets & Studio GUI",
+    "📁 Offline File Audio Processing",
+    "🩺 Diagnostics, Models & System",
+]
+
+
+def _extract_parser_info(parser: argparse.ArgumentParser) -> dict[str, Any]:
+    """Dynamically introspect an argparse ArgumentParser."""
+    subparsers_action = None
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            subparsers_action = action
+            break
+
+    commands_info: dict[str, dict[str, Any]] = {}
+    if not subparsers_action:
+        return commands_info
+
+    for cmd_name, subparser in subparsers_action.choices.items():
+        # Get positional arguments and options
+        positionals: list[dict[str, Any]] = []
+        options: list[dict[str, Any]] = []
+
+        for action in subparser._actions:
+            if isinstance(action, (argparse._HelpAction, argparse._SubParsersAction)):
+                continue
+
+            info = {
+                "dest": action.dest,
+                "help": action.help or "",
+                "default": action.default if action.default != "==SUPPRESS==" else None,
+                "choices": list(action.choices) if action.choices else None,
+                "type": action.type.__name__ if hasattr(action.type, "__name__") else None,
+            }
+
+            if action.option_strings:
+                info["flags"] = "/".join(action.option_strings)
+                options.append(info)
+            else:
+                info["name"] = action.dest
+                positionals.append(info)
+
+        commands_info[cmd_name] = {
+            "help": subparser.description or subparser.format_help().split("\n")[0] or "",
+            "positionals": positionals,
+            "options": options,
+            "parser": subparser,
+        }
+
+    return commands_info
+
+
+def run_help(command_name: str | None = None) -> int:
+    """Entry point for `micforge help [command]`."""
+    from ..cli import build_parser
+
+    parser = build_parser()
+    discovered_commands = _extract_parser_info(parser)
+
+    # 1. SPECIFIC COMMAND DEEP DIVE
+    if command_name:
+        cmd_key = command_name.lower().strip()
+        if cmd_key not in discovered_commands:
+            console.print(f"\n[bold red]✖ Unknown command:[/] '[bold white]{command_name}[/]'")
+            # Suggest matching commands
+            matches = [c for c in discovered_commands if cmd_key in c or c in cmd_key]
+            if matches:
+                console.print(f"[yellow]  Did you mean:[/] [cyan]{', '.join(matches)}[/]")
+            console.print("[dim]  Run [bold white]micforge help[/] to see all available commands.\n[/]")
+            return 1
+
+        _print_command_deep_dive(cmd_key, discovered_commands[cmd_key])
+        return 0
+
+    # 2. COMPLETE CATEGORIZED COMMAND DIRECTORY
+    _print_all_commands_overview(discovered_commands)
+    return 0
+
+
+def _print_all_commands_overview(discovered_commands: dict[str, dict[str, Any]]) -> None:
+    """Print the complete categorized reference table."""
+    banner = Text()
+    banner.append("🎙️  MICFORGE COMMAND REFERENCE  ", style="bold cyan")
+    banner.append(f"v{__version__}\n", style="bold green")
+    banner.append("Real-time local DSP rack, AI speech enhancement, diagnostics, and routing.", style="dim")
+    console.print(Panel(banner, box=box.ROUNDED, border_style="cyan"))
+
+    # Group commands into categories
+    categorized: dict[str, list[str]] = {cat: [] for cat in CATEGORIES_ORDER}
+    uncategorized: list[str] = []
+
+    for cmd_name in sorted(discovered_commands.keys()):
+        meta = COMMAND_METADATA.get(cmd_name)
+        cat = meta.get("category") if meta else None
+        if cat and cat in categorized:
+            categorized[cat].append(cmd_name)
+        else:
+            uncategorized.append(cmd_name)
+
+    if uncategorized:
+        categorized["Other Commands"] = uncategorized
+
+    for category, cmds in categorized.items():
+        if not cmds:
+            continue
+
+        table = Table(
+            title=f"[bold cyan]{category}[/]",
+            title_justify="left",
+            box=box.SIMPLE_HEAD,
+            header_style="bold white",
+            show_lines=False,
+            padding=(0, 1),
+        )
+        table.add_column("Command", style="bold yellow", width=14)
+        table.add_column("Description", style="white", width=42)
+        table.add_column("Typical Example", style="dim cyan")
+
+        for cmd_name in cmds:
+            meta = COMMAND_METADATA.get(cmd_name, {})
+            headline = meta.get("headline")
+            if not headline:
+                headline = discovered_commands[cmd_name]["help"] or "Execute command"
+
+            examples = meta.get("examples", [])
+            example_cmd = examples[0][1] if examples else f"micforge {cmd_name}"
+
+            table.add_row(cmd_name, headline, example_cmd)
+
+        console.print(table)
+        console.print()
+
+    # Helpful Footer
+    console.print(
+        "[bold cyan]Tip:[/] Type [bold white]micforge help <command>[/] "
+        "(e.g. [green]micforge help run[/], [green]micforge help latency[/], [green]micforge help profile[/]) "
+        "for detailed flags, syntax, and options.\n"
+    )
+
+
+def _print_command_deep_dive(cmd_name: str, info: dict[str, Any]) -> None:
+    """Print an exhaustive, beautiful deep dive for a single command."""
+    meta = COMMAND_METADATA.get(cmd_name, {})
+    headline = meta.get("headline") or info.get("help") or "Command reference"
+    category = meta.get("category", "General")
+
+    # 1. Header Banner
+    header = Text()
+    header.append(f"COMMAND: micforge {cmd_name}\n", style="bold cyan")
+    header.append(f"{headline}\n", style="bold white")
+    header.append(f"Category: {category}", style="dim")
+    console.print(Panel(header, box=box.ROUNDED, border_style="cyan"))
+
+    # 2. Syntax / Usage Line
+    positionals = info.get("positionals", [])
+    options = info.get("options", [])
+
+    syntax_parts = [f"micforge {cmd_name}"]
+    if options:
+        syntax_parts.append("[options]")
+    for pos in positionals:
+        syntax_parts.append(f"<{pos['dest']}>")
+
+    syntax_str = " ".join(syntax_parts)
+    console.print(f"[bold cyan]Usage:[/] [bold green]{escape(syntax_str)}[/]\n")
+
+    # 3. Positional Arguments (if any)
+    if positionals:
+        pos_table = Table(title="[bold]Positional Arguments[/]", box=box.SIMPLE_HEAD, header_style="bold cyan")
+        pos_table.add_column("Argument", style="bold yellow", width=18)
+        pos_table.add_column("Choices / Type", style="dim", width=20)
+        pos_table.add_column("Description")
+
+        for pos in positionals:
+            choices_str = ", ".join(map(str, pos["choices"])) if pos.get("choices") else (pos.get("type") or "string")
+            pos_table.add_row(
+                pos["dest"],
+                f"[dim]{escape(choices_str)}[/]",
+                escape(pos.get("help", "")),
+            )
+
+        console.print(pos_table)
+        console.print()
+
+    # 4. Optional Flags (if any)
+    if options:
+        opt_table = Table(title="[bold]Options & Flags[/]", box=box.SIMPLE_HEAD, header_style="bold cyan")
+        opt_table.add_column("Flag", style="bold yellow", width=22)
+        opt_table.add_column("Default", style="dim", width=16)
+        opt_table.add_column("Description")
+
+        for opt in options:
+            default_val = str(opt["default"]) if opt.get("default") is not None and opt["default"] is not False else "-"
+            opt_table.add_row(
+                opt["flags"],
+                f"[dim]{escape(default_val)}[/]",
+                escape(opt.get("help", "")),
+            )
+
+        console.print(opt_table)
+        console.print()
+
+    # 5. Practical Copy-Paste Examples
+    examples = meta.get("examples", [])
+    if examples:
+        console.print("[bold cyan]Practical Examples:[/]")
+        for desc, ex_code in examples:
+            console.print(f"  • [dim]{desc}:[/]")
+            console.print(f"    [bold white]{escape(ex_code)}[/]")
+        console.print()
+
+    # 6. Pro Tips & Best Practices
+    tips = meta.get("tips", [])
+    if tips:
+        console.print("[bold cyan]Pro Tips & Best Practices:[/]")
+        for tip in tips:
+            console.print(f"  💡 {escape(tip)}")
+        console.print()