improve cli documentation

Sources/phbar/CLI/cli+start.swift

@@ -6,10 +6,18 @@ extension phbar {
 	struct start: ParsableCommand {
 		static let configuration = CommandConfiguration(
 			commandName: "start",
-			abstract: "Start the status bar."
+			abstract: "Start the status bar.",
+			discussion: """
+				Launch the bar as a non-stopping background process.
+				This command is meant to be used for both testing and production.
+
+				When testing, you can provide the `--debug` flag to get visual
+				guidance that helps you configure the blocks and a verbose output from
+				the shell scripts to debug the behaviour.
+				"""
 		)
 
-		@Flag(name: .long, help: "Display visual guides to help align elements.")
+		@Flag(name: .long, help: "Display visual guides and print verbose output.")
 		var debug: Bool = false
 
 		mutating func run() throws {

Sources/phbar/cli.swift

@@ -13,12 +13,33 @@ struct phbar: ParsableCommand {
 		commandName: "phbar",
 		abstract: "Modular status bar for macOS.",
 		discussion: """
-			pmenu reads a list of newline-separated items from stdin and presents them to the user.
-			When the user selects an item and presses Return, their choice is printed to stdout and pmenu terminates.
-			Entering text will narrow the items to those matching the tokens in the input.
+			phbar renders a status bar on every visible monitor. Each status bar
+			is dynamically built from the given theme, window configuration,
+			and block set. Thanks to the modularity of phbar, each one of these
+			elements can be overwritten for any given monitor.
+
+			phbar relies on blocks to determine what is visible on a bar and how
+			it should look. Everything in phbar is a block, not just texts but
+			also spaces and dividers. Each block can have a different visual style,
+			refresh conditions, and content source. The content of a block, if any,
+			is computed by calling a shell script, giving you the maximum flexibility.
+
+			Run `phbar install` to create the required config directory filled with
+			a template to start with. The directory will be created in one of these
+			locations in order of priority: $XDG_CONFIG_HOME/phbar, ~/.config/phbar,
+			or ~/.phbar.
+
+			Edit `<config-directory>/blocks/default.toml` to customize the block set used
+			by default and `<config-directory>/themes/default.toml` to customize the look
+			and feel of the bar. Check out the full documentation to learn more about all
+			the possible customisations.
+
+			Run `phbar start` to launch the bar and verify the appearance and behaviour.
+			Once you're ready to go to production, you can create a launch agent that uses
+			the same command to start the bar automatically at login.
 			""",
 		version: "1.0.0",
-		subcommands: [start.self]
+		subcommands: [start.self, refresh.self]
 	)
 }