Update and create CLAUDE.md for all crates and packages

Update 6 existing crate CLAUDE.md files with verified corrections:
- iscc-lib: fix symbol count, add META_TRIM_META, document feature gates
- iscc-py: fix function count (21→27), add SumCodeResult, correct build matrix
- iscc-napi: itemize API surface, fix conformance count, correct NPM secret
- iscc-wasm: 12 fixes including wasm-opt flags, publishing flow, struct exceptions
- iscc-ffi: add csbindgen section, complete symbol lists, opaque handle types
- iscc-rb: expand test entries, add unsafe as_slice() safety pattern

Create 4 new CLAUDE.md files for previously undocumented directories:
- iscc-jni: JNI naming, opaque pointer pattern, Maven build, 12 pitfalls
- packages/go: pure Go reimplementation, embedded conformance, 9 pitfalls
- packages/dotnet: P/Invoke bindings, SafeHandle, NuGet publishing, 9 pitfalls
- packages/cpp: header-only C++17, RAII guards, vcpkg portfile, 6 pitfalls

Author: CID Agent

crates/iscc-ffi/CLAUDE.md

@@ -14,16 +14,22 @@ C ABI FFI layer over `iscc-lib`, enabling integration from C, Go (cgo), Java (JN
 
 ```
 crates/iscc-ffi/
-  Cargo.toml         # cdylib + staticlib, depends only on iscc-lib
-  cbindgen.toml      # Header generation config
+  Cargo.toml         # cdylib + staticlib, depends on iscc-lib; csbindgen build-dep
+  cbindgen.toml      # C header generation config
+  build.rs           # Generates C# P/Invoke bindings via csbindgen
+  include/
+    iscc.h           # Generated C header (checked in, regenerate after API changes)
   src/
     lib.rs           # All extern "C" functions, #[repr(C)] types, memory management
   tests/
     test_iscc.c      # C test program that links against the shared library
+  examples/
+    iscc_sum.c       # Streaming example: reads a file, produces ISCC-CODE
+    CMakeLists.txt   # CMake build for the example
 ```
 
 Single-file crate. All FFI symbols, helper functions, `#[repr(C)]` types, and memory management live
-in `src/lib.rs`. Do not split into submodules unless the file exceeds ~1500 lines.
+in `src/lib.rs`. Do not split into submodules unless the file exceeds ~2500 lines.
 
 ## cbindgen Configuration
 
@@ -33,21 +39,41 @@ in `src/lib.rs`. Do not split into submodules unless the file exceeds ~1500 line
 - System includes: `stdint.h`, `stdbool.h`, `stddef.h`
 - Export prefix: `iscc_` (applied to types like `IsccByteBuffer` -> `iscc_IsccByteBuffer`)
 - Function prefix: none (functions already use `iscc_` prefix via naming convention)
-- Header is NOT checked into the repo; generate on demand:
+- Header is checked into the repo at `include/iscc.h`; regenerate after API changes:
     ```bash
     cbindgen --config crates/iscc-ffi/cbindgen.toml --crate iscc-ffi --output crates/iscc-ffi/include/iscc.h
     ```
 
+## csbindgen (C# P/Invoke)
+
+- Build dependency: `csbindgen = "1.9.7"` in `Cargo.toml`
+- `build.rs` reads `src/lib.rs` and generates `packages/dotnet/Iscc.Lib/NativeMethods.g.cs`
+- DLL name: `iscc_ffi`, namespace: `Iscc.Lib`, class: `NativeMethods`
+- Runs automatically on every `cargo build`; no manual step needed
+
 ## C ABI Conventions
 
 ### Naming
 
 - All exported symbols prefixed with `iscc_`
-- Gen functions: `iscc_gen_meta_code_v0`, `iscc_gen_text_code_v0`, etc.
-- Text utilities: `iscc_text_clean`, `iscc_text_collapse`, etc.
-- Algorithm primitives: `iscc_alg_simhash`, `iscc_alg_minhash_256`, `iscc_alg_cdc_chunks`
+- Gen functions: `iscc_gen_meta_code_v0`, `iscc_gen_text_code_v0`, `iscc_gen_image_code_v0`,
+    `iscc_gen_audio_code_v0`, `iscc_gen_video_code_v0`, `iscc_gen_mixed_code_v0`,
+    `iscc_gen_data_code_v0`, `iscc_gen_instance_code_v0`, `iscc_gen_iscc_code_v0`,
+    `iscc_gen_sum_code_v0`
+- Text utilities: `iscc_text_clean`, `iscc_text_collapse`, `iscc_text_remove_newlines`,
+    `iscc_text_trim`
+- Codec: `iscc_encode_component`, `iscc_decode`, `iscc_decompose`, `iscc_encode_base64`,
+    `iscc_json_to_data_url`, `iscc_sliding_window`
+- Algorithm primitives: `iscc_alg_simhash`, `iscc_alg_minhash_256`, `iscc_alg_cdc_chunks`,
+    `iscc_soft_hash_video_v0`
+- Algorithm constants: `iscc_meta_trim_name`, `iscc_meta_trim_description`, `iscc_meta_trim_meta`,
+    `iscc_io_read_size`, `iscc_text_ngram_size`
+- Streaming hashers: `iscc_data_hasher_new`, `iscc_data_hasher_update`, `iscc_data_hasher_finalize`,
+    `iscc_data_hasher_free`, `iscc_instance_hasher_new`, `iscc_instance_hasher_update`,
+    `iscc_instance_hasher_finalize`, `iscc_instance_hasher_free`
 - Memory management: `iscc_free_string`, `iscc_free_string_array`, `iscc_free_byte_buffer`,
-    `iscc_free_byte_buffer_array`
+    `iscc_free_byte_buffer_array`, `iscc_free_decode_result`, `iscc_free_sum_code_result`
+- WASM allocator: `iscc_alloc`, `iscc_dealloc`
 - Error retrieval: `iscc_last_error`
 - Diagnostics: `iscc_conformance_selftest`
 
@@ -73,16 +99,22 @@ in `src/lib.rs`. Do not split into submodules unless the file exceeds ~1500 line
 
 ## Rust-to-C Type Mapping
 
-| Rust type                  | C type                                | Notes                                                        |
-| -------------------------- | ------------------------------------- | ------------------------------------------------------------ |
-| `*const c_char`            | `const char *`                        | Input strings (null-terminated UTF-8)                        |
-| `*mut c_char`              | `char *`                              | Output strings (caller frees)                                |
-| `*const u8` / `*const i32` | `const uint8_t *` / `const int32_t *` | Input byte/int buffers                                       |
-| `usize`                    | `size_t`                              | Buffer lengths                                               |
-| `u32`                      | `uint32_t`                            | `bits` parameter, feature values                             |
-| `bool`                     | `bool`                                | Requires `stdbool.h`                                         |
-| `IsccByteBuffer`           | `struct iscc_IsccByteBuffer`          | `#[repr(C)]`: `{data: *mut u8, len: usize}`                  |
-| `IsccByteBufferArray`      | `struct iscc_IsccByteBufferArray`     | `#[repr(C)]`: `{buffers: *mut IsccByteBuffer, count: usize}` |
+| Rust type                  | C type                                   | Notes                                                            |
+| -------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
+| `*const c_char`            | `const char *`                           | Input strings (null-terminated UTF-8)                            |
+| `*mut c_char`              | `char *`                                 | Output strings (caller frees)                                    |
+| `*const u8` / `*const i32` | `const uint8_t *` / `const int32_t *`    | Input byte/int buffers                                           |
+| `usize`                    | `uintptr_t`                              | Buffer lengths (cbindgen maps `usize` to `uintptr_t`)            |
+| `u32`                      | `uint32_t`                               | `bits` parameter, feature values                                 |
+| `u64`                      | `uint64_t`                               | `filesize` in `IsccSumCodeResult`                                |
+| `u8`                       | `uint8_t`                                | `mtype`, `stype`, `version`, `length` in codec functions         |
+| `bool`                     | `bool`                                   | Requires `stdbool.h`                                             |
+| `IsccByteBuffer`           | `struct iscc_IsccByteBuffer`             | `#[repr(C)]`: `{data: *mut u8, len: usize}`                      |
+| `IsccByteBufferArray`      | `struct iscc_IsccByteBufferArray`        | `#[repr(C)]`: `{buffers: *mut IsccByteBuffer, count: usize}`     |
+| `IsccDecodeResult`         | `struct iscc_IsccDecodeResult`           | `#[repr(C)]`: `{ok, maintype, subtype, version, length, digest}` |
+| `IsccSumCodeResult`        | `struct iscc_IsccSumCodeResult`          | `#[repr(C)]`: `{ok, iscc, datahash, filesize, units}`            |
+| `FfiDataHasher`            | `struct iscc_FfiDataHasher` (opaque)     | Not `#[repr(C)]`; interact only through function pointers        |
+| `FfiInstanceHasher`        | `struct iscc_FfiInstanceHasher` (opaque) | Not `#[repr(C)]`; interact only through function pointers        |
 
 ## Build Commands
 
@@ -116,7 +148,8 @@ LD_LIBRARY_PATH=target/debug /tmp/test_iscc
 ### C tests (`tests/test_iscc.c`)
 
 - Links against the shared library and `#include "iscc.h"`
-- Uses assertion macros: `ASSERT_STR_EQ`, `ASSERT_NULL`, `ASSERT_NOT_NULL`, `ASSERT_EQ`
+- Uses assertion macros: `ASSERT_STR_EQ`, `ASSERT_STR_STARTS_WITH`, `ASSERT_NULL`,
+    `ASSERT_NOT_NULL`, `ASSERT_EQ`
 - Mirrors the Rust unit test cases with identical expected values
 - Reports pass/fail counts and exits non-zero on any failure
 - Every returned string/buffer is freed to validate the free functions
@@ -129,7 +162,7 @@ LD_LIBRARY_PATH=target/debug /tmp/test_iscc
 - Validate UTF-8 for all `*const c_char` inputs via `CStr::from_ptr` + `.to_str()`
 - Use `#[unsafe(no_mangle)]` (Rust 2024 edition syntax) on all exported functions
 - Use `#[repr(C)]` only on types returned across the FFI boundary (`IsccByteBuffer`,
-    `IsccByteBufferArray`)
+    `IsccByteBufferArray`, `IsccDecodeResult`, `IsccSumCodeResult`)
 - Never expose `Vec`, `String`, `Box`, or any Rust-specific type across FFI
 - Use `into_boxed_slice()` + `Box::into_raw()` to transfer Vec ownership across FFI; reconstruct
     with `Box::from_raw(slice::from_raw_parts_mut(ptr, len))` to free
@@ -150,8 +183,14 @@ LD_LIBRARY_PATH=target/debug /tmp/test_iscc
 - **Missing free functions**: if you add a new return type, you must add a corresponding
     `iscc_free_*` function.
 - **cbindgen regeneration**: after adding or changing exported functions or `#[repr(C)]` types,
-    regenerate the header. The C test will fail to compile if the header is stale.
+    regenerate the C header. The C test will fail to compile if the header is stale.
+- **csbindgen regeneration**: C# bindings regenerate automatically via `build.rs` on every
+    `cargo build`. After changing function signatures, verify the generated
+    `packages/dotnet/Iscc.Lib/NativeMethods.g.cs` is correct.
 - **Optional parameters**: use NULL for optional `*const c_char` params (e.g., `description` and
     `meta` in `iscc_gen_meta_code_v0`). Use `ptr_to_optional_str` for these, not `ptr_to_str`.
 - **Array parameters**: multi-element inputs (frame signatures, code arrays, digest arrays) use
     parallel arrays of pointers and lengths rather than a single struct array.
+- **Struct return types**: `IsccDecodeResult` and `IsccSumCodeResult` are returned by value (not
+    pointer). Each has a dedicated `iscc_free_*` function that must be called to release interior
+    heap allocations, even on error.