Integrate deep-dive content into API docs and expand mapping

docs/dynamic-table-api.md

@@ -1,11 +1,13 @@
 # Dynamic Table API
 
-The dynamic table API centers on `DynamicTable` and allows expressive calls like:
+The dynamic table API centers on `DynamicTable` and allows concise runtime calls.
 
 ```csharp
 dynamic users = db.Table("users");
 ```
 
+This API is best when table/column selection is dynamic or you want very short CRUD code.
+
 ## Read Operations
 
 Examples backed by `DynamORM.Tests/Select/DynamicAccessTests.cs`:
@@ -23,6 +25,14 @@ users.Single(id: 19);
 users.Query(columns: "first,last", order: "id:desc");
 ```
 
+## Filtering with Named Arguments
+
+```csharp
+users.Count(first: "Ori");
+users.Single(code: "101");
+users.Query(columns: "id,first", id: 19);
+```
+
 ## Conditions with `DynamicColumn`
 
 ```csharp
@@ -30,18 +40,32 @@ users.Count(where: new DynamicColumn("id").Greater(100));
 users.Count(where: new DynamicColumn("login").Like("Hoyt.%"));
 users.Count(where: new DynamicColumn("id").Between(75, 100));
 users.Count(where: new DynamicColumn("id").In(75, 99, 100));
+users.Count(where: new DynamicColumn("id").In(new[] { 75, 99, 100 }));
+```
+
+Using aggregate expressions in a condition:
+
+```csharp
+users.Count(condition1: new DynamicColumn
+{
+    ColumnName = "email",
+    Aggregate = "length",
+    Operator = DynamicColumn.CompareOperator.Gt,
+    Value = 27
+});
 ```
 
 ## Insert
 
 ```csharp
-users.Insert(code: "201", first: "Juri", last: "Gagarin");
+users.Insert(code: "201", first: "Juri", last: "Gagarin", email: "juri.gagarin@megacorp.com");
 
 users.Insert(values: new
 {
     code = "202",
     first = "Juri",
-    last = "Gagarin"
+    last = "Gagarin",
+    email = "juri.gagarin@megacorp.com"
 });
 ```
 
@@ -69,10 +93,24 @@ users.Delete(where: new { id = 14, code = 14 });
 ```csharp
 users.Count(type: typeof(User), columns: "id");
 users.Query(type: typeof(User));
+
+var list = (users.Query(type: typeof(User)) as IEnumerable<object>)
+    .Cast<User>()
+    .ToList();
 ```
 
 These usage patterns are covered in `DynamORM.Tests/Select/TypedAccessTests.cs`.
 
+## When to Prefer Fluent Builder Instead
+
+Use fluent builders when:
+
+- Query structure is complex (joins/subqueries/having).
+- You need deterministic SQL text assertions.
+- You prefer strongly typed lambda parser expressions.
+
+See [Fluent Builder API](fluent-builder-api.md).
+
 ## Notes
 
 - Dynamic member names map to table/column names and builder conventions.