From 65e283c46dec1b9810ca7b3c6ff0fb48dbe7e395 Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Tue, 28 Apr 2026 22:08:33 -0700
Subject: [PATCH 1/5] docs(web/guides): align Part 2 with what the model
 generator actually emits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The tutorial described `wheels generate model Post title:string body:text`
as producing "a near-empty `component extends=\"Model\"`", but the
generator now ships `validatesPresenceOf("title,body")` baked in for
every property the user passed in. Onboarding finding F3 — minor
mismatch, but the next step asks the reader to wholesale replace the
file, so they'd notice the discrepancy and wonder which version is
canonical.

Update the description to match what the generator emits, and call
out that we drop the validations in this chapter only because Part 4
brings them back deliberately. No code change required.
---
 .../v4-0-0-snapshot/start-here/tutorial/02-first-model.mdx    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/02-first-model.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/02-first-model.mdx
index adae3896d..304f429c1 100644
--- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/02-first-model.mdx
+++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/02-first-model.mdx
@@ -67,9 +67,9 @@ At the end of Part 1 you had a running `blog` app with a `/hello` route. There's
    wheels generate model Post title:string body:text
    ```
 
-   That creates `app/models/Post.cfc` (a near-empty `component extends="Model"`) and a migration file under `app/migrator/migrations/` with a current timestamp.
+   That creates `app/models/Post.cfc` and a migration file under `app/migrator/migrations/` with a current timestamp. The generated model is short but not empty — it ships with `validatesPresenceOf("title,body")` already populated for the two columns you passed in.
 
-2. Replace the contents of `app/models/Post.cfc` with the version below — it adds the `status` enum we'll use to filter posts:
+2. Replace the contents of `app/models/Post.cfc` with the version below — we drop the auto-generated validations for now (Part 4 brings them back) and add the `status` enum we'll use to filter posts:
 
    ```cfm {test:compile}
    component extends="Model" {

From 3c79b4a0defdf21dc5673efd12c1369a43af40cc Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Tue, 28 Apr 2026 22:09:17 -0700
Subject: [PATCH 2/5] docs(web/guides): rewrite Part 3 scaffold + form sections
 to match reality
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two onboarding findings, both in the CRUD chapter:

F4-doc — The chapter described the scaffold generator as refusing to
overwrite an existing model and bailing before producing any other
files. It then pivoted to having the reader hand-write the
controller, views, and tests. The scaffold's actual current behavior
is much friendlier: existing model + migration are skipped with a
clear `skip` line, but the controller, views, and tests still get
generated. The hand-written code in the chapter is also not what the
scaffold emits (the generator uses `findByKey(params.key)` and
Bootstrap-flavored views; the chapter uses route model binding and
plain HTML). Update the Aside to describe the actual skip-and-
continue behavior, mention the routes.cfm append, and frame the
chapter's code as a deliberate alternative to the scaffold's default.

Also: `wheels destroy` requires `--force` to actually delete files;
without it, it prints a confirmation hint and exits. The chapter
gave the bare command with no warning.

F7 — The form partial wrapped each `textField`/`textArea`/`select`/
`dateField` helper in an outer `<label>...<br>` element. But every
form helper already emits its own `<label>` wrapper, so the rendered
HTML had nested `<label>` elements (browsers handle these
inconsistently — clicking the label may or may not focus the input).
Drop the outer wrappers and pass `label="Title"` to the helpers
directly. Add a one-line note in the helper-list bullets explaining
the convention.
---
 .../start-here/tutorial/03-crud-scaffold.mdx  | 26 +++++++------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/03-crud-scaffold.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/03-crud-scaffold.mdx
index 4557c721a..30b6968fb 100644
--- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/03-crud-scaffold.mdx
+++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/03-crud-scaffold.mdx
@@ -75,10 +75,10 @@ Route model binding kicks in on the actions that take a key. For `show`, `edit`,
 Drop the hand-written controller and views. The model, migration, seed file, and the `resources("posts")` route stay.
 
 ```bash title="your shell"
-wheels destroy Posts controller
+wheels destroy Posts controller --force
 ```
 
-The argument order is `<name> [type]` — `Posts controller`, not `controller Posts`. If you'd rather skip the CLI and remove the files yourself:
+The argument order is `<name> [type]` — `Posts controller`, not `controller Posts`. The `--force` flag skips the interactive confirmation; without it, `destroy` prints `Use --force to confirm deletion.` and exits without touching anything. If you'd rather skip the CLI and remove the files yourself:
 
 ```bash title="your shell"
 rm app/controllers/Posts.cfc
@@ -96,7 +96,9 @@ wheels generate scaffold Post title:string body:text status:enum
 ```
 
 <Aside type="caution">
-  The scaffold generator will refuse to overwrite an existing `app/models/Post.cfc` and bail before producing the controller and views. Since chapter 2 already wrote the model, you'll see `Scaffold failed: Model already exists`. When that happens, hand-write the files in the sections below — they're what the generator would have produced. (A future release will add a `--skip-existing` flag so the scaffold can reuse the existing model.)
+  The scaffold generator skips files that already exist rather than failing the whole run. Since chapter 2 already wrote `app/models/Post.cfc` and the migration, you'll see `skip model: Model already exists` and `skip migration: create_posts_table already exists` in the output — but the controller, views, and tests will still be generated. The scaffold also appends `.resources("posts")` to `config/routes.cfm`; we'll replace the resulting routes file in a few steps anyway.
+
+  The generator's emitted controller uses `findByKey(params.key)` everywhere and emits Bootstrap-flavored views — perfectly fine, but a different shape from this tutorial. Replace the scaffold's output with the code in the sections below to follow along; pass `--force` next time if you want the scaffold to overwrite. Or compare the two — generator vs. tutorial — to see two equally valid CRUD shapes.
 </Aside>
 
 ### The controller
@@ -165,18 +167,10 @@ The `new` and `edit` views both render the same form. Put the shared markup in a
    <cfoutput>
    #errorMessagesFor("post")#
    #startFormTag(action=IsNumeric(post.id ?: "") ? "update" : "create", key=post.id ?: "")#
-       <label>Title<br>
-           #textField(objectName="post", property="title")#
-       </label>
-       <label>Body<br>
-           #textArea(objectName="post", property="body")#
-       </label>
-       <label>Status<br>
-           #select(objectName="post", property="status", options="draft,published,archived")#
-       </label>
-       <label>Published at<br>
-           #dateField(objectName="post", property="publishedAt")#
-       </label>
+       #textField(objectName="post", property="title", label="Title")#
+       #textArea(objectName="post", property="body", label="Body")#
+       #select(objectName="post", property="status", options="draft,published,archived", label="Status")#
+       #dateField(objectName="post", property="publishedAt", label="Published at")#
        <button type="submit">Save</button>
    #endFormTag()#
    </cfoutput>
@@ -189,7 +183,7 @@ Notes:
 - Partial filenames start with `_`. You reference them as `"form"` (no underscore, no extension) when including.
 - `errorMessagesFor("post")` renders a `<div class="errors">` with any validation errors on the `post` object. When there are none, it renders nothing.
 - `startFormTag` picks the right HTTP method and action URL based on whether `post.id` exists. A new `Post` has no id, so the form posts to `create`; an existing one PATCHes to `update`.
-- `textField`, `textArea`, `select`, `dateField` are object-bound helpers — `objectName="post"` plus `property="title"` becomes `name="post[title]"` with the current value pre-filled.
+- `textField`, `textArea`, `select`, `dateField` are object-bound helpers — `objectName="post"` plus `property="title"` becomes `name="post[title]"` with the current value pre-filled. Each helper emits its own `<label>` wrapper around the input; pass `label="Title"` to set the visible text. Don't wrap them in another `<label>` — that produces nested `<label>` elements, which browsers handle inconsistently.
 
 ### The four views
 

From 7659b53b9d5c7fd0110e6ac8cac78f64cf0d2d56 Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Tue, 28 Apr 2026 22:09:38 -0700
Subject: [PATCH 3/5] docs(web/guides): fix non-existent finder syntax + add
 CSRF/curl gotcha note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three onboarding findings in Part 6 (authentication):

F9 — Both the hand-rolled (6a) and built-in (6b) Sessions controllers
used `findOne(where="email = :email", values={email: ...})`. That
named-bind `values=` syntax does not exist on Wheels' `findOne()` —
the available args are `where`, `order`, `select`, `include`, etc.
Wheels parses `:email` as a column reference, can't find it, and
throws `Wheels.QueryParamValue: The value for cfqueryparam cannot
be determined`. So the chapter's copy-paste-it-and-it-works promise
fails on the very first `/login` POST.

Replace with the dynamic finder `findOneByEmail(emailVal)`. Wheels
auto-generates `findOneBy<Property>` for every column and
parameter-binds the value, so it's both idiomatic and injection-safe.
Add an Aside explaining the choice and pointing readers at the
chainable query builder for non-equality predicates.

F8 + F10 — Add a "Scripting smoke tests with curl?" caution sidebar
in the manual-test section. Two subtle things bite anyone who scripts
the auth flow with curl:

  - CSRF token rotation: Wheels invalidates the token after each
    accepted POST. Reusing a scraped token fails with
    `Wheels.InvalidAuthenticityToken`. The signup form has a hidden
    `authenticityToken` input; the login form (raw `<input>` rather
    than form helpers) doesn't, so scrape from the layout's
    `<meta name="csrf-token">` instead.

  - `--data-urlencode` quirks: `curl --data-urlencode "user[email][test@example.com]"`
    (no `=` separator) gets misread by Lucee's form parser as nested
    bracket-key paths, producing a struct value instead of a string.
    The fix is to always include the `=` and let curl encode the
    value side: `--data-urlencode "user[email]=test@example.com"`.
    Browsers always %-encode `@`, so this is curl-only.

Neither bites a real browser submitting through the rendered form,
which is why the rest of the tutorial works fine.
---
 .../start-here/tutorial/06-authentication.mdx  | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/06-authentication.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/06-authentication.mdx
index 5428c3e95..d1513cea5 100644
--- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/06-authentication.mdx
+++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/06-authentication.mdx
@@ -202,7 +202,8 @@ Four pieces to notice:
        }
 
        function create() {
-           user = model("User").findOne(where="email = :email", values={email: LCase(Trim(params.email ?: ""))});
+           emailVal = LCase(Trim(params.email ?: ""));
+           user = model("User").findOneByEmail(emailVal);
            if (IsObject(user) && user.authenticate(params.password ?: "")) {
                session.userId = user.id;
                redirectTo(route="posts", success="Welcome back.");
@@ -224,9 +225,13 @@ Four pieces to notice:
 Three actions, three responsibilities:
 
 - `new` renders the login form. No setup needed; the view uses no dynamic data.
-- `create` is the login POST. It normalizes the submitted email the same way the model does on save, looks up the user via a parameterized finder (`:email` placeholder plus `values` struct — this is injection-safe; never interpolate user input into a `where` string), and calls `user.authenticate(password)`. Success sets `session.userId` and redirects; failure flashes an error and sends the browser back to the login form.
+- `create` is the login POST. It normalizes the submitted email the same way the model does on save, looks up the user via the dynamic finder `findOneByEmail` — Wheels generates `findOneBy<Property>` for every column, and the value is bound as a parameter so this is injection-safe. Then it calls `user.authenticate(password)`. Success sets `session.userId` and redirects; failure flashes an error and sends the browser back to the login form.
 - `delete` is the logout action. It clears `session.userId` and redirects.
 
+<Aside type="tip" title="Why a dynamic finder, not a `where=` string">
+  You'll see two patterns in older code: dynamic finders like `findOneByEmail(value)` and explicit `where=` finders. The dynamic finders parameterize the value automatically — Wheels turns `findOneByEmail(emailVal)` into a prepared statement with a bound parameter. Writing `findOne(where="email = '#emailVal#'")` would interpolate the user input straight into SQL, which is a SQL injection vulnerability. Stick to dynamic finders for single-column lookups; reach for `where=` only when you need an operator other than equality, and always use `cfqueryparam`-style binding via the [chainable query builder](/v4-0-0-snapshot/basics/models-and-the-orm/#chainable-query-builder).
+</Aside>
+
 ### Protect the Posts controller
 
 <Steps>
@@ -478,6 +483,12 @@ Then walk through the flow in the browser:
 
 That's the hand-rolled version. Thirty-ish lines of logic total, no hidden machinery. Now let's see what the framework gives you for free.
 
+<Aside type="caution" title="Scripting smoke tests with curl? Read this first.">
+**CSRF token rotation**: Wheels rotates the CSRF token after each accepted POST. A scraped token is single-use — re-POSTing with the same token fails with `Wheels.InvalidAuthenticityToken`. To script a flow, fetch a fresh form before every write. The signup form has a hidden `authenticityToken` input you can scrape from the response body; the login form (which uses raw `<input>` tags rather than form helpers) doesn't, so scrape from the layout's `<meta name="csrf-token">` tag instead.
+
+**curl `--data-urlencode` and `@`**: `curl --data-urlencode "user[email]=test@example.com"` correctly URL-encodes the `@` to `%40`. But `curl --data-urlencode "user[email][test@example.com]"` (no `=` separator) gets misread by Lucee's form parser as a nested-bracket key path — `params.user.email` arrives as `{"test@example.com": ""}` instead of the string. The cause is curl + Lucee form encoding, not Wheels — but it surfaces as a confusing `Can't cast Complex Object Type Struct to String` error. Browsers always %-encode `@`, so this is curl-only. Always include the `=` and let `--data-urlencode` encode the value side: `--data-urlencode "user[email]=test@example.com"`.
+</Aside>
+
 ---
 
 ## Part 6b: The Built-in Way
@@ -530,7 +541,8 @@ On a cold reload this registers the strategy exactly once. The `hasStrategy` che
        }
 
        function create() {
-           user = model("User").findOne(where="email = :email", values={email: LCase(Trim(params.email ?: ""))});
+           emailVal = LCase(Trim(params.email ?: ""));
+           user = model("User").findOneByEmail(emailVal);
            if (IsObject(user) && user.authenticate(params.password ?: "")) {
                var sessionStrategy = application.wo.service("sessionStrategy");
                sessionStrategy.login(principal={id: user.id, email: user.email});

From 9b021028e82ea47dc5a338d82d02efe69ebb3d08 Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Tue, 28 Apr 2026 22:09:48 -0700
Subject: [PATCH 4/5] docs(web/guides): rename wheels browser install -> setup
 throughout Part 7
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Onboarding finding F11. The chapter told readers to run
`wheels browser install` to download Playwright JARs + Chromium, but
that command doesn't reach the wheels module — LuCLI's built-in
extension installer intercepts `install` first and prints
`No git or extension dependencies to install`, which looks like
success but does nothing. Subsequent `wheels test --filter=browser`
runs then hang for 30 seconds and time out, leaving the reader
confused.

The correct verb is `wheels browser setup`. Update the three
references in Part 7 (initial install, checkpoint, troubleshooting)
and add a one-line note explaining the LuCLI-intercept gotcha so
readers who hit the install version on Stack Overflow or Google
land back in the right place.
---
 .../start-here/tutorial/07-testing-deploying.mdx       | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/07-testing-deploying.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/07-testing-deploying.mdx
index 61044b185..f870b5112 100644
--- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/07-testing-deploying.mdx
+++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/tutorial/07-testing-deploying.mdx
@@ -162,11 +162,15 @@ Browser specs drive a real Chromium through the rendered HTML. Behind the scenes
 Playwright ships as a set of JARs plus a Chromium binary, ~370MB in total. Install it once:
 
 ```bash title="your shell"
-wheels browser install
+wheels browser setup
 ```
 
 The installer downloads the JARs into `lib/`, Chromium into `~/Library/Caches` (macOS) or `~/.cache` (Linux), and writes a manifest so CI knows what's cached.
 
+<Aside type="note">
+  The verb is `setup`, not `install`. `wheels browser install` reaches LuCLI's generic extension installer first and prints `No git or extension dependencies to install` — looks like success but does nothing. Always use `setup`.
+</Aside>
+
 <Steps>
 
 1. Create `tests/specs/browser/SignupFlowSpec.cfc`:
@@ -278,14 +282,14 @@ wheels --version
 Three things to verify before moving on:
 
 1. `wheels test` passes both the model spec and the controller spec.
-2. `wheels browser install` completes without error, and `wheels test --filter=browser` runs the browser spec green — Chromium launches, the signup-to-post-to-comment flow runs end-to-end.
+2. `wheels browser setup` completes without error, and `wheels test --filter=browser` runs the browser spec green — Chromium launches, the signup-to-post-to-comment flow runs end-to-end.
 3. Click through the running app one more time: sign up, create a post, leave a comment, log out, log back in, try to edit someone else's post and get redirected. Every part of the tutorial still works end-to-end.
 
 ## Troubleshooting
 
 **"Model spec fails with `cannot find Post.cfc`."** The test runner boots a fresh schema from `tests/populate.cfm`, which you haven't set up yet. See [Fixtures & Test Data](/v4-0-0-snapshot/testing/fixtures-and-test-data/) for the standard `populate.cfm` that mirrors your development schema into the test database.
 
-**"Browser spec hangs for thirty seconds, then times out."** Playwright isn't installed. Run `wheels browser install` — it downloads ~370MB and prints a progress bar. Once it completes, re-run the spec. If it still hangs, check that `this.browserTestSkipped` isn't incorrectly set; the guard clause should short-circuit when the JARs are missing, not when they're present.
+**"Browser spec hangs for thirty seconds, then times out."** Playwright isn't installed. Run `wheels browser setup` — it downloads ~370MB and prints a progress bar. Once it completes, re-run the spec. If it still hangs, check that `this.browserTestSkipped` isn't incorrectly set; the guard clause should short-circuit when the JARs are missing, not when they're present.
 
 **"`expect(...).toBeTrue is not a function`."** The spec CFC extends the wrong base. Use `component extends="wheels.WheelsTest"` — with a capital T in `WheelsTest`. The legacy `wheels.Test` is the RocketUnit base and doesn't have the BDD matchers.
 

From 1a7b6eb74e311a477ee7e90348a9c1996374660c Mon Sep 17 00:00:00 2001
From: Peter Amiri <peter@alurium.com>
Date: Tue, 28 Apr 2026 22:09:57 -0700
Subject: [PATCH 5/5] docs(web/guides): soften "Lucee Version" claim on the
 install page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The verify step on the install page (in all three platform tabs)
promised that `wheels --version` shows "a Wheels Version line
followed by ASCII art and a Lucee Version line". A first-time user
who has just run `brew install wheels` (and hasn't yet run
`wheels start`, which is what triggers Lucee Express to download)
sees only the Wheels line and worries the install is broken.
Onboarding finding adjacent to F1.

Reword so the Lucee line is described as conditional ("may also
appear once Lucee Express has been downloaded, typically on first
`wheels start`") rather than required. Keep the "any non-empty
version output means the CLI is wired up correctly" reassurance
that was already there.

Three near-identical changes — one per platform tab.
---
 .../content/docs/v4-0-0-snapshot/start-here/installing.mdx  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/installing.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/installing.mdx
index 5702e2b1c..3b16daa1b 100644
--- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/installing.mdx
+++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/installing.mdx
@@ -48,7 +48,7 @@ Install the `wheels` CLI. Five minutes.
    wheels --version
    ```
 
-   You should see a `Wheels Version: <version>` line followed by ASCII art and a `Lucee Version: <version>` line. Any non-empty version output means the CLI is wired up correctly.
+   You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
 </Steps>
 
@@ -84,7 +84,7 @@ The `wheels` package on the public Chocolatey feed is still the v1.x legacy (Com
    wheels --version
    ```
 
-   You should see a `Wheels Version: <version>` line followed by ASCII art and a `Lucee Version: <version>` line. Any non-empty version output means the CLI is wired up correctly.
+   You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
 </Steps>
 
@@ -116,7 +116,7 @@ Pick LuCLI and Wheels Module versions that are known to be paired — see [CLI I
    wheels --version
    ```
 
-   You should see a `Wheels Version: <version>` line followed by ASCII art and a `Lucee Version: <version>` line. Any non-empty version output means the CLI is wired up correctly.
+   You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
 </Steps>