arcane-os 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.24.1
+
+- Add a mail CLI parameter table with command scope, purpose, and defaults.
+  Explain the difference between `--app`, `X-Mail-App`, `--report-stdin`, and
+  the nonsecret `--report-key` used for intentional same-message retries.
+- Remove redundant default-profile configuration and the alternate-account
+  placeholder from the main mail example. Align the CLI reference with the
+  shared configuration and credential files while preserving named-profile APIs.
+- Clarify when subscription headers are required, how ordinary delivery failures
+  retain their existing report, and the separate browser callback and verification
+  service paths that can create feedback. Runtime behavior is unchanged.
+
+## 0.24.0
+
+- Read nonsecret mail settings from `arcane.config.json.mail` and provider keys
+  from `.arcane.env.json.mail`. Keep existing root keys, exact named profiles,
+  and TLS path settings working without migrating or rewriting either file.
+- Let explicit CLI/API options override configuration, replace origin lists,
+  and apply listener defaults after file settings. Share configured profile,
+  sender and provider deadlines with `mail send` without requiring TLS paths.
+- Preserve unrelated settings during credential updates and remove both selected
+  key representations on explicit deletion. Document configuration precedence,
+  origin rejection, startup, platform behavior and the purpose-gate review.
+
 ## 0.23.0
 
 - Rename the mail configuration file to `.arcane.env.json`. Upgrade existing

package/README.md

@@ -19,15 +19,17 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.23.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.24.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
-The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433,
-using certificate paths from `.arcane.env.json` in the command's working
-directory, and defaults browser mail to
-`/v1/mail` on the current domain. Multiple applications can share
-one server with explicit allowed origins. Subscription verification is disabled
+The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433
+by default. Configure its host, port, origin list, certificate paths, and other
+mail settings in `arcane.config.json.mail`; keep provider keys in the ignored
+`.arcane.env.json.mail`. Both files belong in the command's working directory.
+Existing root credential, profile, and TLS settings remain supported. Browser
+mail defaults to `/v1/mail` on the current domain, and multiple applications can
+share one server with explicit allowed origins. Subscription verification is disabled
 until a `verifySubscription` callback is configured; that callback receives the
 application name and bearer subscription key before each provider attempt.
 See the [method and action gate report](docs/reviews/mail-server-purpose-review.md)

package/docs/reference/cli.md

@@ -812,10 +812,13 @@ npm exec -- arcane repo status
 
 ## `arcane mail`
 
-### Resend credential profiles
+### Configuration and provider credentials
 
-The mail commands read `.arcane.env.json` from the invocation directory on Windows,
-Linux, and macOS. The credential subcommands select one profile in that file:
+Mail reads nonsecret settings from `arcane.config.json.mail` and the Resend key
+from `.arcane.env.json.mail.apiKey` in the invocation directory on Windows,
+Linux, and macOS. See [Mail CLI parameters](mail.md#mail-cli-parameters) for the
+complete parameter, configuration-field, default, and precedence reference.
+The credential subcommands manage the provider key:
 
 ```text
 arcane mail key set [profile] [--secret-stdin]
@@ -826,26 +829,43 @@ arcane mail key delete [profile]
 `key set` reads the Resend API key from a hidden terminal prompt. The
 `--secret-stdin` form is for deliberately redirected non-interactive input and
 rejects a TTY before reading. The key is written to `.arcane.env.json` and is never
-accepted in argv or returned in status output. The optional profile defaults
-to `mail`, which selects top-level `RESEND_API_KEY`. Any other exact profile
-selects `MAIL_PROFILES[profile].RESEND_API_KEY`, with no default-key fallback.
+accepted in argv or returned in status output. The optional credential-command
+profile defaults to `mail`, independently of the send/serve configuration.
 
-The minimal file is:
+The minimal `.arcane.env.json` is:
 
 ```json
 {
-  "RESEND_API_KEY": ""
+  "mail": {
+    "apiKey": ""
+  }
 }
 ```
 
 Fill in the key before starting mail, and add `.arcane.env.json` to the project's
-`.gitignore`; the SDK repository already ignores it. Set and delete preserve
-the file's other settings and profiles. Status returns the selected profile,
+`.gitignore`; the SDK repository already ignores it. Keep nonsecret listener
+settings, including certificate file paths, in `arcane.config.json.mail`.
+
+Named profiles remain an optional CLI/toolchain compatibility feature for
+selecting another stored Resend key. An exact name selects
+`mail.profiles[name].apiKey`; the name is independent of incoming application
+names, domains, and subscription keys. One server process uses one selected
+Resend key for all its requests. An absent named key never falls back to the
+default account. Existing root `RESEND_API_KEY` and
+`MAIL_PROFILES[name].RESEND_API_KEY` remain fallbacks when the corresponding
+nested key property is absent. A nested property containing null or an empty
+string means the selected key is absent and takes precedence over a legacy key.
+
+Set and delete preserve the file's other settings and profile containers. New
+keys are written to the nested mail member. Existing legacy keys are updated
+in place unless the selected nested key property exists; delete removes both
+representations of only the selected key. Status returns the selected profile,
 `provider:'resend'`, `storage:'.arcane.env.json'`, and `exists`. Delete returns
 `exists:false` for both a removed and an already-absent credential.
 
-Programmatic `createToolchain().mail(...)` resolves the configuration directory
-from `cwd ?? workspaceRoot ?? process.cwd()`. This uses ordinary Node file
+Programmatic `createToolchain().mail(...)` resolves both files from the directory
+selected by `cwd ?? workspaceRoot ?? process.cwd()`, with no upward search.
+This uses ordinary Node file
 access rather than platform-specific credential processes. An Android host
 supplies a compatible Node runtime and an accessible configuration directory.
 Existing Windows Credential Manager records remain untouched; the JSON reader
@@ -854,11 +874,13 @@ populate or depend on process environment variables for this key.
 
 The SDK's installation directory does not affect this location. With an SDK
 under `my-site/arcane-os-sdk/`, run the command from `my-site/` and keep
-`my-site/.arcane.env.json` alongside that directory. Existing deployments using
+`my-site/arcane.config.json` and `my-site/.arcane.env.json` alongside that
+directory. Existing deployments using
 SDK 0.22.1 or earlier must rename `.env.json` to `.arcane.env.json` while
 preserving its contents; the loader reads only the new name.
 
-Missing files or missing/empty selected keys stop `send` and `serve` with the
+Each file is an optional configuration source. Missing or empty selected keys
+stop `send` and `serve` with the
 configuration path and exact JSON setting to fill in. Invalid JSON and file
 access failures remain observable without printing credential content.
 
@@ -890,11 +912,16 @@ shape:
 
 The CLI forwards the complete provider fields, including template requests.
 Resend owns their accepted shape. The adapter removes the application-only
-`type` field and applies `--from` when supplied; otherwise the report or provider
-template supplies the sender. Direct CLI sending has
-no configured fallback recipients. The Resend credential comes only from the
-selected `.arcane.env.json` profile; omitting `--profile` selects `mail`. Neither the
-key nor report content is accepted through argv or process environment variables.
+`type` field and applies the shared sender from `--from` or `mail.from` when
+supplied; otherwise the report or provider template supplies the sender. Direct
+CLI sending has no configured fallback recipients and requires no listener TLS
+paths. It consumes the configured provider timeout and retry guidance.
+
+The Resend credential comes from the selected `.arcane.env.json` entry.
+An explicit `--profile` overrides `arcane.config.json.mail.profile`; omitting
+both selects the default `mail.apiKey`, with the legacy fallback described
+above. Neither the key nor report content is accepted through argv or process
+environment variables.
 
 The caller owns the nonempty `--report-key`, which is forwarded unchanged.
 Reuse the same key only with the same
@@ -918,22 +945,28 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 4433] [--request-timeout <ms>]
 ```
 
-The selected `.arcane.env.json` profile supplies only the server-side Resend API key;
-omitting `--profile` selects `mail`.
+The selected `.arcane.env.json` entry supplies only the server-side Resend API
+key. An explicit `--profile` overrides `arcane.config.json.mail.profile`;
+omitting both selects the default key.
 
-Add the listener's certificate configuration at the top level of the same file:
+Add the listener's certificate paths to `arcane.config.json`:
 
 ```json
 {
-  "RESEND_API_KEY": "",
-  "MAIL_TLS_CERT_PATH": ".arcane/mail/fullchain.pem",
-  "MAIL_TLS_KEY_PATH": ".arcane/mail/private-key.pem"
+  "mail": {
+    "certPath": ".arcane/mail/fullchain.pem",
+    "keyPath": ".arcane/mail/private-key.pem"
+  }
 }
 ```
 
 Supply an existing PEM certificate chain and its private key. Paths resolve
-relative to `.arcane.env.json`, or may be absolute. They are shared across provider
-profiles. Missing TLS settings name the fields to fill in before a listener
+relative to the selected configuration directory, or may be absolute. They
+belong to the listener regardless of the provider key selected. Legacy root
+`MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` in `.arcane.env.json` remain
+fallbacks for omitted config paths. Explicit programmatic `certPath` and
+`keyPath` options override those files. Missing TLS settings name the fields
+to fill in before a listener
 opens; the TLS owner reports PEM file errors. Keep private-key material outside
 tracked source. The SDK repository already ignores `.arcane/` and `.arcane.env.json`.
 
@@ -949,7 +982,7 @@ server; the incoming request's `X-Mail-App` identifies the application for
 subscription verification. The HTTP authentication contract pairs that
 application with `Authorization: Bearer <subscription_key>`.
 
-Subscription verification is disabled for this initial service setup. The
+Subscription verification is disabled when no callback is configured. The
 programmatic `createToolchain().mail({action: 'serve', ...})` path accepts
 `verifySubscription({appName, subscriptionKey, signal})`; supplying that callback
 enables verification before each provider attempt. It must resolve to `true`
@@ -958,16 +991,27 @@ failure receives retryable 503; cancellation stops verification before sending.
 The callback connects the actual TWiN Stripe endpoint when its contract is
 ready. There is no guessed URL, response schema, or command-line endpoint flag.
 
-The listener defaults to `0.0.0.0`; `--host` selects another bind host. Browser
-mail defaults to `/v1/mail` on the current domain. `--origin` is optional and
-selects an explicit CORS allowlist when supplied. `--allow-to` optionally
-supplies a comma-separated recipient allowlist. CLI parsing preserves supplied
-address spelling and repeated entries. Programmatic `errorTo` selects fallback
-recipients for error reports; when omitted, the selected `allowTo` list supplies
-that fallback. `--request-timeout`
-adds a caller-selected provider-attempt timeout from 1 through 2147483647
-milliseconds, the Node timer range. When it is omitted, the SDK adds no
-provider timeout.
+The listener defaults to `0.0.0.0:4433`; `mail.host` and `mail.port` configure
+the listener, and explicit `--host` and `--port` override them. Browser mail
+defaults to `/v1/mail` on the current domain. `mail.origins` supplies an exact
+origin array; `--origin` replaces it with one origin. Repeated `--origin`
+options keep the last value. An absent or empty list selects the current
+request authority. Other Origins receive `403 mail_origin_not_allowed`;
+requests without an Origin continue normally. This CORS configuration does
+not filter client IPs or give loopback special treatment.
+
+`mail.recipientAllowlist` supplies the recipient list; `--allow-to` replaces it
+with a comma-separated list. CLI parsing preserves supplied address spelling
+and repeated entries. Programmatic `errorTo` or `mail.errorRecipients` selects
+fallback recipients for error reports. When neither is supplied, the effective
+recipient allowlist supplies that fallback; an explicit empty array supplies
+none. The [Mail CLI parameters](mail.md#mail-cli-parameters) reference also
+documents programmatic aliases and list-replacement precedence.
+
+`--request-timeout` overrides `mail.providerTimeoutMs` and accepts 1 through
+2147483647 milliseconds, the Node timer range. An absent effective timeout
+adds no provider deadline; programmatic/configured null also selects no
+deadline. `mail.bodyTimeoutMs` selects the optional request-body deadline.
 
 After binding, `server.ready` reports lifecycle fields such as
 protocol, optional app label, bind address, port, URL, and `callerAuthentication`

package/docs/reference/mail.md

@@ -272,51 +272,154 @@ committed acceptance result.
 
 ## Operate the CLI and gateway
 
-Create `.arcane.env.json` in the directory from which the mail command runs, then fill
-in the provider key and the HTTPS certificate paths:
+### Mail CLI parameters
+
+`mail serve` starts the shared mail server. `mail send` makes one direct Resend
+request. `mail key set|status|delete` manages the provider credential.
+
+| Parameter | Command | What it does | When omitted |
+| --- | --- | --- | --- |
+| `--app <label>` | `mail serve` | Supplies a fallback application label for server events. An incoming `X-Mail-App` supplies the request's label. This option does not choose a Stripe account or limit which apps may send mail. | Uses `mail.appId` when configured; otherwise adds no fallback label. |
+| `--from <sender>` | `mail serve`, `mail send` | Overrides the sender, for example `"Dragon Dispatch <dispatch@example.com>"`. On the server, the override applies to every report. Resend must accept that sender. | Uses `mail.from` when configured, then the report's `from` or provider template default. |
+| `--report-stdin` | `mail send` | Reads one complete UTF-8 report JSON object from redirected standard input, including recipients, subject, body, and other provider fields. | Required; the command reports a usage error. |
+| `--report-key <id>` | `mail send` | Identifies one intended email and is forwarded unchanged as Resend's `Idempotency-Key`. Use a new value for a new email; reuse the value and unchanged report for an intentional retry. It is not a credential. | Required; the command reports a usage error. |
+| `--host <address>` | `mail serve` | Selects the listener bind address. `0.0.0.0` accepts connections through all IPv4 interfaces. | Uses `mail.host`, then `0.0.0.0`. |
+| `--port <number>` | `mail serve` | Selects the HTTPS listener port. Explicit `0` asks the operating system for an available port. | Uses `mail.port`, then `4433`. |
+| `--origin <origin>` | `mail serve` | Replaces the configured CORS origins with one exact browser origin, including scheme and any nondefault port. Use the JSON `origins` array for multiple origins; repeated flags keep only the last value. | Uses `mail.origins`; an absent or empty list uses the current request authority. Requests without an `Origin` header continue normally. |
+| `--allow-to <addresses>` | `mail serve` | Replaces the recipient allowlist with a comma-separated list. Applies to `to`, `cc`, and `bcc`, and supplies error-report fallback recipients unless `mail.errorRecipients` is configured separately. | Uses `mail.recipientAllowlist`; an absent or empty list leaves recipients unrestricted. |
+| `--request-timeout <ms>` | `mail serve`, `mail send` | Sets the deadline for one Resend request, in milliseconds. A timeout after sending begins leaves delivery uncertain; it does not schedule a retry. | Uses `mail.providerTimeoutMs`; absent or null adds no provider deadline. |
+| `--profile <name>` | `mail serve`, `mail send` | Selects an alternate saved Resend credential for this invocation. One listener uses that selected provider key for all callers. | Uses `mail.profile` if configured, otherwise the normal `mail.apiKey`. The single-key setup needs no profile setting. |
+| `[profile]` | `mail key set\|status\|delete` | Optional positional name of the credential to manage; it is not a flag. | Manages the normal `mail.apiKey`, independently of `mail.profile`. |
+| `--secret-stdin` | `mail key set` | Reads the Resend API key from deliberately redirected standard input instead of the hidden terminal prompt. | Prompts with hidden input. Machine-output mode requires redirected input. |
+| `--output human\|json\|ndjson` | All mail commands | Selects readable console output, one JSON result, or newline-delimited JSON events. | Uses `human`. |
+| `--help` | CLI | Displays CLI help instead of running the mail operation. | Runs the requested operation. |
+| `--version` | CLI | Displays the SDK version instead of running the mail operation. | Runs the requested operation. |
+
+There is no `--report` flag. `--report-stdin` supplies the message;
+`--report-key` identifies that same message across attempts. Browser `Mail.send()`
+generates and retains its report key automatically.
+
+Mail reads configuration from the directory in which the command runs;
+`--workspace` does not relocate these mail files. Mail HTTPS uses `mail.certPath`
+and `mail.keyPath` in JSON. The `--cert`, `--key`, `--https`, and `--http-port`
+flags belong to browser `dev`/`run`, and `--http` belongs to `dev`.
+
+### Mail configuration
+
+Keep app-supplied SDK settings under named capability members, starting with
+`mail`. Put the nonsecret mail settings in `arcane.config.json` in the directory
+from which the command runs:
 
 ```json
 {
-  "RESEND_API_KEY": "",
-  "MAIL_TLS_CERT_PATH": "",
-  "MAIL_TLS_KEY_PATH": ""
+  "mail": {
+    "host": "0.0.0.0",
+    "port": 4433,
+    "origins": [
+      "https://dragons.example",
+      "https://www.dragons.example"
+    ],
+    "certPath": "certificates/fullchain.pem",
+    "keyPath": "certificates/private-key.pem"
+  }
 }
 ```
 
-The SDK repository ignores `.arcane.env.json`. Keep the same entry in a consuming
-project's `.gitignore`. This is a JSON configuration file; the mail commands
-read it directly without copying its contents into `process.env`.
-
-The default profile is `mail`, which selects top-level `RESEND_API_KEY`.
-The explicit `--profile mail` form selects the same setting. Other profile names
-select exact entries under `MAIL_PROFILES`:
+Put the Resend provider key in the separate `.arcane.env.json`:
 
 ```json
 {
-  "RESEND_API_KEY": "",
-  "MAIL_PROFILES": {
-    "another-provider-account": {
-      "RESEND_API_KEY": ""
-    }
+  "mail": {
+    "apiKey": ""
   }
 }
 ```
 
-An absent named profile does not fall back to the default key. The profile
-selects Resend provider credentials; it is separate from the incoming
-application name and subscriber key.
+The SDK repository ignores `.arcane.env.json`. Keep the same entry in a consuming
+project's `.gitignore`. `arcane.config.json` contains settings suitable for source
+control; its certificate fields contain file paths, never PEM contents or provider
+keys. Both files are read directly as JSON without copying values into
+`process.env`. Other top-level capability members remain untouched. The portable
+browser `arcane-os/mail` import does not read these Node-side files.
+
+The supported `arcane.config.json.mail` fields are:
 
-Programmatic operations resolve `.arcane.env.json` from `options.cwd`, then
+| Field | Type | Purpose and default |
+| --- | --- | --- |
+| `host` | string | Listener bind address; defaults to `0.0.0.0`. |
+| `port` | integer | Listener port; defaults to `4433`. Explicit `0` selects an available port. |
+| `origins` | string array | Exact allowed browser origins. An absent or empty list uses the current request authority as described below. |
+| `profile` | string | Resend credential profile for send/serve; defaults to `mail`. |
+| `from` | string | Optional shared sender override. Omit it to retain each report's sender or provider template default. |
+| `appId` | string | Optional server event label; does not restrict incoming application names. |
+| `recipientAllowlist` | string array | Optional allowed recipients; absent or empty means unrestricted recipients. |
+| `errorRecipients` | string array | Error-report fallback recipients; defaults to the effective recipient allowlist. An explicit empty array supplies no fallback. |
+| `bodyTimeoutMs` | integer or null | Optional request-body deadline in milliseconds; absent or null adds no deadline. |
+| `providerTimeoutMs` | integer or null | Optional provider deadline in milliseconds; absent or null adds no deadline. |
+| `retryableDelayMs` | positive integer | Retry guidance in a retryable result; defaults to `1000`. It does not schedule a retry. |
+| `certPath` | string | PEM certificate-chain file path, required for gateway HTTPS. |
+| `keyPath` | string | PEM private-key file path, required for gateway HTTPS. |
+
+Resend is the supported provider; no provider selector is needed. Keep callbacks,
+injected providers, `fetchImpl`, `onEvent`, `requestIdFactory`,
+`verifySubscription`, and `AbortSignal` values in programmatic options. They are
+runtime inputs, not JSON settings. Reports and their idempotency keys remain
+inputs to each send operation.
+
+The single-key configuration above needs no `profile` or `profiles` member.
+Omitting the selection uses `.arcane.env.json.mail.apiKey`; multiple apps and
+domains can share that provider key.
+
+For callers that already select an alternate credential, named-profile support
+remains available: `--profile <name>` or `mail.profile` selects
+`.arcane.env.json.mail.profiles[name].apiKey`. An absent named profile does not
+fall back to the default key. Selection happens once when send or serve starts;
+it does not map incoming apps or domains to different provider accounts.
+The profile selects Resend provider credentials, separately from the incoming
+application name and subscriber key. Existing top-level `RESEND_API_KEY` and
+`MAIL_PROFILES[profile].RESEND_API_KEY` remain supported. A nested selected
+`apiKey` takes precedence when the property exists, including null or an empty
+string, which means the selected key is absent. Only an absent nested key
+property permits fallback to the corresponding legacy key.
+
+Programmatic operations resolve both files from `options.cwd`, then
 `options.workspaceRoot`, then `process.cwd()`, choosing the first supplied
 directory. The CLI uses its invocation directory. There is no upward directory
 search or dependency on a Windows installation directory or temporary-directory
-environment variable.
+environment variable. Missing files are optional configuration sources; send and
+serve still report their missing required values before attempting delivery or
+binding. Malformed or unreadable files produce an error.
+
+Configuration precedence is explicit:
+
+1. A CLI/API option overrides its file setting when its value is not `undefined`.
+   An explicit null retains the option's existing meaning; it does not select
+   the file value again.
+2. `arcane.config.json.mail` supplies nonsecret settings absent from those options.
+3. Legacy `.arcane.env.json` root `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH`
+   supply certificate paths absent from the selected options and config member.
+4. Remaining settings use the defaults above.
+
+The existing programmatic aliases `origin`, `allowTo`, `errorTo`, and
+`requestTimeout` take precedence over their corresponding canonical options
+`origins`, `recipientAllowlist`, `errorRecipients`, and `providerTimeoutMs` when
+both are supplied. The CLI continues to expose `--origin`, `--allow-to`, and
+`--request-timeout`. `origin` accepts a string or an array; the recipient aliases
+accept address arrays or comma-separated strings. Lists replace the lower-priority
+list completely. The configuration reader does not concatenate or deduplicate
+lists, rewrite case, or automatically add local addresses.
+
+Use the JSON `origins` array for multiple origins. Repeating the current
+`--origin` option keeps only its last value; there is no `--origins` CLI option.
+The CLI leaves omitted host, port, and send/serve profile options unset until
+configuration resolves, so its defaults do not mask file settings.
 
 Keep the configuration in the deployment directory even when the SDK is nested
 below it:
 
 ```text
 my-site/
+├── arcane.config.json
 ├── .arcane.env.json
 └── arcane-os-sdk/
     └── bin/arcane.mjs
@@ -325,13 +428,15 @@ my-site/
 Run from `my-site`, for example:
 
 ```sh
-node ./arcane-os-sdk/bin/arcane.mjs mail serve --port 4433
+node ./arcane-os-sdk/bin/arcane.mjs mail serve
 ```
 
 The SDK directory does not choose the configuration location. When upgrading
 from SDK 0.22.1 or earlier, rename the existing `.env.json` to
 `.arcane.env.json` in the invocation directory, preserving its contents.
-The loader reads only `.arcane.env.json`.
+The secret loader reads only `.arcane.env.json`; it does not read the old filename.
+Existing root key, profile, and TLS fields can remain in that file. Adopting the
+capability members does not perform an automatic rewrite or migration.
 
 The existing key commands manage the same file:
 
@@ -343,8 +448,14 @@ arcane mail key delete
 
 `key set` prompts with hidden input. `--secret-stdin` is the explicit
 non-interactive alternative and rejects a TTY. Each command accepts an optional
-profile argument, defaulting to `mail`. Set and delete preserve other JSON
-settings and profiles; status reports existence without returning the key.
+profile argument, defaulting to `mail` independently of `arcane.config.json.mail.profile`.
+Set and delete preserve other JSON settings and profiles; status reports
+existence without returning the key. A new credential is written to the nested
+mail member. An existing legacy credential is updated at its existing location
+unless the selected nested key property exists, in which case set updates that
+nested property. Delete removes both representations of only the selected key,
+so an older key cannot reappear through fallback. Other settings and profile
+containers remain intact.
 Results identify `storage: '.arcane.env.json'`. An already-absent deletion succeeds
 with `exists: false`.
 
@@ -363,8 +474,8 @@ arcane mail send --from "Arcane <verified@example.com>" --report-key <stable-id>
 The redirected UTF-8 JSON object is read completely. Its fields and values
 are retained; the Resend adapter removes the SDK's `type` routing field,
 uses `from` when configured (otherwise the report or provider template supplies
-the sender), and applies configured error-recipient fallback
-when applicable. Resend evaluates its own required provider fields. Message
+the sender). Direct sending supplies no fallback recipients. Resend evaluates
+its own required provider fields. Message
 content is not accepted in argv. Programmatic results and observer events
 preserve the complete report, provider request, provider response, and error detail while
 never exposing either credential.
@@ -379,19 +490,28 @@ cancellation after the provider attempt begins is returned as an ambiguous
 nonzero outcome because the provider may already have accepted the request.
 Cancellation before the attempt exits 130 without sending.
 For both CLI mail operations, `--request-timeout` accepts 1 through 2147483647
-milliseconds, the Node timer range. When omitted, the SDK adds no provider
-deadline.
+milliseconds, the Node timer range. The same range applies to configured body
+and provider deadlines. When no provider timeout is selected in options or
+configuration, the SDK adds no provider deadline.
+
+`mail send` consumes the selected profile, sender, provider timeout, and retry
+guidance from the same configuration. It does not require gateway TLS paths.
+Send and serve read each required JSON file once, concurrently when both are
+needed, before consuming their settings. An injected `readCredential` remains
+the credential owner and reads once. With that injection, send reads only
+`arcane.config.json`; serve also reads `.arcane.env.json` for legacy TLS paths
+without interpreting its unused file credential.
 
 Start the gateway:
 
 ```text
-npm exec -- arcane mail serve --profile mail --host 0.0.0.0 --port 4433
+npm exec -- arcane mail serve
 ```
 
-The default listener is `0.0.0.0:4433`; `--host` and `--port` select its bind
-address and port. The server can serve callers from multiple domains on the
-same machine. Route the page's `/v1/mail` to this listener, or configure an
-explicit shared endpoint in the caller.
+The default listener is `0.0.0.0:4433`; `mail.host` and `mail.port` select its
+configured bind address and port, and explicit `--host` / `--port` override them.
+The server can serve callers from multiple domains on the same machine.
+Configure the caller's endpoint to reach that listener.
 
 `mail serve` uses HTTPS with HTTP/2 on that selected port. The published
 `node-http-server` PEM API owns TLS and negotiates HTTP/2 or HTTP/1.1 on the
@@ -399,25 +519,29 @@ same listener. It creates no additional plain-HTTP listener. The returned URL
 uses `https://`; `0.0.0.0` is the bind address, so callers use the deployed
 domain, for example `https://mail.example.com:4433/v1/mail`.
 
-Set `MAIL_TLS_CERT_PATH` to the PEM certificate chain and `MAIL_TLS_KEY_PATH`
-to its PEM private-key file. These top-level settings belong to the listener
-and apply regardless of the selected provider profile. Relative paths resolve
-from the directory containing `.arcane.env.json`; absolute paths are also accepted.
+Set `arcane.config.json.mail.certPath` to the PEM certificate chain and
+`mail.keyPath` to its PEM private-key file. These settings belong to the listener
+and apply regardless of the selected provider profile. The legacy root
+`MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` fields in `.arcane.env.json` remain
+fallbacks. Relative certificate paths resolve from the selected configuration
+directory, including explicit programmatic path options; absolute paths are also accepted.
 The certificate must cover the hostname callers use. One certificate may
 cover multiple names; the gateway does not require one certificate per calling
 application. Keep private-key files outside tracked source, such as in the
 already-ignored `.arcane/` directory or an existing host certificate directory.
 
-Startup reads the JSON configuration once, reports missing TLS settings before
+Startup reads each JSON file once, reports missing TLS settings before
 binding, and lets the TLS owner report unreadable or unusable PEM files. It
 does not generate certificates, modify system trust, or add a renewal watcher.
+No JSON configuration file is reread for an incoming HTTP request.
 Restart the gateway after the configured certificate files are renewed.
 The same Node file and TLS APIs are used on Windows, Linux, and macOS; Android
 requires a compatible Node host and accessible configuration and certificate
 paths. These platform contracts are separate from actual platform execution.
 
 The public `createToolchain().mail({action: 'serve', ...options})` operation
-uses the same JSON certificate pair. Internally, `startResendMailServer` accepts
+uses the same settings with explicit options taking precedence. Internally,
+`startResendMailServer` accepts
 `certPath` and `keyPath` and retains its existing HTTP behavior when neither
 is supplied. That internal function is not an npm package export.
 
@@ -429,18 +553,25 @@ The existing listener remains running; this launch does not retry or select
 another port.
 
 `--app` is an optional server event label and does not restrict incoming
-application names. `--from` is an optional shared sender override; omit it to
-preserve each report's sender or its provider template's default.
-`--origin` selects an exact allowed caller origin; the
-programmatic `origin` option also accepts an array for multiple origins. With
-no origins configured, the gateway accepts an Origin matching its request
+application names. `--from` and `mail.from` are optional shared sender overrides;
+omit both to preserve each report's sender or its provider template's default.
+`mail.origins` supplies an array of exact allowed caller origins. An explicit
+`--origin` replaces that array; the programmatic `origin` alias also accepts an
+array. With no origins configured, the gateway accepts an Origin matching its request
 authority (`:authority` for HTTP/2, `Host` for HTTP/1.1) using HTTP or HTTPS.
-Requests without Origin continue normally.
+An Origin outside the configured list or current-authority default receives
+`403 mail_origin_not_allowed`. Origin strings are compared exactly: include the
+scheme and any nondefault port, with no path or trailing slash. There are no
+wildcards, subdomain expansion, normalization, or loopback exceptions.
+Requests without an `Origin` header continue normally. This is a declared-origin
+CORS list, not a client-IP or connecting-machine allowlist; ordinary
+server-to-server requests commonly omit Origin.
 Cross-origin preflight permits `Content-Type`, `Idempotency-Key`, `X-Mail-App`,
-and `Authorization`. This is origin configuration, not a loopback policy.
+and `Authorization`.
 
-`--allow-to` explicitly limits recipients when supplied. With it omitted, the
-gateway imposes no recipient allowlist. When configured, the list applies to
+`mail.recipientAllowlist` or explicit `--allow-to` limits recipients when
+configured. An absent or empty effective list imposes no recipient allowlist.
+When configured, the list applies to
 every recipient in the resolved `to`, `cc`, and `bcc` fields, whether supplied
 as a string or an array. Sender, recipient, subject, and body
 values are not trimmed, lowercased, or filtered by an SDK email grammar at
@@ -473,6 +604,12 @@ key, and `signal` follows the request lifecycle. These control fields stay
 separate from the mail report and Resend payload. The verifier runs for each
 POST request before any provider attempt; results are not cached.
 
+`X-Mail-App` identifies the originating app so the verifier can select that
+app's subscription account, such as the appropriate Stripe account for `BOSS`
+or `TWiN`. It is separate from the gateway's optional `--app` event label.
+The missing-header and Bearer errors below apply only when `verifySubscription`
+is configured. Ordinary `mail serve` does not require either header.
+
 | Configured-verifier outcome | Gateway response |
 | --- | --- |
 | Missing or empty `X-Mail-App` | `400 mail_invalid_headers` |
@@ -496,6 +633,32 @@ CLI startup output says `Subscription verification: disabled` or
 `Subscription verification: configured`. Structured `server.ready` output
 includes the corresponding `callerAuthentication` value.
 
+## Error reports and retries
+
+An incoming report with `type: 'error'` is an email supplied by its caller.
+The gateway's `errorRecipients` setting only supplies fallback recipients for
+that report when its `to` array is empty. A gateway or provider failure returns
+an HTTP error and diagnostic events; it does not generate another error email.
+Gateway event-handler failures are written to the console. Each POST and each
+direct CLI send performs at most one provider attempt, with no automatic server retry.
+
+The browser outbox retains the same report and key after a retryable delivery
+failure. Each drain attempts each eligible record once; a later startup,
+connectivity event, or explicit drain can retry it. Browser `Errors` notification
+failure retains the same pending occurrence and logs a warning without scheduling
+itself again.
+
+A separate browser callback path can feed back into error reporting: a mail-event
+subscriber that repeatedly throws can reach global error capture, create another
+error report, and trigger another mail event. Subscriber failures cannot change
+an already committed mail result, though global capture can report them as new
+errors. This is a source-level possibility, not evidence of a deployed loop.
+
+For a verification service that sends its own emails, its host integration must
+also avoid the circular request path `mail -> verify subscription -> send mail ->
+verify subscription`. The SDK supplies a callback for verification; it does not
+choose that service's caller flow or enable it in ordinary CLI startup.
+
 ## Gateway request lifecycle
 
 The gateway uses the published `node-http-server` instance lifecycle. Its raw

package/docs/reviews/mail-server-purpose-review.md

@@ -457,3 +457,87 @@ payloads, profiles, other settings and lifecycle remain unchanged.
 
 Existing credential and CLI test fixtures now use the selected name. Source
 and diff were reviewed; local tests, checks and server execution were not run.
+
+## Capability configuration and secret separation follow-up
+
+The selected outcome is one app-authored mail configuration in
+`arcane.config.json.mail`, with Resend credentials in ignored
+`.arcane.env.json.mail`. The SDK owns reading and applying these settings through
+the existing CLI/toolchain mail operation. Domains, senders, certificates, and
+provider accounts remain deployment-owned data. This increment begins the
+named-capability configuration convention with mail; it does not migrate other
+capabilities or consumer files.
+
+The source audit found no existing `arcane.config.json` reader to reuse. The
+workspace loader owns `arcane-packager.json`, descriptors, and application
+layout. Requiring that loader to start a mail listener would add unrelated work.
+The existing mail JSON reader is the reusable boundary for the two selected
+files. Their explicit precedence and credential compatibility rules are in the
+[mail reference](../reference/mail.md#operate-the-cli-and-gateway).
+
+| Method or action | Gates | Decision, callers, and concrete purpose |
+| --- | --- | --- |
+| `readMailConfiguration` | Y/Y/N | Keep the cohesive configuration at the SDK owner. Send/serve read each required file once, in parallel when both are needed. A send with an injected credential reader skips the unused secrets file; incoming HTTP requests use the resolved configuration without file reads. Other capability settings stay untouched. |
+| CLI's early default host, port, and send/serve profile values | Y/Y/Y | Remove premature default assignment. The same defaults remain after file configuration resolves, while explicit CLI values retain priority. Assigning defaults before reading JSON would conceal the deployment's chosen settings. |
+| `origins` string array and list replacement | Y/Y/N | Keep one exact list for multiple caller domains. Explicit options replace the file list, including empty arrays. Existing `origin`, `allowTo`, `errorTo`, and `requestTimeout` aliases remain compatible and win over their canonical programmatic names when both are supplied. No normalization or list-merging helper is needed. |
+| Root provider-key, named-profile, and TLS compatibility | Y/Y/N | Preserve supported inputs using `RESEND_API_KEY`, `MAIL_PROFILES`, `MAIL_TLS_CERT_PATH`, and `MAIL_TLS_KEY_PATH`. Nested selected key presence takes priority even when null or empty. Named profiles never select a different account's default key. Named-profile deployment use is unverified; the retained behavior is a compatibility contract. |
+| Key set/status/delete operations | Y/Y/N | Preserve credential management and secret-free status. New keys use the nested member; existing legacy keys are updated in place unless a nested key exists. Delete removes both selected representations to prevent an old credential reappearing, preserving other keys, settings, and profile containers. Key commands still default to `mail` independently of the serving profile. |
+| Send configuration | Y/Y/N | Use the same profile, sender, provider-timeout, and retry-guidance settings for direct sending. A send needs provider authority and its report, so listener certificates remain a serve-only prerequisite. Reports and idempotency keys remain per-operation inputs. |
+| Explicit runtime dependencies and callbacks | Y/Y/N | Preserve `readCredential`, provider injection, observation, cancellation, and subscription callbacks as programmatic inputs. A function or signal is not JSON configuration. The portable browser mail import retains its existing dependency boundary. |
+| Shared sender omission | Y/Y/N | Preserve per-report `from` and provider-template sender selection when no shared override is configured. One listener can therefore serve independent application sender identities. |
+| Origin rejection behavior and explanation | Y/Y/N | Document the existing `403 mail_origin_not_allowed`, exact current-authority default, acceptance without Origin, and absence of IP filtering or loopback exceptions. This clarifies the retained behavior without adding admission policy. |
+| New provider selector, per-field helper hierarchy, consumer parser, CLI-generation layer, automatic migration, watcher, and request-time config reads | N/N/Y | Add none. Resend is the sole implemented provider, the selected settings fit one owner, and existing CLI/API options express overrides. These additions would increase work without changing the requested outcome. |
+
+The operation graph is at most two asynchronous JSON reads and one selected
+credential per send/serve invocation, followed by its existing provider attempt
+or listener lifecycle. A send with an injected credential reader reads only
+`arcane.config.json` and calls that reader once. Key operations retain one
+credential-file read and a write only when
+the requested set/delete needs one. Certificate contents are still loaded by
+the published HTTP server module. No dependency, process, polling loop, cache,
+or application/host fan-out is introduced. These are source-level work counts,
+not measured performance claims.
+
+The compatibility audit traces the CLI into `executeMailCommand`, the public
+`createToolchain().mail(...)` / `executeOperation('mail', ...)` entry points,
+credential CRUD, direct send, and serve. The complete report and provider-result
+paths are preserved. Configuration paths use the same portable Node filesystem
+contract on Windows, Linux, and macOS, with a compatible Node host as the Android
+adaptation. Local tests, checks, server launches, live mail sends, and platform
+execution were not performed by this documentation author. Selected package
+verification and publication outcomes belong to the release owner's delivery
+record.
+
+## Parameter examples and error-report path clarification
+
+The ordinary shared mail server needs one Resend key. Its current-domain
+behavior, origin list, and incoming application/subscription verification do
+not select among provider profiles. A named profile selects one stored key
+for an entire send or server invocation. Source inspection found named CLI and
+toolchain inputs plus synthetic tests; it did not establish a deployment that
+uses named mail profiles.
+
+| Method or action | Gates | Decision, callers, and concrete purpose |
+| --- | --- | --- |
+| Explicit default `profile: 'mail'` in setup examples | N/N/Y | Remove the redundant setting. Omission already selects the default key when no named configuration is supplied. CLI send/serve still honor an explicitly selected profile or `mail.profile`. |
+| Extra `another-provider-account` credential placeholder | N/N/Y | Remove it from ordinary setup. It adds an unused account choice to a one-key configuration. Existing optional named-profile behavior remains documented without presenting another account as a setup requirement. |
+| Named-profile CLI/toolchain capability and credential CRUD | Y/Y/N for compatibility | Retain the supported optional profile argument and exact named-key operations. Concrete application/deployment use is unverified. This is an account-selection contract, separate from removing redundant default arguments; its retention makes no claim that the nominal deployment needs it. |
+| Full CLI parameter explanation | Y/Y/N | Keep one canonical [Mail CLI parameters](../reference/mail.md#mail-cli-parameters) table. The CLI reference links to it and describes the current split configuration, selected values, defaults, aliases, and provider behavior without another competing table. |
+| Claim that mail errors can never produce an error-report loop | N/N/Y | Replace the absolute claim with the source-path qualification below. Ordinary server failures do not send another mail; a repeatedly failing browser event subscriber can produce new global error incidents during error-mail delivery. |
+
+The Node gateway reports ordinary request/provider failures through responses,
+observer results, or its console logger. Its error reporter does not call the
+mail sender. In the browser, `Errors` owns global `error` and
+`unhandledrejection` capture and sends error notifications through Mail. A
+failed notification remains pending with a warning rather than immediately
+creating another notification from that send failure.
+
+There is a separate conditional path: a subscriber that repeatedly throws
+while handling Mail events reaches the event authority's listener-failure
+reporter. In browsers with `reportError`, that failure can become a new global
+error incident. Sending that incident through Mail can invoke the same failing
+subscriber again. A loop therefore depends on that subscriber and the active
+global error handler; it is not an automatic server response to an ordinary
+mail failure. This is a static source-path finding, not an observed production
+incident or an executed reproduction. This documentation clarification changes
+no error, subscription, retry, or delivery behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/cli/main.mjs

@@ -86,7 +86,7 @@ Usage:
   ${CLI_NAME} mail key delete [profile]
   ${CLI_NAME} mail send [--profile <profile>] [--from <address>] --report-key <id> --report-stdin [--request-timeout <ms>]
   ${CLI_NAME} mail serve [--profile <profile>] [--from <address>] [--app <label>] [--origin <origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 4433] [--request-timeout <ms>]
-    HTTPS/HTTP2; .arcane.env.json supplies RESEND_API_KEY, MAIL_TLS_CERT_PATH, and MAIL_TLS_KEY_PATH.
+    HTTPS/HTTP2; arcane.config.json.mail supplies settings; .arcane.env.json supplies keys.
 
 Development:
   --public                      Bind dev to all IPv4 interfaces (0.0.0.0) and print network URLs.
@@ -692,13 +692,13 @@ function operationOptions(command,parsed,cwd){
             return {
                 action:'serve',
                 cwd,
-                profile:values.profile??'mail',
+                profile:values.profile,
                 from:values.from,
                 appId:values.app,
                 origin:values.origin,
                 allowTo:values['allow-to'],
-                host:values.host??'0.0.0.0',
-                port:readPort(values.port,4433),
+                host:values.host,
+                port:readPort(values.port),
                 requestTimeout:readMailRequestTimeout(values['request-timeout']),
             };
         }
@@ -721,7 +721,7 @@ function operationOptions(command,parsed,cwd){
             return {
                 action:'send',
                 cwd,
-                profile:values.profile??'mail',
+                profile:values.profile,
                 from:values.from,
                 reportKey:values['report-key'],
                 reportStdin:true,

package/src/mail-credentials.mjs

@@ -41,38 +41,63 @@ async function readMailSettings(filePath,signal){
     return settings;
 }
 
-function mailProfileSettings(settings,location){
+function mailProfileSettings(settings,location,nested=false){
+    const source=nested?settings.mail:settings;
+    if(source===undefined)return undefined;
+    if(!source||!is.object(source)||is.array(source)){
+        throw new ArcaneError(ERROR_CODES.usage,`mail in ${location.filePath} must be an object.`);
+    }
     if(location.profile==='mail'){
-        return settings;
+        return source;
     }
-    if(settings.MAIL_PROFILES===undefined){
+    const profiles=nested?source.profiles:source.MAIL_PROFILES;
+    const label=nested?'mail.profiles':'MAIL_PROFILES';
+    if(profiles===undefined){
         return undefined;
     }
-    if(!settings.MAIL_PROFILES||!is.object(settings.MAIL_PROFILES)||is.array(settings.MAIL_PROFILES)){
-        throw new ArcaneError(ERROR_CODES.usage,`MAIL_PROFILES in ${location.filePath} must be an object.`);
+    if(!profiles||!is.object(profiles)||is.array(profiles)){
+        throw new ArcaneError(ERROR_CODES.usage,`${label} in ${location.filePath} must be an object.`);
     }
-    if(!Object.hasOwn(settings.MAIL_PROFILES,location.profile)){
+    if(!Object.hasOwn(profiles,location.profile)){
         return undefined;
     }
-    const profileSettings=settings.MAIL_PROFILES[location.profile];
+    const profileSettings=profiles[location.profile];
     if(!profileSettings||!is.object(profileSettings)||is.array(profileSettings)){
         throw new ArcaneError(
             ERROR_CODES.usage,
-            `MAIL_PROFILES[${JSON.stringify(location.profile)}] in ${location.filePath} must be an object.`
+            `${label}[${JSON.stringify(location.profile)}] in ${location.filePath} must be an object.`
         );
     }
     return profileSettings;
 }
 
+function mailCredentialEntry(settings, location) {
+    const nestedSettings = mailProfileSettings(settings, location, true);
+    const nestedEntry = {
+        profileSettings: nestedSettings,
+        key: 'apiKey',
+        setting: location.profile === 'mail'
+            ? 'mail.apiKey'
+            : `mail.profiles[${JSON.stringify(location.profile)}].apiKey`
+    };
+    if (nestedSettings && Object.hasOwn(nestedSettings, 'apiKey')) return nestedEntry;
+    const legacySettings = mailProfileSettings(settings, location);
+    if (legacySettings && Object.hasOwn(legacySettings, 'RESEND_API_KEY')) {
+        return {profileSettings: legacySettings, key: 'RESEND_API_KEY', setting: location.setting};
+    }
+    return nestedEntry;
+}
+
 function configuredMailKey(settings,location){
-    const apiKey=mailProfileSettings(settings,location)?.RESEND_API_KEY;
+    const entry=mailCredentialEntry(settings,location);
+    const apiKey=entry.profileSettings?.[entry.key];
     if(apiKey===undefined||apiKey===null||apiKey===''){
         return null;
     }
     if(!is.string(apiKey)){
         throw new ArcaneError(
             ERROR_CODES.usage,
-            `${location.setting} in ${location.filePath} must be a string.`
+            `${entry.setting} in ${location.filePath} must be a string.`
         );
     }
     return apiKey;
@@ -88,16 +113,22 @@ export async function setMailCredential(options={}){
         throw new ArcaneError(ERROR_CODES.usage,'The Resend API key must be a nonempty string.');
     }
     const settings=await readMailSettings(location.filePath,options.signal);
-    const profileSettings=mailProfileSettings(settings,location);
-    const updatedProfile={...profileSettings,RESEND_API_KEY:options.secret};
-    const updatedSettings=location.profile==='mail'
-        ?updatedProfile
-        :{
-            ...settings,
-            MAIL_PROFILES:{...settings.MAIL_PROFILES,[location.profile]:updatedProfile}
-        };
+    const entry=mailCredentialEntry(settings,location);
+    if(entry.profileSettings){
+        entry.profileSettings[entry.key]=options.secret;
+    }else{
+        settings.mail??={};
+        if(location.profile==='mail'){
+            settings.mail.apiKey=options.secret;
+        }else{
+            settings.mail.profiles={
+                ...settings.mail.profiles,
+                [location.profile]:{apiKey:options.secret}
+            };
+        }
+    }
     throwIfAborted(options.signal);
-    await writeFile(location.filePath,`${JSON.stringify(updatedSettings,null,2)}\n`,{
+    await writeFile(location.filePath,`${JSON.stringify(settings,null,2)}\n`,{
         encoding:'utf8',
         mode:0o600,
         signal:options.signal
@@ -111,30 +142,58 @@ export async function readMailCredential(options={}){
     return configuredMailKey(settings,location);
 }
 
-export async function readMailServerSettings(options = {}) {
-    const location = mailCredentialLocation(options);
-    const settings = await readMailSettings(location.filePath, options.signal);
-    const serverSettings = (options.readCredential ?? null) === null
-        ? {apiKey: configuredMailKey(settings, location)}
-        : {};
+export async function readMailConfiguration(options = {}) {
+    const directory = path.resolve(options.cwd ?? options.workspaceRoot ?? process.cwd());
+    const configPath = path.join(directory, 'arcane.config.json');
+    const envPath = path.join(directory, '.arcane.env.json');
+    const readCredentialFromFile = (options.readCredential ?? null) === null;
+    const [config, secrets] = await Promise.all(
+        [
+            readMailSettings(configPath, options.signal),
+            options.action !== 'send' || readCredentialFromFile
+                ? readMailSettings(envPath, options.signal)
+                : {}
+        ]
+    );
+    const mailSettings = config.mail === undefined ? {} : config.mail;
+    if (!mailSettings || !is.object(mailSettings) || is.array(mailSettings)) {
+        throw new ArcaneError(ERROR_CODES.usage, `mail in ${configPath} must be an object.`);
+    }
+    const location = mailCredentialLocation(
+        {...options, profile: options.profile !== undefined ? options.profile : mailSettings.profile}
+    );
+    const configuration = {profile: location.profile};
+    for (const name of [
+        'host', 'port', 'origins', 'from', 'appId', 'recipientAllowlist',
+        'errorRecipients', 'bodyTimeoutMs', 'providerTimeoutMs', 'retryableDelayMs'
+    ]) {
+        if (mailSettings[name] !== undefined) configuration[name] = mailSettings[name];
+    }
+    if (readCredentialFromFile) {
+        configuration.apiKey = configuredMailKey(secrets, location);
+    }
+    // Sending a report does not consume listener certificate configuration.
+    if (options.action === 'send') return configuration;
     const tlsSettings = {
         MAIL_TLS_CERT_PATH: 'certPath',
         MAIL_TLS_KEY_PATH: 'keyPath'
     };
     for (const [setting, option] of Object.entries(tlsSettings)) {
-        const value = settings[setting];
+        const value = options[option] !== undefined
+            ? options[option]
+            : mailSettings[option] !== undefined ? mailSettings[option] : secrets[setting];
         if (value === undefined || value === null || value === '') {
             continue;
         }
         if (!is.string(value)) {
             throw new ArcaneError(
                 ERROR_CODES.usage,
-                `${setting} in ${location.filePath} must be a PEM file path string.`
+                `mail.${option} (${setting}) must be a PEM file path string.`
             );
         }
-        serverSettings[option] = path.resolve(path.dirname(location.filePath), value);
+        configuration[option] = path.resolve(directory, value);
     }
-    return serverSettings;
+    return configuration;
 }
 
 export async function getMailCredentialStatus(options={}){
@@ -146,17 +205,18 @@ export async function getMailCredentialStatus(options={}){
 export async function deleteMailCredential(options={}){
     const location=mailCredentialLocation(options);
     const settings=await readMailSettings(location.filePath,options.signal);
-    const profileSettings=mailProfileSettings(settings,location);
-    if(profileSettings&&Object.hasOwn(profileSettings,'RESEND_API_KEY')){
-        const {RESEND_API_KEY,...remainingSettings}=profileSettings;
-        const updatedSettings=location.profile==='mail'
-            ?remainingSettings
-            :{
-                ...settings,
-                MAIL_PROFILES:{...settings.MAIL_PROFILES,[location.profile]:remainingSettings}
-            };
+    let changed=false;
+    for(const nested of [true,false]){
+        const profileSettings=mailProfileSettings(settings,location,nested);
+        const key=nested?'apiKey':'RESEND_API_KEY';
+        if(profileSettings&&Object.hasOwn(profileSettings,key)){
+            delete profileSettings[key];
+            changed=true;
+        }
+    }
+    if(changed){
         throwIfAborted(options.signal);
-        await writeFile(location.filePath,`${JSON.stringify(updatedSettings,null,2)}\n`,{
+        await writeFile(location.filePath,`${JSON.stringify(settings,null,2)}\n`,{
             encoding:'utf8',
             signal:options.signal
         });

package/src/mail.mjs

@@ -5,7 +5,7 @@ import {
     getMailCredentialStatus,
     mailCredentialLocation,
     readMailCredential,
-    readMailServerSettings,
+    readMailConfiguration,
     setMailCredential
 } from './mail-credentials.mjs';
 import {sendResendMail,startResendMailServer} from './mail-server.mjs';
@@ -62,6 +62,12 @@ function mailCredentialOptions(options){
     };
 }
 
+function configuredMailOption(options, settings, name, alias = name) {
+    if (options[alias] !== undefined) return options[alias];
+    if (options[name] !== undefined) return options[name];
+    return settings[name];
+}
+
 async function setMailCredentialFromInput(options){
     const readSecret=resolveMailCommandDependency(options,'readSecret',null);
     const store=resolveMailCommandDependency(options,'setCredential',setMailCredential);
@@ -94,20 +100,23 @@ async function sendMailFromReport(options){
     throwIfAborted(options.signal);
     const report=await readReport();
     throwIfAborted(options.signal);
-    let apiKey=await readMailProviderKey(options);
+    const readConfiguration=resolveMailCommandDependency(options,'readServerSettings',readMailConfiguration);
+    const mailSettings=await readConfiguration(options);
+    throwIfAborted(options.signal);
+    let apiKey=await readMailProviderKey(options,mailSettings);
     try{
         throwIfAborted(options.signal);
         const result=await send({
             apiKey,
             appId:'arcane-cli',
             fetchImpl:options.fetchImpl,
-            from:options.from,
+            from:configuredMailOption(options,mailSettings,'from'),
             onEvent:options.onEvent,
-            providerTimeoutMs:options.requestTimeout,
+            providerTimeoutMs:configuredMailOption(options,mailSettings,'providerTimeoutMs','requestTimeout'),
             report,
             reportKey:options.reportKey,
             requestIdFactory:options.requestIdFactory,
-            retryableDelayMs:options.retryableDelayMs,
+            retryableDelayMs:configuredMailOption(options,mailSettings,'retryableDelayMs'),
             signal:options.signal
         });
         if(result?.classification==='accepted'&&result.status==='accepted'){
@@ -126,16 +135,21 @@ async function sendMailFromReport(options){
     }
 }
 
-async function readMailProviderKey(options, serverSettings){
-    const credentialOptions=mailCredentialOptions(options);
-    const apiKey = serverSettings !== undefined && (options.readCredential ?? null) === null
-        ? serverSettings.apiKey
+async function readMailProviderKey(options, mailSettings){
+    const credentialOptions=mailCredentialOptions(
+        {...options,profile:options.profile??mailSettings?.profile}
+    );
+    const apiKey = mailSettings !== undefined && (options.readCredential ?? null) === null
+        ? mailSettings.apiKey
         : await resolveMailCommandDependency(options, 'readCredential', readMailCredential)(credentialOptions);
     if(apiKey===null){
         const location=mailCredentialLocation(credentialOptions);
+        const nestedSetting = location.profile === 'mail'
+            ? 'mail.apiKey'
+            : `mail.profiles[${JSON.stringify(location.profile)}].apiKey`;
         throw new ArcaneError(
             ERROR_CODES.prerequisiteMissing,
-            `Missing ${location.setting} in ${location.filePath}.`
+            `Missing ${location.setting} or ${nestedSetting} in ${location.filePath}.`
         );
     }
     if(!is.string(apiKey)||!apiKey){
@@ -149,11 +163,9 @@ async function readMailProviderKey(options, serverSettings){
 
 async function serveMailGateway(options){
     const startServer=resolveMailCommandDependency(options,'startServer',startResendMailServer);
-    const readServerSettings = resolveMailCommandDependency(options, 'readServerSettings', readMailServerSettings);
+    const readServerSettings = resolveMailCommandDependency(options, 'readServerSettings', readMailConfiguration);
     throwIfAborted(options.signal);
-    const serverSettings = await readServerSettings(
-        {...mailCredentialOptions(options), readCredential: options.readCredential}
-    );
+    const serverSettings = await readServerSettings(options);
     throwIfAborted(options.signal);
     let apiKey=await readMailProviderKey(options, serverSettings);
     try{
@@ -165,32 +177,36 @@ async function serveMailGateway(options){
             const location = mailCredentialLocation(options);
             throw new ArcaneError(
                 ERROR_CODES.prerequisiteMissing,
-                `Missing ${missingSettings.join(', ')} in ${location.filePath}. Mail HTTPS requires a certificate and private key.`
+                `Missing ${missingSettings.join(', ')} in ${location.filePath}, or the corresponding mail.certPath/mail.keyPath in arcane.config.json. Mail HTTPS requires a certificate and private key.`
             );
         }
-        const recipientAllowlist=mailRecipientOptions(options.allowTo,'allowTo');
-        const errorRecipients=options.errorTo===undefined
+        const recipientAllowlist=mailRecipientOptions(
+            configuredMailOption(options,serverSettings,'recipientAllowlist','allowTo'),'recipientAllowlist'
+        );
+        const errorTo=configuredMailOption(options,serverSettings,'errorRecipients','errorTo');
+        const errorRecipients=errorTo===undefined
             ? recipientAllowlist
-            : mailRecipientOptions(options.errorTo,'errorTo');
+            : mailRecipientOptions(errorTo,'errorRecipients');
+        const origins=configuredMailOption(options,serverSettings,'origins','origin');
         return await startServer({
             apiKey,
-            appId:options.appId,
-            allowedOrigins:options.origin===undefined
+            appId:configuredMailOption(options,serverSettings,'appId'),
+            allowedOrigins:origins===undefined
                 ?[]
-                :is.array(options.origin)?[...options.origin]:[options.origin],
-            bodyTimeoutMs:options.bodyTimeoutMs,
+                :is.array(origins)?[...origins]:[origins],
+            bodyTimeoutMs:configuredMailOption(options,serverSettings,'bodyTimeoutMs'),
             certPath:serverSettings.certPath,
             errorRecipients,
             fetchImpl:options.fetchImpl,
-            from:options.from,
-            host:options.host??'0.0.0.0',
+            from:configuredMailOption(options,serverSettings,'from'),
+            host:configuredMailOption(options,serverSettings,'host')??'0.0.0.0',
             keyPath:serverSettings.keyPath,
             onEvent:options.onEvent,
-            port:options.port,
-            providerTimeoutMs:options.requestTimeout,
+            port:configuredMailOption(options,serverSettings,'port'),
+            providerTimeoutMs:configuredMailOption(options,serverSettings,'providerTimeoutMs','requestTimeout'),
             recipientAllowlist,
             requestIdFactory:options.requestIdFactory,
-            retryableDelayMs:options.retryableDelayMs,
+            retryableDelayMs:configuredMailOption(options,serverSettings,'retryableDelayMs'),
             signal:options.signal,
             verifySubscription:options.verifySubscription
         });