clan: add examples and description to most help

Add examples and description to most toplevel help outputs.

pkgs/clan-cli/clan_cli/facts/__init__.py

@@ -23,7 +23,42 @@ def register_parser(parser: argparse.ArgumentParser) -> None:
     register_list_parser(list_parser)
 
     parser_generate = subparser.add_parser(
-        "generate", help="generate secrets for machines if they don't exist yet"
+        "generate",
+        help="generate public and secret facts for machines",
+        epilog=(
+            """
+This subcommand allows control of the generation of facts.
+Often this function will be invoked automatically on deploying machines,
+but there are situations the user may want to have more granular control,
+especially for the regeneration of certain services.
+
+A service is an included clan-module that implements facts generation functionality.
+For example the zerotier module will generate private and public facts.
+In this case the public fact will be the resulting zerotier-ip of the machine.
+The secret fact will be the zerotier-identity-secret, which is used by zerotier
+to prove the machine has control of the zerotier-ip.
+
+
+Examples:
+
+  $ clan facts generate
+  Will generate facts for all machines.
+   
+  $ clan facts generate [MACHINE]
+  Will generate facts for the specified machine.
+
+  $ clan facts generate [MACHINE] --service [SERVICE]
+  Will generate facts for the specified machine for the specified service.
+
+  $ clan facts generate --service [SERVICE] --regenerate
+  Will regenerate facts, if they are already generated for a specific service.
+  This is especially useful for resetting certain passwords while leaving the rest
+  of the facts for a machine in place.
+
+For more detailed information, visit: https://docs.clan.lol/getting-started/secrets/
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
     )
     register_generate_parser(parser_generate)