From 9dd123e1d25325f09167134e98c04fd6d7e91970 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Thu, 12 Feb 2026 12:23:17 +0100
Subject: Update docs and help messages for CNN v2 completion

Updated:
- HOWTO.md: Complete pipeline, storage buffer, --validate mode
- TODO.md: Mark CNN v2 complete, add QAT TODO
- PROJECT_CONTEXT.md: Update Effects status
- CNN_V2.md: Mark complete, add storage buffer notes
- train_cnn_v2_full.sh: Add --help message

All documentation now reflects:
- Storage buffer architecture
- Binary weight format
- Live training progress
- Validation-only mode
- 8-bit quantization TODO
---
 doc/CNN_V2.md |  7 +++++--
 doc/HOWTO.md  | 52 ++++++++++++++++++++++++++++++++++------------------
 2 files changed, 39 insertions(+), 20 deletions(-)

(limited to 'doc')

diff --git a/doc/CNN_V2.md b/doc/CNN_V2.md
index b3b6587..9407934 100644
--- a/doc/CNN_V2.md
+++ b/doc/CNN_V2.md
@@ -13,10 +13,13 @@ CNN v2 extends the original CNN post-processing effect with parametric static fe
 - Multi-frequency position encoding (NeRF-style)
 - Per-layer configurable kernel sizes (1×1, 3×3, 5×5)
 - Variable channel counts per layer
-- Float16 weight storage (GPU-optimized)
+- Float16 weight storage (~3.2 KB for 3-layer model)
 - Bias integrated as static feature dimension
+- Storage buffer architecture (dynamic layer count)
+- Binary weight format for runtime loading
 
-**Status:** Design complete, ready for implementation
+**Status:** ✅ Complete. Training pipeline functional, validation tools ready.
+**TODO:** 8-bit quantization with QAT for 2× size reduction (~1.6 KB)
 
 ---
 
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 7be5246..1ae1d94 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -132,36 +132,52 @@ Processes entire image with sliding window (matches WGSL):
 
 ### CNN v2 Training
 
-Enhanced CNN with parametric static features (7D input: RGBD + UV + sin encoding + bias):
+Enhanced CNN with parametric static features (7D input: RGBD + UV + sin encoding + bias).
 
+**Complete Pipeline** (recommended):
 ```bash
-# Train CNN v2 with default config (1×1, 3×3, 5×5 kernels, 16→8→4 channels)
+# Train → Export → Build → Validate
+./scripts/train_cnn_v2_full.sh
+```
+
+Config: 100 epochs, 3×3 kernels, 8→4→4 channels, patch-based (harris detector).
+- Live progress with single-line update
+- Validates all input images on final epoch
+- Exports binary weights (storage buffer architecture)
+
+**Validation Only** (skip training):
+```bash
+# Use latest checkpoint
+./scripts/train_cnn_v2_full.sh --validate
+
+# Use specific checkpoint
+./scripts/train_cnn_v2_full.sh --validate checkpoints/checkpoint_epoch_50.pth
+```
+
+**Manual Training:**
+```bash
+# Default config
 ./training/train_cnn_v2.py \
-  --input training/input/ --target training/output/ \
-  --epochs 5000 --batch-size 16 \
-  --checkpoint-every 1000
+  --input training/input/ --target training/target_2/ \
+  --epochs 100 --batch-size 16 --checkpoint-every 5
 
-# Custom architecture (smaller for size optimization)
+# Custom architecture
 ./training/train_cnn_v2.py \
-  --input training/input/ --target training/output/ \
-  --kernel-sizes 1 3 3 --channels 8 4 4 \
+  --input training/input/ --target training/target_2/ \
+  --kernel-sizes 1 3 5 --channels 16 8 4 \
   --epochs 5000 --batch-size 16
 ```
 
-**Export shaders:**
+**Export Binary Weights:**
 ```bash
-./training/export_cnn_v2_shader.py checkpoints/checkpoint_epoch_5000.pth \
-  --output-dir workspaces/main/shaders
+./training/export_cnn_v2_weights.py checkpoints/checkpoint_epoch_100.pth \
+  --output-weights workspaces/main/cnn_v2_weights.bin
 ```
 
-Generates `cnn_v2_layer_0.wgsl`, `cnn_v2_layer_1.wgsl`, `cnn_v2_layer_2.wgsl` with f16 weights.
+Generates binary format: header + layer info + f16 weights (~3.2 KB for 3-layer model).
+Storage buffer architecture allows dynamic layer count.
 
-### CNN v2 Validation
-
-End-to-end testing: checkpoint → shaders → build → test images → results
-
-```bash
-./scripts/validate_cnn_v2.sh checkpoints/checkpoint_epoch_5000.pth
+**TODO:** 8-bit quantization for 2× size reduction (~1.6 KB). Requires quantization-aware training (QAT).
 
 # Options:
 #   -i DIR     Test images directory (default: training/validation)
-- 
cgit v1.2.3