docs(web/guides): fix basics + digging-deeper guide audit findings (group 5, un-gated) (#3130)

* docs(web/guides): fix basics + digging-deeper guide audit findings (un-gated group 5)

Behavioral-audit corrections, all source- or probe-verified:

basics/
- models-and-the-orm: correct the callbacks contract — afterFind on
  query-returning finders receives row columns as arguments and
  decorates by returning a struct; 'must be private' softened to the
  actual convention (public works but leaks onto the model API)
- associations: caution that hasMany shortcut= is currently broken
  (Wheels.AssociationNotFound on every advertised surface, #3109)
- validation-and-errors: drop the nonexistent validatesAssociated
  helper; point at nested-properties validation instead
- forms-and-form-helpers: checkBox hidden companion renders AFTER the
  box under name '<name>($checkbox)' and the dispatcher applies
  uncheckedValue only when the real field is absent; labelPlacement
  default is 'around', not 'before'
- index: replace the Phase 2 placeholder with a real section landing
  page linking all 12 content pages

digging-deeper/
- background-jobs: rewrite worker/monitor/retry/purge sections around
  the programmatic surface that exists (processQueue, queueStats,
  retryFailed, purgeCompleted) — there is no 'wheels jobs' CLI (#3090)
- route-model-binding: silent skip on missing model applies only to
  conventional binding; explicit binding="Name" rethrows (#3118)
- dependency-injection-usage: singleton cache is keyed by alias (not
  component path) and names are case-insensitive (#3117)
- authentication-patterns: parenthesize the elvis in the format check
  (unparenthesized form can never reach the JSON branch, #3116); fix
  the hasStrategy rationale (registerStrategy replaces same-name
  entries; duplicates cannot stack)

verify:docs exit 0 on every touched page; guides site builds clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

* docs(web/guides): correct afterFind argument contract and job backoff retry count

Review findings on #3130:

- models-and-the-orm.mdx: object-mode afterFind callbacks DO receive the
  record's properties as named arguments ($afterFindCallback invokes with
  invokeArgs = properties()) and a returned struct is applied back via
  setProperties(). Both finder modes now documented as receiving named
  arguments and honoring a returned struct; the dual-branch
  StructKeyExists example replaced with the portable return-a-struct
  pattern.

- background-jobs.mdx: maxRetries counts total attempts
  (currentAttempts < maxRetries in Job.cfc), so maxRetries=5 yields the
  first run plus four retries at 4s/8s/16s/32s — the 64s retry never
  fires. Reframed around attempts vs retries and expanded the
  maxRetries=3 default parenthetical (retries at 4s and 8s).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: bpamiri

web/sites/guides/src/content/docs/v4-0-0/basics/associations.mdx

@@ -229,6 +229,10 @@ Include multiple associations by comma-separating: `include="comments,author"`.
 
 ## Many-to-many (through a join model)
 
+<Aside type="caution">
+  **`shortcut` is currently broken in 4.0.x.** Declaring `hasMany(name="...", shortcut="...")` poisons the association's expansion: the shortcut method, the plain join-rows method, *and* `findAll(include=...)` for that association all throw `Wheels.AssociationNotFound` at runtime. Track the fix in [#3109](https://github.com/wheels-dev/wheels/issues/3109). Until it lands, declare the plain `hasMany` join-model associations (no `shortcut`) and traverse the join model explicitly — `user.userRoles(include="role")` — or query the far side with an explicit join.
+</Aside>
+
 Wheels handles many-to-many through a real join model plus the `shortcut` argument on `hasMany`. If a User has many Roles via a UserRole join table, model the relationship as three classes:
 
 ```cfm {test:compile}

web/sites/guides/src/content/docs/v4-0-0/basics/forms-and-form-helpers.mdx

@@ -102,7 +102,7 @@ Every helper also accepts the standard Wheels form options — `label`, `labelPl
 See `vendor/wheels/view/formsobject.cfc` for the full argument surface.
 
 <Aside type="note">
-  **`checkBox` emits two inputs.** A single checkbox only submits its `name` when it's checked, which means unchecking a box sends no value at all and the controller never learns the user cleared it. `checkBox` works around this by also rendering a hidden `<input type="hidden" name="..." value="0">` just before the real checkbox. On submit, the last value wins: checked → `1`, unchecked → `0`. The underlying model always sees one of the two.
+  **`checkBox` emits two inputs.** A single checkbox only submits its `name` when it's checked, which means unchecking a box sends no value at all and the controller never learns the user cleared it. `checkBox` works around this by also rendering a hidden companion *after* the real checkbox, under a marker name — `<input type="hidden" name="post[published]($checkbox)" value="0">`. On submit, Wheels' dispatcher detects the `($checkbox)` key and applies its `uncheckedValue` only when the real field is absent from the form post: checked → `1`, unchecked → `0`. The underlying model always sees one of the two.
 </Aside>
 
 <Aside type="note">
@@ -162,7 +162,7 @@ The summary block only renders when the object has errors — on a new-form rend
 
 Wheels does not ship a standalone `label()` helper. Labels are a first-class argument on every object-bound form helper via `label=` and `labelPlacement=`:
 
-- `textField(objectName="post", property="title", label="Post title")` — wraps the input in a `<label for="post-title">Post title</label>` with `labelPlacement` controlling whether the text comes `before` (default), `after`, or `around` the input.
+- `textField(objectName="post", property="title", label="Post title")` — wraps the input in a `<label for="post-title">Post title</label>` with `labelPlacement` controlling whether the text comes `around` (default), `before`, or `after` the input.
 - `label=false` suppresses the auto-label — use this when you want to write the `<label>` tag by hand (for icons, extra classes, or explicit `for` attributes).
 
 The third and most common pattern is in the canonical example above: skip the `label` argument entirely and wrap the helper call inside a raw `<label>` element in your markup. The browser associates the label with the input via containment, no `for="..."` attribute needed.

web/sites/guides/src/content/docs/v4-0-0/basics/index.mdx

@@ -6,4 +6,85 @@ sidebar:
   order: 3
 ---
 
-Placeholder — content lands in Phase 2.
+import { CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+The Basics covers the everyday surface of a Wheels app — the routing, controller, view, and model work you'll do on every feature. Each page is a task-oriented how-to. They're ordered to follow a request through the framework, but every page stands alone — jump to whichever matches what you're building right now.
+
+**You'll find:**
+
+- Routing, controllers, and the seven REST actions
+- Views, layouts, partials, and every form helper
+- Validations and rendering errors back to the user
+- Models, finders, associations, and the chainable query builder
+- Migrations, seeding, and multi-datasource setups
+
+## All Basics guides
+
+<CardGrid>
+  <LinkCard
+    title="Routing"
+    href="/v4-0-0/basics/routing/"
+    description="Define routes — resources, nested resources, namespaced routes, custom patterns, and route helpers."
+  />
+  <LinkCard
+    title="Controllers and Actions"
+    href="/v4-0-0/basics/controllers-and-actions/"
+    description="Writing a controller, the seven REST actions, filters, params, rendering, redirect, and flash."
+  />
+  <LinkCard
+    title="Views, Layouts, Partials"
+    href="/v4-0-0/basics/views-layouts-partials/"
+    description="Rendering templates, the default layout, extracting partials, and how controller data reaches the view."
+  />
+  <LinkCard
+    title="Forms and Form Helpers"
+    href="/v4-0-0/basics/forms-and-form-helpers/"
+    description="Every form helper Wheels ships — object-bound and tag-style — plus data-auto-id for stable test selectors."
+  />
+  <LinkCard
+    title="Validation and Error Display"
+    href="/v4-0-0/basics/validation-and-errors/"
+    description="Built-in validations, when they fire, the errors API, and rendering errors inline."
+  />
+  <LinkCard
+    title="Models and the ORM"
+    href="/v4-0-0/basics/models-and-the-orm/"
+    description="Defining a model, finders, persistence, and lifecycle callbacks — the everyday ORM surface."
+  />
+  <LinkCard
+    title="Associations"
+    href="/v4-0-0/basics/associations/"
+    description="Modeling relationships — hasMany, belongsTo, hasOne, nested creation, eager loading, cascade deletes."
+  />
+  <LinkCard
+    title="Migrations"
+    href="/v4-0-0/basics/migrations/"
+    description="Writing and running schema migrations — column types, indexes, foreign keys, and rollbacks."
+  />
+  <LinkCard
+    title="Seeding"
+    href="/v4-0-0/basics/seeding/"
+    description="Populate development and production databases with default records — idempotently."
+  />
+  <LinkCard
+    title="Query Builder and Scopes"
+    href="/v4-0-0/basics/query-builder-and-scopes/"
+    description="Chainable query builder, reusable scopes, enum declarations, and batch processing."
+  />
+  <LinkCard
+    title="Database and Multiple Datasources"
+    href="/v4-0-0/basics/database-and-multiple-datasources/"
+    description="Configuring the default datasource, per-model overrides, transactions, and raw queries."
+  />
+  <LinkCard
+    title="Shared Development Databases"
+    href="/v4-0-0/basics/shared-development-databases/"
+    description="Reconciling the migration tracking table when several developers share one dev database."
+  />
+</CardGrid>
+
+## See also
+
+- [Start Here](/v4-0-0/start-here/) — install Wheels and build your first app with the tutorial
+- [Core Concepts](/v4-0-0/core-concepts/) — the explanations behind what these guides show you how to do
+- [Digging Deeper](/v4-0-0/digging-deeper/) — authentication, jobs, caching, uploads, and the rest of the advanced surface

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

@@ -162,7 +162,7 @@ For a key-only delete without loading the record, use `model("Post").deleteByKey
 
 ## Lifecycle callbacks
 
-Callbacks register a `private` method to run at a specific point in the record's lifecycle. The method takes no arguments (the record is `this`), returns nothing, and can mutate any property on `this` before the write happens. Return `false` from a `before*` callback to cancel the operation.
+Callbacks register a method to run at a specific point in the record's lifecycle. For the write-cycle callbacks the method takes no arguments (the record is `this`), returns nothing, and can mutate any property on `this` before the write happens. Return `false` from a `before*` callback to cancel the operation. (`afterFind` is the exception — see below.)
 
 | Callback | When it fires |
 |----------|---------------|
@@ -177,7 +177,7 @@ Callbacks register a `private` method to run at a specific point in the record's
 | `beforeUpdate` / `afterUpdate` | Around UPDATE only |
 | `beforeDelete` / `afterDelete` | Around DELETE |
 
-Register callbacks in `config()` — `beforeSave("methodName")` or `beforeSave(methods="one,two")` when you want several. The methods themselves must be `private` and live on the same component.
+Register callbacks in `config()` — `beforeSave("methodName")` or `beforeSave(methods="one,two")` when you want several. The methods live on the same component and should be `private` — invocation is internal, so `public` also works, but a public callback method leaks onto the model's callable API.
 
 ```cfm {test:compile}
 component extends="Model" {
@@ -200,7 +200,24 @@ component extends="Model" {
 
 The ordering is strict: `beforeValidation` → validation runs → `afterValidation` → `beforeSave` → (`beforeCreate` or `beforeUpdate`) → SQL write → (`afterCreate` or `afterUpdate`) → `afterSave`. If any `before*` callback returns `false`, the chain stops and the write is skipped.
 
-`afterFind` is the one callback that fires without a write: it runs once per row returned by a finder, which makes it the right place for decorating loaded records with derived values.
+`afterFind` is the one callback that fires without a write: it runs once per record returned by a finder, which makes it the right place for decorating loaded records with derived values. Its contract differs by what the finder returns:
+
+- **Object-returning finders** (`findOne`, `findByKey`, `findAll(returnAs="objects")`) — the callback receives the record's properties as named arguments. You can mutate `this` directly, or return a struct — the returned keys are applied back onto the object via `setProperties()`.
+- **Query-returning finders** (`findAll` by default) — there is no object per row. The callback receives the row's columns as named arguments and decorates by *returning a struct*; any keys you return are merged back into the row (new keys become new query columns). Mutating `this` does nothing here.
+
+Both modes receive named arguments and both honor a returned struct, so the portable pattern — one callback that decorates objects and query rows alike — is to compute from `arguments` and return a struct:
+
+```cfm {test:compile}
+component extends="Model" {
+    function config() {
+        afterFind("setFullName");
+    }
+
+    private function setFullName() {
+        return {fullName: arguments.firstName & " " & arguments.lastName};
+    }
+}
+```
 
 ## Custom methods
 

web/sites/guides/src/content/docs/v4-0-0/basics/validation-and-errors.mdx

@@ -171,7 +171,7 @@ component extends="Model" {
 - `unless` — inverse of `condition`; the rule runs only when the expression returns `false`.
 
 <Aside type="tip">
-  Validations on associations — like requiring child records to be valid before the parent saves — are covered in the associations guide (coming up in this series). `validatesAssociated` is the relevant helper.
+  Validations on associations — like requiring child records to be valid before the parent saves — happen through nested properties: when a parent saves children via `nestedProperties()`, each child runs its own validations and an invalid child blocks the save. See the [associations guide](/v4-0-0/basics/associations/) for the setup. (There is no `validatesAssociated` helper in Wheels.)
 </Aside>
 
 ## Related guides

web/sites/guides/src/content/docs/v4-0-0/digging-deeper/authentication-patterns.mdx

@@ -61,7 +61,7 @@ local.di.map("sessionStrategy").to("wheels.auth.SessionStrategy").asSingleton();
 
 Both are singletons — one instance per app lifetime. The authenticator holds its strategy registry in instance state, so a singleton is the correct scope.
 
-Wire the session strategy into the authenticator on app init. A cold reload registers it once; the `hasStrategy` check keeps a second reload from stacking duplicates:
+Wire the session strategy into the authenticator on app init. The `hasStrategy` check just avoids needlessly re-registering on a warm reload — duplicates can't stack either way, because `registerStrategy()` replaces any existing entry with the same name:
 
 ```cfm {test:compile} title="config/app.cfm or equivalent init hook"
 if (StructKeyExists(application, "wheelsdi") && application.wheelsdi.containsInstance("authenticator")) {
@@ -340,7 +340,7 @@ component extends="wheels.Controller" {
     private function authenticate() {
         var result = service("authenticator").authenticate(request);
         if (!result.success) {
-            if (request.format ?: "html" == "json") {
+            if ((request.format ?: "html") == "json") {
                 renderWith(data={error: result.error}, status=result.statusCode);
             } else {
                 flashInsert(error="Please log in first");