@lowdefy/docs-content 6.0.0 → 6.1.0

package/content/agents/agentchat.md

@@ -66,8 +66,9 @@ The `AgentChat` block renders a streaming AI chat interface. It connects to a [L
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `agentId` | string | | __Required__ - The `id` of the agent to connect to. |
-| `conversationId` | string | | Active conversation ID. When this changes, messages are cleared. If left empty, the block auto-mints a stable id for the session and surfaces it via `onConversationStart`, so every turn posts a consistent id. App-supplied ids are always authoritative. |
-| `messages` | array | | Load messages externally. `undefined` = no sync, `null` = clear, array = load. |
+| `conversationId` | string | | Active conversation ID. When this changes, any in-flight reply is aborted (so it stops emitting `onDataPart` and tool events into the page) and messages are cleared. If left empty, the block auto-mints a stable id for the session and surfaces it via `onConversationStart`, so every turn posts a consistent id. App-supplied ids are always authoritative. |
+| `messages` | array | | Load messages externally. `undefined` = no sync, `null` = clear, array = load. Re-synced whenever the array's length, last message id or `conversationId` changes. |
+| `loading` | boolean | `false` | The app is still loading this conversation's transcript (for example, reading it from a database after a conversation switch). While `true`, a skeleton replaces the message area, suggestions are hidden and the composer is disabled, so nothing can be sent into a conversation whose messages have not synced yet. Drive it from state alongside `messages`, for the window before the transcript has synced — not while a reply is streaming, since a disabled composer also hides the stop control. |
 | `urlQuery` | object | | Query parameters sent with each request. Available server-side via `_payload`. |
 | `sharedState` | object | | Two-way bridge between page state and the agent. See [Shared State](#shared-state). |
 | `height` | string | `'calc(100dvh - 170px)'` | CSS height of the chat container. Only applies when `display` is `'inline'`. |

package/content/concepts/events-and-actions.md

@@ -102,6 +102,37 @@ If one action in the chain of event actions fails by throwing an error, the acti
             # ...
 ```
 
+Inside the `catch` list, the [`_error`](/_error) operator returns the error that sent the event there — the error of the failed action, or of a control whose operators failed. Outside a `catch` list it returns `null`. An error from the server carries the message "Something went wrong." unless the endpoint author wrote it, and keeps its `code` and `statusCode`, so a `catch` list can branch on them. An error raised in the browser keeps its real message, and carries `actionId`, the id of the action that failed.
+
+###### Branch on the error in a catch list:
+```yaml
+events:
+  onClick:
+    try:
+      - id: save
+        type: Request
+        params: save_customer
+        messages:
+          error: false
+    catch:
+      - :if:
+          _eq:
+            - _error: statusCode
+            - 409
+        :then:
+          - id: conflict_message
+            type: DisplayMessage
+            params:
+              status: warning
+              content: Someone else changed this customer. Reload the page and try again.
+        :else:
+          - id: error_message
+            type: DisplayMessage
+            params:
+              status: error
+              content: Could not save the customer.
+```
+
 ## Control flow in action lists
 
 An item in an action list is either an action (`id` and `type`) or a control. Action lists support the routine controls [`:if`](/:if), [`:switch`](/:switch) and [`:return`](/:return):

package/content/concepts/i18n.md

@@ -128,7 +128,7 @@ The page-shell blocks ([`PageHeaderMenu`](/PageHeaderMenu), [`PageSidebarLayout`
 
 ## Built-in framework strings
 
-The framework emits a few user-visible strings (action loading toasts, validation summaries, popup-blocker warnings, the global error page). They live in a built-in catalog and surface as English by default. Override any of them by adding the same key under `config.i18n.messages.{locale}`:
+The framework emits a few user-visible strings (action loading toasts, validation summaries, popup-blocker warnings, the global error page, the generic server error message). They live in a built-in catalog and surface as English by default. Override any of them by adding the same key under `config.i18n.messages.{locale}`:
 
 ```yaml
 config:
@@ -147,6 +147,7 @@ config:
         errorPage.name: 'Fehler'
         errorPage.message: 'Ein Fehler ist aufgetreten.'
         errorPage.homeLink: 'Zurück zur Startseite'
+        server.genericError: 'Etwas ist schiefgelaufen.'
 ```
 
 **Built-in keys you can override:**
@@ -164,6 +165,9 @@ config:
 | `errorPage.name` | `Error` | Full-page error fallback heading |
 | `errorPage.message` | `An error has occurred.` | Full-page error fallback body |
 | `errorPage.homeLink` | `Return to home page` | Full-page error fallback link |
+| `server.genericError` | `Something went wrong.` | Message of any server error that is not an author error or an auth refusal |
+
+`server.genericError` is the message users see for any server error that is not an author error (`:throw`, `:reject`, a failed `ValidateSchema` step, a plugin's `UserError`) or an authentication refusal. The server translates it for the request's locale, the same way in development and production, and it is the message that `_actions`, `_request_details` and [`_error`](/_error) read in page config. To show something else for one action, set `messages.error` on the action to override its error toast. To show the real message, read it with [`_error`](/_error) inside the endpoint's `:catch` and send it on, for example `:throw: { _error: message }`.
 
 ## Localizing block defaults
 

package/content/concepts/lowdefy-schema.md

@@ -41,7 +41,15 @@ Find the more detailed block schema [here](/blocks).
 
 The config object has the following properties:
 
-- `cron: object`: Declare the deployment environments scheduled endpoints run in (`cron.environments`), so that every environment's crons are registered on the Vercel production deployment and forwarded from there. See [Scheduled Endpoints](/api).
+- `environments: object`: The deployment environments of the app, keyed by name (for example `prod`, `staging`, `local`). Each build is for one of them, named by the `LOWDEFY_ENVIRONMENT` environment variable, and the current environment supplies the defaults for everything environment-specific. See [Deployment environments](/deployment-environments). Each environment has:
+  - `url: string`: The deployment origin, for example `https://staging.example.com`. Default for the auth base URL (`AUTH_URL`), notification links and logos (`RenderNotification` `serverUrl`), and where crons are forwarded to.
+  - `cron.secret: string`: The **name** of the Lowdefy secret holding this environment's `CRON_SECRET` — a plain string, not a `_secret` operator (environment settings are resolved at build time, where `_secret` is not evaluated). The value is read at runtime from `LOWDEFY_SECRET_<name>` on the deployment that forwards. An environment with a `cron.secret` has its schedules forwarded to it from the environment Vercel fires crons on.
+  - `cron.enabled: boolean`: Set `false` to register no cron jobs for this environment. Defaults to `true`.
+  - `email.filter: object`: The delivery filter (`replaceAddress`, `allowlist`, `regex`) applied to every `SMTPMailSend` and `SendGridMailSend` request in this environment, unless the connection sets its own `filter` (`filter: false` on a connection turns filtering off).
+  - `email.enabled: boolean`: Set `false` to send no email from `SMTPMailSend` and `SendGridMailSend` requests in this environment (auth emails still send). Defaults to `true`.
+  - `sentry.enabled: boolean`: Set `false` to turn Sentry off, server and client, in this environment. Defaults to `true`.
+  - `guards: object`: Pin secrets and environment variables to a pattern kept in config. `guards.secrets` maps a Lowdefy secret name (`LOWDEFY_SECRET_<name>`) and `guards.env` an environment variable name to a regular expression; in this environment the build fails unless each value matches (a missing value fails too), so changing a guarded value also takes a config change. See [Guards](/deployment-environments).
+- `environment: string`: The name of the environment this build is for, used when the `LOWDEFY_ENVIRONMENT` environment variable is not set; the variable always wins. When `environments` is declared it must be one of its names. Server log lines carry it as `environment`, `_app: environment` reads it, and Sentry reports under it unless `logger.sentry.environment` is set.
 - `basePath: string`: Set the base path to serve the Lowdefy application from. This will route all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`. The basePath value must start with "/".
 - `homePageId: string`: The id of the page that will load when a visitor navigates to the home route, in other words, when the visitor navigates to `yourdomain.com` or `yourdomain.com/`.
 - `requestTimeout: number`: Maximum time in milliseconds a request may run before the server returns a timeout. This protects against requests that hang on an upstream call (database, SMTP, an external API) running all the way to the host's function limit — important on serverless platforms that bill by execution duration. Defaults to `30000` (30 seconds). Set to `0` to disable. Agent streaming routes are exempt, since they are long-lived by design.

package/content/connections/sendgridmail.md

@@ -41,6 +41,7 @@ Request types:
   - `replaceAddress: string`: Redirect all mail to this single address. When set, it takes precedence — every message goes to this address only, with `cc` and `bcc` dropped.
   - `allowlist: string[]`: A list of domains. Only recipients whose domain is in the list are sent to.
   - `regex: string`: A regular expression. Only recipient addresses matching the pattern are sent to.
+  When the connection sets no `filter`, or every field of it resolves to `null`, the current environment's `email.filter` from [`config.environments`](/lowdefy-schema) applies instead. A connection's own `filter` wins when it sets at least one field, and `filter: false` turns filtering off entirely, the environment's too. With `email.enabled: false` on the current environment, mail requests send nothing and report each message as `{ disabled: true }`.
 
 ### SendGridMailSend
 

package/content/connections/smtp.md

@@ -75,6 +75,20 @@ The connection's `filter` is applied to every message before it is sent — from
 - `allowlist: string[]`: A list of domains. Only recipients whose domain is in the list are sent to; others are dropped. When every `to` recipient is filtered out, the message is not sent.
 - `regex: string`: A regular expression. Only recipient addresses matching the pattern are sent to.
 
+When the connection sets no `filter`, or every field of it resolves to `null`, the current environment's `email.filter` from [`config.environments`](/lowdefy-schema) applies instead, so the per-environment rule lives in one place for every mail connection. A connection's own `filter` wins when it sets at least one field, and `filter: false` turns filtering off entirely — the environment's too — for mail that must reach its real recipient in every environment (an invite, say). Auth emails are never filtered. With `email.enabled: false` on the current environment, mail requests send nothing and report each message as `{ disabled: true }`.
+
+```yaml
+config:
+  environments:
+    prod:
+      url: https://app.example.com
+    staging:
+      url: https://staging.example.com
+      email:
+        filter:
+          replaceAddress: team+staging@example.com
+```
+
 `allowlist` and `regex` combine — a recipient must satisfy both to receive mail.
 
 ### Examples

package/content/controls/reject.md

@@ -1,7 +1,7 @@
 # :reject
 
 ```
-({:reject: string, :cause: any}): void
+({:reject: string | Error, :cause: any}): void
 ```
 
 The `:reject` control is used to return a user-friendly error to the client when validation fails or business rules are violated.
@@ -9,9 +9,11 @@ Unlike [`:throw`](/:throw), which indicates a system error, `:reject` represents
 The control immediately stops routine execution and returns with a `"reject"` status.
 Importantly, `:reject` does not trigger `:catch` blocks in [`:try`](/:try) statements, making it ideal for handling validation and business logic errors separately from system errors.
 
+`:reject` also takes an Error as its message, such as the error a `:catch` caught: `:reject: { _error: true }`. The reject message is then "Something went wrong.", unless the error was a `UserError` or an authentication error, whose message is kept. To reject with the caught error's real message, name it: `:reject: { _error: message }`. See [`_error`](/_error).
+
 #### Keys
 
-- `:reject: string`: __Required__ - The error message that will be returned in the response object of the API call result.
+- `:reject: string | Error`: __Required__ - The error message that will be returned in the response object of the API call result, or an Error whose message to use.
 - `:cause: any`: Additional metadata that will be returned with the error message.
 
 #### Examples

package/content/controls/throw.md

@@ -1,7 +1,7 @@
 # :throw
 
 ```
-({:throw: string, :cause: any}): void
+({:throw: string | Error, :cause: any}): void
 ```
 
 The `:throw` control creates a system error that immediately stops routine execution and returns with an "error" status.
@@ -9,13 +9,40 @@ Unlike [`:reject`](/:reject), which handles expected user errors, `:throw` is de
 The key difference is that `:throw` can be caught and handled by [`:try`](/:try)/`:catch` blocks, while [`:reject`](/:reject) cannot.
 This makes `:throw` ideal for recoverable system errors where you might want to implement fallback logic.
 
+`:throw` also takes an Error as its message, such as the error a `:catch` caught: `:throw: { _error: true }`. The error is rethrown as it is, with its own class and cause, and `:cause` is ignored. The client receives it with the message "Something went wrong.", keeping its `code` and `statusCode`, unless it was a `UserError`, whose message is kept. To show the user the caught error's real message, name it: `:throw: { _error: message }`. See [`_error`](/_error).
+
 #### Keys
 
-- `:throw: string`: __Required__ - The error message that will be returned in the response object of the API call result.
+- `:throw: string | Error`: __Required__ - The error message that will be returned in the response object of the API call result, or an Error to rethrow.
 - `:cause: any`: Additional metadata that will be returned with the error message.
 
 #### Examples
 
+###### Rethrow a caught error
+```yaml
+- :try:
+    - id: update_stock
+      type: MongoDBUpdateOne
+      connectionId: inventory
+      properties:
+        filter:
+          sku:
+            _payload: sku
+        update:
+          $inc:
+            quantity:
+              _payload: change
+  :catch:
+    - :log:
+        message: Stock update failed
+        reason:
+          _error: message
+      :level: error
+    - :throw:
+        _error: true
+```
+The `:catch` logs the real message, then rethrows the error. The client receives it with the message "Something went wrong.", with the error's `code` and `statusCode`.
+
 ###### Throw on invalid status
 ```yaml
 - :switch:

package/content/controls/try.md

@@ -7,6 +7,7 @@
 If one control in the routine chain defined in the `:try` key fails by throwing an error, the steps in the list following the failed control will not be executed.
 To handle any errors thrown by a routine element, a routine can be provided using `catch` key.
 The routine defined using the `:finally` key will be run regardless of whether or not the routine throws an error.
+Inside the `:catch` routine, the [`_error`](/_error) operator returns the error that was caught, so the routine can branch on its `statusCode` or `code`, or read its `message`. `_error` returns the error of the innermost `:catch` that encloses it, and `null` outside a `:catch`.
 
 #### Keys
 
@@ -16,6 +17,25 @@ The routine defined using the `:finally` key will be run regardless of whether o
 
 #### Examples
 
+###### Branch on the caught error
+```yaml
+- :try:
+    - id: get_customer
+      type: AxiosHttp
+      connectionId: crm
+      properties:
+        url: /customers
+        params:
+          id:
+            _payload: id
+  :catch:
+    - :if:
+        _eq: [{ _error: statusCode }, 404]
+      :then:
+        - :reject: Customer not found
+    - :throw: Customer lookup failed
+```
+
 ###### Try external API with fallback
 ```yaml
 - :try:

package/content/deployment/deployment-environments.md

@@ -0,0 +1,143 @@
+# Deployment environments
+
+Most apps run as more than one deployment: production, a staging copy, a developer's machine. Everything that differs between them is declared once, under `config.environments`, and each deployment says which environment it is with the `LOWDEFY_ENVIRONMENT` environment variable. Lowdefy then takes every environment-specific default from the **current environment** — the app URL, crons, the email delivery filter, Sentry, and the feature switches — so none of them needs its own variable or operator chain.
+
+```yaml
+# lowdefy.yaml
+config:
+  environments:
+    local:
+      email:
+        filter:
+          replaceAddress: team+local@example.com
+    staging:
+      url: https://staging.example.com
+      cron:
+        secret: STAGING_CRON_SECRET
+      email:
+        filter:
+          replaceAddress: team+staging@example.com
+    prod:
+      url: https://app.example.com
+      guards:
+        secrets:
+          MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net'
+```
+
+Then set `LOWDEFY_ENVIRONMENT=prod` on the production deployment, `LOWDEFY_ENVIRONMENT=staging` on staging, and `LOWDEFY_ENVIRONMENT=local` in your local `.env`.
+
+## The current environment
+
+`LOWDEFY_ENVIRONMENT` is read **at build time**, so set it wherever the app is built (on Vercel, as an Environment Variable of each Vercel environment). `config.environment` can name the current environment in config instead, for a deployment that sets no `LOWDEFY_ENVIRONMENT`; the variable always wins, so a literal committed to config never forces every deployment into one environment.
+
+- With `config.environments` declared, the current environment must be one of its names — a typo fails the build.
+- With `config.environments` declared, a production build (`lowdefy build`) fails when no current environment is set: no environment setting would apply — no email filter, no forwarded crons, no guards. The dev server warns and runs with no environment setting.
+- Environment names may contain `A-Z`, `a-z`, `0-9`, `-` and `_`. `default` is reserved.
+
+## Environment settings
+
+Every setting is optional, and every feature is **on by default**: only an explicit `enabled: false` switches one off.
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `url` | none | The deployment origin, e.g. `https://staging.example.com`. |
+| `cron.secret` | none | The name of the Lowdefy secret holding this environment's `CRON_SECRET`; makes this environment a cron forwarding target. |
+| `cron.enabled` | `true` | `false`: no cron jobs registered or forwarded for this environment. |
+| `email.filter` | none | Delivery filter (`replaceAddress`, `allowlist`, `regex`) for mail requests. |
+| `email.enabled` | `true` | `false`: mail requests send nothing. |
+| `sentry.enabled` | `true` | `false`: Sentry off, server and client. |
+| `guards.secrets`, `guards.env` | none | Regular expressions the named secrets and environment variables must match, or the build fails. |
+
+## URL
+
+The current environment's `url` is the default for:
+
+- the auth base URL (`AUTH_URL`) — sign-in callbacks and auth links;
+- the `serverUrl` of `RenderNotification` steps — the links and logo in notification emails;
+- where crons are forwarded to, when another environment forwards to this one.
+
+An explicit `AUTH_URL` / `NEXTAUTH_URL` or `serverUrl` still wins. The dev server (`lowdefy dev`) never uses the current environment's `url`: auth and notification links use the request origin, the local app, even when your local `.env` names a deployed environment. Production never uses the request origin, since a spoofed `Host` header would then steer the links in outgoing mail.
+
+Every deployment that names an environment is taken to be served at its `url`. Preview deployments that should not sign users in on the staging host need their own environment, e.g. a `preview` environment with no `url` and the same `email.filter` and guards as staging.
+
+## Crons
+
+Vercel fires cron jobs only on the **production** deployment, so the schedules of other environments are registered there too and forwarded:
+
+- The current environment registers its own schedules as `/api/cron/<endpointId>` jobs.
+- An environment with a `cron.secret` is a **forwarding target**. The environment without one (production) also registers the target's schedules as `/api/cron-forward/<environment>/<endpointId>` jobs; when one fires, it pings the target's own `/api/cron/<endpointId>` at its `url` with the target's `CRON_SECRET` and answers immediately.
+- `cron.secret` is the **name** of a Lowdefy secret — a plain string such as `STAGING_CRON_SECRET`, not a `_secret` operator (environment settings are resolved at build time, where `_secret` is not evaluated). Production reads the value at runtime from `LOWDEFY_SECRET_STAGING_CRON_SECRET`, so set that variable on the production deployment to staging's `CRON_SECRET`.
+- `cron.enabled: false` registers nothing for that environment, and production does not forward to it.
+
+Endpoint `schedules` can be keyed by environment name, with a `default` for the rest and `[]` to turn an endpoint off in one environment — see [Schedules per environment](/lowdefy-api). The Vercel side (securing the routes, plan limits) is covered in [Deploy with Vercel](/vercel).
+
+## Email
+
+- **`email.filter`** is applied to every `SMTPMailSend` and `SendGridMailSend` request whose connection sets no `filter` of its own, or a filter whose fields all resolve to `null` (a `_secret` that is not set on this deployment, say). Put a catch-all `replaceAddress` on every non-production environment and no environment can email real users by accident.
+- A connection's own `filter` wins when it sets at least one field, and **`filter: false`** on a connection turns filtering off entirely, the environment's too — for mail that must reach its real recipient everywhere, such as an invite.
+- **`email.enabled: false`** sends nothing: each message reports `{ messageId: null, to: null, disabled: true }`.
+- Auth emails (magic links, verification, invitations sent by the auth engine) never go through a mail request, so neither setting affects them — sign-in keeps working in every environment.
+
+See the [SMTP](/SMTP) and [SendGridMail](/SendGridMail) connections for the filter fields.
+
+## Logs and Sentry
+
+- Every server log line carries `environment` next to `app_name`, `app_version` and `git_sha`, so one log drain can hold every environment. Logging cannot be switched off.
+- Sentry reports under the environment name unless `logger.sentry.environment` is set, and `sentry.enabled: false` turns it off on the server and in the browser.
+
+## Guards
+
+Guards pin an environment's secrets and environment variables to a pattern kept in config — a second factor for deploy-time configuration. In the current environment the build fails before anything deploys unless every guarded value matches its regular expression; an unset value fails too. The production server checks the same guards again when it starts, against the variables it runs with, and refuses to start on a mismatch — an image built once can be started with different variables. Changing the production database then takes both a new variable value **and** a reviewed config change.
+
+```yaml
+config:
+  environments:
+    prod:
+      url: https://app.example.com
+      guards:
+        secrets: # Lowdefy secrets, by name (LOWDEFY_SECRET_<name>)
+          MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net'
+        env: # any environment variable
+          AUTH_URL: '^https://app\.example\.com$'
+```
+
+- Patterns match anywhere in the value, so a distinctive substring is enough; add `^` and `$` to pin the whole value. A pattern is committed with your config, so never put the sensitive part of a secret in it — a host name or database name is enough.
+- Only the current environment's guards are checked. Every environment's patterns are validated, so a broken pattern fails the build that introduces it. `secrets` and `env` are the only guard kinds; any other key (a `secret:` typo, say) fails the build.
+- A failure names the variable and never prints its value.
+- Guards need the real values at build time and at startup. On Vercel, Environment Variables are available to both; a container build that only injects secrets when the container starts sees them as unset and fails.
+
+## What reaches the browser
+
+Environment settings stay on the server. The browser only learns the current environment's **name** and the list of features it switches off, through the app metadata:
+
+- `_app: environment` — the current environment's name.
+- `_app: disabled` — the switched-off features, e.g. `[email, sentry]`.
+
+Other environments' settings, URLs, secret names, email filters and guards never reach the client bundle. Only the current environment's guards are kept in the build output, in the server-only `config.json`, for the startup check.
+
+## Upgrading from `config.cron`
+
+Lowdefy 6.0 declared cron environments under `config.cron.environments`. That key is replaced, and a build that still has it fails with the migration:
+
+```yaml
+# Before
+config:
+  cron:
+    environments:
+      production: {}
+      staging:
+        url: https://staging.example.com
+        secret: STAGING_CRON_SECRET
+
+# After
+config:
+  environments:
+    production:
+      url: https://app.example.com
+    staging:
+      url: https://staging.example.com
+      cron:
+        secret: STAGING_CRON_SECRET
+```
+
+Move each `secret` to `cron.secret` and `enabled` to `cron.enabled`, give production its `url`, and set `LOWDEFY_ENVIRONMENT` on each deployment.

package/content/deployment/docker.md

@@ -123,7 +123,8 @@ The server is configured entirely through environment variables at runtime — t
 | `PORT`              | Port the server listens on (default `3000`).                             |
 | `LOWDEFY_SECRET_*`  | App secrets, accessed with the [`_secret`](/_secret) operator.           |
 | `AUTH_SECRET`       | Required when using [Lowdefy Auth](/users-introduction).                 |
-| `AUTH_URL`          | The deployed app URL, required for OAuth providers.                      |
+| `LOWDEFY_ENVIRONMENT` | Read at build time: the environment this image is built for, one of `config.environments`. |
+| `AUTH_URL`          | The deployed app URL, required for OAuth providers. Defaults to the `url` of the current environment in `config.environments`. |
 | `CRON_SECRET`       | Bearer token protecting `/api/cron/*` and `/api/detached/*` endpoints.   |
 | `LOWDEFY_LOG_LEVEL` | Server log level: `debug`, `info` (default), `warn`, `error`.            |
 | `SENTRY_DSN`        | Enables Sentry error reporting when set.                                 |

package/content/deployment/vercel.md

@@ -34,7 +34,7 @@ Files in your app's `public/` directory (favicon, icons, images, `manifest.webma
 
 ###### Secrets and environment variables
 
-Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`. Use `AUTH_SECRET` (and `AUTH_URL` for OAuth) for authentication. Different secrets can be set for production and preview deployments.
+Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`. Use `AUTH_SECRET` (and `AUTH_URL` for OAuth, which defaults to the current environment's `url` — see [Deployment environments](#deployment-environments)) for authentication. Different secrets can be set for production and preview deployments.
 
 ###### Function settings
 
@@ -80,33 +80,28 @@ Each schedule becomes a cron job pointing at `/api/cron/<endpointId>`. When it f
 - **Plan limits:** Vercel **Hobby** only allows daily crons (a sub-daily expression fails the deployment); **Pro**/**Enterprise** allow per-minute. Up to 100 cron jobs per project.
 - **Idempotency:** Vercel does not retry failed runs and delivery is best-effort (a run can be missed or delivered more than once). Design scheduled routines to be idempotent.
 
-###### Crons for staging and other environments
+###### Deployment environments
 
-Vercel fires cron jobs only on the **production** deployment — a staging or preview deployment never runs its schedules on its own. Declare your environments under `config.cron` and Lowdefy registers every environment's schedules on production; when one for another environment fires, production forwards it to that environment's own `/api/cron/<endpointId>` and answers Vercel immediately (the ping is fire-and-forget, kept alive via the request context and bounded by `maxDuration`; its outcome is logged as `forward_scheduled_endpoint_done` / `_failed`).
+Declare the app's environments once under `config.environments` and name the current one with the `LOWDEFY_ENVIRONMENT` Environment Variable — see [Deployment environments](/deployment-environments) for every setting (URL, crons, email, Sentry, feature switches, guards). On Vercel, add `LOWDEFY_ENVIRONMENT` to each Vercel environment (for example `prod` on Production and `staging` on the staging branch's Preview environment). Vercel Environment Variables are available at build time, which is when Lowdefy reads it and checks guards.
 
-```yaml
-config:
-  cron:
-    environments:
-      production: {} # no url: the deployment Vercel fires crons on
-      staging:
-        url: https://staging.example.com
-        secret: STAGING_CRON_SECRET
-```
+###### Crons for staging and other environments
+
+Vercel fires cron jobs only on the **production** deployment — a staging or preview deployment never runs its schedules on its own. Give an environment a `cron.secret` and the environment Vercel fires crons on registers that environment's schedules too; when one fires, production forwards it to that environment's own `/api/cron/<endpointId>` at its `url` and answers Vercel immediately (the ping is fire-and-forget, kept alive via the request context and bounded by `maxDuration`; its outcome is logged as `forward_scheduled_endpoint_done` / `_failed`).
 
-- **One host environment:** exactly one environment has no `url` — the deployment whose crons Vercel fires. Every other environment needs its `url` (deployment origin) and a `secret`: the Lowdefy secret name holding that environment's own `CRON_SECRET`. Set `enabled: false` on an environment to register no crons for it.
+- **Forwarded environments:** an environment with a `cron.secret` is forwarded to, so it must have a `url`. `cron.secret` is the **name** of the Lowdefy secret holding that environment's own `CRON_SECRET` — a plain string such as `STAGING_CRON_SECRET`, not `{ _secret: ... }`: environment settings are resolved at build time, and the forward route reads the value at runtime from `LOWDEFY_SECRET_<name>`. Set `cron.enabled: false` on an environment to register no crons for it.
 - **Secrets on production:** for each forwarded environment add an Environment Variable `LOWDEFY_SECRET_<secret name>` (for example `LOWDEFY_SECRET_STAGING_CRON_SECRET`) to the production deployment, with that environment's `CRON_SECRET` as value. The forward route `/api/cron-forward/*` itself is secured by production's own `CRON_SECRET` like every cron route, and fails closed when the environment's secret is missing.
-- **Per-environment schedules:** key an endpoint's `schedules` by environment name with an optional `default` (`staging: []` turns them off) — see [Schedules per environment](/api). The generated crons are `/api/cron/<endpointId>` for the host environment and `/api/cron-forward/<environment>/<endpointId>` for the others; all of them count toward the project's cron limit.
+- **Per-environment schedules:** key an endpoint's `schedules` by environment name with an optional `default` (`staging: []` turns them off) — see [Schedules per environment](/lowdefy-api). The generated crons are `/api/cron/<endpointId>` for the current environment and `/api/cron-forward/<environment>/<endpointId>` for the forwarded ones; all of them count toward the project's cron limit.
 - **Plan limits still apply per project:** a per-minute staging schedule needs the same Pro plan as a per-minute production one.
+- **Upgrading from 6.0:** `config.cron.environments` is replaced by `config.environments`; see [Upgrading from `config.cron`](/deployment-environments).
 
 ###### Background work: async endpoints and detached calls
 
-Two [API endpoint](/api) controls exist for work that should not hold up a response — they behave differently on Vercel:
+Two [API endpoint](/lowdefy-api) controls exist for work that should not hold up a response — they behave differently on Vercel:
 
 - **`async: true` endpoints** respond `{ accepted: true }` immediately and run the routine in the background. On Vercel the invocation is kept alive via the platform request context (Fluid compute) until the routine settles — but it is still the *same* invocation, so the background work remains bounded by `maxDuration`. Raise `config.vercel.maxDuration` to cover your longest async routine.
 - **`detached: true` on `CallApi` steps** fire-and-forget the target endpoint through a `POST` to the deployment's own `/api/detached/<endpointId>` route, so the target runs in its **own** invocation with a fresh `maxDuration` budget. The route is secured by `CRON_SECRET` (same secret as cron, fail closed), and detached steps fail with a config error if it is not set. Delivery is at-most-once with no retry; targets run as system context (`_user` is `undefined`) and must be idempotent.
 
-See [Async Endpoints](/api) and [Detached Endpoint Calls](/api) in the API docs for full semantics.
+See [Async Endpoints](/lowdefy-api) and [Detached Endpoint Calls](/lowdefy-api) in the API docs for full semantics.
 
 ###### Cost protection
 

package/content/operators/_error.md

@@ -0,0 +1,173 @@
+# _error
+
+```
+(key: string): any
+(all: boolean): Error | null
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any,
+}): any
+```
+
+The `_error` operator returns the error that is being handled:
+
+- Inside a server [`:catch`](/:try) routine, it returns the error that sent the routine to the `:catch`.
+- Inside a client [`catch`](/events-and-actions) action list, it returns the error that sent the event to the `catch` list.
+- Outside a catch, it returns `null`, the way [`_item`](/_item) does outside a `:for`. Reading a key outside a catch returns `null`, or the `default` when one is given.
+
+On the server, `_error` resolves lexically. It returns the error of the innermost enclosing `:catch`. After an inner `:try` finishes, the outer `:catch` reads its own error again. A `:finally` reads the error of the `:catch` that encloses its `:try`, or `null` if no `:catch` does. Each [`:parallel`](/:parallel) branch reads its own error. [`:reject`](/:reject) does not trigger `:catch`, so `_error` never holds a reject.
+
+Dot notation is supported for reading fields of the error, such as `_error: statusCode` or `_error: cause.message`.
+
+##### The error on the server
+
+Inside a `:catch`, `_error` is an Error rebuilt from the caught error with only these fields:
+
+- `name`: The error class name, such as `RequestError`.
+- `message`: The real error message, with the values of known secrets (`_secret` values, `CRON_SECRET` and `AUTH_SECRET`) replaced by `[REDACTED]`.
+- `code`: The error's `code`, if it has one.
+- `statusCode`: The error's HTTP status, if it has one.
+- `handled`: `true` once the server has logged the error.
+- `cause`: The error that caused this one, with the same fields, down the chain.
+
+A caught `UserError` (from a [`:throw`](/:throw) or a plugin) also keeps its `:cause` and `metaData`. The error carries no `received`, `source`, `config`, `configKey`, `location` or `stack`.
+
+##### The error on the client
+
+Inside a client `catch` list, `_error` is the error the browser holds:
+
+- An error from the server (a failed `Request` or `CallAPI`) is the error as the browser received it: `name`, `message`, `code`, `statusCode` and `requestId`. The `message` is "Something went wrong." (the [`server.genericError`](/i18n) message) unless the author wrote it with `:throw` or `:reject`, it comes from a failed `ValidateSchema` step, or it is a plugin's `UserError`.
+- An error raised in the browser (an action or operator that failed on the page) keeps its real message, and carries `actionId`, the id of the action that failed.
+
+##### Sending the error on
+
+Inside the routine, `_error: message` and `_error: statusCode` read the real values. When a routine sends the whole error to the client, the client receives it with the generic message, keeping `name`, `code` and `statusCode`. This applies when the whole `_error` is used as a `:cause`, as a [`:throw`](/:throw) message, or inside a [`:return`](/:return) value. To show the user the real message, send it by name: `:throw: { _error: message }`.
+
+Sent to a plugin as data, such as `body: { error: { _error: true } }` in an `AxiosHttp` request or a document in a MongoDB insert, the error records no message. Name the fields to send them:
+
+```yaml
+error:
+  name:
+    _error: name
+  message:
+    _error: message
+  statusCode:
+    _error: statusCode
+```
+
+##### `code` and `statusCode`
+
+`code` and `statusCode` follow one rule across connection libraries. `code` is the error's own `code`, such as `ERR_BAD_REQUEST` from AxiosHttp or `11000` from MongoDB. `statusCode` is the first number among the error's `statusCode`, `status` and `response.status`. A request error takes both from the error the connection threw, so `_error: statusCode` reads the HTTP status of a failed `AxiosHttp` request without reading the cause.
+
+#### Arguments
+
+###### string
+If the `_error` operator is called with a string argument, the value of that field of the error is returned. If the field is not found, or there is no error, `null` is returned. Dot notation is supported.
+
+###### boolean
+If the `_error` operator is called with boolean argument `true`, the whole error is returned, or `null` outside a catch.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the whole error is returned, or `null` outside a catch. One of `all` or `key` are required.
+  - `key: string`: The value of that field of the error is returned. If the field is not found, or there is no error, `null` or the specified default value is returned. Dot notation is supported. One of `all` or `key` are required.
+  - `default: any`: A value to return if the `key` is not found. By default, `null` is returned.
+
+#### Examples
+
+###### Branch on the HTTP status in a server `:catch`:
+```yaml
+- :try:
+    - id: get_customer
+      type: AxiosHttp
+      connectionId: crm
+      properties:
+        url: /customers
+        params:
+          id:
+            _payload: id
+  :catch:
+    - :if:
+        _eq: [{ _error: statusCode }, 404]
+      :then:
+        - :reject: Customer not found
+    - :throw: Customer lookup failed
+```
+A `404` from the CRM rejects with a message for the user. Any other failure throws a new error, which the user sees as "Customer lookup failed".
+
+###### Rethrow with the real message:
+```yaml
+- :try:
+    - id: charge
+      type: AxiosHttp
+      connectionId: payments
+      properties:
+        url: /charges
+        method: post
+        data:
+          amount:
+            _payload: amount
+  :catch:
+    - :throw:
+        _string.concat:
+          - 'Payment failed: '
+          - _error: message
+```
+The user sees the real error message after `Payment failed: `. Without naming `message`, `:throw: { _error: true }` would show "Something went wrong.".
+
+###### Log the error with a default:
+```yaml
+- :try:
+    - id: sync_orders
+      type: MongoDBInsertMany
+      connectionId: orders
+      properties:
+        docs:
+          _payload: orders
+  :catch:
+    - :log:
+        message: Order sync failed
+        code:
+          _error:
+            key: code
+            default: unknown
+        reason:
+          _error: message
+      :level: warn
+    - :return:
+        synced: false
+```
+
+###### Branch on the HTTP status in a client `catch` list:
+```yaml
+- id: save_button
+  type: Button
+  properties:
+    title: Save
+  events:
+    onClick:
+      try:
+        - id: save
+          type: Request
+          params: save_customer
+          messages:
+            error: false
+      catch:
+        - :if:
+            _eq:
+              - _error: statusCode
+              - 409
+          :then:
+            - id: conflict_message
+              type: DisplayMessage
+              params:
+                status: warning
+                content: Someone else changed this customer. Reload the page and try again.
+          :else:
+            - id: error_message
+              type: DisplayMessage
+              params:
+                status: error
+                content: Could not save the customer.
+```
+`messages.error: false` turns off the request's own error message, so the `catch` list decides what the user sees.

package/index.json

@@ -235,6 +235,12 @@
       "section": "Deployment",
       "path": "content/deployment/vercel.md"
     },
+    {
+      "slug": "deployment/deployment-environments",
+      "title": "Deployment environments",
+      "section": "Deployment",
+      "path": "content/deployment/deployment-environments.md"
+    },
     {
       "slug": "plugins/plugins-introduction",
       "title": "Plugins",
@@ -1723,6 +1729,14 @@
       "kind": "operator",
       "typeName": "_eq"
     },
+    {
+      "slug": "operators/_error",
+      "title": "_error",
+      "section": "Operators",
+      "path": "content/operators/_error.md",
+      "kind": "operator",
+      "typeName": "_error"
+    },
     {
       "slug": "operators/_event",
       "title": "_event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/docs-content",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "description": "Lowdefy documentation extracted as markdown for AI coding agents.",
   "homepage": "https://lowdefy.com",