From c00bbbd4fc21f6c34a8dcf3f96fe5a85e918c7d2 Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Fri, 7 Aug 2026 21:48:43 +0200
Subject: [PATCH] docs: ease the landing examples into the API

The SQL template belongs later in the journey than the landing page and the
README opener: it is the escape hatch, not the first impression. The intro
sequence now ends at the query builder, and the Kotlin example uses the
chained builder rather than the block DSL.
---
 README.md     |  8 +-------
 docs/index.md | 24 +++++-------------------
 2 files changed, 6 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index ed3c10c5a..b51818540 100644
--- a/README.md
+++ b/README.md
@@ -25,15 +25,9 @@ val users = orm.findAll(User_.city.name eq "Sunnyvale")
 interface UserRepository : EntityRepository<User, Int> {
     fun findByCity(name: String) = findAll(User_.city.name eq name)
 }
-
-// Drop to SQL whenever you want it. Interpolations become bind parameters.
-val users = orm.query { """
-    SELECT ${User::class}
-    FROM ${User::class}
-    WHERE ${User_.city.name} = $cityName""" }.resultList<User>()
 ```
 
-The `city` graph loads in a single query, `User_` is generated at compile time so a typo is a compile error, and every interpolation is a bind parameter. What you write is what runs.
+The `city` graph loads in a single query, and `User_` is generated at compile time so a typo is a compile error. What you write is what runs.
 
 ## Why Storm
 
diff --git a/docs/index.md b/docs/index.md
index 664b0f108..157f8fd54 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -66,18 +66,11 @@ interface UserRepository : EntityRepository<User, Int> {
     fun findByCityName(name: String) = findAll(User_.city.name eq name)
 }
 
-// Block DSL — build queries with where, orderBy, joins, pagination
-val users = userRepository.select {
-    where(User_.city.name eq "Sunnyvale")
-    orderBy(User_.name)
-}.resultList
-
-// SQL Template for full control; parameterized by default, SQL injection safe
-val users = orm.query { """
-        SELECT ${User::class}
-        FROM ${User::class}
-        WHERE ${User_.city.name} = $cityName"""
-    }.resultList<User>()
+// Query builder — where, orderBy, joins, pagination
+val users = userRepository.select()
+    .where(User_.city.name eq "Sunnyvale")
+    .orderBy(User_.name)
+    .resultList
 ```
 
 Full coroutine support with `Flow` for streaming and programmatic transactions:
@@ -118,13 +111,6 @@ List<User> users = orm.entity(User.class)
     .where(User_.city.name, EQUALS, "Sunnyvale")
     .orderBy(User_.name)
     .getResultList();
-
-// SQL Template for full control; parameterized by default, SQL injection safe
-List<User> users = orm.query(RAW."""
-        SELECT \{User.class}
-        FROM \{User.class}
-        WHERE \{User_.city.name} = \{cityName}
-        """).getResultList(User.class);
 ```
 
 </TabItem>