docs: update documentation for collection mapping support

README.md

@@ -57,15 +57,15 @@ public class Product
 ### 2. Create a mapper class
 
 ```csharp
-using DynamoMapper.Attributes;
+using DynamoMapper.Runtime;
 using Amazon.DynamoDBv2.Model;
 
 namespace MyApp.Data;
 
 [DynamoMapper(Convention = DynamoNamingConvention.CamelCase)]
+[DynamoField(nameof(Product.Description), OmitIfNull = true, OmitIfEmptyString = true)]
 public static partial class ProductMapper
 {
-    [DynamoField(nameof(Product.Description), OmitIfNullOrWhiteSpace = true)]
     public static partial Dictionary<string, AttributeValue> ToItem(Product source);
 
     public static partial Product FromItem(Dictionary<string, AttributeValue> item);
@@ -111,15 +111,15 @@ For more examples including single-table patterns and custom converters, see the
 
 ## Key Features
 
-- **Attribute-Based Configuration** (Phase 1): Configure mapping via `[DynamoField]` and `[DynamoIgnore]` attributes on mapper methods
+- **Attribute-Based Configuration** (Phase 1): Configure mapping via `[DynamoField]` and `[DynamoIgnore]` on mapper classes
 - **Fluent DSL Configuration** (Phase 2): Optional strongly-typed DSL for configuration
 - **Naming Conventions**: CamelCase, SnakeCase, or Exact field naming
 - **Required Field Validation**: Compile-time and runtime validation of required fields
 - **Omission Policies**: Flexible null/empty value omission strategies
 - **Custom Converters**: Type-safe converter pattern for custom serialization
 - **Customization Hooks**: Before/After hooks for injecting pk/sk and custom logic
 - **Single-Table Support**: Built for single-table DynamoDB design patterns
-- **Supported Types**: string, numeric types, bool, Guid, DateTime, DateTimeOffset, TimeSpan, enums
+- **Supported Types**: strings, numerics, bool, Guid, DateTime, DateTimeOffset, TimeSpan, enums, plus lists/maps/sets of supported element types
 - **Comprehensive Diagnostics**: Clear compile-time errors with actionable messages
 - **Zero Configuration**: Sensible defaults for most use cases
 
@@ -155,4 +155,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Made with ⚡ by the LayeredCraft team**
+**Made with ⚡ by the LayeredCraft team**

docs/api-reference/attributes.md

@@ -1,3 +1,64 @@
 # Attributes
 
-Documentation coming soon. See [Phase 1 Requirements](../roadmap/phase-1.md) for detailed specifications.
+DynamoMapper configuration is done via attributes on the **mapper class**.
+
+## DynamoMapperAttribute
+
+Marks a static partial class as a mapper and sets defaults.
+
+```csharp
+[DynamoMapper(
+    Convention = DynamoNamingConvention.CamelCase,
+    DefaultRequiredness = Requiredness.InferFromNullability,
+    OmitNullStrings = true,
+    OmitEmptyStrings = false,
+    DateTimeFormat = "O",
+    EnumFormat = "G")]
+public static partial class OrderMapper
+{
+    public static partial Dictionary<string, AttributeValue> ToItem(Order source);
+    public static partial Order FromItem(Dictionary<string, AttributeValue> item);
+}
+```
+
+## DynamoFieldAttribute
+
+Configures mapping for a specific member. Apply multiple times to the mapper class.
+
+```csharp
+[DynamoMapper]
+[DynamoField(nameof(Order.Notes), OmitIfNull = true, OmitIfEmptyString = true)]
+[DynamoField(nameof(Order.OrderId), AttributeName = "orderId")]
+public static partial class OrderMapper
+{
+    public static partial Dictionary<string, AttributeValue> ToItem(Order source);
+    public static partial Order FromItem(Dictionary<string, AttributeValue> item);
+}
+```
+
+Properties:
+- `MemberName` (ctor) - target member name
+- `AttributeName` - DynamoDB attribute name override
+- `Required` - requiredness override
+- `Kind` - DynamoDB `DynamoKind` override
+- `OmitIfNull` - omit when null
+- `OmitIfEmptyString` - omit when empty string
+- `ToMethod` / `FromMethod` - static conversion methods on the mapper class
+
+## DynamoIgnoreAttribute
+
+Skips a member in one or both directions.
+
+```csharp
+[DynamoMapper]
+[DynamoIgnore(nameof(Order.InternalNotes), Ignore = IgnoreMapping.All)]
+public static partial class OrderMapper
+{
+    public static partial Dictionary<string, AttributeValue> ToItem(Order source);
+    public static partial Order FromItem(Dictionary<string, AttributeValue> item);
+}
+```
+
+Properties:
+- `MemberName` (ctor) - target member name
+- `Ignore` - `IgnoreMapping.All`, `IgnoreMapping.FromModel`, or `IgnoreMapping.ToModel`

docs/api-reference/generated-code.md

@@ -1,3 +1,47 @@
 # Generated Code
 
-Documentation coming soon. See [Phase 1 Requirements](../roadmap/phase-1.md) for detailed specifications.
+The generator emits explicit `ToItem`/`FromItem` implementations that call the runtime
+extension methods. The example below is a real-world output.
+
+```csharp
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This code was generated by a tool.
+//
+//     Changes to this file may cause incorrect behavior and will be lost if
+//     the code is regenerated.
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+#nullable enable
+
+using DynamoMapper.Runtime;
+using System.Collections.Generic;
+using Amazon.DynamoDBv2.Model;
+
+namespace Trivia.Manager.Shared.Models;
+
+internal static partial class DuplicateResultMapper
+{
+    [global::System.CodeDom.Compiler.GeneratedCode("DynamoMapper", "1.0.0.0")]
+    internal static partial global::System.Collections.Generic.Dictionary<string, global::Amazon.DynamoDBv2.Model.AttributeValue> ToItem(global::Trivia.Manager.Shared.Models.DuplicateResult duplicateResult) =>
+        new Dictionary<string, AttributeValue>(2)
+            .SetString("id", duplicateResult.Id, false, true)
+            .Set("score", ScoreToAttribute(duplicateResult));
+
+    [global::System.CodeDom.Compiler.GeneratedCode("DynamoMapper", "1.0.0.0")]
+    internal static partial global::Trivia.Manager.Shared.Models.DuplicateResult FromItem(global::System.Collections.Generic.Dictionary<string, global::Amazon.DynamoDBv2.Model.AttributeValue> item)
+    {
+        var duplicateResult = new global::Trivia.Manager.Shared.Models.DuplicateResult
+        {
+            Id = item.GetString("id", Requiredness.InferFromNullability),
+            Score = item.GetFloat("score", Requiredness.InferFromNullability),
+        };
+        return duplicateResult;
+    }
+}
+```
+
+Notes:
+- Generated code uses `SetX`/`GetX` helpers from `DynamoMapper.Runtime`.
+- Class-level `[DynamoField]`/`[DynamoIgnore]` configuration influences argument values.

docs/api-reference/runtime-helpers.md

@@ -1,3 +1,75 @@
 # Runtime Helpers
 
-Documentation coming soon. See [Phase 1 Requirements](../roadmap/phase-1.md) for detailed specifications.
+The runtime package exposes extension methods on
+`Dictionary<string, AttributeValue>` for both generated code and manual use.
+
+## Core Value Helpers
+
+These methods live in `DynamoMapper.Runtime` and are used by the generator.
+
+String:
+- `GetString`, `GetNullableString`
+- `SetString`
+
+Boolean:
+- `GetBool`, `GetNullableBool`
+- `SetBool`
+
+Numbers:
+- `GetInt`, `GetNullableInt`
+- `GetLong`, `GetNullableLong`
+- `GetFloat`, `GetNullableFloat`
+- `GetDouble`, `GetNullableDouble`
+- `GetDecimal`, `GetNullableDecimal`
+- `GetShort`, `GetNullableShort`
+- `GetByte`, `GetNullableByte`
+- `SetInt`, `SetLong`, `SetFloat`, `SetDouble`, `SetDecimal`, `SetShort`, `SetByte`
+
+Date/Time:
+- `GetDateTime`, `GetNullableDateTime`
+- `GetDateTimeOffset`, `GetNullableDateTimeOffset`
+- `GetTimeSpan`, `GetNullableTimeSpan`
+- `SetDateTime`, `SetDateTimeOffset`, `SetTimeSpan`
+
+Guid:
+- `GetGuid`, `GetNullableGuid`
+- `SetGuid`
+
+Enum:
+- `GetEnum<T>`, `GetNullableEnum<T>`
+- `SetEnum<T>`
+
+## Collection Helpers
+
+Lists and maps:
+- `GetList<T>`, `GetNullableList<T>`
+- `SetList<T>`
+- `GetMap<T>`, `GetNullableMap<T>`
+- `SetMap<T>`
+
+Sets:
+- `GetStringSet`, `GetNullableStringSet`, `SetStringSet`
+- `GetNumberSet<T>`, `GetNullableNumberSet<T>`, `SetNumberSet<T>`
+- `GetBinarySet`, `GetNullableBinarySet`, `SetBinarySet`
+
+## Parameters
+
+- `Requiredness` controls missing-attribute behavior (`Required`, `Optional`,
+  `InferFromNullability`).
+- `DynamoKind` lets you override the inferred DynamoDB kind.
+
+## Example
+
+```csharp
+var attributes = new Dictionary<string, AttributeValue>();
+
+attributes
+    .SetString("pk", "USER#123")
+    .SetInt("version", 2)
+    .SetList("tags", new List<string> { "alpha", "beta" })
+    .SetMap("metadata", new Dictionary<string, int> { ["count"] = 42 })
+    .SetBinarySet("payloads", new List<byte[]> { new byte[] { 1, 2, 3 } });
+
+var tags = attributes.GetList<string>("tags");
+var version = attributes.GetInt("version");
+```