docs: Expand man pages with workflow examples and tips

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
 

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