improvement(self-host): centralize capability resolution

Author: TheodoreSpeaks

apps/docs/content/docs/en/platform/self-hosting/object-storage.mdx

@@ -23,14 +23,14 @@ Sim stores every uploaded file — knowledge base documents, chat attachments, e
 
 ## How the backend is selected
 
-Sim picks the backend automatically from environment variables — there is no explicit "provider" flag. The logic, in order of precedence:
+Set `STORAGE_PROVIDER` to `local`, `s3`, `azure`, or `gcs` to select a backend explicitly. When it is unset, Sim infers the backend from the configured environment variables in this order:
 
 1. **Azure Blob** — used if `AZURE_STORAGE_CONTAINER_NAME` is set **and** either (`AZURE_ACCOUNT_NAME` + `AZURE_ACCOUNT_KEY`) or `AZURE_CONNECTION_STRING` is set.
 2. **AWS S3** — used if `S3_BUCKET_NAME` **and** `AWS_REGION` are set (and Azure is not configured).
 3. **Google Cloud Storage** — used if `GCS_BUCKET_NAME` is set (and neither Azure nor S3 is configured).
 4. **Local disk** — the fallback when none is configured.
 
-If more than one backend is configured, the first match in that order wins. Set only the variables for the backend you intend to use.
+If `STORAGE_PROVIDER` is unset, Sim skips incomplete backends and uses the first ready match in that order. A higher-priority backend with its required fields present but invalid supplied values fails fast instead of silently falling through. An explicit `STORAGE_PROVIDER` takes precedence and must be valid and complete.
 
 ## Set up AWS S3
 

apps/sim/.env.example

@@ -32,9 +32,9 @@ API_ENCRYPTION_KEY=your_api_encryption_key # Use `openssl rand -hex 32` to gener
 CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authenticates the scheduler against the background job endpoints (scheduled workflows, polling triggers, connector syncs)
 
 # Email Provider (Optional)
-# Configure ONE provider — the mailer auto-detects in priority order:
-# Resend → AWS SES → SMTP → Azure Communication Services → Gmail. If none
-# are configured, emails are logged to console instead.
+# Configure one or more providers. Every configured provider stays active and is
+# tried in order: Resend → AWS SES → SMTP → Azure Communication Services → Gmail.
+# If none are configured, emails are logged to console instead.
 #
 # Resend
 # RESEND_API_KEY=                       # API key from https://resend.com

apps/sim/lib/core/config/env-capabilities.server.ts

@@ -5,35 +5,35 @@
  */
 import { env } from '@/lib/core/config/env'
 import {
+  ASYNC_JOBS_CAPABILITY,
+  CACHE_CAPABILITY,
   type ConfiguredOAuthClient,
   type FallbackCapabilityDefinition,
   inspectOAuthClientCapability,
   type OAuthClientCapabilityField,
   type OAuthClientCapabilityId,
+  requireCapability,
   requireOAuthClientCapability,
-  resolveAsyncJobsProvider,
-  resolveCacheProvider,
-  resolveSandboxProviderId,
-  resolveSelectedCapability,
+  SANDBOX_CAPABILITY,
   STORAGE_CAPABILITY,
   type WireFallbackOptions,
   wireFallback,
 } from '@/lib/core/config/env-capabilities'
 
 export function getConfiguredStorageProviderId() {
-  return resolveSelectedCapability(STORAGE_CAPABILITY, env).providerId
+  return requireCapability(STORAGE_CAPABILITY, env).providerId
 }
 
 export function getConfiguredSandboxProviderId() {
-  return resolveSandboxProviderId(env)
+  return requireCapability(SANDBOX_CAPABILITY, env).providerId
 }
 
 export function getConfiguredAsyncJobsProvider() {
-  return resolveAsyncJobsProvider(env)
+  return requireCapability(ASYNC_JOBS_CAPABILITY, env).providerId
 }
 
 export function getConfiguredCacheProvider() {
-  return resolveCacheProvider(env)
+  return requireCapability(CACHE_CAPABILITY, env).providerId
 }
 
 export function inspectConfiguredOAuthClient(serviceId: string) {