diff --git a/GENERATOR_COMMIT b/GENERATOR_COMMIT
index 6ecaf18..014e522 100644
--- a/GENERATOR_COMMIT
+++ b/GENERATOR_COMMIT
@@ -1 +1 @@
-d15925cd24ebcc93532771b7e5b1b793371fc853
+3af612046afc12c82626a18e575dc59763285a63
diff --git a/README.md b/README.md
index 4508150..36fb5cc 100644
--- a/README.md
+++ b/README.md
@@ -317,3 +317,12 @@ The publisher fills this README's package metadata from `VERSION` and checks
 documentation drift together with the other distribution files. The primary
 installation command remains unpinned; release tags are an optional choice
 for reproducible builds.
+
+## Source navigation
+
+`opencl.v` is generated; its introduction and declarations belong to the
+[canonical generator](https://github.com/antono2/v_opencl_bindings).
+Handwritten discovery, ownership, event, image and interoperability files have
+purpose comments describing their role. Make shared source and example changes
+in that repository, then run its publisher; direct edits here can be overwritten.
+Keep vendored OpenCL headers and their upstream license notices intact.
diff --git a/abi/main.c.v b/abi/main.c.v
index 2946b94..518b36d 100644
--- a/abi/main.c.v
+++ b/abi/main.c.v
@@ -1,3 +1,4 @@
+// Compiles representative OpenCL declarations to check C/V ABI compatibility.
 module main
 
 import antono2.opencl as cl
diff --git a/capabilities.v b/capabilities.v
index 7ad359a..4ba3f8d 100644
--- a/capabilities.v
+++ b/capabilities.v
@@ -1,3 +1,4 @@
+// Collects optional device extensions and identity information for capability-gated operations.
 module opencl
 
 // DeviceCapabilities is a snapshot of optional extension support advertised by
diff --git a/convenience.v b/convenience.v
index 0263f33..204436e 100644
--- a/convenience.v
+++ b/convenience.v
@@ -1,3 +1,4 @@
+// Converts OpenCL status codes to contextual V errors and copies platform/device query results.
 module opencl
 
 // OpenCLError preserves the native OpenCL status code and the operation that failed.
diff --git a/convenience_test.v b/convenience_test.v
index a1fc269..d45d03a 100644
--- a/convenience_test.v
+++ b/convenience_test.v
@@ -1,3 +1,4 @@
+// Checks typed errors, resource reference counts, ownership, and convenience operations.
 module main
 
 import antono2.opencl as cl
@@ -104,8 +105,7 @@ fn test_clone_ref_retains_independently_owned_native_references() ! {
 	assert memory_reference_count(buffer.handle)! == buffer_refs
 
 	mut program := cl.build_source_program(context, device,
-		'__kernel void retain_test(__global uint *values) { values[get_global_id(0)] += 1; }',
-		'')!
+		'__kernel void retain_test(__global uint *values) { values[get_global_id(0)] += 1; }', '')!
 	program_refs := program_reference_count(program.handle)!
 	mut retained_program := program.clone_ref()!
 	assert program_reference_count(program.handle)! == program_refs + 1
@@ -119,13 +119,20 @@ fn test_clone_ref_retains_independently_owned_native_references() ! {
 	retained_kernel.close()!
 	assert kernel_reference_count(kernel.handle)! == kernel_refs
 
-	mut event := queue.marker([]cl.Event{})!
+	// A queued marker may lose runtime-owned references as it completes. Use an
+	// unqueued user event so these counts measure only our retain/release calls.
+	mut event_status := cl.ErrorCode(0)
+	mut event := &cl.OwnedEvent{
+		handle: cl.create_user_event(context.handle, &event_status)
+	}
+	cl.check(event_status, 'create user event for reference-count test')!
 	event_refs := event_reference_count(event.handle)!
 	mut retained_event := event.clone_ref()!
 	assert event_reference_count(event.handle)! == event_refs + 1
 	retained_event.close()!
 	assert event_reference_count(event.handle)! == event_refs
 
+	cl.check(cl.set_user_event_status(event.handle, cl.complete), 'complete reference-count event')!
 	event.close()!
 	kernel.close()!
 	program.close()!
diff --git a/event.v b/event.v
index 70ad52e..cfdd516 100644
--- a/event.v
+++ b/event.v
@@ -1,3 +1,5 @@
+// Owns OpenCL event references and exposes completion and profiling queries.
+// Close each owned reference after dependent work no longer needs it.
 module opencl
 
 // OwnedEvent owns one OpenCL event reference. The command queue and context
diff --git a/examples/image_svm/main.v b/examples/image_svm/main.v
index 81ee468..a5cab3f 100644
--- a/examples/image_svm/main.v
+++ b/examples/image_svm/main.v
@@ -1,3 +1,4 @@
+// Demonstrates typed images and shared virtual memory where the device supports them.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vector_add/main.v b/examples/vector_add/main.v
index 9eaea19..245f0aa 100644
--- a/examples/vector_add/main.v
+++ b/examples/vector_add/main.v
@@ -1,3 +1,4 @@
+// Builds and executes a vector-add kernel using owned OpenCL resource helpers.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/compile_shaders.sh b/examples/vulkan_particles/compile_shaders.sh
index dbfd9f4..ecc59d8 100755
--- a/examples/vulkan_particles/compile_shaders.sh
+++ b/examples/vulkan_particles/compile_shaders.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
+# Compiles the particle and trail GLSL shaders to the SPIR-V files used by the demo.
 set -eu
 
 : "${VULKAN_SDK:?Set VULKAN_SDK to the Vulkan SDK directory}"
diff --git a/examples/vulkan_particles/compute.v b/examples/vulkan_particles/compute.v
index 8a477a7..b2c654e 100644
--- a/examples/vulkan_particles/compute.v
+++ b/examples/vulkan_particles/compute.v
@@ -1,3 +1,5 @@
+// Owns OpenCL particle kernels and their compute buffers.
+// Supports reset, simulation updates, and readback for staged presentation.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/fd_abi.v b/examples/vulkan_particles/fd_abi.v
index 8d8784b..cacb3d7 100644
--- a/examples/vulkan_particles/fd_abi.v
+++ b/examples/vulkan_particles/fd_abi.v
@@ -1,3 +1,4 @@
+// Adapts Vulkan external-memory and semaphore file-descriptor output pointers to the C ABI.
 module main
 
 import antono2.vulkan as vk
diff --git a/examples/vulkan_particles/frame_resources.v b/examples/vulkan_particles/frame_resources.v
index 9a0ba44..7548cb9 100644
--- a/examples/vulkan_particles/frame_resources.v
+++ b/examples/vulkan_particles/frame_resources.v
@@ -1,3 +1,5 @@
+// Owns per-frame Vulkan command and synchronization resources for particle drawing.
+// Coordinates graphics completion with external compute handoffs.
 module main
 
 import antono2.vulkan as vk
diff --git a/examples/vulkan_particles/interop_probe.v b/examples/vulkan_particles/interop_probe.v
index 0318ffe..9729482 100644
--- a/examples/vulkan_particles/interop_probe.v
+++ b/examples/vulkan_particles/interop_probe.v
@@ -1,3 +1,5 @@
+// Checks matching device UUIDs and external-memory/semaphore capabilities.
+// Reports whether zero-copy presentation is available before choosing the runtime path.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/interop_probe_test.v b/examples/vulkan_particles/interop_probe_test.v
index 237134f..247487c 100644
--- a/examples/vulkan_particles/interop_probe_test.v
+++ b/examples/vulkan_particles/interop_probe_test.v
@@ -1,3 +1,4 @@
+// Checks complete extension-token matching and device UUID comparisons.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/live_sync.v b/examples/vulkan_particles/live_sync.v
index e2906b9..0d3b637 100644
--- a/examples/vulkan_particles/live_sync.v
+++ b/examples/vulkan_particles/live_sync.v
@@ -1,3 +1,5 @@
+// Coordinates live OpenCL/Vulkan access through imported external semaphores.
+// Pairs compute acquire/release operations with graphics ownership handoffs.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/main.v b/examples/vulkan_particles/main.v
index cdeb6f0..d6a4925 100644
--- a/examples/vulkan_particles/main.v
+++ b/examples/vulkan_particles/main.v
@@ -1,3 +1,4 @@
+// Particle-demo entry point selecting headless, staged, or zero-copy execution from options.
 module main
 
 import os
diff --git a/examples/vulkan_particles/options.v b/examples/vulkan_particles/options.v
index b1da489..b1a07c1 100644
--- a/examples/vulkan_particles/options.v
+++ b/examples/vulkan_particles/options.v
@@ -1,3 +1,5 @@
+// Parses particle-demo environment settings and command-line overrides.
+// Rejects incompatible runtime modes before allocating device resources.
 module main
 
 import os
diff --git a/examples/vulkan_particles/options_test.v b/examples/vulkan_particles/options_test.v
index c748ab7..1b34987 100644
--- a/examples/vulkan_particles/options_test.v
+++ b/examples/vulkan_particles/options_test.v
@@ -1,3 +1,4 @@
+// Checks option precedence, invalid combinations, and cursor-to-particle coordinate mapping.
 module main
 
 fn test_command_line_options_override_defaults() {
diff --git a/examples/vulkan_particles/particle_buffer.v b/examples/vulkan_particles/particle_buffer.v
index af7f6fd..d3ab609 100644
--- a/examples/vulkan_particles/particle_buffer.v
+++ b/examples/vulkan_particles/particle_buffer.v
@@ -1,3 +1,5 @@
+// Creates particle buffers for staged uploads or shared external-memory access.
+// Owns the Vulkan allocation and any OpenCL import until explicit destruction.
 module main
 
 import antono2.opencl as cl
diff --git a/examples/vulkan_particles/particles.cl b/examples/vulkan_particles/particles.cl
index c473eb5..a1fb7c1 100644
--- a/examples/vulkan_particles/particles.cl
+++ b/examples/vulkan_particles/particles.cl
@@ -1,3 +1,4 @@
+// OpenCL kernels for deterministic particle initialization and time-step updates.
 typedef struct {
 	float4 position;
 	float4 velocity;
diff --git a/examples/vulkan_particles/particles.frag b/examples/vulkan_particles/particles.frag
index 2fca705..908778c 100644
--- a/examples/vulkan_particles/particles.frag
+++ b/examples/vulkan_particles/particles.frag
@@ -1,3 +1,4 @@
+// Shades particle fragments using interpolated particle color.
 #version 450
 
 layout(location = 0) in vec3 color;
diff --git a/examples/vulkan_particles/particles.vert b/examples/vulkan_particles/particles.vert
index 8623338..268c5a6 100644
--- a/examples/vulkan_particles/particles.vert
+++ b/examples/vulkan_particles/particles.vert
@@ -1,3 +1,4 @@
+// Transforms particle positions and supplies per-particle color to the fragment stage.
 #version 450
 
 layout(location = 0) in vec4 in_position;
diff --git a/examples/vulkan_particles/pipeline.v b/examples/vulkan_particles/pipeline.v
index 209b28f..140c5b3 100644
--- a/examples/vulkan_particles/pipeline.v
+++ b/examples/vulkan_particles/pipeline.v
@@ -1,3 +1,4 @@
+// Creates shader modules and Vulkan pipelines for particle and trail rendering.
 module main
 
 import antono2.vulkan as vk
diff --git a/examples/vulkan_particles/shader_test.v b/examples/vulkan_particles/shader_test.v
index 4dfe2ff..b546f8c 100644
--- a/examples/vulkan_particles/shader_test.v
+++ b/examples/vulkan_particles/shader_test.v
@@ -1,3 +1,4 @@
+// Checks committed shader binaries for valid SPIR-V structure using available tooling.
 module main
 
 import os
diff --git a/examples/vulkan_particles/swapchain.v b/examples/vulkan_particles/swapchain.v
index 4c0179e..77a2ab0 100644
--- a/examples/vulkan_particles/swapchain.v
+++ b/examples/vulkan_particles/swapchain.v
@@ -1,3 +1,5 @@
+// Creates presentation images, views, and framebuffers for the particle window.
+// Queries surface support and destroys the associated swapchain resources.
 module main
 
 import antono2.glfw
diff --git a/examples/vulkan_particles/trails.frag b/examples/vulkan_particles/trails.frag
index 349fa7d..e4cd85d 100644
--- a/examples/vulkan_particles/trails.frag
+++ b/examples/vulkan_particles/trails.frag
@@ -1,3 +1,4 @@
+// Shades trail fragments using the interpolated trail color.
 #version 450
 
 layout(location = 0) in vec3 color;
diff --git a/examples/vulkan_particles/trails.vert b/examples/vulkan_particles/trails.vert
index a353dcb..ab34876 100644
--- a/examples/vulkan_particles/trails.vert
+++ b/examples/vulkan_particles/trails.vert
@@ -1,3 +1,4 @@
+// Transforms trail vertices for the particle demo's history rendering.
 #version 450
 
 layout(location = 0) in vec4 in_position;
diff --git a/examples/vulkan_particles/window_smoke.v b/examples/vulkan_particles/window_smoke.v
index e12fe51..ff45887 100644
--- a/examples/vulkan_particles/window_smoke.v
+++ b/examples/vulkan_particles/window_smoke.v
@@ -1,3 +1,5 @@
+// Runs the GLFW/Vulkan particle presentation loop with staged or shared compute buffers.
+// Maps pointer input into simulation coordinates and selects a graphics/present queue.
 module main
 
 import antono2.glfw
diff --git a/examples/vulkan_particles/zero_copy_smoke.v b/examples/vulkan_particles/zero_copy_smoke.v
index eb3aad7..df189df 100644
--- a/examples/vulkan_particles/zero_copy_smoke.v
+++ b/examples/vulkan_particles/zero_copy_smoke.v
@@ -1,3 +1,4 @@
+// Probes external-memory and semaphore sharing between UUID-matched OpenCL/Vulkan devices.
 module main
 
 import antono2.opencl as cl
diff --git a/external_interop.v b/external_interop.v
index bad1963..3fc713c 100644
--- a/external_interop.v
+++ b/external_interop.v
@@ -1,3 +1,5 @@
+// Loads optional external-memory and semaphore entry points for a selected platform.
+// Imports native handles and coordinates ownership across API boundaries.
 module opencl
 
 $if windows {
diff --git a/image.v b/image.v
index 573ea3a..69e5f82 100644
--- a/image.v
+++ b/image.v
@@ -1,3 +1,4 @@
+// Typed image and sampler ownership with checked dimensions, formats, and transfers.
 module opencl
 
 // Image2D owns a typed two-dimensional OpenCL image. T represents one complete
diff --git a/opencl.v b/opencl.v
index 8ecad26..4673f92 100644
--- a/opencl.v
+++ b/opencl.v
@@ -1,4 +1,6 @@
 // Code generated from the Khronos OpenCL XML API Registry. DO NOT EDIT.
+// Raw OpenCL constants, types, and entry points; resource lifetimes follow the C API.
+// Regenerate in antono2/v_opencl_bindings with python3 src/main.py.
 module opencl
 
 #flag linux -lOpenCL
diff --git a/ownership.v b/ownership.v
index f84a624..5f35ca2 100644
--- a/ownership.v
+++ b/ownership.v
@@ -1,3 +1,5 @@
+// Owned context, queue, and buffer helpers with explicit retain/close operations.
+// Raw handles remain available for operations outside the convenience layer.
 module opencl
 
 // OwnedContext owns one reference to an OpenCL context. Call close when done.
diff --git a/program.v b/program.v
index 486efb1..f9d701f 100644
--- a/program.v
+++ b/program.v
@@ -1,3 +1,4 @@
+// Builds source programs with diagnostic logs and owns kernels and their arguments.
 module opencl
 
 // ProgramBuildError includes the compiler log returned for the selected device.
diff --git a/svm.v b/svm.v
index 42b4fca..9b753c7 100644
--- a/svm.v
+++ b/svm.v
@@ -1,3 +1,4 @@
+// Capability-gated shared virtual memory allocation, mapping, and kernel argument helpers.
 module opencl
 
 fn platform_svm_alloc(context Context, flags SvmMemFlags, size usize, alignment u32) voidptr {
diff --git a/test/pointer_abi_shim.c b/test/pointer_abi_shim.c
index a9b391b..6bcd015 100644
--- a/test/pointer_abi_shim.c
+++ b/test/pointer_abi_shim.c
@@ -1,3 +1,4 @@
+// C-side instrumentation for null pointers, handle arrays, and transfer callback ABI tests.
 #include <CL/opencl.h>
 #include <stddef.h>
 #include <stdint.h>
diff --git a/test/pointer_abi_test.v b/test/pointer_abi_test.v
index 6d807c6..efee09b 100644
--- a/test/pointer_abi_test.v
+++ b/test/pointer_abi_test.v
@@ -1,3 +1,4 @@
+// Checks the exact pointers passed from V wrappers to instrumented C entry points.
 module main
 
 import antono2.opencl as cl