diff --git a/README.md b/README.md
index 090acbeb..5dfe97e6 100644
--- a/README.md
+++ b/README.md
@@ -155,7 +155,7 @@ execution engines differ; the depicted content and motion should agree.
 
 These controls are independent unless noted otherwise:
 
-| Control | Slow reference | Default | Aggressive | Main impact |
+| Control | Slow reference | Balanced fast | Aggressive | Main impact |
 |---|---:|---:|---:|---|
 | Denoising passes | `--steps 50` | `--steps 20` | `--steps 4..7` | The number always names actual denoising passes. |
 | Whole denoiser reuse | `--reuse 1` | `--reuse 2` | `--reuse 3` | At 20 steps: 20, 11, or 8 fresh DiT evaluations. |
@@ -369,6 +369,11 @@ the media semantics:
   -o outputs/fox-image-audio.mp4
 ```
 
+Reference images use `--ref-image-size match` by default, which preserves the
+source aspect ratio while scaling down to approximately the output canvas area.
+Use `--ref-image-size max` to retain more source detail, downscaling only when
+the source's short edge exceeds 2048 pixels. Neither mode enlarges the source.
+
 Reference flags may be repeated and their command-line order is preserved.
 Standalone audio must accompany an image or video reference. Audio references
 must be 2–15 seconds; at most three audio inputs are accepted and their total
diff --git a/h3.h b/h3.h
index c3d3a9d3..d5db0a31 100644
--- a/h3.h
+++ b/h3.h
@@ -58,7 +58,11 @@ typedef struct {
     int denoise_steps;
 } h3_frame;
 
+/* The frame and its RGB data remain valid only for the duration of the call.
+ * Return zero to continue generation or nonzero to cancel it. */
 typedef int (*h3_frame_callback)(const h3_frame *frame, void *opaque);
+/* The phase string remains valid only for the duration of the call. Return
+ * zero to continue generation or nonzero to cancel it. */
 typedef int (*h3_progress_callback)(const char *phase, int completed, int total,
                                     void *opaque);
 
diff --git a/main.c b/main.c
index a694b37c..d7e59187 100644
--- a/main.c
+++ b/main.c
@@ -28,9 +28,9 @@ static void usage(const char *program) {
         "      --frames N         Requested frames (default: 56)\n"
         "      --seconds N        Requested duration at 24 fps (instead of --frames)\n"
         "      --steps N          Denoising passes (default: 20)\n"
-        "      --reuse N          Denoiser reuse: 1 close, 2 fast, 3 aggressive\n"
-        "      --layers N         DiT blocks: 50 exact, 45 fast, 40 aggressive\n"
-        "      --core-reuse N     Core refresh: 1 exact, 4 fast, 6 aggressive\n"
+        "      --reuse N          Denoiser reuse: 1 close (default), 2 fast, 3 aggressive\n"
+        "      --layers N         DiT blocks: 50 exact (default), 45 fast, 40 aggressive\n"
+        "      --core-reuse N     Core refresh: 1 exact (default), 4 fast, 6 aggressive\n"
         "      --token-reduction  Pair video tokens in middle DiT blocks\n"
         "      --use-int8-row-fc2 Faster one-scale int8 FC2 (M5)\n"
         "      --use-reference-rope  Disable native 256 RoPE adaptation\n"
@@ -54,7 +54,7 @@ static void usage(const char *program) {
         "      --ref-video-audio VIDEO AUDIO  Append video + soundtrack\n"
         "      --ref-audio PATH    Append an ordered standalone audio clip\n"
         "      --frames-dir PATH  Write generated frames as PPM files\n"
-        "      --show             Display a frame after every denoising step (M5)\n"
+        "      --show             Display a frame after every denoising step\n"
         "      --zoom N           Terminal image zoom (default: 2 for Retina)\n"
         "      --profile          Print per-phase Metal timing and allocation data\n"
         "      --info             Inspect model/device without mapping weights\n"