docs: split contract pattern guides

Author: adz

README.md

@@ -14,14 +14,17 @@
 [![Last Commit](https://img.shields.io/github/last-commit/adz/CodecMapper)](https://github.com/adz/CodecMapper/commits/main)
 [![Stars](https://img.shields.io/github/stars/adz/CodecMapper?style=social)](https://github.com/adz/CodecMapper/stargazers)
 
-`CodecMapper` is a schema-first serialization library for F# focused on explicit wire contracts, symmetric encode/decode behavior, and portability to Native AOT and Fable-style targets.
+CodecMapper is a schema-first serialization library for F# focused on explicit wire contracts,
+symmetric encode/decode behavior, and portability to Native AOT and Fable-style targets.
 
-It is for cases where serializer attributes and implicit conventions stop being helpful. You define one schema that mirrors the wire shape, then compile it into reusable codecs.
+It's for cases where serializer attributes and implicit conventions stop being helpful. 
+You define one schema that mirrors the wire shape, then compile it into reusable codecs.
 
 ## Why the schema feels different
 
 ```fsharp
 open CodecMapper
+open CodecMapper.Schema
 
 type Address = { Street: string; City: string }
 let makeAddress street city = { Street = street; City = city }
@@ -30,19 +33,19 @@ type Person = { Id: int; Name: string; Home: Address }
 let makePerson id name home = { Id = id; Name = name; Home = home }
 
 let addressSchema =
-    Schema.define<Address>
-    |> Schema.construct makeAddress
-    |> Schema.field "street" _.Street
-    |> Schema.field "city" _.City
-    |> Schema.build
+    define<Address>
+    |> construct makeAddress
+    |> field "street" _.Street
+    |> field "city" _.City
+    |> build
 
 let personSchema =
-    Schema.define<Person>
-    |> Schema.construct makePerson
-    |> Schema.field "id" _.Id
-    |> Schema.field "name" _.Name
-    |> Schema.fieldWith "home" _.Home addressSchema
-    |> Schema.build
+    define<Person>
+    |> construct makePerson
+    |> field "id" _.Id
+    |> field "name" _.Name
+    |> fieldWith "home" _.Home addressSchema
+    |> build
 
 let codec = Json.compile personSchema
 let person =
@@ -142,6 +145,8 @@ One of the main benefits over convention-based serializers is that model evoluti
 If your domain gets richer but the wire contract does not need to change yet, keep the same wire shape and refine it:
 
 ```fsharp
+open CodecMapper.Schema
+
 type UserId = UserId of int
 
 module UserId =
@@ -155,15 +160,15 @@ type Account = { Id: UserId; Name: string }
 let makeAccount id name = { Id = id; Name = name }
 
 let userIdSchema =
-    Schema.int
-    |> Schema.tryMap UserId.create UserId.value
+    int
+    |> tryMap UserId.create UserId.value
 
 let accountSchema =
-    Schema.define<Account>
-    |> Schema.construct makeAccount
-    |> Schema.fieldWith "id" _.Id userIdSchema
-    |> Schema.field "name" _.Name
-    |> Schema.build
+    define<Account>
+    |> construct makeAccount
+    |> fieldWith "id" _.Id userIdSchema
+    |> field "name" _.Name
+    |> build
 ```
 
 The JSON contract is still:
@@ -177,16 +182,18 @@ The in-memory model is stronger, but you did not need a second DTO type just to
 If the wire contract really changes, the schema changes with it in one obvious place:
 
 ```fsharp
+open CodecMapper.Schema
+
 type PersonV2 = { Id: int; Name: string; Email: string option }
 let makePersonV2 id name email = { Id = id; Name = name; Email = email }
 
 let personV2Schema =
-    Schema.define<PersonV2>
-    |> Schema.construct makePersonV2
-    |> Schema.field "id" _.Id
-    |> Schema.field "name" _.Name
-    |> Schema.field "email" _.Email
-    |> Schema.build
+    define<PersonV2>
+    |> construct makePersonV2
+    |> field "id" _.Id
+    |> field "name" _.Name
+    |> field "email" _.Email
+    |> build
 ```
 
 That does not silently "pick up" the new field just because the record changed. You add it deliberately to the schema, so the contract review point is explicit.
@@ -227,7 +234,8 @@ When benchmark numbers move, profile before changing the runtime. The repo now i
 ## Docs
 
 - Start with [Getting started](docs/GETTING_STARTED.md).
-- Copy from [How to model common contract patterns](docs/HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md).
+- Use the [contract pattern index](docs/HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md) when you need a quick jump page.
+- Copy from [How to model a basic record](docs/HOW_TO_MODEL_A_BASIC_RECORD.md), [how to model a nested record](docs/HOW_TO_MODEL_A_NESTED_RECORD.md), [how to model a validated wrapper](docs/HOW_TO_MODEL_A_VALIDATED_WRAPPER.md), or [how to model a versioned contract](docs/HOW_TO_MODEL_A_VERSIONED_CONTRACT.md).
 - Use [Configuration contracts guide](docs/CONFIG_CONTRACTS.md) for versioned config shapes.
 - Use [How to export JSON Schema](docs/HOW_TO_EXPORT_JSON_SCHEMA.md) and [JSON Schema support reference](docs/JSON_SCHEMA_SUPPORT.md) for schema interchange.
 - Use [How to import existing C# contracts](docs/HOW_TO_IMPORT_CSHARP_CONTRACTS.md) for the bridge/facade story.

docs/CONFIG_CONTRACTS.md

@@ -66,6 +66,8 @@ Use this for flat config-style boundaries only. Collections, raw JSON, and other
 When a config field should fall back to a known value only when it is absent, keep that policy explicit in the schema:
 
 ```fsharp
+open CodecMapper.Schema
+
 type AppConfig =
     {
         Mode: string
@@ -74,17 +76,17 @@ type AppConfig =
     }
 
 let appConfigSchema =
-    Schema.define<AppConfig>
-    |> Schema.construct (fun mode retryCount labels ->
+    define<AppConfig>
+    |> construct (fun mode retryCount labels ->
         {
             Mode = mode
             RetryCount = retryCount
             Labels = labels
         })
-    |> Schema.fieldWith "mode" _.Mode (Schema.string |> Schema.missingAsValue "strict")
-    |> Schema.fieldWith "retry_count" _.RetryCount (Schema.int |> Schema.missingAsValue 3)
-    |> Schema.fieldWith "labels" _.Labels (Schema.list Schema.string |> Schema.missingAsValue [])
-    |> Schema.build
+    |> fieldWith "mode" _.Mode (string |> missingAsValue "strict")
+    |> fieldWith "retry_count" _.RetryCount (int |> missingAsValue 3)
+    |> fieldWith "labels" _.Labels (list string |> missingAsValue [])
+    |> build
 ```
 
 That keeps the default local to the contract instead of smuggling it through serializer settings or post-deserialize mutation.
@@ -94,22 +96,24 @@ That keeps the default local to the contract instead of smuggling it through ser
 Some config boundaries treat an explicit `null` or an explicit empty collection as "use the contract default" rather than as a distinct payload state. Keep that normalization local to the field too:
 
 ```fsharp
+open CodecMapper.Schema
+
 type ServiceConfig =
     {
         Region: string
         Labels: string list
     }
 
 let serviceConfigSchema =
-    Schema.define<ServiceConfig>
-    |> Schema.construct (fun region labels ->
+    define<ServiceConfig>
+    |> construct (fun region labels ->
         {
             Region = region
             Labels = labels
         })
-    |> Schema.fieldWith "region" _.Region (Schema.string |> Schema.nullAsValue "global")
-    |> Schema.fieldWith "labels" _.Labels (Schema.list Schema.string |> Schema.emptyCollectionAsValue [ "general" ])
-    |> Schema.build
+    |> fieldWith "region" _.Region (string |> nullAsValue "global")
+    |> fieldWith "labels" _.Labels (list string |> emptyCollectionAsValue [ "general" ])
+    |> build
 ```
 
 That means:
@@ -142,14 +146,14 @@ retry_count: 3
 mode: strict
 ```
 
-Current YAML scope is intentionally narrow:
+The YAML projection supports:
 
 - mappings
 - sequences
 - scalars and `null`
 - quoted or plain strings
 
-It does not aim at full YAML feature parity. Anchors, tags, multi-document streams, block scalars, and broader YAML syntax are still out of scope.
+Unsupported YAML features include anchors, tags, multi-document streams, block scalars, and broader YAML syntax.
 
 ## Recommended Shape
 
@@ -329,6 +333,8 @@ With `CodecMapper`, the wire contract should be explicit in the schema, not infe
 A versioned envelope schema is the right place to make changes visible:
 
 ```fsharp
+open CodecMapper.Schema
+
 type AppConfigV2 =
     {
         ServiceUrl: string
@@ -344,29 +350,29 @@ type VersionEnvelope<'T> =
 
 module Schemas =
     let appConfigV2 =
-        Schema.define<AppConfigV2>
-        |> Schema.construct (fun serviceUrl retryCount mode ->
+        define<AppConfigV2>
+        |> construct (fun serviceUrl retryCount mode ->
             {
                 ServiceUrl = serviceUrl
                 RetryCount = retryCount
                 Mode = mode
             })
-        |> Schema.field "service_url" _.ServiceUrl
-        |> Schema.field "retry_count" _.RetryCount
-        |> Schema.field "mode" _.Mode
-        |> Schema.build
+        |> field "service_url" _.ServiceUrl
+        |> field "retry_count" _.RetryCount
+        |> field "mode" _.Mode
+        |> build
 ```
 
 Then wrap that with a schema for the envelope:
 
 ```fsharp
 module Schemas =
     let versionEnvelope inner =
-        Schema.define<VersionEnvelope<'T>>
-        |> Schema.construct (fun version config -> { Version = version; Config = config })
-        |> Schema.field "version" _.Version
-        |> Schema.fieldWith "config" _.Config inner
-        |> Schema.build
+        define<VersionEnvelope<'T>>
+        |> construct (fun version config -> { Version = version; Config = config })
+        |> field "version" _.Version
+        |> fieldWith "config" _.Config inner
+        |> build
 ```
 
 The latest version should be the one you serialize.