Integrate deep-dive content into API docs and expand mapping

docs/fluent-builder-api.md

@@ -1,6 +1,13 @@
 # Fluent Builder API
 
-The fluent API is built around interfaces like `IDynamicSelectQueryBuilder`, `IDynamicInsertQueryBuilder`, `IDynamicUpdateQueryBuilder`, and `IDynamicDeleteQueryBuilder`.
+The fluent API is built around interfaces like:
+
+- `IDynamicSelectQueryBuilder`
+- `IDynamicInsertQueryBuilder`
+- `IDynamicUpdateQueryBuilder`
+- `IDynamicDeleteQueryBuilder`
+
+This API is best when SQL structure must be explicit and composable.
 
 ## Core Select Flow
 
@@ -26,10 +33,11 @@ using (var query = db.From<User>("u")
 
 ## Parser Lambda Patterns
 
-The parser supports patterns tested in `DynamORM.Tests/Select/ParserTests.cs`:
+The parser supports patterns tested in `DynamORM.Tests/Select/ParserTests.cs` and `DynamORM.Tests/Select/LegacyParserTests.cs`:
 
 - `From(x => x.dbo.Users)`
 - `From(x => x.dbo.Users.As(x.u))`
+- `From(x => "dbo.Users AS u")`
 - `Join(x => x.Left().Accounts.As(x.a).On(x.a.userId == x.u.id))`
 - `Where(x => x.Or(x.u.id > 100))`
 - `Select(x => x.u.first.As(x.firstName))`
@@ -37,10 +45,28 @@ The parser supports patterns tested in `DynamORM.Tests/Select/ParserTests.cs`:
 - `Having(x => x.Count() > 1)`
 - `OrderBy(x => x.u.id.Desc())`
 
+## Joins and Projection Example
+
+```csharp
+using (var query = db.From("users", "u")
+    .Join(x => x.Left().profiles.As(x.p).On(x.p.user_id == x.u.id))
+    .Select(
+        x => x.u.id,
+        x => x.u.first.As(x.firstName),
+        x => x.p.city.As(x.city))
+    .Where(x => x.u.id > 10)
+    .OrderBy(x => x.u.id.Desc()))
+{
+    var rows = query.Execute().ToList();
+}
+```
+
 ## Subqueries
 
 ```csharp
-var sub = new DynamicSelectQueryBuilder(db).From(x => x.dbo.Users);
+var sub = new DynamicSelectQueryBuilder(db)
+    .From(x => x.dbo.Users)
+    .Where(x => x.id > 100);
 
 using (var query = new DynamicSelectQueryBuilder(db)
     .From(x => x(sub).As("u"))
@@ -61,7 +87,10 @@ var count = db.From<User>()
 ## Modify Builders
 
 ```csharp
-db.Insert("users").Values("code", "301").Values("first", "Ada").Execute();
+db.Insert("users")
+    .Values("code", "301")
+    .Values("first", "Ada")
+    .Execute();
 
 db.Update("users")
     .Values("first", "Alicia")
@@ -73,6 +102,15 @@ db.Delete("users")
     .Execute();
 ```
 
+Typed variant:
+
+```csharp
+db.Insert<User>()
+    .Values(x => x.code, "302")
+    .Values(x => x.first, "Grace")
+    .Execute();
+```
+
 ## SQL Inspection
 
 You can inspect generated SQL from builder objects: