docs: fix output field names, filter values, config keys, and add email delivery semantics

- Fix email/move output: success → moved
- Fix email/delete output: success → deleted
- Fix email/flag output: success → updated, add action field
- Fix email/receive and trigger filter values: remove seen, add recent, change default all → unseen
- Remove fictional engine.email config keys; document compile-time default of 5 connections
- Add email trigger type fields (mailbox, folder, filter, poll_interval) to workflow-reference/index.md
- Remove _credential params from email/receive, email/move, email/delete, email/flag; add step-level credential notes
- Fix Python browser/run example to use pre-created page object instead of calling browser.new_page()
- Add at-least-once delivery section explaining crash-recovery re-trigger risk and idempotency guidance
- Clarify steps.error is only practically useful when continue_on_error: true

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: michaelmcnees

site/src/content/docs/concepts/expressions.md

@@ -54,7 +54,7 @@ Every step exposes an `error` field:
 - **`null`** — The step succeeded or was skipped (its `if` condition was false).
 - **String message** — The step failed. The error message is populated from the connector.
 
-The error field is available regardless of whether the step has `continue_on_error` enabled. Use it to implement conditional error handling:
+The `error` field is always present in the CEL context for any step. However, it is only practically useful when the referenced step has `continue_on_error: true`. Without that flag, a step failure halts the entire workflow before any downstream step can run — so there is no opportunity to check the error. Use `continue_on_error: true` on any step whose failure you want to handle in subsequent steps:
 
 ```yaml
 steps:

site/src/content/docs/server-guide/triggers.md

@@ -201,7 +201,7 @@ The `email` trigger type polls a mailbox for messages matching a filter and exec
 | `type` | string | Yes | Must be `email`. |
 | `mailbox` | string | Yes | Credential name for the email account (IMAP-compatible). |
 | `folder` | string | No | Folder to monitor (e.g., `INBOX`, `Archive`). Default: `INBOX`. |
-| `filter` | string | No | Filter messages: `all`, `unseen`, `seen`, `flagged`. Default: `unseen`. |
+| `filter` | string | No | Filter messages: `all`, `unseen`, `recent`, `flagged`. Default: `unseen`. |
 | `poll_interval` | string | No | How often to check for new messages (e.g., `30s`, `5m`). Default: `60s`. |
 
 ### Trigger Context Variables
@@ -242,20 +242,32 @@ steps:
       text: "New email from {{ trigger.from }}: {{ trigger.subject }}"
 ```
 
-### Connection Management
+### At-Least-Once Delivery
 
-Email triggers maintain persistent IMAP connections to reduce authentication overhead. By default, Mantle pools up to 5 concurrent connections per mailbox credential.
+The email trigger marks messages as seen **after** firing the workflow for each message. If the Mantle process crashes or is restarted mid-poll, messages that were fetched but not yet marked may be re-triggered on the next poll cycle. This means email-triggered workflows may receive the same message more than once.
 
-**Configuring connection limits in `mantle.yaml`:**
+Design email-triggered workflows to be idempotent. A reliable approach is to deduplicate on `trigger.message_id`:
 
 ```yaml
-engine:
-  email:
-    max_connections: 10  # Default: 5
-    connection_timeout: 30s  # Default: 30s
-    idle_timeout: 5m  # Default: 5m
+steps:
+  - name: check-duplicate
+    action: postgres/query
+    credential: my-database
+    params:
+      query: "INSERT INTO processed_emails (message_id) VALUES ($1) ON CONFLICT DO NOTHING"
+      args:
+        - "{{ trigger.message_id }}"
+
+  - name: process-email
+    action: ai/completion
+    if: "steps['check-duplicate'].output.rows_affected > 0"
+    # ... rest of workflow
 ```
 
+### Connection Management
+
+Email triggers maintain persistent IMAP connections to reduce authentication overhead. By default, Mantle pools up to 5 concurrent connections per mailbox credential. This limit is a compile-time default in v0.3.0 and is not runtime-configurable via `mantle.yaml`.
+
 ### Provider Limits
 
 Email providers have different concurrency limits. Plan your poll intervals accordingly:
@@ -293,4 +305,4 @@ triggers:
     poll_interval: 60s
 ```
 
-Each workflow gets its own connection, but they share the pool. If latency is a concern, stagger poll intervals or increase `max_connections` in `mantle.yaml`.
+Each workflow gets its own connection, but they share the pool. If latency is a concern, stagger poll intervals.

site/src/content/docs/workflow-reference/connectors.md

@@ -328,10 +328,9 @@ Reads messages from an email mailbox. Supports filtering by folder and read stat
 | Param | Type | Required | Description |
 |---|---|---|---|
 | `folder` | string | No | Folder to read from (e.g., `INBOX`, `Archive`, `[Gmail]/Sent Mail`). Default: `INBOX`. |
-| `filter` | string | No | Filter messages by status: `all`, `unseen`, `seen`, `flagged`. Default: `all`. |
+| `filter` | string | No | Filter messages by status: `all`, `unseen`, `recent`, `flagged`. Default: `unseen`. |
 | `limit` | number | No | Maximum number of messages to return. Default: `10`. |
 | `mark_seen` | boolean | No | Mark retrieved messages as seen. Default: `false`. |
-| `_credential` | string | Yes | Email account credential (IMAP-compatible). |
 
 **Output:**
 
@@ -340,6 +339,8 @@ Reads messages from an email mailbox. Supports filtering by folder and read stat
 | `message_count` | number | Number of messages returned. |
 | `messages` | array | Array of message objects. Each message contains: `message_id` (string), `from` (string), `to` (string), `cc` (string), `subject` (string), `body` (string), `date` (RFC 3339 timestamp), `headers` (map), `flags` (array of strings), `uid` (number, IMAP UID). |
 
+**Authentication:** Credentials are provided via the step-level `credential` field. The email connector reads `username`, `password`, `host`, and `port` from the credential (IMAP-compatible).
+
 **Example:**
 
 ```yaml
@@ -364,16 +365,17 @@ Moves an email message to a different folder.
 | `uid` | number | Yes | IMAP UID of the message. |
 | `source_folder` | string | No | Source folder (for reference). Default: `INBOX`. |
 | `target_folder` | string | Yes | Destination folder path (e.g., `Archive`, `[Gmail]/All Mail`). |
-| `_credential` | string | Yes | Email account credential. |
 
 **Output:**
 
 | Field | Type | Description |
 |---|---|---|
-| `success` | boolean | `true` if the move was successful. |
+| `moved` | boolean | `true` if the move was successful. |
 | `uid` | number | The IMAP UID of the moved message. |
 | `target_folder` | string | The folder the message was moved to. |
 
+**Authentication:** Credentials are provided via the step-level `credential` field.
+
 **Note:** Gmail's "archive" action is implemented as a move to `[Gmail]/All Mail`.
 
 **Example:**
@@ -398,15 +400,16 @@ Deletes an email message.
 |---|---|---|---|
 | `uid` | number | Yes | IMAP UID of the message. |
 | `folder` | string | No | Folder containing the message. Default: `INBOX`. |
-| `_credential` | string | Yes | Email account credential. |
 
 **Output:**
 
 | Field | Type | Description |
 |---|---|---|
-| `success` | boolean | `true` if the deletion was successful. |
+| `deleted` | boolean | `true` if the deletion was successful. |
 | `uid` | number | The IMAP UID of the deleted message. |
 
+**Authentication:** Credentials are provided via the step-level `credential` field.
+
 **Example:**
 
 ```yaml
@@ -430,7 +433,6 @@ Adds or removes flags (labels) on an email message.
 | `flags` | array | Yes | List of flag names to modify (e.g., `["flagged", "important"]`). |
 | `action` | string | Yes | `add` to set flags, `remove` to unset flags. |
 | `folder` | string | No | Folder containing the message. Default: `INBOX`. |
-| `_credential` | string | Yes | Email account credential. |
 
 **Standard IMAP Flags:**
 
@@ -448,10 +450,13 @@ Adds or removes flags (labels) on an email message.
 
 | Field | Type | Description |
 |---|---|---|
-| `success` | boolean | `true` if the flag operation was successful. |
+| `updated` | boolean | `true` if the flag operation was successful. |
+| `action` | string | The operation performed: `add` or `remove`. |
 | `uid` | number | The IMAP UID of the message. |
 | `flags` | array | The flags that were modified. |
 
+**Authentication:** Credentials are provided via the step-level `credential` field.
+
 **Example:**
 
 ```yaml
@@ -739,7 +744,6 @@ Runs browser automation scripts (JavaScript, TypeScript, or Python) using Playwr
       import os
       import json
 
-      page = browser.new_page()
       page.goto('https://example.com/report')
       page.pdf(path='/mantle/artifacts/report.pdf')
 

site/src/content/docs/workflow-reference/index.md

@@ -253,7 +253,7 @@ steps:
 
 ### Available Error Fields
 
-- **`steps['name'].error`** — `null` for successful or skipped steps; a string error message for failed steps. Available for all steps regardless of `continue_on_error`.
+- **`steps['name'].error`** — `null` for successful or skipped steps; a string error message for failed steps. The field is always present in the CEL context, but is only practically reachable on a step that has `continue_on_error: true` — without that flag, a step failure halts the workflow before any downstream step can inspect the error.
 - **`steps['name'].output`** — Partial output available from the failed step if the connector provided it. Structure depends on the connector.
 
 ### Example: Fallback Pattern
@@ -355,9 +355,13 @@ Triggers are optional. Without them, the workflow can still be executed manually
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `type` | string | Yes | Trigger type. One of: `cron`, `webhook`. |
+| `type` | string | Yes | Trigger type. One of: `cron`, `webhook`, `email`. |
 | `schedule` | string | Cron only | Cron expression defining the schedule. Required when `type` is `cron`. |
 | `path` | string | Webhook only | URL path for the webhook endpoint. Required when `type` is `webhook`. |
+| `mailbox` | string | Email only | Credential name for the email account (IMAP-compatible). Required when `type` is `email`. |
+| `folder` | string | Email only | Folder to monitor (e.g., `INBOX`). Default: `INBOX`. |
+| `filter` | string | Email only | Filter messages: `all`, `unseen`, `recent`, `flagged`. Default: `unseen`. |
+| `poll_interval` | string | Email only | How often to check for new messages (e.g., `30s`, `5m`). Default: `60s`. |
 
 ### Trigger Lifecycle