docs: add JSON/protobuf compatibility guide for unwrap feature

- Create new docs/json-protobuf-compatibility.md with comprehensive
  guide for handling map values that serialize as arrays
- Update http-generation.md with unwrap annotation example
- Update openapi-generation.md with unwrap schema mapping
- Update client-generation.md with unwrap serialization note
- Update getting-started.md with link to new compatibility guide
- Update CLAUDE.md with unwrap annotation and test references

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: SebastienMelki

CLAUDE.md

@@ -151,6 +151,20 @@ service UserService {
 }
 ```
 
+**Unwrap Annotation** - For map values that should serialize as arrays in JSON:
+```protobuf
+// Wrapper message with unwrap annotation
+message BarList {
+  repeated Bar bars = 1 [(sebuf.http.unwrap) = true];
+}
+
+message Response {
+  // JSON: {"bars": {"AAPL": [...], "GOOG": [...]}}
+  // Without unwrap: {"bars": {"AAPL": {"bars": [...]}, ...}}
+  map<string, BarList> bars = 1;
+}
+```
+
 ## Development Commands
 
 ### Testing
@@ -209,6 +223,7 @@ The project uses a comprehensive two-tier testing approach:
 - **Function-level testing**: Tests individual functions for HTTP and OpenAPI generators
 - **Mocked components**: Uses protogen mocks for isolated testing
 - **File locations**: internal/httpgen/ and internal/openapiv3/ test files
+- **Unwrap tests**: internal/httpgen/unwrap_test.go for map value unwrapping
 
 ## Validation System
 

docs/client-generation.md

@@ -181,6 +181,8 @@ const (
 client := api.NewUserServiceClient("http://localhost:8080")
 ```
 
+The client automatically handles special JSON serialization, including messages with `unwrap` annotations for map values. See [JSON/Protobuf Compatibility](./json-protobuf-compatibility.md) for details.
+
 ### Binary Protobuf
 
 For better performance with large payloads:

docs/getting-started.md

@@ -203,6 +203,7 @@ curl -X GET http://localhost:8080/api/v1/users/1
 - **[Client Generation Guide](./client-generation.md)** - Type-safe HTTP clients
 - **[OpenAPI Guide](./openapi-generation.md)** - Documentation customization
 - **[Validation Guide](./validation.md)** - Automatic request validation
+- **[JSON/Protobuf Compatibility](./json-protobuf-compatibility.md)** - Handling serialization edge cases
 
 ## More examples
 

docs/http-generation.md

@@ -1169,6 +1169,27 @@ message UploadFileRequest {
 }
 ```
 
+### Map with Array Values (Unwrap)
+
+When you need a map where values are arrays (common in market data APIs):
+
+```protobuf
+import "sebuf/http/annotations.proto";
+
+// Wrapper message with unwrap annotation
+message BarList {
+  repeated Bar bars = 1 [(sebuf.http.unwrap) = true];
+}
+
+message GetBarsResponse {
+  // JSON output: {"bars": {"AAPL": [...], "GOOG": [...]}}
+  // Instead of: {"bars": {"AAPL": {"bars": [...]}, ...}}
+  map<string, BarList> bars = 1;
+}
+```
+
+See [JSON and Protobuf Compatibility](./json-protobuf-compatibility.md) for complete details.
+
 ## Best Practices
 
 ### 1. Consistent URL Design
@@ -1426,6 +1447,7 @@ The OpenAPI spec will automatically reflect your HTTP annotations and routing.
 **See also:**
 - [Getting Started Guide](./getting-started.md)
 - [Validation Guide](./validation.md)
+- [JSON/Protobuf Compatibility](./json-protobuf-compatibility.md)
 - [All Examples](./examples/)
 
 **Feature-specific examples:**