diff --git a/docs/src/man/bcvk-ephemeral-run-ssh.md b/docs/src/man/bcvk-ephemeral-run-ssh.md
index ea7e084..c6f1eb8 100644
--- a/docs/src/man/bcvk-ephemeral-run-ssh.md
+++ b/docs/src/man/bcvk-ephemeral-run-ssh.md
@@ -4,11 +4,36 @@ bcvk-ephemeral-run-ssh - Run ephemeral VM and SSH into it
 
 # SYNOPSIS
 
-**bcvk ephemeral run-ssh** [*OPTIONS*]
+**bcvk ephemeral run-ssh** \[*OPTIONS*\] *IMAGE* \[*SSH_ARGS*\]
 
 # DESCRIPTION
 
-Run ephemeral VM and SSH into it
+Run a bootc container as an ephemeral VM and immediately connect via SSH.
+When the SSH session ends, the VM is automatically stopped and cleaned up.
+
+This is the recommended command for quick testing and iteration. It combines
+**bcvk ephemeral run** and **bcvk ephemeral ssh** into a single command with
+automatic lifecycle management.
+
+## Lifecycle Behavior
+
+Unlike **bcvk ephemeral run -d** which starts a background VM that persists
+until explicitly stopped, **run-ssh** ties the VM lifecycle to the SSH session:
+
+1. VM boots and waits for SSH to become available
+2. SSH session is established
+3. When you exit the SSH session (or the connection drops), the VM is stopped
+4. The container is automatically removed
+
+This makes **run-ssh** ideal for:
+
+- Quick one-off testing of container images
+- Rapid build-test iteration cycles
+- Running a single command in a VM environment
+- Demos and exploration
+
+For longer-running VMs where you need to reconnect multiple times, use
+**bcvk ephemeral run -d --rm -K** instead.
 
 # OPTIONS
 
@@ -125,25 +150,83 @@ Run ephemeral VM and SSH into it
 
 # EXAMPLES
 
-Run an ephemeral VM and automatically SSH into it (VM cleans up when SSH exits):
+## Basic Usage
+
+Test a public bootc image:
 
     bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
 
-Run a quick test with automatic SSH and cleanup:
+Test a CentOS bootc image:
 
-    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral run-ssh quay.io/centos-bootc/centos-bootc:stream10
+
+## Build and Test Workflow
+
+The most common development pattern is building and immediately testing:
+
+    # Build your container
+    podman build -t localhost/mybootc .
+
+    # Boot it and SSH in (auto-cleanup on exit)
+    bcvk ephemeral run-ssh localhost/mybootc
+
+For rapid iteration, combine in one command:
+
+    podman build -t localhost/mybootc . && bcvk ephemeral run-ssh localhost/mybootc
+
+## Running Commands
+
+Execute a specific command and exit:
+
+    bcvk ephemeral run-ssh localhost/mybootc 'systemctl status'
+
+Check what services are running:
+
+    bcvk ephemeral run-ssh localhost/mybootc 'systemctl list-units --type=service --state=running'
+
+Verify your custom configuration:
+
+    bcvk ephemeral run-ssh localhost/mybootc 'cat /etc/myapp/config.yaml'
+
+## Resource Allocation
+
+For memory-intensive testing:
+
+    bcvk ephemeral run-ssh --memory 8G --vcpus 4 localhost/mybootc
+
+Using instance types:
+
+    bcvk ephemeral run-ssh --itype u1.medium localhost/mybootc
+
+## With Bind Mounts
+
+Mount source code for testing:
+
+    bcvk ephemeral run-ssh --bind /home/user/project:src localhost/mybootc
+    # Inside VM: ls /run/virtiofs-mnt-src
+
+## Debugging
+
+Enable console output to see boot messages:
+
+    bcvk ephemeral run-ssh --console localhost/mybootc
 
-Execute a specific command via SSH:
+# TIPS
 
-    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42 'systemctl status'
+- **Fast iteration**: Keep your container builds small and layered for faster
+  rebuilds. The VM boots in seconds, so the container build is usually the
+  bottleneck.
 
-Run with custom memory and CPU allocation:
+- **SSH arguments**: Any arguments after the image name are passed to SSH.
+  Use this for commands, port forwarding, or SSH options.
 
-    bcvk ephemeral run-ssh --memory 8G --vcpus 4 quay.io/fedora/fedora-bootc:42
+- **Exit cleanly**: Use `exit` or Ctrl+D to cleanly end the SSH session and
+  trigger VM cleanup. Ctrl+C may not clean up properly.
 
 # SEE ALSO
 
-**bcvk**(8)
+**bcvk**(8), **bcvk-ephemeral**(8), **bcvk-ephemeral-run**(8),
+**bcvk-ephemeral-ssh**(8)
 
 # VERSION
 
diff --git a/docs/src/man/bcvk-ephemeral-run.md b/docs/src/man/bcvk-ephemeral-run.md
index 800fe7d..b3d26e8 100644
--- a/docs/src/man/bcvk-ephemeral-run.md
+++ b/docs/src/man/bcvk-ephemeral-run.md
@@ -1,14 +1,16 @@
 # NAME
 
-bcvk-ephemeral-run - Run bootc containers as ephemeral VMs
+bcvk-ephemeral-run - Run bootc containers as stateless VMs
 
 # SYNOPSIS
 
-**bcvk ephemeral run** [*OPTIONS*]
+**bcvk ephemeral run** \[*OPTIONS*\] *IMAGE*
 
 # DESCRIPTION
 
-Run bootc containers as ephemeral VMs using a sophisticated container-in-container approach.
+Run bootc containers as stateless VMs managed by podman. The VM boots directly
+from the container image's filesystem via virtiofs, with no disk image creation
+required. This makes startup fast and the VM stateless by default.
 
 ## How It Works
 
@@ -24,7 +26,6 @@ This command creates an ephemeral virtual machine by launching a podman containe
 5. **Kernel Boot**: The VM boots using the kernel and initramfs from the bootc container image
 
 This architecture provides several advantages:
-- **No Root Required**: Runs as a regular user without requiring root privileges on the host
 - **Isolation**: The VM runs in a contained environment separate from the host
 - **Fast I/O**: virtiofs provides efficient filesystem access between container and VM
 - **Resource Efficiency**: Leverages existing container infrastructure while providing full VM capabilities
@@ -38,7 +39,7 @@ The relationship between the podman container and the VM inside it:
 - **VM Guest**: The bootc container image runs as a complete operating system inside the VM
 - **Filesystem Sharing**: The container's root filesystem is shared with the VM via virtiofs at runtime
 
-This design allows bcvk to provide VM-like isolation and boot behavior while leveraging container tooling and not requiring root access on the host system.
+This design allows bcvk to provide VM-like isolation and boot behavior while leveraging container tooling.
 
 # OPTIONS
 
@@ -151,39 +152,111 @@ This design allows bcvk to provide VM-like isolation and boot behavior while lev
 
 # EXAMPLES
 
-Run an ephemeral VM in the background:
+## Build and Test Workflow
 
-    bcvk ephemeral run -d --rm --name mytestvm quay.io/fedora/fedora-bootc:42
+The most common use case is testing container images you're building:
 
-Run with custom memory and CPU allocation:
+    # Build your bootc container image
+    podman build -t localhost/mybootc .
 
-    bcvk ephemeral run --memory 8G --vcpus 4 --name bigvm quay.io/fedora/fedora-bootc:42
+    # Run it as an ephemeral VM (background, auto-cleanup, SSH keys)
+    bcvk ephemeral run -d --rm -K --name test localhost/mybootc
 
-Run with automatic SSH key generation and removal when done:
+    # SSH in to verify it works
+    bcvk ephemeral ssh test
+
+    # Stop when done (container auto-removed due to --rm)
+    podman stop test
+
+For a faster iteration loop, use **bcvk-ephemeral-run-ssh**(8) which combines
+run and SSH into one command with automatic cleanup.
+
+## Common Flag Combinations
+
+**Testing a public image**:
 
     bcvk ephemeral run -d --rm -K --name testvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral ssh testvm
 
-Run with host directory bind mount:
+**Development with mounted source code**:
 
-    bcvk ephemeral run --bind /home/user/code:workspace --name devvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral run -d --rm -K \
+        --bind /home/user/project:src \
+        --name devvm localhost/mybootc
+    bcvk ephemeral ssh devvm
+    # Files available at /run/virtiofs-mnt-src inside VM
 
-Run with console output for debugging:
+**Resource-intensive workloads**:
 
-    bcvk ephemeral run --console --name debugvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral run -d --rm -K \
+        --memory 8G --vcpus 4 \
+        --name bigvm localhost/mybootc
 
-Run with custom kernel arguments:
+**Debugging boot issues**:
 
-    bcvk ephemeral run --karg "console=ttyS0" --name serialvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral run --console --name debugvm localhost/mybootc
 
-Development workflow example:
+## Understanding the Flags
 
-    # Start a development VM with code mounted
-    bcvk ephemeral run -d --rm -K --bind /home/user/project:code --name devvm quay.io/fedora/fedora-bootc:42
-    
-    # SSH into it for development
-    bcvk ephemeral ssh devvm
-    
-    # VM automatically cleans up when stopped due to --rm flag
+**-d, --detach**: Run in background. Without this, the container runs in
+foreground and you see QEMU output directly.
+
+**--rm**: Auto-remove the container when it stops. Highly recommended for
+ephemeral testing to avoid accumulating stopped containers.
+
+**-K, --ssh-keygen**: Generate SSH keypair and inject into the VM via
+systemd credentials. Required for **bcvk ephemeral ssh** to work.
+
+**--name**: Assign a name for easy reference with other commands like
+**bcvk ephemeral ssh**.
+
+## Bind Mounts
+
+Share host directories with the VM using **--bind** or **--ro-bind**:
+
+    # Read-write mount
+    bcvk ephemeral run -d --rm -K --bind /host/path:name --name vm image
+
+    # Inside VM, access at:
+    /run/virtiofs-mnt-name
+
+    # Read-only mount (safer for sensitive data)
+    bcvk ephemeral run -d --rm -K --ro-bind /etc/myconfig:config --name vm image
+
+## Disk File Mounts
+
+Mount raw disk images as block devices:
+
+    # Create a test disk
+    truncate -s 10G /tmp/testdisk.raw
+
+    # Mount into VM
+    bcvk ephemeral run -d --rm -K \
+        --mount-disk-file /tmp/testdisk.raw:testdisk \
+        --name vm localhost/mybootc
+
+    # Inside VM: /dev/disk/by-id/virtio-testdisk
+
+## Port Forwarding
+
+For SSH port forwarding (recommended), use **bcvk ephemeral ssh** with **-L** or **-R**:
+
+    # Forward VM port 80 to localhost:8080
+    bcvk ephemeral ssh myvm -L 8080:localhost:80
+
+For network-level port forwarding via podman, configure slirp4netns:
+
+    bcvk ephemeral run -d --rm -K \
+        --network slirp4netns:port_handler=slirp4netns,allow_host_loopback=true \
+        --name webvm localhost/mybootc
+
+## Instance Types
+
+Use predefined instance types for consistent resource allocation:
+
+    bcvk ephemeral run -d --rm -K --itype u1.small --name vm localhost/mybootc
+    bcvk ephemeral run -d --rm -K --itype u1.medium --name vm localhost/mybootc
+    bcvk ephemeral run -d --rm -K --itype u1.large --name vm localhost/mybootc
 
 # DEBUGGING
 
diff --git a/docs/src/man/bcvk-ephemeral-ssh.md b/docs/src/man/bcvk-ephemeral-ssh.md
index 01ee2ae..325e16a 100644
--- a/docs/src/man/bcvk-ephemeral-ssh.md
+++ b/docs/src/man/bcvk-ephemeral-ssh.md
@@ -4,21 +4,42 @@ bcvk-ephemeral-ssh - Connect to running VMs via SSH
 
 # SYNOPSIS
 
-**bcvk ephemeral ssh** [*OPTIONS*]
+**bcvk ephemeral ssh** *CONTAINER_NAME* \[*SSH_ARGS*\]
 
 # DESCRIPTION
 
-Connect to running ephemeral VMs via SSH. This command provides SSH access to VMs created by **bcvk-ephemeral-run**(8).
+Connect to a running ephemeral VM via SSH. This command locates the VM's
+SSH port and connects using the SSH key that was injected when the VM
+was started with **-K** or **--ssh-keygen**.
 
-## VM Lifecycle Management
+## Prerequisites
 
-When using SSH with ephemeral VMs, the VM lifecycle can be bound to the SSH connection depending on how the VM was started:
+The target VM must have been started with SSH key injection:
 
-- **Background VMs** (started with `-d`): The VM continues running independently after SSH disconnection
-- **Interactive VMs** (started without `-d`): The VM terminates when SSH disconnects
-- **Auto-cleanup VMs** (started with `--rm`): The VM and container are automatically removed when the VM stops
+    bcvk ephemeral run -d --rm -K --name myvm image
 
-For the **bcvk-ephemeral-run-ssh**(8) command, the VM lifecycle is tightly coupled to the SSH session - when the SSH client terminates (e.g., by running `exit`), the entire VM and its container are automatically cleaned up.
+Without **-K**, the VM will not have SSH keys configured and this command
+will fail to authenticate.
+
+## How It Works
+
+1. Queries the podman container to find the VM's SSH port
+2. Retrieves the SSH private key from the container
+3. Connects using the dynamically assigned port and key
+4. Passes any additional arguments to the ssh client
+
+## VM Lifecycle
+
+SSH connections do not affect the VM lifecycle for background VMs:
+
+- **Background VMs** (started with **-d**): Continue running after SSH disconnect.
+  You can reconnect as many times as needed.
+- **Auto-cleanup VMs** (started with **--rm**): Container is removed when the VM
+  stops, but SSH disconnect alone does not stop the VM.
+
+To stop a background VM, use **podman stop**.
+
+For automatic cleanup on SSH exit, use **bcvk-ephemeral-run-ssh**(8) instead.
 
 # OPTIONS
 
@@ -37,38 +58,83 @@ For the **bcvk-ephemeral-run-ssh**(8) command, the VM lifecycle is tightly coupl
 
 # EXAMPLES
 
-Connect to a running ephemeral VM:
+## Basic Connection
+
+Connect to a running VM:
+
+    bcvk ephemeral ssh myvm
+
+## Running Remote Commands
+
+Execute a command directly:
+
+    bcvk ephemeral ssh myvm 'systemctl status'
+
+Check disk usage:
+
+    bcvk ephemeral ssh myvm 'df -h'
+
+View journal logs:
+
+    bcvk ephemeral ssh myvm 'journalctl -f'
+
+## SSH Options
+
+Enable verbose output for debugging connection issues:
+
+    bcvk ephemeral ssh myvm -v
+
+Forward a local port to the VM:
+
+    bcvk ephemeral ssh myvm -L 8080:localhost:80
+    # Access VM's port 80 at localhost:8080
+
+Reverse port forwarding (expose host port to VM):
+
+    bcvk ephemeral ssh myvm -R 3000:localhost:3000
+
+## Typical Workflow
+
+    # Start a VM in the background
+    bcvk ephemeral run -d --rm -K --name testvm quay.io/fedora/fedora-bootc:42
+
+    # Connect and do some work
+    bcvk ephemeral ssh testvm
+    # ... interactive session ...
+    # exit
+
+    # Reconnect later
+    bcvk ephemeral ssh testvm
+
+    # Run a quick command without interactive session
+    bcvk ephemeral ssh testvm 'cat /etc/os-release'
+
+    # Stop the VM when done
+    podman stop testvm
+
+## File Transfer
 
-    bcvk ephemeral ssh mytestvm
+Use scp-style operations by getting the SSH details:
 
-Connect with SSH verbose mode:
+    # For now, use podman exec for file transfer
+    podman cp localfile testvm:/path/in/container
 
-    bcvk ephemeral ssh mytestvm -v
+    # Or mount a shared directory when starting the VM
+    bcvk ephemeral run -d --rm -K --bind /host/path:shared --name vm image
 
-Connect with port forwarding:
+# TROUBLESHOOTING
 
-    bcvk ephemeral ssh mytestvm -L 8080:localhost:80
+**Connection refused**: The VM may still be booting. Wait a few seconds and retry.
 
-VM lifecycle examples:
+**Permission denied**: Ensure the VM was started with **-K** for SSH key injection.
 
-    # Start a background VM (continues after SSH disconnect)
-    bcvk ephemeral run -d --name persistent-vm quay.io/fedora/fedora-bootc:42
-    bcvk ephemeral ssh persistent-vm
-    # VM keeps running after 'exit'
-    
-    # Start an auto-cleanup VM (removes when stopped)
-    bcvk ephemeral run -d --rm --name temp-vm quay.io/fedora/fedora-bootc:42
-    bcvk ephemeral ssh temp-vm
-    # VM and container auto-removed when VM stops
-    
-    # For tightly-coupled lifecycle, use run-ssh instead
-    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
-    # VM terminates automatically when SSH session ends
+**Host key verification failed**: Each VM gets a unique host key. Use **-o StrictHostKeyChecking=no** if needed.
 
 # SEE ALSO
 
-**bcvk**(8), **bcvk-ephemeral**(8), **bcvk-ephemeral-run**(8), **bcvk-ephemeral-run-ssh**(8)
+**bcvk**(8), **bcvk-ephemeral**(8), **bcvk-ephemeral-run**(8),
+**bcvk-ephemeral-run-ssh**(8), **ssh**(1)
 
 # VERSION
 
-v0.1.0
\ No newline at end of file
+<!-- VERSION PLACEHOLDER -->
diff --git a/docs/src/man/bcvk-ephemeral.md b/docs/src/man/bcvk-ephemeral.md
index 123eb26..d1d27a4 100644
--- a/docs/src/man/bcvk-ephemeral.md
+++ b/docs/src/man/bcvk-ephemeral.md
@@ -4,32 +4,126 @@ bcvk-ephemeral - Manage ephemeral VMs for bootc containers
 
 # SYNOPSIS
 
-**bcvk ephemeral** [*OPTIONS*]
+**bcvk ephemeral** \<*SUBCOMMAND*\>
 
 # DESCRIPTION
 
-Manage ephemeral VMs for bootc containers
+Manage stateless VMs for bootc container images.
+
+Ephemeral VMs are managed by podman and boot directly from the container
+image's filesystem. Unlike libvirt VMs created with **bcvk-libvirt-run**(8),
+ephemeral VMs:
+
+- **Boot directly from the container image** via virtiofs (no disk image creation)
+- **Start in seconds** rather than minutes
+- **Are stateless by default** - filesystem changes don't persist across restarts
+- **Are managed via podman** - use familiar container tooling
+
+This makes ephemeral VMs ideal for local development, CI pipelines, and any
+workflow where you want fast iteration without persistent state.
+
+## How It Works
+
+Ephemeral VMs use a container-in-container architecture:
+
+1. A podman container is launched containing QEMU and virtiofsd
+2. The bootc container image's filesystem is shared into the VM via virtiofs
+3. The VM boots using the kernel and initramfs from the container image
+4. SSH access is provided via dynamically generated keys
+
+The host needs /dev/kvm access and a virtualization stack (qemu, virtiofsd).
 
 <!-- BEGIN GENERATED OPTIONS -->
 <!-- END GENERATED OPTIONS -->
 
+# SUBCOMMANDS
+
+bcvk-ephemeral-run(8)
+
+:   Run a bootc container as an ephemeral VM
+
+bcvk-ephemeral-run-ssh(8)
+
+:   Run an ephemeral VM and immediately SSH into it (auto-cleanup on exit)
+
+bcvk-ephemeral-ssh(8)
+
+:   SSH into a running ephemeral VM
+
+bcvk-ephemeral-ps(8)
+
+:   List running ephemeral VMs
+
+bcvk-ephemeral-rm-all(8)
+
+:   Remove all ephemeral VM containers
+
 # EXAMPLES
 
-Run an ephemeral VM in the background:
+## Quick Interactive Session
 
-    bcvk ephemeral run -d --rm --name mytestvm quay.io/fedora/fedora-bootc:42
+The simplest way to boot a bootc image is **run-ssh**, which starts the VM
+and drops you into an SSH session. When you exit, the VM is cleaned up:
 
-Run an ephemeral VM with custom resources:
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
 
-    bcvk ephemeral run --memory 4096 --cpus 4 --name bigvm quay.io/fedora/fedora-bootc:42
+## Build and Test Workflow
 
-Run an ephemeral VM with automatic SSH key generation:
+A typical development loop combines podman build with ephemeral testing:
 
+    # Edit your Containerfile
+    vim Containerfile
+
+    # Build the image
+    podman build -t localhost/mybootc .
+
+    # Test it immediately
+    bcvk ephemeral run-ssh localhost/mybootc
+
+    # Iterate: edit, build, test again
+    podman build -t localhost/mybootc . && bcvk ephemeral run-ssh localhost/mybootc
+
+## Background VM with SSH Access
+
+For longer sessions or when you need to reconnect, run the VM in the background:
+
+    # Start VM in background with SSH keys and auto-cleanup
     bcvk ephemeral run -d --rm -K --name testvm quay.io/fedora/fedora-bootc:42
 
+    # SSH into it (can reconnect multiple times)
+    bcvk ephemeral ssh testvm
+
+    # Run commands directly
+    bcvk ephemeral ssh testvm 'systemctl status'
+
+    # Stop when done (--rm ensures cleanup)
+    podman stop testvm
+
+## Development VM with Host Directory Access
+
+Mount your source code into the VM for development:
+
+    bcvk ephemeral run -d --rm -K \
+        --bind /home/user/project:project \
+        --name devvm localhost/mybootc
+
+    bcvk ephemeral ssh devvm
+    # Inside VM: cd /run/virtiofs-mnt-project
+
+## Resource Customization
+
+Allocate more resources for heavy workloads:
+
+    bcvk ephemeral run-ssh --memory 8G --vcpus 4 localhost/mybootc
+
+Or use instance types:
+
+    bcvk ephemeral run-ssh --itype u1.medium localhost/mybootc
+
 # SEE ALSO
 
-**bcvk**(8)
+**bcvk**(8), **bcvk-ephemeral-run**(8), **bcvk-ephemeral-run-ssh**(8),
+**bcvk-ephemeral-ssh**(8), **bcvk-libvirt**(8)
 
 # VERSION
 
diff --git a/docs/src/man/bcvk.md b/docs/src/man/bcvk.md
index 8c5f553..4f5c6b7 100644
--- a/docs/src/man/bcvk.md
+++ b/docs/src/man/bcvk.md
@@ -8,30 +8,62 @@ bcvk - A toolkit for bootable containers and (local) virtualization.
 
 # DESCRIPTION
 
-bcvk helps launch bootc containers using local virtualization.
-Build containers using your tool of choice (podman, docker, etc),
-then use `bcvk libvirt run` to quickly and conveniently create
-a libvirt virtual machine, and connect with `ssh`.
+bcvk helps launch bootc containers using local virtualization for
+development and CI workflows. Build containers using your tool of choice
+(podman, docker, etc), then use bcvk to boot them as virtual machines.
 
-The toolkit includes commands for:
+Note: bcvk is designed for local development and CI environments, not for
+running production servers.
 
-- Running ephemeral VMs for testing container images
-- Installing bootc containers to persistent disk images
-- Managing libvirt integration and VM lifecycle
-- SSH access to running VMs
+## Quick Start
+
+The fastest way to boot a bootc container image is with **bcvk ephemeral run-ssh**:
+
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
+
+This boots the container as a VM and drops you into an SSH session. When you
+exit the SSH session, the VM is automatically cleaned up.
+
+## Build and Test Workflow
+
+A typical development workflow combines container builds with ephemeral VM testing:
+
+    # Build your bootc container
+    podman build -t localhost/myimage .
+
+    # Boot it as a VM and SSH in (auto-cleanup on exit)
+    bcvk ephemeral run-ssh localhost/myimage
+
+    # Or run in background for longer testing
+    bcvk ephemeral run -d --rm -K --name testvm localhost/myimage
+    bcvk ephemeral ssh testvm
+    # ... test, then stop the VM when done
+    podman stop testvm
+
+## Ephemeral vs Libvirt
+
+bcvk provides two ways to run bootc containers as VMs:
+
+**bcvk ephemeral** runs stateless VMs managed by podman. The VM boots directly
+from the container image's filesystem via virtiofs with no disk image creation,
+making startup very fast. Ideal for quick iteration and CI pipelines.
+
+**bcvk libvirt** creates stateful VMs managed by libvirt with persistent disk
+images. These VMs survive reboots and support the full bootc upgrade workflow.
+Useful for longer-running local development or testing upgrade scenarios.
 
 <!-- BEGIN GENERATED OPTIONS -->
 <!-- END GENERATED OPTIONS -->
 
 # SUBCOMMANDS
 
-bcvk-images(8)
+bcvk-ephemeral(8)
 
-:   Manage and inspect bootc container images
+:   Manage stateless VMs via podman (fast startup, no disk images)
 
-bcvk-run-ephemeral(8)
+bcvk-images(8)
 
-:   Run bootc containers as temporary VMs for testing and development
+:   Manage and inspect bootc container images
 
 bcvk-to-disk(8)
 
@@ -39,16 +71,34 @@ bcvk-to-disk(8)
 
 bcvk-libvirt(8)
 
-:   Manage libvirt integration for bootc containers
+:   Manage stateful VMs via libvirt (persistent disk images)
+
+# EXAMPLES
+
+Test a public bootc image interactively:
+
+    bcvk ephemeral run-ssh quay.io/centos-bootc/centos-bootc:stream10
+
+Build and test a local image:
+
+    podman build -t localhost/mybootc .
+    bcvk ephemeral run-ssh localhost/mybootc
+
+Run a background VM with SSH access:
+
+    bcvk ephemeral run -d --rm -K --name dev quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral ssh dev
 
-bcvk-ssh(8)
+Create a libvirt VM with persistent disk:
 
-:   Connect to running VMs via SSH
+    bcvk libvirt run --name myvm quay.io/centos-bootc/centos-bootc:stream10
+    bcvk libvirt ssh myvm
 
-bcvk-help(8)
+# SEE ALSO
 
-:   Print this message or the help of the given subcommand(s)
+**bcvk-ephemeral**(8), **bcvk-ephemeral-run**(8), **bcvk-ephemeral-run-ssh**(8),
+**bcvk-libvirt**(8), **bcvk-to-disk**(8), **bootc**(8)
 
 # VERSION
 
-v0.1.0
+<!-- VERSION PLACEHOLDER -->