diff --git a/.env.example b/.env.example
index 3e2b52ed..20d8f3dc 100644
--- a/.env.example
+++ b/.env.example
@@ -13,6 +13,14 @@ SM_SECRET_KEY=change-me-in-production
 # Dev-only: Vite asset URL (ignored in production builds)
 SM_VITE_DEV_URL=http://localhost:5050
 
+# Multi-tenancy (opt-in). When false (default), TenantMiddleware is not
+# installed and queries on MultiTenantMixin models ignore tenant filtering.
+# Production tenant deployments should set SM_MULTI_TENANT=true and carry
+# tenant_id in the auth token — SM_TENANT_HEADER is only a convenience for
+# internal/test clients; leave empty to disable header-based resolution.
+# SM_MULTI_TENANT=false
+# SM_TENANT_HEADER=X-Tenant-ID
+
 # First-boot admin seed (optional). Only applied when the users table is empty.
 # Leave unset and use `uv run sm-users create-admin` instead if you prefer.
 # SM_USERS_BOOTSTRAP_EMAIL=admin@example.com