arcane-os 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.19.0
+
+- Read mail credentials from `.env.json` in the invocation directory through
+  portable Node file APIs. Remove the Windows Credential Manager subprocess,
+  embedded PowerShell/C# helper, helper timeouts, and transport-only machinery.
+  Existing Windows credential records remain untouched; populate the JSON file
+  explicitly when adopting this configuration change.
+- Default mail commands to the top-level `RESEND_API_KEY`; `--profile mail`
+  selects that same key. Preserve named key set/status/delete operations through
+  exact `MAIL_PROFILES` entries, retaining unrelated JSON settings and naming
+  the missing setting and file before send or server startup.
+- Ignore `.env.json` in the SDK checkout and newly scaffolded workspaces. Update
+  the mail reference and purpose-gate report with the portable configuration
+  contract and the reasons for each retained or removed operation.
+
 ## 0.18.0
 
 - Adopt published `node-http-server` 10.0.0. PEM-backed development and

package/README.md

@@ -19,7 +19,7 @@ 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.18.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.19.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/cli.md

@@ -32,7 +32,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane update-check` | Performs one explicit, read-only npm dist-tag query for the installed SDK version. |
 | `arcane targets` | Lists target ids, declared status, formats, architectures, signing profiles, methods, and pairing reason. |
 | `arcane repo status\|pull\|push` | Runs one selected repository operation for the current app workspace. |
-| `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in Windows Credential Manager. |
+| `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in `.env.json`. |
 | `arcane mail send` | Performs one explicit, idempotency-keyed Resend attempt from a complete JSON report on redirected stdin. |
 | `arcane mail serve` | Starts one Arcane-to-Resend gateway with a server-only provider profile, a selected listener, and optional CORS and recipient configuration. |
 
@@ -813,22 +813,47 @@ npm exec -- arcane repo status
 
 ### Resend credential profiles
 
-The credential subcommands select one local profile:
+The mail commands read `.env.json` from the invocation directory on Windows,
+Linux, and macOS. The credential subcommands select one profile in that file:
 
 ```text
-arcane mail key set <profile> [--secret-stdin]
-arcane mail key status <profile>
-arcane mail key delete <profile>
+arcane mail key set [profile] [--secret-stdin]
+arcane mail key status [profile]
+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 sent to the Windows Credential Manager
-helper over child-process stdin, never argv, and no plaintext fallback is
-created. Status reports only whether the profile exists. Delete returns the
-selected profile with `exists:false`; it intentionally does not distinguish a
-new deletion from an already-absent profile. Non-Windows hosts report the
-credential operation as unavailable.
+rejects a TTY before reading. The key is written to `.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.
+
+The minimal file is:
+
+```json
+{
+  "RESEND_API_KEY": ""
+}
+```
+
+Fill in the key before starting mail, and add `.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,
+`provider:'resend'`, `storage:'.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
+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
+does not migrate or fall back to them. Mail reads JSON directly and does not
+populate or depend on process environment variables for this key.
+
+Missing files or missing/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.
 
 Machine output for `key set` requires `--secret-stdin`. Raw CLI arguments are
 not included in acceptance events, and usage errors do not echo unknown option
@@ -840,7 +865,7 @@ or positional values.
 server:
 
 ```text
-arcane mail send --profile <profile> [--from <verified-sender>] --report-key <id> --report-stdin [--request-timeout <ms>]
+arcane mail send [--profile <profile>] [--from <verified-sender>] --report-key <id> --report-stdin [--request-timeout <ms>]
 ```
 
 `--report-stdin` is mandatory and rejects a terminal before attaching input
@@ -861,8 +886,8 @@ 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 Windows Credential Manager profile; neither it nor report content is
-accepted through argv or environment variables.
+selected `.env.json` profile; omitting `--profile` selects `mail`. 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
@@ -883,10 +908,11 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 `mail serve` starts one owned Node HTTP gateway:
 
 ```text
-arcane mail serve --profile <profile> [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
+arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
 ```
 
-The selected credential profile supplies only the server-side Resend API key.
+The selected `.env.json` profile supplies only the server-side Resend API key;
+omitting `--profile` selects `mail`.
 The CLI does not read a browser app key. Its optional `--app` value labels the
 server; the incoming request's `X-Mail-App` identifies the application for
 subscription verification. The HTTP authentication contract pairs that

package/docs/reference/mail.md

@@ -13,12 +13,14 @@ gateway and is never included in browser or WebAssembly state.
 | `MailTransport.mjs` | Browser, WebView, or compatible Fetch host | Sends one already-persisted request to the configured Arcane gateway with the stable report key as its idempotency key. |
 | `arcane mail send` | Node on the local machine | Reads one complete provider-neutral report from redirected stdin and performs one explicit Resend attempt with a caller-owned idempotency key. |
 | `arcane mail serve` | Node on the configured host | Owns caller verification, protects the provider credential, applies explicitly configured recipient and origin settings, and makes one server-side Resend request. |
-| `arcane mail key ...` | Node on Windows | Stores, inspects, or deletes a Resend API key in Windows Credential Manager. |
+| `arcane mail key ...` | Node on Windows, Linux, or macOS | Stores, inspects, or deletes a Resend API key in the selected `.env.json`. |
 
 The browser never receives the Resend API key. The gateway never writes that
 key to source, argv, logs, events, fixtures, browser storage, or its public
-lifecycle result. Non-Windows hosts report credential operations as unavailable;
-there is no plaintext fallback.
+lifecycle result. The CLI and gateway use the same Node filesystem and network
+interfaces on Windows, Linux, and macOS. An Android host supplies a compatible
+Node runtime and an accessible configuration directory; the mail implementation
+contains no Windows credential process or platform-specific path convention.
 
 ## Public npm import
 
@@ -42,8 +44,8 @@ import Mail,{
   and `sendMailReport`.
 
 This entrypoint contains only the portable browser/WebView runtime, outbox, and
-transport contract. It does not import the Node HTTP gateway or Windows
-Credential Manager adapter. Programmatic developer tooling reaches those
+transport contract. It does not import the Node HTTP gateway or its filesystem
+credential adapter. Programmatic developer tooling reaches those
 host-owned operations through the existing `createToolchain().mail(...)`
 boundary; ordinary operators use `arcane mail send`, `arcane mail serve`, and
 `arcane mail key ...`. This keeps Node credential and server authority out of a
@@ -53,9 +55,9 @@ browser import while preserving one shared CLI/toolchain implementation.
 
 Arcane Mail deliberately separates two credentials:
 
-- The **Resend API key** is provider authority. `arcane mail key set <profile>`
-  stores it in Windows Credential Manager. `mail send --profile <profile>` and
-  `mail serve --profile <profile>` read it only inside the owning Node process.
+- The **Resend API key** is provider authority. The Node process reads it from
+  `.env.json`. `arcane mail key set [profile]` can store it there through hidden
+  input; `mail send` and `mail serve` read the selected profile inside that process.
 - The **subscription key** is the application user's subscription credential.
   When present, the browser sends it as `Authorization: Bearer <subscriptionKey>`,
   with the exact application name in `X-Mail-App`. The application name identifies the
@@ -270,21 +272,69 @@ committed acceptance result.
 
 ## Operate the CLI and gateway
 
-Store one Resend key under a local profile:
+Create `.env.json` in the directory from which the mail command runs, then fill
+in the provider key:
+
+```json
+{
+  "RESEND_API_KEY": ""
+}
+```
+
+The SDK repository ignores `.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`:
+
+```json
+{
+  "RESEND_API_KEY": "",
+  "MAIL_PROFILES": {
+    "another-provider-account": {
+      "RESEND_API_KEY": ""
+    }
+  }
+}
+```
+
+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.
+
+Programmatic operations resolve `.env.json` 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.
+
+The existing key commands manage the same file:
 
 ```text
-arcane mail key set arcane-dev
-arcane mail key status arcane-dev
-arcane mail key delete arcane-dev
+arcane mail key set
+arcane mail key status
+arcane mail key delete
 ```
 
 `key set` prompts with hidden input. `--secret-stdin` is the explicit
-non-interactive alternative and rejects a TTY.
+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.
+Results identify `storage: '.env.json'`. An already-absent deletion succeeds
+with `exists: false`.
+
+Existing Windows Credential Manager records remain untouched. The JSON path
+does not read, migrate, or delete those records; populate the selected JSON
+setting to use it. Missing files or missing/empty provider settings produce an
+actionable startup/send error naming the file and exact setting. Unreadable or
+invalid JSON is reported without including credential content in the error.
 
 Perform one provider attempt directly from the SDK CLI:
 
 ```text
-arcane mail send --profile arcane-dev --from "Arcane <verified@example.com>" --report-key <stable-id> --report-stdin
+arcane mail send --from "Arcane <verified@example.com>" --report-key <stable-id> --report-stdin
 ```
 
 The redirected UTF-8 JSON object is read completely. Its fields and values
@@ -312,7 +362,7 @@ deadline.
 Start the gateway:
 
 ```text
-arcane mail serve --profile arcane-dev --from "Arcane <verified@example.com>"
+npm exec -- arcane mail serve --profile mail --host 0.0.0.0 --port 8025
 ```
 
 The default listener is `0.0.0.0:8025`; `--host` and `--port` select its bind

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

@@ -1,13 +1,14 @@
-[Roshi's Codex PRIME] The method and action review is complete, and the inspected gateway implements the removals and simplifications below. Subscription verification now has a public optional callback: an omitted callback leaves the initial setup operational with `callerAuthentication: 'none'`; a configured callback selects `'subscription'` and controls admission before any provider attempt. The real TWiNStripeServer endpoint adapter comes later and does not block this delivery. Version `0.16.0` is selected; commit, package, and publication outcomes must be reported by the delivery owner when they actually occur.
+[Roshi's Codex PRIME] The gateway review and its portable credential follow-up apply the same three purpose gates. The gateway removals preserve complete delivery outcomes, configured CORS and recipient policy, and the optional subscription verifier. Mail credentials now belong in the user-selected `.env.json`, with one portable Node implementation for Windows, Linux, and macOS and a compatible Node host as the Android adaptation boundary. The original gateway inventory below uses baseline `f055e05`; the credential follow-up reviews the Windows storage implementation present at SDK `0.18.0`. Commit, package, publication, and actual platform execution outcomes belong to the delivery record rather than to this source-review report.
 
 | Decision | Behavior | Why it matters | Source status at this review |
 | --- | --- | --- | --- |
 | Remove | Loopback-only admission, manual header reconstruction, address/origin normalization, local payload grammar, manual content-length scan, dead queue knobs | These restrict supported use, rewrite supplied values, or repeat work already owned elsewhere. | Removed from the inspected source; naming-only changes carry no runtime claim. |
 | Remove and replace | Local app-key hashes and X-Mail-Key authentication | The selected application plus bearer subscription contract needs an actual verifier, not a local shared-key comparison. | Removed. Optional `verifySubscription` implements the local integration contract; the remote endpoint adapter remains future work. Initial setup without that callback performs no caller authentication. |
+| Remove and replace | Windows-only credential process, native interop, helper timers, environment prerequisites, encoding and input/output limits | They prevent the required portable startup and perform work absent from the selected JSON storage path. | Replaced by direct `.env.json` access. Existing Windows credential records remain untouched. Default and named credential operations remain useful and are preserved. |
 | Simplify | Exact CORS policy, one configuration resolution, one provider request construction/serialization, optional observation | Preserve the intended result while eliminating repeated parsing, copies, policy structures, and absent-observer work. | Present in inspected source. Explicit nonempty origin lists remain authoritative; otherwise the nominal-domain default applies. |
 | Keep | Configured subscription authentication, explicit recipient policy/fallback, stable idempotency, real cancellation/deadlines, complete provider outcomes, concurrent requests and owned shutdown | These have concrete callers and determine whether mail is sent, retried, reported honestly, or stopped correctly. | Retained. Only a verifier result of `true` permits authenticated delivery; failures and cancellation prevent the provider attempt. |
 
-This review covers every named method, callback owner, constant, and significant action in `src/mail-server.mjs` at baseline `f055e05`, plus the coupled CLI/browser paths needed to preserve behavior. The current-source observations were reconciled on 2026-09-07. No runtime speedup, successful live mail delivery, completed source release, or subscription acceptance is claimed.
+This review covers every named method, callback owner, constant, and significant action in `src/mail-server.mjs` at baseline `f055e05`, plus the coupled CLI/browser paths needed to preserve behavior. The portable credential addendum covers `src/mail-credentials.mjs`, its command/CLI callers, and the ignored configuration file. The current-source observations were reconciled on 2026-09-07. Source simplification is distinct from measured speedup, successful live mail delivery, release evidence, and execution on a particular platform.
 
 The intended software outcome is one complete mail request reaching the configured provider through the owning gateway, followed by an honest complete result. The gateway must preserve caller content, useful recipient policy, configured subscription authentication, explicit allowed-origin CORS behavior, caller cancellation, provider acceptance and uncertainty, and owned shutdown. It must use the published `node-http-server` interface and work on the selected host/domain without a loopback-only assumption. The initial unauthenticated setup is an implementation assumption stated to the user; no live deployment is selected in this work.
 
@@ -19,7 +20,7 @@ The user's three gates apply to the behavior, not to how impressive a helper nam
 
 In the tables, `Y/Y/N` means keep the behavior; `Y/Y/Y` means simplify it by removing the identified redundant step; `N/N/Y` means remove the behavior. `Pending` identifies a real unresolved external contract or compatibility question, not an automatic delivery hold. Cost descriptions identify allocations, scans, calls, listeners, or waits that source removal eliminates; they are not timing measurements. A rename alone has no claimed runtime benefit. The tables state the current source name when behavior remains; recommendations and pending changes are marked explicitly. Existing public entry-point names remain stable unless the user expressly changes their contract.
 
-The review sources are [the gateway](../../src/mail-server.mjs), [mail command orchestration](../../src/mail.mjs), [CLI server ownership](../../src/cli/main.mjs), [the portable transport](../../runtime/arcane/modules/MailTransport.mjs), [the browser Mail owner](../../runtime/arcane/modules/Mail.js), [the outbox's result consumers](../../runtime/arcane/modules/MailOutbox.mjs), and [the public mail reference](../reference/mail.md). Outbox storage, scheduling, maintenance methods, and unrelated SDK modules are outside this cleanup scope. Relevant test source was read as evidence of expected interfaces; tests were not executed.
+The review sources are [the gateway](../../src/mail-server.mjs), [mail credentials](../../src/mail-credentials.mjs), [mail command orchestration](../../src/mail.mjs), [CLI server ownership](../../src/cli/main.mjs), [the portable transport](../../runtime/arcane/modules/MailTransport.mjs), [the browser Mail owner](../../runtime/arcane/modules/Mail.js), [the outbox's result consumers](../../runtime/arcane/modules/MailOutbox.mjs), and [the public mail reference](../reference/mail.md). Outbox storage, scheduling, maintenance methods, and unrelated SDK modules are outside this cleanup scope. Relevant test source was read as evidence of expected interfaces; tests were not executed.
 
 Resend's send API accepts recipient strings or arrays, additional provider fields, and templates whose content rules differ from ordinary text/HTML messages. Its response includes a provider identifier. These are reasons to retain provider-boundary mapping while removing narrower gateway schemas. [Resend Send Email](https://resend.com/docs/api-reference/emails/send-email)
 
@@ -34,6 +35,7 @@ The latest user-selected boundaries govern this review:
 - Explicit recipient allowlists and error-recipient fallback remain. A configured nonempty allowlist covers resolved `to`, `cc`, and `bcc` recipients; allowing additional provider fields must not bypass the selected recipient policy. With no allowlist, the policy performs no recipient scan. Per-address trimming, lowercasing, and local email grammar do not remain.
 - Caller-selected deadlines, the cancellation adapter, complete provider outcomes, retry classification, stable idempotency, and independently constructed snapshots for emitted observations remain. Shared mutable provider snapshots have not been selected.
 - Remove manual response content-length scanning, duplicate configuration/CORS construction, unobserved event payload creation, unused `allowZero`, and unused CLI queue options.
+- All SDK mail operations require a functional Windows, Linux, and macOS path, with Android adaptation at the host boundary. Read provider configuration directly from an ignored `.env.json`; an operating-system limitation notice does not satisfy the portable requirement. Default profile `mail` uses `RESEND_API_KEY`; other exact names use `MAIL_PROFILES[profile].RESEND_API_KEY`. Missing configuration must identify the file and setting to fill in. Existing Windows records remain untouched, without an automatic read or migration.
 
 Source inspection during this report's handoff shows local app/email/sender/API-key format validators and loopback admission removed; origin values retained in one Set; complete provider JSON values or raw response text preserved; template-shaped provider requests no longer required to supply local text/HTML fields; and configuration passed once into `createConfiguredMailHandler`. Observer objects, pending Sets, callback closures, event payload reconstruction, and drain waits are absent when `onEvent` is omitted. An already-cancelled direct send stops before provider payload construction or serialization. Response writing no longer calculates content length. The fixed `/v1/mail` route accepts its query-bearing form, matching the portable endpoint parser. These are source observations, not executed behavior.
 
@@ -309,13 +311,13 @@ The coupled CLI/browser actions below are necessary to avoid leaving contradicto
 
 | Coupled path/action | Gates and decision | Required result and evidence boundary |
 | --- | --- | --- |
-| `src/mail.mjs` `serveMail` old hidden app-key input and local auth options | Y/Y/Y — Reconciled with the optional verifier contract. | Obsolete shared-app-key prompt/options are removed. Current `serveMailGateway` forwards `options.verifySubscription` to the server and keeps provider credential-manager operations and the provider API key separate. |
+| `src/mail.mjs` `serveMail` old hidden app-key input and local auth options | Y/Y/Y — Reconciled with the optional verifier contract. | Obsolete shared-app-key prompt/options are removed. Current `serveMailGateway` forwards `options.verifySubscription` to the server and keeps provider credential operations and the provider API key separate. The portable follow-up resolves that provider credential from `.env.json`. |
 | `src/mail.mjs` `recipientList` and origin list preparation | Y/Y/Y — Remove redundant rewriting, preserve configured policy values. | Gateway and CLI must not disagree about preserved recipients/origins. An exact allowlist is still an intentional policy. |
 | `src/mail.mjs` `withoutMailCredentials` | N/N/Y for recursive payload-key redaction — Remove. | It recursively traversed/copied complete results and deleted any content property named `apiKey` or `appKey`, including ordinary user payload fields. Keep actual transport credentials outside constructed public results at their owning boundary; do not rewrite the report based on property names. Source inspection shows this traversal removed. |
 | `src/mail.mjs` `completeSendFailure` | Y/Y/Y — Remove helper after preserving the complete result directly. | Failure output still contains the provider result, or a narrow wrapper for a non-object injected result. No recursive copying/redaction pass remains. |
 | CLI queue fields passed to a server that no longer consumes them | N/N/Y — Remove dead options/help/forwarding together. | `bodyQueueTimeoutMs`, `maxConcurrentBodyReads`, `maxConcurrentSends`, `maxQueuedBodyReads`, `maxQueuedSends`, and `sendQueueTimeoutMs` have no consumer in baseline mail-server configuration. Do not preserve misleading knobs or recreate queues for them. |
 | CLI app-slug validation/help and server-wide app identity requirement | Y/Y/Y — Remove app restriction and shared-server assumption. | Application is an ordinary per-request string; any app may use the server. Do not locally lowercase, rewrite, enumerate, or compare it to one server app. |
-| CLI mandatory `--from` | Y/Y/Y — Remove the redundant requirement; retain an explicit sender override. | The report or provider template may supply its sender. Requiring a shared CLI sender blocked those supported requests and per-report sender selection. Both mail commands now accept optional `--from`; Resend owns sender validity. The chosen credential profile and stable send key remain required. |
+| CLI mandatory `--from` | Y/Y/Y — Remove the redundant requirement; retain an explicit sender override. | The report or provider template may supply its sender. Requiring a shared CLI sender blocked those supported requests and per-report sender selection. Both mail commands accept optional `--from`; Resend owns sender validity. The stable send key remains required. The portable credential follow-up makes the profile optional, defaulting to `mail`. |
 | `MailTransport.mjs` request-header construction | Y/Y/Y — Updated to optional bearer Authorization; retain X-Mail-App. | Current source accepts an omitted, null, or empty subscription key and omits Authorization when no key exists, allowing the initial server setup. A supplied nonempty string is sent unchanged as the bearer credential; a configured server owns rejection of missing/invalid authentication. Preserve complete report payload, exact report key, cancellation, and configured destination. Never use the subscriber key as Resend provider authority. |
 | `MailTransport.mjs` provider ID/error code regexes | Y/Y/Y — Simplified in current source. | Provider ID requires an actual nonempty string, and provider error codes remain complete strings. The gateway and browser no longer disagree about provider metadata syntax. |
 | Browser/native/outbox request-ID grammar | Y/Y/N — Preserve; broader relaxation deferred. | Request-ID consumers still require the existing form. No half-implemented grammar change is included in this cleanup. |
@@ -344,8 +346,48 @@ The final status and intentionally deferred work are explicit:
 | Native-only request/response interface narrowing | Deferred and preserved. The non-Buffer request-chunk conversion, reader-based provider body interface, cancellation adapter, and invalid injected-status classification remain. Removing them requires proving that supported injected callers do not need them. | No claim of safe removal or measured saving is made for these retained compatibility paths. |
 | Escaped handler and event observer failure reporting | Implemented. Both call `reportMailError`, which uses native `inspect` with depth/array/string clipping disabled before stderr output. `closeResponseAfterHandlerFailure(error)` also passes the error to response destruction; observer errors do not change delivery classification. | Source evidence only; formatting work occurs only on failure. No local error-injection or runtime check was performed for this report. |
 | Remaining local lifecycle rejection-observer names | Preserved. Their narrow purpose is preventing duplicate unhandled rejections while the public lifecycle/close promise retains failure. The inventory records their actual names; no additional abstraction or blanket naming rewrite is selected. | Do not report every possible naming improvement as implemented. |
-| Final source delivery evidence | Version `0.16.0` selected; root owns final source/documentation reconciliation and the actual commit/package/publication outcome. | This report claims no completed source release, runtime test, live send, or remote subscription verification. The pending remote adapter does not hold the current increment. |
+| Final source delivery evidence | The original gateway review selected `0.16.0`; this portable credential follow-up extends the source present in `0.18.0`. Root owns final source/documentation reconciliation and the actual next commit/package/publication outcome. | This report supplies source-review evidence. Actual platform execution, live send, and remote subscription verification remain separate evidence boundaries. The pending remote adapter does not hold the current increment. |
 
 TWiNStripeServer owns the future `verify-subscription` endpoint adapter contract; the SDK owns the mail request's application/token consumption and the provider-attempt decision. Any application can use the shared service under its selected CORS policy. The current optional callback allows delivery now without pretending the remote adapter exists: omitted means initial setup with no caller authentication, configured means only an affirmative verifier result permits provider delivery. The later endpoint integration remains recorded and does not cancel or block this current increment.
 
 No local test, lint, type check, validation build, browser QA, performance measurement, or live Resend send was performed for this report. No Git index, commit, branch, push, package, or publication operation was performed by the report author. Every baseline named method and callback owner, constant, and significant action remains represented above; removed names are retained in the inventory for traceability. Root owns source/documentation delivery and selected-output verification under its governing authorization. This report records source inspection, not release or runtime evidence.
+
+## Portable credential follow-up: 0.19.0
+
+The selected storage owner is `src/mail-credentials.mjs`. The public CLI and
+`createToolchain().mail(...)` reach it through `src/mail.mjs`. Repository caller
+tracing found the old Windows target helpers only in this owner and its direct
+test source; the package has no `./mail-credentials` public subpath. The supported
+key operations remain, with JSON replacing their Windows storage implementation.
+Existing native credential records are neither read nor changed.
+
+| Method or action | Gates | Decision, callers, and concrete purpose |
+| --- | --- | --- |
+| `WINDOWS_CREDENTIAL_HELPER`, its C# `Write`, `Read`, `Exists`, `Delete`, native structs, and Advapi32 imports | N/N/Y | Remove. These existed solely to reach Windows Credential Manager; all four operations now use the selected JSON owner. No child process or native compilation remains. |
+| `WINDOWS_CREDENTIAL_HELPER_COMMAND`, `powershellExecutable`, `helperArguments`, `helperEnvironment`, `validatePlatform`, `helperOptions` | N/N/Y | Remove. Windows path discovery, environment reconstruction, command encoding, and injected Windows runner options have no consumer in portable JSON storage. `SystemRoot`, `WINDIR`, `TEMP`, and `TMP` are no longer mail credential prerequisites. |
+| `runCredentialProcess`, `runWindowsCredentialHelper`, `invokeCredentialHelper` and their nested process callbacks | N/N/Y | Remove. File operations replace spawning, helper stdin/stdout accumulation, process listeners, timeout allocation, and process shutdown. |
+| `serializeRequest`, `parseResponse`, `decodeSecret`, `BASE64_PATTERN`, helper input/output and credential limits | N/N/Y | Remove. There is no helper transport to encode, decode, scan, or limit. The complete configuration is parsed as JSON at its actual owner. |
+| `validateMailCredentialProfile`, `mailCredentialTarget`, `RESEND_CREDENTIAL_TARGET_PREFIX`, `PROFILE_PATTERN`, `MAX_PROFILE_LENGTH` | N/N/Y for the native target machinery | Remove. JSON profile keys need no native target namespace or lowercase/length grammar. Existing names remain usable; arbitrary nonempty string names are selected exactly. |
+| `validateSecret`, `SECRET_PATTERN`, `validateTimeout`, helper timeout constants | Y/Y/Y for reading a usable key; N/N/Y for helper restrictions | Remove the helper-specific grammar and deadline machinery. A key must be a nonempty string to supply provider authorization; Resend owns its acceptance. No helper deadline is needed. |
+| `usageError`, `unavailableError`, `operationError`, `cancellationError`, `assertNotAborted`, `validateOptions` | Y/Y/Y | Remove the Windows error wrappers and duplicate option/cancellation scaffolding. File failures surface at the file owner; shared `throwIfAborted` handles cancellation. Errors identify the file or setting without including secret values. |
+| `mailCredentialLocation` | Y/Y/N | Keep. All four operations and the missing-key reporter need the same directory/profile mapping. It selects `cwd`, then `workspaceRoot`, then `process.cwd()`, with no directory search. Default `mail` maps to top-level `RESEND_API_KEY`; another exact name maps to its `MAIL_PROFILES` entry. |
+| `readMailSettings` | Y/Y/N | Keep. Each credential operation reads the complete selected file once. Missing files support read/status/delete absence; unreadable JSON cannot supply settings. Parser excerpts are omitted because they may contain the credential. |
+| `mailProfileSettings` | Y/Y/N | Keep. Read, status, set, and delete need the same exact default/named selection. An absent named profile stays absent, including after deletion; it never reveals the default account's key. Object checks identify configuration that cannot represent the requested profile. |
+| `configuredMailKey` | Y/Y/N | Keep. Read and status share missing/empty-key semantics and a useful error for a value that cannot be a provider key. The returned key is preserved exactly. |
+| `mailCredentialStatus` | Y/Y/N | Keep the shared status shape for set/status/delete: profile, provider, storage, and existence. This preserves the useful operation result without returning the credential. |
+| `setMailCredential`, `readMailCredential`, `getMailCredentialStatus`, `deleteMailCredential` | Y/Y/Y | Preserve all four operations and replace their implementation. Explicit set/delete update only the selected credential field while preserving other settings and profiles; read returns the selected key or null; status reports existence. File access uses portable Node APIs. |
+| `mailCredentialOptions`, `readMailProviderKey` | Y/Y/Y | Keep shared command configuration and consolidate the real send/serve duplicate key-read error path. Remove Windows runner, helper directory, and helper timeout forwarding. Missing configuration names the exact JSON setting and file before opening a listener or attempting delivery. |
+| CLI required profile flag and omitted invocation directory | Y/Y/Y | Make the profile optional with default `mail`, retaining explicit profiles. Forward the invocation directory through every mail operation, so the CLI reads the operator's selected file. Preserve hidden/stdin key entry and existing send/serve lifecycle. |
+| Repository and workspace-template `.gitignore` entry | Y/Y/N | Keep `.env.json` out of source control in this checkout and newly generated workspaces. The populated local file is outside the committed and published change. |
+
+The credential path performs one file read per selected operation and one write
+only for an explicit set or a deletion that finds a credential. Startup reads
+once; there is no polling, watcher, background cache, migration, or platform
+process. These are source-level work reductions, not a measured speedup.
+
+The same Node filesystem contract covers Windows, Linux, and macOS. Android
+requires a compatible Node host and accessible configuration directory. This
+review does not claim execution on those platforms or an actual provider send.
+The updated test source covers disposable JSON storage, exact named selection,
+preservation of other settings, missing settings, credential-free error output,
+cancellation before writes, and CLI defaults. Local tests and checks were not run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "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

@@ -81,11 +81,11 @@ Usage:
   ${CLI_NAME} update-check
   ${CLI_NAME} targets
   ${CLI_NAME} repo status|pull|push
-  ${CLI_NAME} mail key set <profile> [--secret-stdin]
-  ${CLI_NAME} mail key status <profile>
-  ${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 8025] [--request-timeout <ms>]
+  ${CLI_NAME} mail key set [profile] [--secret-stdin]
+  ${CLI_NAME} mail key status [profile]
+  ${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 8025] [--request-timeout <ms>]
 
 Development:
   --public                      Bind dev to all IPv4 interfaces (0.0.0.0) and print network URLs.
@@ -657,9 +657,9 @@ function operationOptions(command,parsed,cwd){
         if(area==='key'){
             noExtraPositionals(command,positionals,3);
             const action=positionals[1];
-            const profile=positionals[2];
-            if(!['set','status','delete'].includes(action)||!profile){
-                usage('mail key requires set, status, or delete followed by one profile id.');
+            const profile=positionals[2]??'mail';
+            if(!['set','status','delete'].includes(action)){
+                usage('mail key requires set, status, or delete, with an optional profile id.');
             }
             if(values.profile!==undefined||values.from!==undefined||values.app!==undefined
                 ||values.origin!==undefined
@@ -675,6 +675,7 @@ function operationOptions(command,parsed,cwd){
             }
             return {
                 action:`key-${action}`,
+                cwd,
                 profile,
                 secretStdin:flags.has('secret-stdin'),
             };
@@ -687,10 +688,10 @@ function operationOptions(command,parsed,cwd){
             if(flags.has('report-stdin')||values['report-key']!==undefined){
                 usage('--report-stdin and --report-key are supported only by mail send.');
             }
-            if(!values.profile)usage('mail serve requires --profile <value>.');
             return {
                 action:'serve',
-                profile:values.profile,
+                cwd,
+                profile:values.profile??'mail',
                 from:values.from,
                 appId:values.app,
                 origin:values.origin,
@@ -710,25 +711,23 @@ function operationOptions(command,parsed,cwd){
                 ||values.port!==undefined){
                 usage('mail send does not accept gateway server options.');
             }
-            for(const [name,value]of Object.entries({
-                profile:values.profile,
-                'report-key':values['report-key'],
-            })){
-                if(!value)usage(`mail send requires --${name} <value>.`);
+            if(!values['report-key']){
+                usage('mail send requires --report-key <value>.');
             }
             if(!flags.has('report-stdin')){
                 usage('mail send requires --report-stdin.');
             }
             return {
                 action:'send',
-                profile:values.profile,
+                cwd,
+                profile:values.profile??'mail',
                 from:values.from,
                 reportKey:values['report-key'],
                 reportStdin:true,
                 requestTimeout:readMailRequestTimeout(values['request-timeout']),
             };
         }
-        usage('mail requires key set|status|delete <profile>, send, or serve.');
+        usage('mail requires key set|status|delete [profile], send, or serve.');
     }
     usage(`Unknown command. Run ${CLI_NAME} --help for usage.`);
 }