@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-email/DELIVERY-CONTROLS.md

@@ -0,0 +1,84 @@
+# Native email delivery controls
+
+Read this for suppression, unsubscribe, deduplication, provider webhooks and
+rendering. Source root: `storage/framework/core/email/src/`.
+
+Native mail.queue(message) and mail.later(delaySeconds, message) dispatch
+SendEmailJob to the emails queue. Their current dispatch failure path logs and
+falls back to synchronous sending, so an awaited queue call does not guarantee
+background execution or durable acceptance. A sync QUEUE_DRIVER also executes
+inline. Read email.ts and stacks-queue before depending on timing or delivery.
+
+## Results, suppression and send keys
+
+Mail.send returns EmailResult and can return success false without throwing.
+Mail.sendOrFail throws EmailDeliveryError for that structured failure. Resolve
+template HTML/text before the provider call; a provider failure must not enter
+a rendering fallback that sends a second message.
+
+Suppression helpers are isSuppressed/getSuppressions/suppress/unsuppress.
+Mail.send checks recipients against the configured suppression policy. Message
+tag transactional/broadcast affects the transactional-allowed policy; do not tag
+marketing as transactional merely to bypass an opt-out.
+
+EmailMessage.idempotencyKey returns the cached prior successful result on a
+retry, and only successful sends are recorded. The implementation looks up the
+key before delivery and records after delivery, so do not call this exactly-once
+concurrent provider sending or a transactional outbox. Missing table/connection
+compatibility paths can warn and degrade controls; apply EmailSuppression,
+EmailIdempotency and EmailWebhookEvent model migrations first. Inspect source
+failure handling before treating a key as a guarantee.
+
+Source: `email.ts`, `suppression.ts`, `idempotency.ts`. Evidence:
+`tests/suppression.test.ts`, `email.test.ts`, `driver-credentials.test.ts`.
+
+## Recipient unsubscribe
+
+createUnsubscribeToken(email, ttlSeconds?, scope?), verifyUnsubscribeToken(token),
+buildUnsubscribeUrl(email, ttlSeconds?, options?) and buildListUnsubscribeHeaders
+are native signed helpers. APP_KEY must exist. Scope can distinguish an
+application list/workspace policy; preserve it through verification and the
+unsubscribe action. Tokens are expiring recipient grants, not arbitrary user
+authentication or permission to read inbox data.
+
+The default unsubscribe routes have their own exact GET/POST behavior. Read the
+selected bundle rather than adding a second route with different token semantics.
+Persist the resulting suppression before reporting opt-out completion.
+
+Source: `unsubscribe.ts`, default email routes; evidence:
+`tests/unsubscribe.test.ts` and `unsubscribe-scope.test.ts`.
+
+## Provider webhooks
+
+The high-level processors are handleMailgunWebhook, handleSendgridWebhook,
+handleSesWebhook and handlePostmarkWebhook. Signature helpers include
+verifyMailgunSignature, verifySendgridSignature, verifySesSnsSignature and
+verifyPostmarkAuth. Read `webhook-handlers.ts` for each actual input/config shape.
+
+Use exact provider raw-body bytes, headers and external callback URL as required
+by the signature algorithm. The native pipeline validates, deduplicates the
+provider event ID, classifies it, persists suppressions for hard bounces,
+complaints/unsubscribe and emits the associated framework event. Soft bounces
+are events rather than automatic permanent suppressions. A configured processor
+does not mean its default route bundle is mounted or its credentials exist.
+
+Source: `webhook-handlers.ts`, `webhook-signatures.ts`, `webhook-dedup.ts`,
+`webhook-events.ts`; evidence: `tests/webhook-signatures.test.ts`.
+Retained signature/request evidence is not a live provider delivery test.
+
+## Rendering and preview
+
+Email template names resolve application emails first, then framework defaults;
+typed names and extensions are exposed by EmailTemplateReference. The renderer
+escapes interpolated values; explicitly raw template HTML needs the same trust
+boundary as a web template. inlineCss/shouldInlineByDefault provide native
+inlining; media rules that cannot be inlined remain separate. HTML-to-text is
+a mail rendering conversion, not a sanitization proof for arbitrary HTML.
+
+Use typed Mailable and native make:mail/mail:preview for repeatable message
+types and non-delivering reviews. See stacks-mail for those APIs. The preview
+includes MIME/body/attachment inspection; keep it behind its development route
+gates. Source: `template.ts`, `css-inliner.ts`, `mailable.ts`, `preview.ts`,
+`mime-preview.ts`. Evidence: `tests/template-escaping.test.ts`,
+`css-inliner.test.ts`, `html-to-text.test.ts`, `preview.test.ts` and
+`mime-preview.test.ts`.

package/ai/skills/stacks-email/SKILL.md

@@ -105,7 +105,7 @@ import { template, renderHtml, templateExists, listTemplates } from '@stacksjs/e
 
 const { html, text } = await template('welcome', {
   variables: { name: 'John', url: 'https://app.com' },
-  layout: 'default',   // or false to skip layout
+  layout: 'base',   // HTML layout, or false; STX templates own their layout
   subject: 'Welcome'
 })
 
@@ -317,7 +317,7 @@ Reprocessing refreshes existing messages instead of skipping them, preserves the
 - Default driver is `ses` - requires AWS credentials
 - Template rendering supports both `.stx` and `.html` files
 - Variable interpolation uses `{{ }}` double-brace syntax
-- The `mail` singleton auto-registers all 5 drivers on initialization
+- The mail singleton registers smtp, ses, sendgrid, mailgun, mailtrap, log and capture; provider selection comes from config
 - SMTP driver handles TLS handshake manually (not via node:tls)
 - SendGrid/Mailgun retry with exponential backoff on failure
 - `mail.send()` returns structured failures; use `mail.sendOrFail()` when success is required
@@ -329,3 +329,19 @@ Reprocessing refreshes existing messages instead of skipping them, preserves the
 - `buddy email:reprocess` preserves existing read state and exits nonzero on failure
 - Email categorization auto-sorts incoming mail by domain/substring patterns
 - The `text` fallback is auto-generated from HTML via `htmlToText()`
+
+
+## Delivery controls and provider evidence
+
+The package exports native suppression, send idempotency, unsubscribe tokens,
+webhook deduplication/signature/processors, CSS inlining, typed Mailable and mail
+previews. Read [DELIVERY-CONTROLS.md](DELIVERY-CONTROLS.md) when sending campaigns,
+processing provider callbacks or building recipient unsubscribe flows.
+
+Log and capture have local test contracts. SMTP/SES/SendGrid/Mailgun/Mailtrap
+are partial in `core/config/src/capabilities.ts`: credentials and request
+behavior are retained, live inbox delivery assertions are not. A successful
+provider API result means accepted by that provider, not received by the user.
+The default email webhook bundle is subject to route selection and the email
+feature gate. A preview/scaffold workflow never needs a production transport;
+see `stacks-mail` for make:mail and mail:preview.

package/ai/skills/stacks-enums/SKILL.md

@@ -8,93 +8,40 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Enums
 
-## Key Paths
-- Core package: `storage/framework/core/enums/src/`
-- Source: `storage/framework/core/enums/src/index.ts`
-- Package: `@stacksjs/enums`
+Use `@stacksjs/enums` for internal NpmScript and Action identifiers. Read their
+actual enum members rather than deriving command names from an old copied list.
 
-## NpmScript Enum (45 values)
+## Action paths
 
-Used by the CLI and build system to run specific npm scripts:
+Action values identify framework action source paths, for example BuildViews is
+build/views and QueueWork is queue/work. The enum's source links point at each
+handler; the action-source-links test verifies the member/path/file agreement.
+This is the framework's dispatch vocabulary, distinct from an application action
+path and from the public buddy CLI command registry.
 
-```typescript
-import { NpmScript } from '@stacksjs/enums'
-```
+Current members include component/library/native app builds, auth setup/pruning,
+generation/release, migration/seed, queue inspection/DLQ/quarantine/pause/resume,
+search, scheduling and upgrades. Read stacks-actions/stacks-buddy for dispatch
+and command invocation. Removed BuildVueComponentLib/MigrateDns/BuildComponents
+symbols should not be resurrected because an older skill lists them.
 
-### Build Scripts
-| Value | Script |
-|-------|--------|
-| `Build` | `'build'` |
-| `BuildComponents` | `'vite build --config ./src/vite-config/src/components.ts'` |
-| `BuildWebComponents` | `'build:web-components'` |
-| `BuildFunctions` | `'build:functions'` |
-| `BuildDocs` | `'build:docs'` |
-| `BuildStacks` | `'build:stacks'` |
+## Script values
 
-### Dev Scripts
-| Value | Script |
-|-------|--------|
-| `Dev` | `'dev'` |
-| `DevApi` | `'dev:api'` |
-| `DevDocs` | `'dev:docs'` |
-| `DevDesktop` | `'dev:desktop'` |
-| `DevFunctions` | `'dev:functions'` |
+NpmScript contains both script names and literal command strings. Some values
+invoke pickier or Bun tests directly; they are not all keys in package.json.
+Use ./buddy lint and the project's actual scripts for user workflows. Treat
+Clean/Fresh/Release as real operations, not harmless metadata probes.
 
-### Test Scripts
-| Value | Script |
-|-------|--------|
-| `Test` | `'test'` |
-| `TestUnit` | `'test:unit'` |
-| `TestFeature` | `'test:feature'` |
-| `TestUi` | `'test:ui'` |
-| `TestTypes` | `'test:types'` |
+## Scheduling constants
 
-### Maintenance Scripts
-`Clean`, `Fresh`, `Lint`, `LintFix`, `Upgrade`, `Generate`, `GenerateTypes`, `GenerateEntries`, `GenerateWebTypes`, `GenerateIdeHelpers`, `GenerateComponentMeta`, `Commit`, `Release`, `KeyGenerate`, `Preinstall`, `Prepublish`
+The Every enum lives in `@stacksjs/types` (core/types/src/cron-jobs.ts), not the
+enums entry. Its seconds forms need the appropriate scheduler layer; a six-field
+enum value does not make the low-level five-field parser accept arbitrary seconds.
+Read stacks-scheduler/stacks-cron for that distinction.
 
-## Action Enum (60+ values)
+## Source and verification
 
-Used to dispatch framework actions via the action runner:
-
-```typescript
-import { Action } from '@stacksjs/enums'
-```
-
-### Build Actions
-`BuildViews`, `BuildStacks`, `BuildComponentLibs`, `BuildVueComponentLib`, `BuildWebComponentLib`, `BuildFunctionLib`, `BuildCli`, `BuildCore`, `BuildDesktop`, `BuildDocs`, `BuildServer`
-
-### Dev Actions
-`DevComponents`, `DevDashboard`, `DevSystemTray`, `Dev`, `DevApi`, `DevDesktop`, `DevDocs`
-
-### Database Actions
-`Migrate`, `MigrateFresh`, `MigrateDns`, `Seed`
-
-### Queue Actions
-`QueueTable`, `QueueWork`, `QueueRetry`, `QueueFailed`, `QueueClear`, `QueueStatus`, `QueueFlush`, `QueueMonitor`, `QueueInspect`, `QueueSchedule`, `QueueScheduleList`
-
-### Domain Actions
-`DomainsAdd`, `DomainsPurchase`, `DomainsRemove`
-
-### Search Engine Actions
-`SearchEngineImport`, `SearchEngineFlush`, `SearchEngineListSettings`, `SearchEnginePushSettings`
-
-### Other Actions
-`Lint`, `LintFix`, `Test`, `TestUnit`, `TestFeature`, `TestUi`, `Typecheck`, `Deploy`, `ScheduleRun`, `Release`, `RouteList`, `Upgrade`, `UpgradeDeps`
-
-## Usage
-
-```typescript
-import { Action, NpmScript } from '@stacksjs/enums'
-
-// Used in buddy CLI commands
-runAction(Action.Migrate, options)
-
-// Used in build system
-runNpmScript(NpmScript.BuildComponents)
-```
-
-## Gotchas
-- **Action values use path format** — e.g., `Action.BuildViews = 'build/views'`, `Action.QueueWork = 'queue/work'`
-- **NpmScript values are actual script commands** — some are full vite commands, not just script names
-- **Used throughout the framework** — CLI, build system, and actions all reference these enums
-- **Adding new actions** — requires adding the enum value AND creating the action handler file
+`storage/framework/core/enums/src/index.ts` is the authoritative list.
+Retained tests: core/enums/tests/enums.test.ts and action-source-links.test.ts.
+When adding an internal action, add the enum member/source link and the handler,
+then verify its actual resolver and any public command registration separately.

package/ai/skills/stacks-env/SKILL.md

@@ -13,13 +13,14 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Environment config: `config/env.ts`
 - Environment file: `.env`
 - Example: `.env.example`
-- Type definitions: `storage/framework/env.d.ts`
+- Type definitions: core/env/src/types.ts and storage/framework/types/env.d.ts
 
 ## Source Files
 ```
 env/src/
 ├── index.ts     # main exports
-├── utils.ts     # runtime/platform detection, StacksEnv proxy
+├── runtime.ts   # typed/coerced environment proxy
+├── utils.ts     # runtime/platform/environment detection
 ├── plugin.ts    # Bun plugin for auto .env loading
 ├── parser.ts    # .env file parser with encryption support
 ├── cli.ts       # CLI commands (get, set, encrypt, decrypt, rotate)
@@ -33,12 +34,12 @@ env/src/
 import { env } from '@stacksjs/env'
 
 env.APP_NAME        // string
-env.APP_ENV         // 'local' | 'dev' | 'stage' | 'prod'
+env.APP_ENV         // configured environment label, including long and short forms
 env.APP_KEY         // string
 env.APP_URL         // string
 env.DEBUG           // boolean (auto-coerced)
 env.PORT            // number (auto-coerced)
-env.DB_CONNECTION   // 'sqlite' | 'mysql' | 'postgres' | 'dynamodb'
+env.DB_CONNECTION   // declared connection name; availability comes from capabilityRegistry
 env.DB_HOST         // string
 env.DB_PORT         // number
 env.DB_DATABASE     // string
@@ -49,13 +50,18 @@ env.STRIPE_SECRET_KEY    // string
 env.MAIL_MAILER          // string
 env.QUEUE_DRIVER         // string
 env.REDIS_HOST           // string
-env[key]                 // any custom env var
 ```
 
-The `env` proxy auto-coerces: `'true'` → `true`, `'123'` → `123`, etc.
+All values may be undefined. The env proxy coerces true/false case-insensitively.
+Numeric variables declared by the framework or schema.number are numbers;
+recognized numeric-setting suffixes are also coerced. IDs/codes and values with
+leading zeros remain strings unless declared numeric. Arbitrary numeric-looking
+text is not always a number.
 
 ## StacksEnv Type (100+ typed variables)
-App, Ports, API, Database, AWS, Mail, Services (Stripe, Meilisearch), Frontend, Realtime, Redis, Pusher, Auth, Storage, Queue, plus `[key: string]` catch-all.
+The typed interface covers framework variables without a catch-all index
+signature. Declare an application variable in config/env.ts rather than reading
+undeclared names through a dynamic env key.
 
 ## Adding your own variables
 
@@ -63,6 +69,9 @@ Declare them in `config/env.ts`. That is the whole step:
 
 ```typescript
 // config/env.ts
+import { defineEnv } from '@stacksjs/env'
+import { schema } from '@stacksjs/validation/runtime'
+
 export default defineEnv({
   STRIPE_WEBHOOK_SECRET: { validation: schema.string(), default: '' },
   BILLING_RETRIES: { validation: schema.number(), default: 3 },
@@ -87,7 +96,7 @@ which is the failure `config/env.ts` exists to prevent.
 import { isBun, isNode, runtime, runtimeInfo, platform, isWindows, isMacOS, isLinux, hasTTY, hasWindow, isCI, isDebug, isMinimal, isColorSupported, provider, providerInfo } from '@stacksjs/env'
 
 isBun           // true
-isNode          // false
+isNode          // Node-compatible process detection; may also be true under Bun
 runtime         // 'bun'
 platform        // 'darwin'
 isWindows       // false
@@ -178,8 +187,8 @@ is not a security boundary.
 ```typescript
 import { loadEnv, autoLoadEnv, envPlugin } from '@stacksjs/env'
 
-await loadEnv({ path: '.env', override: false })
-autoLoadEnv()  // detects .env, .env.local, .env.{APP_ENV}
+const loaded = loadEnv({ path: '.env', overload: false }) // { loaded, errors }
+autoLoadEnv()  // .env, .env.local, .env.<effectiveEnv>, .env.<effectiveEnv>.local
 
 // Bun plugin (auto-loads .env before app starts)
 envPlugin()
@@ -190,8 +199,7 @@ envPlugin()
 ```typescript
 import { parse } from '@stacksjs/env'
 
-const vars = parse(envContent, {
-  encryption: true,       // decrypt encrypted values
+const { parsed, errors, skippedEncrypted } = parse(envContent, {
   privateKey: '...'       // decryption key
 })
 ```
@@ -281,12 +289,12 @@ calls or raw client-side `fetch`.
 - **A tenant's keys in your env file get shipped everywhere.** `buddy deploy`
   sends the entire env file as each site's `.env`. Declare `tenants` in
   `config/cloud.ts` so they are stripped, then delete them at source
-- Bun natively loads `.env` — no dotenv package needed
+- Bun natively loads `.env` - no dotenv package needed
 - The `env` proxy auto-coerces strings to booleans/numbers
-- `.env` should never be committed — use `.env.example` as template
+- `.env` should never be committed - use `.env.example` as template
 - New encrypted values use ephemeral-static X25519, HKDF-SHA-256, and
   AES-256-GCM. Legacy ciphertext remains readable for migration
-- `autoLoadEnv()` loads in order: `.env`, `.env.local`, `.env.{APP_ENV}`
+- autoLoadEnv loads least to most specific, including .env.<effectiveEnv>.local; effective env resolution is in plugin.ts and existing shell values are preserved unless overloaded
 - Runtime detection uses Bun globals and process properties
 - CI provider detection checks environment variables specific to each CI system
 - The `StacksEnv` type provides autocomplete for 100+ known variables

package/ai/skills/stacks-error-handling/SKILL.md

@@ -8,130 +8,77 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Error Handling
 
-Type-safe error handling with Result types, error pages, and structured logging.
+Use Result for recoverable operation outcomes, HttpError for HTTP boundary
+refusals, and the native reporter/rendering pipeline for failures.
 
-## Key Paths
-- Core package: `storage/framework/core/error-handling/src/`
-- Configuration: `config/errors.ts`
-- Error model: `storage/framework/defaults/app/Models/Error.ts`
+## Results
 
-## Result Type (from ts-error-handling)
-
-```typescript
+~~~ts
 import { ok, err, fromPromise } from '@stacksjs/error-handling'
-import type { Result, Ok, Err, ResultAsync } from '@stacksjs/error-handling'
-
-// Create results
-const success: Ok<string> = ok('data')
-const failure: Err<Error> = err(new Error('failed'))
 
-// From promises
-const result: ResultAsync<Data, Error> = fromPromise(fetchData())
-
-// Pattern matching
-if (result.isOk()) {
+const result = await fromPromise(Promise.resolve('ready'))
+if (result.isOk)
   console.log(result.value)
-} else {
+else
   console.error(result.error)
-}
-```
-
-## Error Handler
-
-```typescript
-import { handleError, ErrorHandler } from '@stacksjs/error-handling'
-
-// Function-based
-handleError(error)
-handleError(error, { shouldExit: true })
-
-// Class-based
-ErrorHandler.handle(error)
-ErrorHandler.handleError(error, { shouldExit: true })
-ErrorHandler.writeErrorToFile(error)
-ErrorHandler.writeErrorToConsole(error)
-```
-
-## Log File Writing
-
-```typescript
-import { writeToLogFile, setLogPath } from '@stacksjs/error-handling'
-
-setLogPath('/custom/log/path')
-await writeToLogFile('Error message', { path: '/custom/path' })
-```
-
-Default log path: `storage/logs/stacks.log`
-
-## Error Page Rendering
-
-```typescript
-import { ErrorPageHandler, renderError, renderErrorPage, renderProductionErrorPage, createErrorHandler, errorResponse } from '@stacksjs/error-handling'
-
-// Development: shows stack trace, source code, file paths
-const devPage = renderErrorPage(error, request)
-
-// Production: friendly error message, no internals
-const prodPage = renderProductionErrorPage(error, request)
-
-// Auto-detect environment
-const page = renderError(error, request)
-
-// Create handler for routes
-const handler = createErrorHandler()
-const response = errorResponse(error, request)
-```
-
-## HTTP Error Mapping
-
-```typescript
-import { HTTP_ERRORS } from '@stacksjs/error-handling'
-
-// Maps status codes to error details
-HTTP_ERRORS[400]  // { title: 'Bad Request', ... }
-HTTP_ERRORS[401]  // { title: 'Unauthorized', ... }
-HTTP_ERRORS[403]  // { title: 'Forbidden', ... }
-HTTP_ERRORS[404]  // { title: 'Not Found', ... }
-HTTP_ERRORS[500]  // { title: 'Internal Server Error', ... }
-```
-
-## Custom Exceptions
-
-```typescript
-import { ModelNotFoundException } from '@stacksjs/error-handling'
-
-throw new ModelNotFoundException('User not found')
-```
-
-## Error Page Types
-
-```typescript
-interface HttpError { status: number, title: string, message: string }
-interface StackFrame { file: string, line: number, column: number, function?: string }
-interface CodeSnippet { line: number, code: string, isHighlighted: boolean }
-```
-
-## Error Model (storage/framework/defaults/app/Models/Error.ts)
-
-Fields: type, message, stack (stacktrace), status, additional_info
-Seeder: 10 records for testing
-
-## config/errors.ts
-
-Contains comprehensive validation error messages for all field types:
-- String validation: required, minLength, maxLength, email, url, uuid, etc.
-- Number validation: required, min, max, positive, negative, integer, etc.
-- Enum validation: invalid value messages
-- Date validation: format, before, after, etc.
-- File validation: size, type, dimensions, etc.
-
-## Gotchas
-- Use `Result<T, E>` types instead of try/catch for recoverable errors
-- `ok()` and `err()` are from `ts-error-handling` (neverthrow-compatible)
-- Error pages automatically detect environment (dev shows stack traces, prod doesn't)
-- `handleError()` logs to both console and file
-- `ModelNotFoundException` is thrown by `findOrFail()` and `firstOrFail()` ORM methods
-- The Error model persists errors to the database for tracking
-- `config/errors.ts` is a comprehensive i18n-ready error message catalog
-- `ErrorHandler.isTestEnvironment` prevents process exit during tests
-- `ERROR_PAGE_CSS` contains built-in styling for error pages
+~~~
+
+ok(value)/err(error), Result/Ok/Err and ResultAsync are re-exported from
+ts-error-handling. isOk/isErr are discriminant properties, not methods.
+fromPromise returns a Promise<Result>; await it before narrowing. Returning an
+Err does not throw, and an awaited Result does not imply success.
+
+## HTTP errors and rendering
+
+~~~ts
+import { HttpError, renderHttpError } from '@stacksjs/error-handling'
+
+const error = new HttpError(422, 'Validation failed', { errors: { email: ['Required'] } })
+const response = await renderHttpError(error, undefined, { status: 422, isDevelopment: false })
+~~~
+
+renderHttpError returns a Response and accepts optional request/options.
+createHttpErrorHandler offers setRequest/setRouting/addQuery and status helpers.
+The lower-level renderErrorPage(error, status?, config?) and renderError(error,
+status?) are async HTML renderers. renderProductionErrorPage(status) is the
+synchronous production HTML renderer, not a function taking error/request.
+errorResponse(error, status?, config?) returns Promise<Response>.
+
+createErrorHandler(config?) returns the ErrorPageHandler builder; set request,
+routing/user/framework context on it, then await render/handleError. Explicitly
+resolve development mode for a public entrypoint rather than assuming an env
+alias's default will protect details. Production pages omit source/trace detail;
+custom error pages and illustration selection use the renderer's own contracts.
+
+HTTP_ERRORS is status metadata; exported HttpErrorInfo is its interface, distinct
+from the throwable HttpError class. ModelNotFoundException is the ORM failure
+type. isUniqueViolation recognizes provider uniqueness errors; map a business
+conflict deliberately rather than returning raw provider text.
+
+## Handling, reporting and shutdown
+
+handleError(value, options?) returns an Error synchronously and schedules logging.
+ErrorHandler.handle preserves an existing Error's trace/cause when possible.
+writeErrorToFile is async; writeErrorToConsole is sync. shouldExit is a process
+policy, not appropriate inside a request action. A background file write cannot
+be assumed finished before process.exit.
+
+writeToLogFile(message, { logFile? }) uses a file path; setLogPath changes its
+fallback. config/errors.ts holds validation messages, not all operational logging
+or monitoring configuration. An Error model definition does not itself persist
+every exception to its table.
+
+registerErrorReporter(reporter) returns a detach function; reporters() snapshots
+registered/configured reporters. captureError(error, context?) isolates reporter
+failure and deduplicates by Error object identity, not message text.
+flushErrorReporters drains buffers. Configured monitoring reporters and BugHQ
+use the shared environment gate; see stacks-env and config/monitoring.ts.
+The logging report() chokepoint filters ordinary 4xx from incident reporting.
+
+## Evidence
+
+Source: `storage/framework/core/error-handling/src/index.ts`, handler.ts,
+http.ts, error-page.ts, reporters.ts, bughq.ts and unique-violation.ts.
+Tests: result-type.test.ts, http-errors.test.ts, error-page-render.test.ts,
+custom-error-pages.test.ts and reporters.test.ts under core/error-handling/tests.
+Keep error payloads and credentials out of public responses and diagnostics.