@zyno-io/ts-server-foundation 26.712.36

package/docs/content/di.md

@@ -0,0 +1,212 @@
+# Dependency Injection
+
+TSF has a dependency injection container that uses reflected type metadata for constructor parameter types. It supports class providers, structured providers, scopes, modules, request contexts, and globally injectable exports from imported modules.
+
+## Basic Providers
+
+Register providers through `createApp()` or `createContainer()`:
+
+```ts
+import { createApp } from '@zyno-io/ts-server-foundation';
+
+class UserRepository {}
+
+class UserService {
+    constructor(readonly users: UserRepository) {}
+}
+
+const app = createApp({
+    providers: [UserRepository, UserService]
+});
+
+const service = app.get(UserService);
+```
+
+Constructor dependencies are inferred from reflected class types. Optional constructor parameters are injected only when a matching provider is registered.
+
+## Structured Providers
+
+```ts
+const TOKEN = Symbol('token');
+
+const app = createApp({
+    providers: [
+        { provide: TOKEN, useValue: 7 },
+        { provide: BaseUserService, useClass: UserService },
+        { provide: CurrentUserService, useExisting: BaseUserService },
+        {
+            provide: UserPresenter,
+            useFactory: (users: UserService) => new UserPresenter(users),
+            deps: [UserService]
+        }
+    ]
+});
+```
+
+Supported provider forms:
+
+| Provider           | Behavior                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| Class              | Singleton class provider by default.                                                            |
+| `useValue`         | Static singleton value.                                                                         |
+| `useClass`         | Instantiate a concrete class for a token.                                                       |
+| `useExisting`      | Alias another provider token and preserve the target provider's scope.                          |
+| `useFactory`       | Call a factory with explicit `deps`.                                                            |
+| `useTargetFactory` | Call a factory with the consuming class target plus explicit `deps`. Useful for scoped loggers. |
+
+## Scopes
+
+Provider scopes are:
+
+| Scope       | Behavior                                                                               |
+| ----------- | -------------------------------------------------------------------------------------- |
+| `singleton` | One instance per container. Default for class, `useClass`, and `useFactory` providers. |
+| `transient` | New instance per resolution. Default for `useExisting` and `useTargetFactory`.         |
+| `request`   | One instance per request context. Requires a request context.                          |
+| `http`      | Legacy alias for `request`; normalized to request scope.                               |
+
+```ts
+const app = createApp({
+    providers: [{ provide: RequestState, useClass: RequestState, scope: 'request' }]
+});
+```
+
+Request-scoped providers cannot be captured by singletons. The container throws `ScopeMismatchError` instead of letting a singleton hold request-local state forever.
+
+The same rule applies to request-local values placed directly in `RequestContext.instances`: resolving them through a singleton factory is rejected. Request-scoped and transient consumers may depend on request-scoped providers when they are resolved with a context. A transient consumer is rebuilt on every resolution, while its request-scoped dependency is reused within that context. The legacy `scope: 'http'` spelling is normalized to `request` and has identical caching and error behavior.
+
+## Modules And Global Exports
+
+Modules are plain definitions created with `createModule()` or `new AppModule()`.
+
+```ts
+import { createApp, createModule } from '@zyno-io/ts-server-foundation';
+
+class ExportedService {}
+class HiddenService {}
+
+const featureModule = createModule({
+    providers: [ExportedService, HiddenService],
+    exports: [ExportedService]
+});
+
+class Consumer {
+    constructor(readonly service: ExportedService) {}
+}
+
+const app = createApp({
+    imports: [featureModule],
+    providers: [Consumer]
+});
+```
+
+An exported provider from a module imported by the root app is globally injectable. Consumers do not need to explicitly import the feature module at their own declaration site.
+
+Non-exported providers stay local to their module. Transitive exports do not leak unless the intermediate module re-exports them.
+
+Duplicate global exports are rejected with `DuplicateProviderError`.
+
+Module definitions can also declare `controllers`, `listeners`, and `commands`. `createApp()` walks imported modules recursively, registers their controllers as request-scoped providers, wires decorated listeners, and makes decorated commands available to app command dispatch. Controllers must use `@http.controller()`; commands must use `@cli.command()` or `@cli.controller()`.
+
+## Request Context
+
+The HTTP router creates a request context for controller and middleware resolution. Request-scoped providers resolve from that context.
+
+For manual container usage:
+
+```ts
+import { createContainer } from '@zyno-io/ts-server-foundation';
+
+const container = createContainer({
+    providers: [{ provide: RequestState, useClass: RequestState, scope: 'request' }]
+});
+
+const context = container.createRequestContext();
+const state = container.get(RequestState, context);
+```
+
+Resolving a request-scoped provider without a request context throws `RequestScopeError`.
+
+## Controller Lifecycle
+
+HTTP controllers are registered as request-scoped providers by `createApp()`. A matched route creates a request context, resolves the controller inside that context, invokes the route method, and then lets the context go.
+
+Normal injected services are singletons by default. This means a controller instance is per request, but a constructor-injected repository/service stays shared unless its provider is explicitly registered with `scope: 'request'` or `scope: 'transient'`.
+
+## Application Lifecycle
+
+`App` exposes five lifecycle tokens:
+
+| Token                       | Dispatch point                                                                                                       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `onAppBootstrap`            | At the start of `app.start()`, before database construction, `AutoConstruct` providers, and the worker runner.       |
+| `onServerBootstrap`         | After the Node HTTP server has successfully bound and after signal handlers/DevConsole startup.                      |
+| `onServerMainBootstrapDone` | Immediately after all `onServerBootstrap` handlers complete.                                                         |
+| `onServerShutdownRequested` | First step of a started app's `stop()` sequence, before framework-owned resources are closed.                        |
+| `onServerShutdown`          | After worker services, signal handlers, DevConsole, and the owned HTTP server are closed; before telemetry shutdown. |
+
+`app.start()` dispatches only application bootstrap. `app.http.listen()` calls `start()` automatically and then dispatches the two server-bootstrap tokens after binding. Calling `start()` concurrently shares the in-flight startup work; calling it again after startup is a no-op. After a completed `stop()`, a later `start()` is a new lifecycle and dispatches bootstrap again.
+
+Register a direct handler with `app.on()`:
+
+```ts
+import { onAppBootstrap } from '@zyno-io/ts-server-foundation';
+
+const unsubscribe = app.on(
+    onAppBootstrap,
+    async () => {
+        await warmCache();
+    },
+    10
+);
+```
+
+Or register a DI-backed listener class:
+
+```ts
+import { createApp, event, onAppBootstrap } from '@zyno-io/ts-server-foundation';
+
+class LifecycleListener {
+    constructor(private readonly service: UserService) {}
+
+    @event.listen(onAppBootstrap, 10)
+    async warm() {
+        await this.service.warmCache();
+    }
+}
+
+const app = createApp({ listeners: [LifecycleListener] });
+```
+
+Handlers run sequentially in descending numeric `order`; handlers with the same order retain registration order. `app.on()` registers the callback directly and returns an unsubscribe function. Decorated methods are discovered only on classes listed in `listeners` (including imported-module listeners); those classes are registered with DI and resolved when the event dispatches.
+
+`@AutoConstruct()` follows the provider graph rather than scanning every decorated class in the program. During startup, TSF instantiates only decorated classes already registered as class or `useClass` providers, including registered providers in imported modules. The decorator does not register a class. A configured database is constructed before these providers so entity metadata is ready for startup services.
+
+If worker-runner startup fails, the app attempts both runner and queue-registry rollback. A rollback failure is attached as the startup error's cause when possible; otherwise startup and rollback failures are combined in an `AggregateError`.
+
+`app.stop()` is idempotent after shutdown and does nothing before startup. For a started app it dispatches `onServerShutdownRequested`, closes enabled worker runner/queue resources, removes installed signal handlers, closes DevConsole and the owned HTTP listener, dispatches `onServerShutdown`, then shuts down installed TSF telemetry. A failed listener or framework cleanup step does not prevent later steps from running; after cleanup, `stop()` rethrows the single failure or an `AggregateError` containing multiple failures. It does not infer teardown methods on arbitrary DI providers and does not close a configured database driver; use a shutdown listener for application-owned database clients, Redis clients, or other resources. SIGINT/SIGTERM handlers are installed only after an HTTP listener binds and call `app.stop()` before exiting.
+
+## App-Level Resolution
+
+Use constructor injection first. When you need to resolve from the current app outside constructor injection, use `resolve()` or `r()`:
+
+```ts
+import { BaseAppConfig, r, resolve } from '@zyno-io/ts-server-foundation';
+
+const config = resolve(BaseAppConfig);
+const sameConfig = r(BaseAppConfig);
+```
+
+`resolve()` uses the current app created by `createApp()`.
+
+## Errors
+
+Common DI errors:
+
+| Error                    | Meaning                                                           |
+| ------------------------ | ----------------------------------------------------------------- |
+| `ProviderNotFoundError`  | No provider is visible for the requested token.                   |
+| `DuplicateProviderError` | Two imported modules expose the same token as a global export.    |
+| `CyclicDependencyError`  | Constructor/factory dependency graph contains a cycle.            |
+| `RequestScopeError`      | A request-scoped provider was resolved without a request context. |
+| `ScopeMismatchError`     | A singleton attempted to capture request-scoped state.            |

package/docs/content/documentation-plan.md

@@ -0,0 +1,182 @@
+# Documentation Maintenance
+
+This page defines how TSF documentation is kept current as implementation changes.
+
+## Update Rules
+
+- Prefer examples that compile against `@zyno-io/ts-server-foundation`.
+- Import application APIs from the package root unless a page documents the sole supported subpath, `/otel`.
+- Keep HTTP parameter examples explicit: `HttpBody`, `HttpQueries`, `HttpQuery`, `HttpPath`, `HttpHeader`, `FileUpload`, and `HttpRequest`.
+- Keep database examples focused on `BaseDatabase`, sessions, active-record helpers, migrations, and SQL fragments.
+- Document environment keys through `Env` and config classes instead of direct `process.env` access.
+- Run `corepack yarn docs:build` after sidebar, link, frontmatter, or VitePress config changes.
+
+## Content Map
+
+Core application pages:
+
+- `getting-started.md`
+- `public-api.md`
+- `di.md`
+- `configuration.md`
+- `env.md`
+- `http.md`
+- `uploads.md`
+- `openapi.md`
+- `authentication.md`
+- `health.md`
+- `logging.md`
+- `reflection.md`
+- `type-reflection-architecture.md`
+- `types.md`
+
+Database pages:
+
+- `database.md`
+- `sql.md`
+- `migrations.md`
+
+Services and runtime pages:
+
+- `worker.md`
+- `redis.md`
+- `srpc.md`
+- `devconsole.md`
+- `leader-service.md`
+- `mail.md`
+- `mesh-service.md`
+- `mesh-client.md`
+
+Utilities and operations pages:
+
+- `helpers.md`
+- `telemetry.md`
+- `testing.md`
+- `cli.md`
+- `release.md`
+- `documentation-plan.md`
+
+## Change Checklist
+
+When an API changes:
+
+1. Update the feature page that owns the API.
+2. Update [Public API](./public-api.md) if exports or supported import paths change.
+3. Update [Configuration](./configuration.md) and [Environment](./env.md) if environment keys or config defaults change.
+4. Update [OpenAPI](./openapi.md) if route metadata, response typing, or schema output changes.
+5. Update [Testing](./testing.md) when testing helpers or required local services change.
+6. Rebuild the docs with `corepack yarn docs:build`.
+
+## Optional Improvements
+
+- Add deployment examples once a standard TSF app deployment shape is finalized.
+- Add generated API reference pages if the package adopts a docs extractor.
+- Extract and compile every TypeScript documentation fence if the representative package-import smoke test is expanded into executable documentation.
+- Add an isolated publish/install fixture for shared-package `__tsfTypeAliases` metadata.
+- Extend conditional live MySQL and PostgreSQL coverage to exercise every schema-builder operation in addition to the fake-driver SQL checks.
+- Automate DevConsole screenshot capture if screenshots need regular refreshes.
+
+## Audit Progress Record
+
+The main code-to-docs audit was implemented in three phases. A second-pass review found additional operational and adversarial cases, recorded below rather than treating the audit as fully closed. Service-backed integration suites skip when their required Redis, MySQL, or PostgreSQL environment is not configured.
+
+### Legacy Coverage Baseline
+
+The July 2026 documentation pass compared the full `dk-server-foundation` README and every page in its documentation directory against TSF. Each durable feature area has a current TSF destination: application/lifecycle/DI, configuration, database and migrations, HTTP/CORS/uploads, authentication, workers, SRPC, Redis/leader/mesh, mail, telemetry, health, helpers, testing, types, logging, DevConsole, and CLI operations are linked from [Feature Overview](./overview.md).
+
+The comparison does not copy Deepkit-specific classes, decorators, ORM connection types, Jest behavior, or removed commands into TSF docs. Where TSF kept or replaced the capability, the current API is documented instead. The pass added explicit coverage for the process model and operational defaults; the complete CLI; trusted proxy addresses and request caching; test facade lifecycle, global setup, and module reset; telemetry resources and remote span inputs; worker metadata and observers; SRPC codec/stream types, pending byte-stream limits, and the current telemetry boundary; calendar-version generation; and GitHub Pages deployment.
+
+TSF-only material remains separately documented for its native DI and reflection pipeline, environment snapshots, PostgreSQL, SQL fragments, schema diffs and migrations, multipart/raw uploads, OpenAPI generation, public export policy, mesh client tracking, and reflection architecture. The root README intentionally stays short and points to the overview and full documentation index instead of duplicating these guides.
+
+### Phase 1: Settled Contracts
+
+Completed in the first implementation pass:
+
+1. A missing non-optional standalone `FileUpload` returns `400`; optional uploads receive `undefined`. Runtime and OpenAPI tests cover non-multipart, text-only multipart, wrong-field, required, and optional cases.
+2. Routes with multiple `HttpBody` parameters fail registration. This avoids the previous runtime/OpenAPI shape conflict.
+3. An optional `HttpQueries<T>` receives `undefined` when no query is present, and its expanded OpenAPI query parameters are non-required.
+4. Collision-prone `cast<T>()`, `assert<T>()`, and `is<T>()` are compiler-recognized only when import identity proves that they come from the foundation package. They fail closed when metadata is absent, with focused runtime and compiler-policy tests.
+5. Relation lookup/grouping helpers preserve numeric ID `0`, with direct, keyed, grouped, and pivot-relation coverage.
+
+### Phase 2: Core Guides
+
+Completed coverage includes project setup and scaffold anatomy; routing, middleware, request scope, and lifecycle order; HTTP headers, queries, bodies, encodings, streams, responses, observers, and port `0`; upload selection, MIME policies, and temporary-file lifetime; logger levels, contexts, sinks, and alerting; JWT configuration, token precedence, entity validation, and verification warnings; application lifecycle and DI; and the OpenAPI configuration and runtime/schema parity rules.
+
+Typed multi-file parameter arrays are not supported. A direct `FileUpload` selects one file, while handlers that need every file read `HttpRequest.uploadedFiles`.
+
+### Phase 3: Feature References
+
+Completed coverage includes the public reflection API and shared-package metadata; database sessions, relations, SQL, schema building, and migrations; exported helpers and supported package entry points; SRPC handshakes, handlers, reconnect behavior, and errors; mesh-client reservations, activation, delivery, and metadata synchronization; worker execution modes; telemetry; and DevConsole operation. Type Reflection Architecture and this maintenance page are included in navigation.
+
+Among the implementation defects fixed by the audit are required-upload enforcement, optional aggregate-query parity, relation ID `0` preservation, malformed-path and request-encoding handling, HEAD response parity, upload cleanup/order, remote mesh-client metadata persistence, and JSDoc-derived OpenAPI operation summaries.
+
+### Verification Coverage
+
+The audit added focused checks for:
+
+- documentation links, headings, navigation coverage, representative root and `/otel` imports, and the VitePress production build in CI;
+- HTTP routing, middleware, headers, bodies, encodings, streams, uploads, cleanup, response behavior, and Node/in-memory parity;
+- OpenAPI environment and route-flag precedence, internal routes, security, summaries, and nested body-file schemas;
+- JWTs, authentication entities, logging, lifecycle, DI, reflection, SQL guards, sessions, schema building, and migration failure ordering;
+- selected DevConsole, worker, SRPC, mesh, leader-service, and telemetry success and failure paths.
+
+Redis-, MySQL-, and PostgreSQL-backed cases are conditional integration tests. Configure the service-specific environment described in [Testing](./testing.md) to run them; an absent service skips those cases rather than changing the package contract.
+
+### Confirmed Corrections Awaiting Focused Coverage
+
+The second and third review passes found objective defects and documentation errors that have been corrected. The following regression cases are still planned; they are not behavior decisions:
+
+1. HTTP and application lifecycle:
+    - make worker startup and both worker rollback steps fail independently, verifying that every cleanup is attempted without losing the startup error;
+    - exercise a post-bind bootstrap failure and verify that the listener and app-owned resources roll back;
+    - make both composed rollback hooks fail and prove that each is attempted and their failures are preserved;
+    - make multiple `App.stop()` steps fail and verify later cleanup plus single/aggregate rethrow behavior;
+    - cover `onResponse` failure before and after Node headers commit;
+    - cover `flushHeaders(); end(body)` and prove that the Node response completes with the body.
+2. Data, types, and reflection:
+    - cover present hostile keys (`__proto__`, `constructor`, `toString`) in public keyed results, absent hostile keys during relation resolution, same-key additional filters, and number/bigint ID `0`;
+    - cover explicit-secret `Crypto` construction before app creation, with both default and explicit IV lengths;
+    - reject a non-NANP international number through `PhoneNumberNANP` while retaining valid country-code-1 inputs;
+    - load the built health controller from compiled package output and verify working-directory package-version resolution.
+3. Runtime services and observability:
+    - cover sequential partial mesh-start rollback and instance deregistration;
+    - prove that DevConsole broadcasts target only active SRPC streams, falsy secret values are masked, and the database-query index evicts with its ring entry;
+    - cover metrics option/environment precedence, socket-peer authorization with spoofed forwarding headers, synchronous and asynchronous provider shutdown failures, reset failures, and state clearing;
+    - cover a throwing global error reporter without suppressing later reporting, and assert that `Logger.data()` preserves the parent scope.
+
+### Decision Register
+
+These items intentionally remain unchanged until the project chooses a contract:
+
+1. Authentication and network policy:
+    - Should generated OpenAPI advertise configured JWT-cookie authentication in addition to Bearer authentication? Runtime accepts both, while the current document intentionally describes only Bearer.
+    - Is a private transport peer sufficient authorization for `/metrics`, or should it be localhost-only, authenticated, or controlled by an explicit allowlist? A public client behind a private reverse proxy appears as that private peer.
+2. Concurrent lifecycle behavior:
+    - Should concurrent `HttpServerRuntime.listen()` and `App.stop()` calls coalesce, reject, or follow another contract?
+    - Should concurrent `MeshService.start()` calls reject or coalesce, and should `stop()` during startup wait, cancel startup, or reject?
+3. Data and reflection semantics:
+    - Should migration tracking-write failure after a successful `up()` be reconciled, retried, or transactionally coupled where the dialect permits?
+    - Should tuples reject trailing input at direct validation and deserializing/HTTP boundaries, or should deserialization continue to project only declared positions?
+    - Should public keyed database helpers retain ordinary object prototypes for compatibility or return null-prototype dictionaries so every absent hostile key reads as `undefined`?
+4. Mesh and SRPC semantics:
+    - Should the Redis client-registry safety TTL be refreshed from mesh liveness, replaced with per-client leases, or removed?
+    - Should explicit MeshSrpc metadata updates merge, replace, or support explicit deletion, and how should live and registry state resolve races?
+    - Should both SRPC invocation directions preserve/expose `SrpcError.userError`, and should malformed established server frames be ignored or close the client?
+5. Worker and DevConsole policy:
+    - Is recorder persistence part of successful job execution, and how should recorder failure combine with an original handler failure?
+    - What timeout/cancellation contract should runner shutdown use for hanging handlers?
+    - Should `WorkerRecorderService` be bounded, and if so independently of the DevConsole's 200-entry view?
+    - Should process-global database, SRPC, worker, and mutex observers gain per-app ownership filtering?
+6. Compatibility and release operations:
+    - Should removed legacy telemetry subpaths, the `serializer` name, deleted conversion tooling, and removed standalone OpenAPI options retain deprecated compatibility aliases for a transition release?
+    - Confirm whether main-branch CI should publish to public npm and force-push the GitHub `main` mirror.
+
+### Planned Fixtures And Quality Gates
+
+These gaps do not require a product behavior choice, but do require broader fixtures or test infrastructure:
+
+1. Extend live schema-builder coverage across both supported database engines and add a real migrated `_jobs` table fixture once recorder failure semantics are settled.
+2. Cover pending versus active SRPC maps, rejected-conflict callbacks, metadata races under the chosen semantics, and quiet-client Redis expiry under the chosen registry policy.
+3. Scan root and nested Markdown, reverse-check sidebar/navigation targets, and either adopt a Markdown parser or define the regex gate's supported Markdown subset.
+4. Add dynamic ESM import and packed-install checks, plus assertions that `/otel` exposes only its intended bootstrap surface.
+5. Compile documentation fences selectively, starting with setup, middleware, uploads, authentication, logging, and mail examples.

package/docs/content/env.md

@@ -0,0 +1,120 @@
+# Environment
+
+TSF centralizes environment access through the exported `Env` object and config loader. Application code should prefer `Env` and reflected config classes over direct `process.env` reads.
+
+## `Env`
+
+`Env` is preloaded with `process.env` and typed as optional strings.
+
+```ts
+import { Env } from '@zyno-io/ts-server-foundation';
+
+const adapter = Env.DB_ADAPTER; // string | undefined
+Env.APP_ENV = 'development';
+delete Env.PORT;
+```
+
+Reading or writing `Env` reads or writes `process.env` at runtime. This keeps all known keys discoverable in one interface while preserving Node environment behavior.
+
+## Snapshots
+
+Tests can snapshot and restore the full environment.
+
+```ts
+import { applyEnv, envSnapshot } from '@zyno-io/ts-server-foundation';
+
+const before = envSnapshot();
+
+try {
+    applyEnv({ APP_ENV: 'test', DB_ADAPTER: 'postgres' });
+    // run isolated logic
+} finally {
+    applyEnv(before);
+}
+```
+
+Helpers:
+
+| Helper               | Description                                                          |
+| -------------------- | -------------------------------------------------------------------- |
+| `envSnapshot()`      | Returns a shallow copy of the current `Env`.                         |
+| `applyEnv(env)`      | Clears `process.env` and replaces it with defined values from `env`. |
+| `toProcessEnv(env?)` | Converts an `EnvObject` to a plain `NodeJS.ProcessEnv`.              |
+
+## Config Loading
+
+`ConfigLoader` loads a reflected config class from dotenv files and `Env` using `@zyno-io/config`.
+
+```ts
+import { BaseAppConfig, ConfigLoader } from '@zyno-io/ts-server-foundation';
+
+class AppConfig extends BaseAppConfig {
+    FEATURE_ENABLED = false;
+    API_TIMEOUT_MS = 5000;
+}
+
+const config = new ConfigLoader(AppConfig).load();
+```
+
+File load order from the current working directory:
+
+1. `.env`
+2. `.env.local`
+3. `.env.development` and `.env.development.local` when running tests
+4. `.env.${APP_ENV}`
+5. `.env.${APP_ENV}.local`
+6. Values already present in `Env`
+
+Later values override earlier values. Config loading does not delete consumed keys from `process.env`, so loaded values remain available to later code and child processes. `_SECRET` keys are decrypted by `@zyno-io/config` when `CONFIG_DECRYPTION_SECRET` or the legacy `CONFIG_DECRYPTION_KEY` is present.
+
+## Defaults
+
+`APP_ENV` is required in production. Outside production, it defaults automatically:
+
+| Condition                                    | Default       |
+| -------------------------------------------- | ------------- |
+| Node test context is active                  | `test`        |
+| `NODE_ENV !== 'production'`                  | `development` |
+| `NODE_ENV === 'production'` and no `APP_ENV` | Error         |
+
+## Type Coercion
+
+Config values are strings when read from files or environment. The loader coerces reflected number and boolean fields.
+
+```ts
+class AppConfig extends BaseAppConfig {
+    PORT = 3000; // "8080" becomes 8080
+    ENABLE_CACHE = false; // "true" or "1" becomes true
+}
+```
+
+Literal boolean and number types are also coerced.
+
+## Loaded Environment Keys
+
+When a config property is loaded from `Env`, the loader leaves that key in `Env` after loading. This keeps Node's process environment intact for later code and child processes.
+
+```ts
+Env.PORT = '8080';
+const config = new ConfigLoader(BaseAppConfig).load();
+
+config.PORT; // 8080
+Env.PORT; // "8080"
+```
+
+## Common Keys
+
+The runtime recognizes these built-in config and environment keys. Most are reflected `BaseAppConfig` properties; early telemetry bootstrap also reads its `OTEL_*` controls directly from `Env`:
+
+- application and HTTP: `APP_ENV`, `DEVCONSOLE_ENABLED`, `PORT`, `USE_REAL_IP_HEADER`, `HTTP_MAX_REQUEST_BODY_BYTES`, `HTTP_MAX_REQUEST_COMPRESSED_BODY_BYTES`
+- database: `DB_ADAPTER`, `MYSQL_*`, `PG_*`
+- auth: `AUTH_JWT_*`, `AUTH_BASIC_SECRET`
+- Redis and workers: `REDIS_*`, `CACHE_REDIS_*`, `MUTEX_REDIS_*`, `BROADCAST_REDIS_*`, `MESH_REDIS_*`, `BULL_REDIS_*`, `BULL_QUEUE`, `MUTEX_MODE`, `ENABLE_JOB_RUNNER`
+- OpenAPI: `ENABLE_OPENAPI_ROUTE`, `ENABLE_OPENAPI_SCHEMA`
+- logging: `HTTP_REQUEST_LOGGING_MODE`, `HEALTHZ_ENABLE_REQUEST_LOGGING`, `ENABLE_PINO_PRETTY`, `ENABLE_PINO_SINGLE_LINE`, `LOG_LEVEL`
+- telemetry: `SENTRY_DSN`, `OTEL_*`, `ALERTS_SLACK_WEBHOOK_URL`
+- SRPC: `SRPC_AUTH_SECRET`, `SRPC_AUTH_CLOCK_DRIFT_MS`
+- mail: `MAIL_*`, `SMTP_*`, `POSTMARK_SECRET`
+- tests and tooling: `TEST_KEEP_DB`, `TEST_RUN_TS`, `TSF_TEST_*`, `PROTOC`
+
+See [Configuration](./configuration.md) for the value-level config reference.