docs: document includeCalculated finder argument for select=false SQL properties

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: github-actions[bot]

.ai/wheels/snippets/model-snippets.md

@@ -151,10 +151,18 @@ function recent(days=30) {
 ## Calculated Properties
 ```cfm
 function config() {
-    // SQL-based calculated property
+    // SQL-based calculated property — included in every SELECT by default
     property(name="orderTotal", sql="(SELECT SUM(amount) FROM order_items WHERE order_id = orders.id)");
+
+    // Keep off the hot path with select=false; opt in per-call with includeCalculated
+    property(name="fullName", sql="firstName || ' ' || lastName", select=false);
 }
 
+// Opt a select=false property back into one finder (additive — base columns still selected)
+user = model("User").findOne(includeCalculated="fullName");
+order = model("Order").findAll(includeCalculated="orderTotal,shippingCost");
+```
+
 // Method-based calculated property
 function displayName() {
     if (Len(this.nickName)) {

CLAUDE.md

@@ -280,6 +280,9 @@ component extends="Model" {
         // Callbacks
         beforeSave("sanitizeInput");
 
+        // Calculated SQL properties — select=false keeps them off the default SELECT (hot path)
+        property(name="fullName", sql="firstName || ' ' || lastName", select=false);
+
         // Query scopes — reusable, composable query fragments
         scope(name="active", where="status = 'active'");
         scope(name="recent", order="createdAt DESC");
@@ -299,6 +302,7 @@ component extends="Model" {
 Finders: `model("User").findAll()`, `findOne(where="...")`, `findByKey(params.key)`.
 Create: `model("User").new(params.user).save()`, or `model("User").create(params.user)`.
 Include associations: `findAll(include="role,orders")`. Pagination: `findAll(page=params.page, perPage=25)`.
+Opt a `select=false` calculated property into one call (additive): `findAll(includeCalculated="fullName")`. Unknown names throw `Wheels.CalculatedPropertyNotFound` in dev/testing.
 
 ### Scopes / Enums / Builder / Batch
 

web/sites/guides/src/content/docs/v4-0-0/basics/models-and-the-orm.mdx

@@ -65,6 +65,26 @@ component extends="Model" {
 
 Composite keys are also supported — pass a comma-separated list to `setPrimaryKey("tenantId,entryId")`. Most apps never need them.
 
+## Calculated SQL properties
+
+A `property()` declaration can carry a `sql` expression that Wheels evaluates as a computed `SELECT` column. Pass `select=false` to keep the property off the default `SELECT` (reducing hot-path cost), then opt it back into a specific finder with `includeCalculated`:
+
+```cfm
+component extends="Model" {
+    function config() {
+        property(name="fullName", sql="firstName || ' ' || lastName", select=false);
+    }
+}
+
+// Additive — all base columns are still selected; fullName is merged on top
+user = model("User").findOne(includeCalculated="fullName");
+
+// Comma-list for multiple properties; composes with other finder arguments
+users = model("User").active().findAll(include="role", includeCalculated="fullName", page=1, perPage=25);
+```
+
+Unknown names passed to `includeCalculated` throw `Wheels.CalculatedPropertyNotFound` in `development` and `testing`, and are silently ignored in `production`.
+
 ## Finders
 
 The finders read from the database. Every finder below is a method on the class, called via `model("Name")`. The calls return different shapes depending on whether you're loading many, one, or just asking a question.