cnn_test: --weights now overrides layer config from .bin file

When using --weights option:
- Layer count and kernel sizes loaded from binary header
- Warnings shown if --layers or --cnn-version specified
- Help text clarifies precedence order
- Binary weights always take precedence over CLI args

Updated documentation:
- doc/CNN_TEST_TOOL.md: Usage examples with --weights
- doc/HOWTO.md: Runtime weight loading example

handoff(Claude): cnn_test --weights config override

3 files changed, 30 insertions, 6 deletions

diff --git a/doc/CNN_TEST_TOOL.md b/doc/CNN_TEST_TOOL.md
index 82d5799..4307894 100644
--- a/doc/CNN_TEST_TOOL.md
+++ b/doc/CNN_TEST_TOOL.md
@@ -41,10 +41,11 @@ Standalone tool for validating trained CNN shaders with GPU-to-CPU readback. Sup
 cnn_test input.png output.png [OPTIONS]
 
 OPTIONS:
-  --cnn-version N          CNN version: 1 (default) or 2
+  --cnn-version N          CNN version: 1 (default) or 2 (ignored with --weights)
+  --weights PATH           Load weights from .bin (forces CNN v2, overrides layer config)
   --blend F                Final blend amount (0.0-1.0, default: 1.0)
   --format ppm|png         Output format (default: png)
-  --layers N               Number of CNN layers (1-10, v1 only, default: 3)
+  --layers N               Number of CNN layers (1-10, v1 only, default: 3, ignored with --weights)
   --save-intermediates DIR Save intermediate layers to directory
   --debug-hex              Print first 8 pixels as hex (debug)
   --help                   Show usage
@@ -55,9 +56,12 @@ OPTIONS:
 # CNN v1 (render pipeline, 3 layers)
 ./build/cnn_test input.png output.png --cnn-version 1
 
-# CNN v2 (compute, storage buffer, dynamic layers)
+# CNN v2 (compute, storage buffer, uses asset system weights)
 ./build/cnn_test input.png output.png --cnn-version 2
 
+# CNN v2 with runtime weight loading (loads layer config from .bin)
+./build/cnn_test input.png output.png --weights checkpoints/checkpoint_epoch_100.pth.bin
+
 # 50% blend with original (v2)
 ./build/cnn_test input.png output.png --cnn-version 2 --blend 0.5
 
@@ -65,6 +69,8 @@ OPTIONS:
 ./build/cnn_test input.png output.png --cnn-version 2 --debug-hex
 ```
 
+**Important:** When using `--weights`, the layer count and kernel sizes are read from the binary file header, overriding any `--layers` or `--cnn-version` arguments.
+
 ---
 
 ## Implementation Details
@@ -119,6 +125,13 @@ std::vector<uint8_t> OffscreenRenderTarget::read_pixels() {
 
 **Binary format:** Header (20B) + layer info (20B×N) + f16 weights
 
+**Weight Loading:**
+- **Without `--weights`:** Loads from asset system (`ASSET_WEIGHTS_CNN_V2`)
+- **With `--weights PATH`:** Loads from external `.bin` file (e.g., checkpoint exports)
+  - Layer count and kernel sizes parsed from binary header
+  - Overrides any `--layers` or `--cnn-version` arguments
+  - Enables runtime testing of training checkpoints without rebuild
+
 ---
 
 ## Build Integration
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 85ce801..3746d65 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -268,6 +268,9 @@ See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
 # CNN v2 (recommended, fully functional)
 ./build/cnn_test input.png output.png --cnn-version 2
 
+# CNN v2 with runtime weight loading (loads layer config from .bin)
+./build/cnn_test input.png output.png --weights checkpoints/checkpoint_epoch_100.pth.bin
+
 # CNN v1 (produces incorrect output, debug only)
 ./build/cnn_test input.png output.png --cnn-version 1
 
@@ -282,6 +285,8 @@ See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
 - **CNN v2:** ✅ Fully functional, matches CNNv2Effect
 - **CNN v1:** ⚠️ Produces incorrect output, use CNNEffect in demo for validation
 
+**Note:** `--weights` loads layer count and kernel sizes from the binary file, overriding `--layers` and forcing CNN v2.
+
 See `doc/CNN_TEST_TOOL.md` for full documentation.
 
 ---
diff --git a/tools/cnn_test.cc b/tools/cnn_test.cc
index 826d9ea..4599512 100644
--- a/tools/cnn_test.cc
+++ b/tools/cnn_test.cc
@@ -111,6 +111,12 @@ static bool parse_args(int argc, char** argv, Args* args) {
               args->cnn_version);
     }
     args->cnn_version = 2;
+
+    // Warn if --layers was specified (binary file config takes precedence)
+    if (args->num_layers != 3) {  // 3 is the default
+      fprintf(stderr, "WARNING: --layers %d ignored (--weights loads layer config from .bin)\n",
+              args->num_layers);
+    }
   }
 
   return true;
@@ -122,11 +128,11 @@ static void print_usage(const char* prog) {
   fprintf(stderr, "\nOPTIONS:\n");
   fprintf(stderr, "  --blend F                Final blend amount (0.0-1.0, default: 1.0)\n");
   fprintf(stderr, "  --format ppm|png         Output format (default: png)\n");
-  fprintf(stderr, "  --layers N               Number of CNN layers (1-10, default: 3)\n");
+  fprintf(stderr, "  --layers N               Number of CNN layers (1-10, default: 3, ignored with --weights)\n");
   fprintf(stderr, "  --save-intermediates DIR Save intermediate layers to directory\n");
   fprintf(stderr, "  --debug-hex              Print first 8 pixels as hex (debug)\n");
-  fprintf(stderr, "  --cnn-version N          CNN version: 1 (default) or 2\n");
-  fprintf(stderr, "  --weights PATH           Load weights from .bin file (forces CNN v2)\n");
+  fprintf(stderr, "  --cnn-version N          CNN version: 1 (default) or 2 (ignored with --weights)\n");
+  fprintf(stderr, "  --weights PATH           Load weights from .bin (forces CNN v2, overrides layer config)\n");
   fprintf(stderr, "  --help                   Show this help\n");
 }