done with wuditing with AI

README.md

@@ -102,7 +102,7 @@ pgm -version
 
 ### 1. Create Your Schema
 
-Create a SQL schema file `schema.sql`:
+Create a SQL schema file `schema.sql` or use the one created by [dbmate](https://github.com/amacneil/dbmate):
 
 ```sql
 CREATE TABLE users (
@@ -174,16 +174,49 @@ func main() {
 
 ## Important: Query Builder Lifecycle
 
-⚠️ **Query builders are single-use and should not be reused:**
+### ✅ Conditional Building (CORRECT)
+
+Query builders are **mutable by design** to support conditional query building:
 
 ```go
-// ❌ WRONG - Don't reuse query builders
-baseQuery := users.User.Select(users.ID, users.Email)
-baseQuery.Where(users.ID.Eq(1)).First(ctx, &id1, &email1)
-baseQuery.Where(users.Status.Eq(2)).First(ctx, &id2, &email2)
-// Second query has BOTH WHERE clauses - incorrect behavior!
+// ✅ CORRECT - Conditional building pattern
+query := users.User.Select(users.ID, users.Email, users.Name)
 
-// ✅ CORRECT - Create new query each time
+// Add conditions based on filters
+if nameFilter != "" {
+    query = query.Where(users.Name.Like("%" + nameFilter + "%"))
+}
+
+if statusFilter > 0 {
+    query = query.Where(users.Status.Eq(statusFilter))
+}
+
+if sortByName {
+    query = query.OrderBy(users.Name.Asc())
+}
+
+// Execute the final query with all accumulated conditions
+err := query.First(ctx, &id, &email, &name)
+```
+
+**This is the intended use!** The builder accumulates your conditions, which is powerful and flexible.
+
+### ❌ Unintentional Reuse (INCORRECT)
+
+Don't try to create a "base query" and reuse it for **multiple different queries**:
+
+```go
+// ❌ WRONG - Trying to reuse for multiple separate queries
+baseQuery := users.User.Select(users.ID, users.Email)
+
+// First query - adds ID condition
+baseQuery.Where(users.ID.Eq(1)).First(ctx, &id1, &email1)
+
+// Second query - ALSO has ID=1 from above PLUS Status=2!
+baseQuery.Where(users.Status.Eq(2)).First(ctx, &id2, &email2)
+// This executes: WHERE users.id = 1 AND users.status = 2 (WRONG!)
+
+// ✅ CORRECT - Each separate query gets its own builder
 users.User.Select(users.ID, users.Email).Where(users.ID.Eq(1)).First(ctx, &id1, &email1)
 users.User.Select(users.ID, users.Email).Where(users.Status.Eq(2)).First(ctx, &id2, &email2)
 ```