Sync docs from wheels@b9b70ff

Author: github-actions[bot]

docs/3.1.0/guides/database-interaction-through-models/using-multiple-data-sources.md

@@ -64,3 +64,20 @@ Because the `photo` model is the main model being used in the following example,
 myPhotos = model("photo").findAll(include="photoGalleries");
 ```
 {% endcode %}
+
+### Automatic Datasource Switching with Multi-Tenancy
+
+If you're building a multi-tenant application where each tenant has its own database, Wheels can automatically switch the datasource on every request — no manual `dataSource()` calls needed.
+
+When the **TenantResolver** middleware is active, all model queries are automatically routed to the current tenant's datasource. Models that should always use the central (default) datasource — like a `Tenant` registry table — can opt out by calling `sharedModel()` in their `config()`:
+
+```javascript
+// app/models/Tenant.cfc — always uses the default datasource
+component extends="Model" {
+    function config() {
+        sharedModel();
+    }
+}
+```
+
+For the full setup guide, see [Multi-Tenancy](../working-with-wheels/multi-tenancy.md).

docs/3.1.0/guides/handling-requests-with-controllers/middleware.md

@@ -153,6 +153,32 @@ set(middleware = [
 
 For simple CORS needs, you may prefer the existing [CORS Requests](cors-requests.md) guide which covers header-only approaches.
 
+### TenantResolver
+
+Resolves the current tenant from the incoming request and sets `request.wheels.tenant` for automatic per-request datasource switching. Supports three resolution strategies.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `resolver` | `""` | Closure that receives the request struct and returns a tenant struct (`{id, dataSource, config}`). Return `{}` for unrecognized tenants. |
+| `strategy` | `"custom"` | Resolution strategy: `"custom"`, `"header"`, or `"subdomain"` |
+| `headerName` | `"X-Tenant-ID"` | HTTP header to read when strategy is `"header"` |
+
+```javascript
+set(middleware = [
+    new wheels.middleware.TenantResolver(
+        resolver = function(req) {
+            var t = model("Tenant").findOne(where="domain='#cgi.server_name#'");
+            if (IsObject(t)) return {id: t.id, dataSource: t.dsName};
+            return {};
+        }
+    )
+]);
+```
+
+The middleware locks the tenant for the duration of the request and cleans up automatically. All model queries are transparently routed to the tenant's datasource (except models marked with `sharedModel()`).
+
+For the full multi-tenancy guide — including shared models, tenant migrations, and background jobs — see [Multi-Tenancy](../working-with-wheels/multi-tenancy.md).
+
 ## Writing Custom Middleware
 
 Create a CFC that implements `wheels.middleware.MiddlewareInterface`:

docs/3.1.0/guides/working-with-wheels/background-jobs.md

@@ -346,6 +346,22 @@ The formula is `baseDelay * 2^attempt`, capped at `maxDelay`:
 | 5th retry | 64s | 320s |
 | 6th retry | 128s | 600s (capped) |
 
+## Multi-Tenant Jobs
+
+If you're using [multi-tenancy](multi-tenancy.md), background jobs automatically capture the current tenant context when enqueued and restore it before `perform()` runs. No extra code is needed.
+
+```javascript
+// Enqueued during a tenant request — context is captured automatically
+job = new app.jobs.GenerateInvoiceJob();
+job.enqueue(data={userId: user.id});
+```
+
+When the job processes (possibly later, on a different server, or outside a web request), Wheels restores the original tenant context so all model queries inside `perform()` run against the correct tenant database.
+
+{% hint style="info" %}
+The tenant context is stored internally as `$wheelsTenantContext` in the job's data. It's automatically removed before your `perform()` method receives the data struct — you don't need to handle it yourself.
+{% endhint %}
+
 ## Best Practices
 
 1. **Keep jobs small and focused**: Each job should do one thing. Chain multiple jobs for complex workflows.