cli: Add examples to ephemeral and libvirt --help

crates/kit/src/ephemeral.rs

@@ -64,6 +64,42 @@ pub struct ContainerListEntry {
 
 /// Ephemeral VM operations
 #[derive(Debug, Subcommand)]
+#[command(after_long_help = "\
+EXAMPLES:
+
+  Fire-and-forget interactive session (VM is removed on exit):
+
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
+
+  Background VM you can reconnect to:
+
+    bcvk ephemeral run -d --rm --ssh-keygen --name myvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral ssh myvm
+    podman stop myvm
+
+  Run a single command and capture its exit code (CI pattern):
+
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42 -- systemctl is-active myservice
+
+  Stream the boot console in real time:
+
+    bcvk ephemeral run -d --console --name myvm quay.io/fedora/fedora-bootc:42
+    podman logs -f myvm
+
+  Mount a host directory into the VM (available at /run/virtiofs-mnt-src):
+
+    bcvk ephemeral run-ssh --bind .:src quay.io/fedora/fedora-bootc:42
+
+  Make the root filesystem writable (changes are still lost on shutdown):
+
+    bcvk ephemeral run-ssh --karg systemd.volatile=overlay quay.io/fedora/fedora-bootc:42
+
+  Tip for systemd unit authors - detect ephemeral vs. real hardware:
+
+    ConditionKernelCommandLine=!rootfstype=virtiofs
+
+  (virtiofs root is the stable indicator that the VM is running under bcvk ephemeral)\
+")]
 pub enum EphemeralCommands {
     /// Run bootc containers as ephemeral VMs
     #[clap(name = "run")]

crates/kit/src/main.rs

@@ -135,13 +135,13 @@ enum Commands {
     Images(images::ImagesOpts),
 
     #[cfg(target_os = "linux")]
-    /// Manage ephemeral VMs for bootc containers
+    /// Run bootc images as stateless VMs via QEMU+Podman (no root required)
     #[clap(subcommand)]
     Ephemeral(ephemeral::EphemeralCommands),
 
     // macOS stub: ephemeral command exists but errors out
     #[cfg(not(target_os = "linux"))]
-    /// Manage ephemeral VMs for bootc containers (not available on this platform)
+    /// Run bootc images as stateless VMs via QEMU+Podman (not available on this platform)
     #[clap(subcommand)]
     Ephemeral(StubEphemeralCommands),
 
@@ -152,7 +152,31 @@ enum Commands {
 
     // Note: libvirt is intentionally NOT available on macOS
     #[cfg(target_os = "linux")]
-    /// Manage libvirt integration for bootc containers
+    /// Run bootc images as persistent VMs managed by libvirt
+    #[clap(after_long_help = "\
+EXAMPLES:
+
+  Check that your libvirt environment is ready:
+
+    bcvk libvirt status
+
+  Create a persistent VM and SSH into it:
+
+    bcvk libvirt run --name myvm quay.io/centos-bootc/centos-bootc:stream10
+    bcvk libvirt ssh myvm
+
+  List running bootc VMs:
+
+    bcvk libvirt list
+
+  Connect to a remote hypervisor:
+
+    bcvk libvirt -c qemu+ssh://myhost/system run quay.io/fedora/fedora-bootc:42
+
+  Use base disks for fast VM cloning (saves disk space and creation time):
+
+    bcvk libvirt base-disks --help\
+")]
     Libvirt {
         /// Hypervisor connection URI (e.g., qemu:///system, qemu+ssh://host/system)
         #[clap(short = 'c', long = "connect", global = true)]