docs: add comprehensive usage documentation

- Expand CLI --help with examples, dmenu mode, and search prefixes
- Add dmenu mode section to README with practical examples
- Add plugin management CLI reference to README
- Update argument descriptions with all valid modes listed

README.md

@@ -99,12 +99,40 @@ sudo cp target/release/libowlry_plugin_*.so /usr/lib/owlry/plugins/
 ## Usage
 
 ```bash
-owlry                      # Launch with defaults
-owlry --mode app           # Applications only
-owlry --providers app,cmd  # Specific providers
-owlry --help               # Show all options
+owlry                      # Launch with all providers
+owlry -m app               # Applications only
+owlry -m cmd               # PATH commands only
+owlry -p app,cmd           # Multiple specific providers
+owlry -m calc              # Calculator plugin only (if installed)
+owlry --help               # Show all options with examples
 ```
 
+### dmenu Mode
+
+Owlry is dmenu-compatible. Pipe input for interactive selection:
+
+```bash
+# Basic selection
+echo -e "Option A\nOption B\nOption C" | owlry -m dmenu
+
+# Select from files
+ls ~/Documents | owlry -m dmenu
+
+# Git branch checkout
+git branch | owlry -m dmenu --prompt "checkout:" | xargs git checkout
+
+# Kill a process
+ps -eo comm | sort -u | owlry -m dmenu --prompt "kill:" | xargs pkill
+
+# Select and open a project
+find ~/projects -maxdepth 1 -type d | owlry -m dmenu | xargs code
+
+# Package manager search
+pacman -Ssq | owlry -m dmenu --prompt "install:" | xargs sudo pacman -S
+```
+
+The `--prompt` flag sets a custom label for the search input.
+
 ### Keyboard Shortcuts
 
 | Key | Action |
@@ -221,6 +249,38 @@ Add plugin IDs to the disabled list in your config:
 disabled = ["emoji", "pomodoro"]
 ```
 
+### Plugin Management CLI
+
+```bash
+# List installed plugins
+owlry plugin list
+owlry plugin list --enabled        # Only enabled
+owlry plugin list --available      # Show registry plugins
+
+# Search registry
+owlry plugin search "weather"
+
+# Install/remove
+owlry plugin install <name>        # From registry
+owlry plugin install ./my-plugin   # From local path
+owlry plugin remove <name>
+
+# Enable/disable
+owlry plugin enable <name>
+owlry plugin disable <name>
+
+# Plugin info
+owlry plugin info <name>
+owlry plugin commands <name>       # List plugin CLI commands
+
+# Create new plugin
+owlry plugin create my-plugin              # Lua (default)
+owlry plugin create my-plugin -r rune      # Rune
+
+# Run plugin command
+owlry plugin run <plugin-id> <command> [args...]
+```
+
 ### Creating Custom Plugins
 
 See [docs/PLUGIN_DEVELOPMENT.md](docs/PLUGIN_DEVELOPMENT.md) for:

crates/owlry/src/cli.rs

@@ -10,19 +10,55 @@ use crate::providers::ProviderType;
 #[command(
     name = "owlry",
     about = "An owl-themed application launcher for Wayland",
-    version
+    long_about = "An owl-themed application launcher for Wayland, built with GTK4 and Layer Shell.\n\n\
+                  Owlry provides fuzzy search across applications, commands, and plugins.\n\
+                  Native plugins add features like calculator, clipboard, emoji, weather, and more.",
+    version,
+    after_help = "\
+EXAMPLES:
+    owlry                           Launch with all providers
+    owlry -m app                    Applications only
+    owlry -m cmd                    PATH commands only
+    owlry -m dmenu                  dmenu-compatible mode (reads from stdin)
+    owlry -p app,cmd                Multiple providers
+    owlry -m calc                   Calculator plugin only (if installed)
+
+DMENU MODE:
+    Pipe input to owlry for interactive selection:
+
+    echo -e \"Option A\\nOption B\" | owlry -m dmenu
+    ls | owlry -m dmenu
+    git branch | owlry -m dmenu --prompt \"checkout:\"
+
+SEARCH PREFIXES:
+    :app firefox                    Search applications
+    :cmd git                        Search PATH commands
+    = 5+3                           Calculator (requires plugin)
+    ? rust docs                     Web search (requires plugin)
+    / .bashrc                       File search (requires plugin)
+
+For configuration, see ~/.config/owlry/config.toml
+For plugin management, see: owlry plugin --help"
 )]
 pub struct CliArgs {
-    /// Start in single-provider mode (app, cmd, uuctl)
-    #[arg(long, short = 'm', value_parser = parse_provider)]
+    /// Start in single-provider mode
+    ///
+    /// Core modes: app, cmd, dmenu
+    /// Plugin modes: calc, clip, emoji, ssh, sys, bm, file, web, uuctl, weather, media, pomodoro
+    #[arg(long, short = 'm', value_parser = parse_provider, value_name = "MODE")]
     pub mode: Option<ProviderType>,
 
-    /// Comma-separated list of enabled providers (app,cmd,uuctl)
-    #[arg(long, short = 'p', value_delimiter = ',', value_parser = parse_provider)]
+    /// Comma-separated list of enabled providers
+    ///
+    /// Examples: -p app,cmd or -p app,calc,emoji
+    #[arg(long, short = 'p', value_delimiter = ',', value_parser = parse_provider, value_name = "PROVIDERS")]
     pub providers: Option<Vec<ProviderType>>,
 
-    /// Custom prompt text for the search input (useful for dmenu mode)
-    #[arg(long)]
+    /// Custom prompt text for the search input
+    ///
+    /// Useful in dmenu mode to indicate what the user is selecting.
+    /// Example: --prompt "Select file:"
+    #[arg(long, value_name = "TEXT")]
     pub prompt: Option<String>,
 
     /// Subcommand to run (if any)