@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki → content}/extensions/components/static-asset/index.md

@@ -129,16 +129,16 @@ export class Application extends BaseApplication {
 The component auto-registers REST endpoints for each configured backend. No injection needed in downstream code.
 
 ```
-GET    /assets/buckets                                — List all buckets
-GET    /assets/buckets/:bucketName                    — Get bucket details (or null)
-POST   /assets/buckets/:bucketName                    — Create a bucket
-DELETE /assets/buckets/:bucketName                    — Delete a bucket
-POST   /assets/buckets/:bucketName/upload             — Upload files
-GET    /assets/buckets/:bucketName/objects             — List objects in bucket
-GET    /assets/buckets/:bucketName/objects/:obj        — Stream file inline
-GET    /assets/buckets/:bucketName/objects/:obj/download — Download file (attachment)
-DELETE /assets/buckets/:bucketName/objects/:obj        — Delete file
-PUT    /assets/buckets/:bucketName/objects/:obj/meta-links — Sync MetaLink (MetaLink only)
+GET    /assets/buckets                                - List all buckets
+GET    /assets/buckets/:bucketName                    - Get bucket details (or null)
+POST   /assets/buckets/:bucketName                    - Create a bucket
+DELETE /assets/buckets/:bucketName                    - Delete a bucket
+POST   /assets/buckets/:bucketName/upload             - Upload files
+GET    /assets/buckets/:bucketName/objects             - List objects in bucket
+GET    /assets/buckets/:bucketName/objects/:obj        - Stream file inline
+GET    /assets/buckets/:bucketName/download/:obj        - Download file (attachment)
+DELETE /assets/buckets/:bucketName/objects/:obj        - Delete file
+PUT    /assets/buckets/:bucketName/meta-links/:obj      - Sync MetaLink (MetaLink only)
 ```
 
 Each storage backend gets its own base path (`/assets`, `/resources`, etc.) with the same endpoint structure.
@@ -237,12 +237,12 @@ Each route can be individually configured with authentication, middleware, and p
     name: 'AssetController',
     basePath: '/assets',
     routes: {
-      getBuckets: { authenticate: { strategies: ['jwt'], mode: 'required' } },
-      upload: { authenticate: { strategies: ['jwt'], mode: 'required' }, middleware: [rateLimitMw] },
+      getBuckets: { authenticate: { strategies: ['jwt'], mode: 'any' } },
+      upload: { authenticate: { strategies: ['jwt'], mode: 'any' }, middleware: [rateLimitMw] },
       getObjectByName: { /* public -- no authenticate */ },
       downloadObjectByName: { /* public */ },
-      deleteObject: { authenticate: { strategies: ['jwt'], mode: 'required' } },
-      deleteBucket: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+      deleteObject: { authenticate: { strategies: ['jwt'], mode: 'any' } },
+      deleteBucket: { authenticate: { strategies: ['jwt'], mode: 'any' } },
     },
   },
   // ...
@@ -288,11 +288,13 @@ type TStaticAssetExtraOptions = {
   };
   normalizeNameFn?: (opts: { originalName: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+  /** Maximum folder nesting depth allowed in object paths. Default: 2 */
+  maxFolderDepth?: number;
   [key: string]: any;
 };
 
 type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
-  model: typeof BaseEntity<Schema>;
+  model: typeof BasePostgresEntity<Schema>;
   repository: DefaultCRUDRepository<Schema>;
   createMetaLink?: (opts: {
     uploadResult: IUploadResult;
@@ -393,7 +395,8 @@ MetaLink is an optional feature that tracks uploaded files in a database, storin
 **1. Create Model:**
 
 ```typescript
-import { BaseMetaLinkModel, model } from '@venizia/ignis/static-asset';
+import { BaseMetaLinkModel } from '@venizia/ignis/static-asset';
+import { model } from '@venizia/ignis';
 
 @model({ type: 'entity' })
 export class FileMetaLinkModel extends BaseMetaLinkModel {
@@ -405,18 +408,13 @@ export class FileMetaLinkModel extends BaseMetaLinkModel {
 
 ```typescript
 import { BaseMetaLinkRepository } from '@venizia/ignis/static-asset';
-import { repository, inject } from '@venizia/ignis';
-import type { IDataSource } from '@venizia/ignis';
+import { repository } from '@venizia/ignis';
+import { FileMetaLinkModel } from './file-meta-link.model';
+import { PostgresDataSource } from '../datasources/postgres.datasource';
 
-@repository({})
+@repository({ model: FileMetaLinkModel, dataSource: PostgresDataSource })
 export class FileMetaLinkRepository extends BaseMetaLinkRepository {
-  constructor(@inject({ key: 'datasources.postgres' }) dataSource: IDataSource) {
-    super({
-      entityClass: FileMetaLinkModel,
-      relations: {},
-      dataSource,
-    });
-  }
+  // No constructor needed - dataSource auto-injected from @repository metadata
 }
 ```
 
@@ -427,8 +425,8 @@ The model has `skipMigrate: true`, so create the table manually:
 ```sql
 CREATE TABLE "MetaLink" (
   id              TEXT PRIMARY KEY,
-  created_at      TIMESTAMP NOT NULL DEFAULT NOW(),
-  modified_at     TIMESTAMP NOT NULL DEFAULT NOW(),
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  modified_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   bucket_name     TEXT NOT NULL,
   object_name     TEXT NOT NULL,
   link            TEXT NOT NULL,

package/{wiki → content}/extensions/components/static-asset/usage.md

@@ -15,9 +15,9 @@ The component dynamically generates REST endpoints for each configured storage b
 | `POST` | <code v-pre>/{basePath}/buckets/:bucketName/upload</code> | Upload files |
 | `GET` | <code v-pre>/{basePath}/buckets/:bucketName/objects</code> | List objects |
 | `GET` | <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName</code> | Stream file |
-| `GET` | <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName/download</code> | Download file |
+| `GET` | <code v-pre>/{basePath}/buckets/:bucketName/download/:objectName</code> | Download file |
 | `DELETE` | <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName</code> | Delete object |
-| `PUT` | <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName/meta-links</code> | Sync MetaLink (MetaLink only) |
+| `PUT` | <code v-pre>/{basePath}/buckets/:bucketName/meta-links/:objectName</code> | Sync MetaLink (MetaLink only) |
 
 #### GET <code v-pre>/{basePath}/buckets</code>
 **Response `200`:**
@@ -74,6 +74,7 @@ The `isDeleted` field is a boolean indicating whether the bucket was successfull
 - `principalType` (optional, string): Type of the principal to associate with the uploaded files (e.g., `"user"`, `"service"`)
 - `principalId` (optional, string or number): ID of the principal. Always coerced to a string via `String()` before storage regardless of input type
 - `variant` (optional, string): Variant tag for the upload (e.g., `"thumbnail"`, `"original"`)
+- `folderPath` (optional, string): Target folder path for uploaded files (e.g., `"photos/2024"`). Each segment is validated with `isValidName()` and the segment count must not exceed the configured `maxFolderDepth` (default 2); returns 400 on violation
 
 **Validation:** Bucket name validated with `isValidName()`. Returns 400 `"Invalid bucket name"` if invalid.
 
@@ -187,7 +188,7 @@ All fields in the `IObjectInfo` response are optional. The `prefix` field is pre
 - `bucketName` (path): Bucket name
 - `objectName` (path): Object name (URL-encoded)
 
-**Validation:** Both bucket and object names validated with `isValidName()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name"` respectively if either is invalid.
+**Validation:** Bucket name validated with `isValidName()`; object name validated with `isValidPath()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name or path"` respectively if either is invalid.
 
 **Response:**
 - Streams file content with appropriate headers
@@ -196,12 +197,12 @@ All fields in the `IObjectInfo` response are optional. The `prefix` field is pre
 - `X-Content-Type-Options`: `nosniff`
 - Additional whitelisted headers forwarded from storage metadata (see [Header Sanitization](./api#header-sanitization))
 
-#### GET <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName/download</code>
+#### GET <code v-pre>/{basePath}/buckets/:bucketName/download/:objectName</code>
 **Parameters:**
 - `bucketName` (path): Bucket name
 - `objectName` (path): Object name (URL-encoded)
 
-**Validation:** Both bucket and object names validated with `isValidName()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name"` respectively if either is invalid.
+**Validation:** Bucket name validated with `isValidName()`; object name validated with `isValidPath()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name or path"` respectively if either is invalid.
 
 **Response:**
 - Streams file with download headers
@@ -214,7 +215,7 @@ All fields in the `IObjectInfo` response are optional. The `prefix` field is pre
 
 **Example:**
 ```typescript
-const downloadUrl = `/assets/buckets/uploads/objects/${encodeURIComponent('document.pdf')}/download`;
+const downloadUrl = `/assets/buckets/uploads/download/${encodeURIComponent('document.pdf')}`;
 window.open(downloadUrl, '_blank');
 ```
 
@@ -223,7 +224,7 @@ window.open(downloadUrl, '_blank');
 - `bucketName` (path): Bucket name
 - `objectName` (path): Object to delete (URL-encoded)
 
-**Validation:** Both bucket and object names validated with `isValidName()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name"` respectively if either is invalid.
+**Validation:** Bucket name validated with `isValidName()`; object name validated with `isValidPath()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name or path"` respectively if either is invalid.
 
 **Behavior:**
 - Deletes file from storage
@@ -248,14 +249,14 @@ await fetch(`/assets/buckets/${bucketName}/objects/${encodeURIComponent(objectNa
 // MetaLink record deletion initiated (if enabled) but may complete after response
 ```
 
-#### PUT <code v-pre>/{basePath}/buckets/:bucketName/objects/:objectName/meta-links</code>
+#### PUT <code v-pre>/{basePath}/buckets/:bucketName/meta-links/:objectName</code>
 **Availability:** Only registered when `useMetaLink: true`.
 
 **Parameters:**
 - `bucketName` (path): Bucket name
 - `objectName` (path): Object name (URL-encoded)
 
-**Validation:** Both bucket and object names validated with `isValidName()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name"` respectively if either is invalid.
+**Validation:** Bucket name validated with `isValidName()`; object name validated with `isValidPath()`. Returns 400 `"Invalid bucket name"` or `"Invalid object name or path"` respectively if either is invalid.
 
 **Behavior:**
 - Fetches current file metadata from storage via `helper.getStat()`
@@ -302,7 +303,7 @@ const bucketName = 'user-uploads';
 const objectName = 'document.pdf';
 
 const response = await fetch(
-  `/assets/buckets/${bucketName}/objects/${encodeURIComponent(objectName)}/meta-links`,
+  `/assets/buckets/${bucketName}/meta-links/${encodeURIComponent(objectName)}`,
   { method: 'PUT' }
 );
 
@@ -315,7 +316,7 @@ const objects = await fetch(`/assets/buckets/${bucketName}/objects`).then(r => r
 
 for (const obj of objects) {
   await fetch(
-    `/assets/buckets/${bucketName}/objects/${encodeURIComponent(obj.name)}/meta-links`,
+    `/assets/buckets/${bucketName}/meta-links/${encodeURIComponent(obj.name)}`,
     { method: 'PUT' }
   );
 }
@@ -345,7 +346,7 @@ async function uploadFile(file: File, principalType?: string, principalId?: stri
 
 // Download file
 function downloadFile(bucketName: string, objectName: string) {
-  const url = `/assets/buckets/${bucketName}/objects/${encodeURIComponent(objectName)}/download`;
+  const url = `/assets/buckets/${bucketName}/download/${encodeURIComponent(objectName)}`;
   window.open(url, '_blank');
 }
 

package/{wiki → content}/extensions/components/template/index.md

@@ -1,6 +1,6 @@
 # Component Documentation Template
 
-Guide for writing consistent, professional component reference docs for Ignis.
+Guide for writing consistent, professional component reference docs for IGNIS.
 
 ## Principles
 
@@ -14,7 +14,7 @@ Guide for writing consistent, professional component reference docs for Ignis.
 | Tier | Structure | When to Use | Examples |
 |------|-----------|-------------|----------|
 | **Tier 1** | [Single page](./single-page) | 5 or fewer config options, straightforward behavior | Health Check, Request Tracker, Swagger |
-| **Tier 2** | 4 pages | 6+ config options, multiple strategies/providers, architectural depth | Authentication, Mail, Socket.IO, WebSocket, Static Asset |
+| **Tier 2** | 4 pages | 6+ config options, multiple strategies/providers, architectural depth | Authentication, Authorization, Mail, Socket.IO, WebSocket, Static Asset |
 
 ### Tier 1 -- Single Page
 

package/{wiki → content}/extensions/components/template/setup-page.md

@@ -13,7 +13,7 @@ Paired with [Usage](./usage-page), [API Reference](./api-page), and [Error Refer
 ## Page Structure
 
 ```markdown
-# {Component Name}
+# {Component Name} -- Setup & Configuration
 
 {One-line description of what this component does.}
 

package/{wiki → content}/extensions/components/websocket/api.md

@@ -111,7 +111,7 @@ upgrade()  fetch(req, server)
 ```typescript
 interface IWebSocketEmitterOptions {
   identifier?: string;           // Default: 'WebSocketEmitter' (used as logger scope)
-  redisConnection: DefaultRedisHelper;  // Required -- same Redis as the server(s)
+  redisConnection: IRedisHelper;  // Required -- same Redis as the server(s)
 }
 ```
 
@@ -127,7 +127,7 @@ const emitter = new WebSocketEmitter({
 The constructor:
 1. Calls `super({ scope })` with `identifier` (or `'WebSocketEmitter'` if not provided)
 2. Validates `redisConnection` is truthy (throws `"Invalid redis connection!"` if not)
-3. Calls `redisConnection.getClient().duplicate()` to create an isolated pub client
+3. Calls `redisConnection.duplicateClient()` to create an isolated pub client
 
 ### `EMITTER_SERVER_ID`
 
@@ -217,7 +217,7 @@ Reads all binding keys from the DI container and validates required ones:
 | Binding | Validation | Error on Failure |
 |---------|-----------|------------------|
 | `SERVER_OPTIONS` | Optional, merged with `DEFAULT_SERVER_OPTIONS` via `Object.assign()` | -- |
-| `REDIS_CONNECTION` | Must be `instanceof DefaultRedisHelper` | `"Invalid instance of redisConnection"` |
+| `REDIS_CONNECTION` | Must be `instanceof AbstractRedisHelper` | `"Invalid instance of redisConnection"` |
 | `AUTHENTICATE_HANDLER` | Must be truthy (non-null) | `"Invalid authenticateFn to setup WebSocket server!"` |
 | `VALIDATE_ROOM_HANDLER` | Optional, coerced `null` to `undefined` | -- |
 | `CLIENT_CONNECTED_HANDLER` | Optional, coerced `null` to `undefined` | -- |

package/{wiki → content}/extensions/components/websocket/errors.md

@@ -28,7 +28,7 @@ The server can send `error` events or close the connection under the following c
 |--------|-----------|---------------|
 | `binding()` | `application` is falsy | `"[binding] Invalid application to bind WebSocketComponent"` |
 | `binding()` | Node.js runtime detected | `"[WebSocketComponent] Node.js runtime is not supported yet. Please use Bun runtime."` |
-| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `DefaultRedisHelper` | `"[WebSocketComponent][resolveBindings] Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
+| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `AbstractRedisHelper` | `"[WebSocketComponent][resolveBindings] Invalid instance of redisConnection | Please init connection with RedisSingleHelper (single), RedisClusterHelper (cluster), or RedisSentinelHelper (sentinel)"` |
 | `resolveBindings()` | `AUTHENTICATE_HANDLER` is falsy | `"[WebSocketComponent] Invalid authenticateFn to setup WebSocket server!"` |
 | `registerBunHook()` | Bun server instance not available | `"[WebSocketComponent] Bun server instance not available!"` |
 
@@ -42,20 +42,20 @@ The server can send `error` events or close the connection under the following c
 
 ### "Invalid instance of redisConnection"
 
-**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `DefaultRedisHelper` (or its subclasses `RedisHelper` / `RedisClusterHelper`).
+**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `AbstractRedisHelper` (i.e. not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`).
 
-**Fix**: Use `RedisHelper` (single instance) or `RedisClusterHelper` (cluster mode):
+**Fix**: Use one of the concrete topology helpers:
 
 ```typescript
 import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
 
 // Correct
 this.bind({ key: WebSocketBindingKeys.REDIS_CONNECTION })
-  .toValue(new RedisHelper({ name: 'websocket', host, port, password }));
+  .toValue(new RedisSingleHelper({ name: 'websocket', host, port, password }));
 
 // Wrong -- raw ioredis client
 this.bind({ key: WebSocketBindingKeys.REDIS_CONNECTION })
-  .toValue(new Redis(6379));  // This is NOT a DefaultRedisHelper!
+  .toValue(new Redis(6379));  // This is NOT an AbstractRedisHelper!
 ```
 
 ### "Invalid authenticateFn to setup WebSocket server!"

package/{wiki → content}/extensions/components/websocket/index.md

@@ -92,7 +92,7 @@ import {
   WebSocketBindingKeys,
 } from '@venizia/ignis/websocket';
 import {
-  RedisHelper,
+  RedisSingleHelper,
 } from '@venizia/ignis-helpers';
 import type {
   TWebSocketAuthenticateFn,
@@ -107,7 +107,7 @@ import type {
 } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
-  private redisHelper: RedisHelper;
+  private redisHelper: RedisSingleHelper;
 
   preConfigure(): ValueOrPromise<void> {
     this.setupWebSocket();
@@ -116,7 +116,7 @@ export class Application extends BaseApplication {
 
   setupWebSocket() {
     // 1. Redis connection (required for cross-instance messaging)
-    this.redisHelper = new RedisHelper({
+    this.redisHelper = new RedisSingleHelper({
       name: 'websocket-redis',
       host: process.env.REDIS_HOST ?? 'localhost',
       port: +(process.env.REDIS_PORT ?? 6379),
@@ -124,7 +124,7 @@ export class Application extends BaseApplication {
       autoConnect: false,
     });
 
-    this.bind<RedisHelper>({
+    this.bind<RedisSingleHelper>({
       key: WebSocketBindingKeys.REDIS_CONNECTION,
     }).toValue(this.redisHelper);
 
@@ -331,7 +331,7 @@ interface IServerOptions {
 | Binding Key | Constant | Type | Required | Default |
 |------------|----------|------|----------|---------|
 | `@app/websocket/server-options` | `WebSocketBindingKeys.SERVER_OPTIONS` | `Partial<IServerOptions>` | No | See [Configuration](#configuration) |
-| `@app/websocket/redis-connection` | `WebSocketBindingKeys.REDIS_CONNECTION` | `DefaultRedisHelper` | **Yes** | `null` |
+| `@app/websocket/redis-connection` | `WebSocketBindingKeys.REDIS_CONNECTION` | `IRedisHelper` | **Yes** | `null` |
 | `@app/websocket/authenticate-handler` | `WebSocketBindingKeys.AUTHENTICATE_HANDLER` | `TWebSocketAuthenticateFn` | **Yes** | `null` |
 | `@app/websocket/validate-room-handler` | `WebSocketBindingKeys.VALIDATE_ROOM_HANDLER` | `TWebSocketValidateRoomFn` | No | `null` |
 | `@app/websocket/client-connected-handler` | `WebSocketBindingKeys.CLIENT_CONNECTED_HANDLER` | `TWebSocketClientConnectedFn` | No | `null` |

package/{wiki → content}/extensions/components/websocket/usage.md

@@ -109,10 +109,10 @@ It connects to Redis and publishes messages using the same `IRedisSocketMessage`
 #### Emitter Setup
 
 ```typescript
-import { WebSocketEmitter, RedisHelper } from '@venizia/ignis-helpers';
+import { WebSocketEmitter, RedisSingleHelper } from '@venizia/ignis-helpers';
 
 // 1. Create a Redis connection (same Redis instance as the WebSocket server)
-const redisHelper = new RedisHelper({
+const redisHelper = new RedisSingleHelper({
   name: 'emitter-redis',
   host: process.env.REDIS_HOST ?? 'localhost',
   port: +(process.env.REDIS_PORT ?? 6379),
@@ -343,7 +343,7 @@ Both `WebSocketServerHelper` and `WebSocketEmitter` support Redis single instanc
 type TRedisClient = Redis | Cluster;
 ```
 
-The Redis client is obtained via `redisConnection.getClient().duplicate()`. The `duplicate()` call creates a fresh connection that inherits the parent's configuration (including cluster mode). This ensures WebSocket pub/sub traffic does not interfere with application Redis usage.
+The Redis client is obtained via `redisConnection.duplicateClient()`. This creates a fresh connection that inherits the parent's configuration (including cluster mode). This ensures WebSocket pub/sub traffic does not interfere with application Redis usage.
 
 ### Subscription Setup
 

package/{wiki → content}/extensions/helpers/cron/index.md

@@ -147,7 +147,7 @@ hourlyJob.start();
 
 ### Accessing the Underlying CronJob
 
-The `instance` property exposes the underlying `CronJob` from the `cron` package, giving access to the full API (e.g., `stop()`, `running`, `lastDate()`).
+The `instance` property exposes the underlying `CronJob` from the `cron` package, giving access to the full API (e.g., `stop()`, `isActive`, `lastDate()`).
 
 ```typescript
 const job = new CronHelper({
@@ -158,7 +158,7 @@ const job = new CronHelper({
 job.start();
 
 // Access the underlying CronJob directly
-console.log(job.instance.running);  // true
+console.log(job.instance.isActive);  // true
 job.instance.stop();
 ```
 

package/{wiki → content}/extensions/helpers/crypto/index.md

@@ -18,7 +18,7 @@ Cryptographic utilities for AES symmetric encryption, RSA asymmetric encryption,
 | Type | Symmetric | Asymmetric | Asymmetric + Symmetric |
 | Key exchange | Shared secret | Public/private | Diffie-Hellman |
 | Speed | Fast | Slow (large keys) | Fast (small keys) |
-| Max message | Unlimited | ~190 bytes (2048-bit) | Unlimited |
+| Max message | Unlimited | ~214 bytes (2048-bit, OAEP) | Unlimited |
 | Async | No | No | Yes (Web Crypto) |
 | Runtime | Node.js `crypto` | Node.js `crypto` | `crypto.subtle` (Bun/Browser) |
 

package/{wiki → content}/extensions/helpers/env/index.md

@@ -8,7 +8,7 @@ Structured access to application environment variables with prefix filtering, ty
 |------|-------|
 | **Package** | `@venizia/ignis-helpers` |
 | **Classes** | `ApplicationEnvironment`, `Environment` |
-| **Extends** | `IApplicationEnvironment` (interface) |
+| **Implements** | `IApplicationEnvironment` (interface) |
 | **Singleton** | `applicationEnvironment` (alias `Envs`) -- auto-initialized at module load |
 | **Runtimes** | Both |
 
@@ -129,17 +129,32 @@ if (Environment.is({ name: 'staging' })) {
 
 #### Available Stages
 
-| Constant | Value |
-|----------|-------|
-| `Environment.LOCAL` | `'local'` |
-| `Environment.DEBUG` | `'debug'` |
-| `Environment.DEVELOPMENT` | `'development'` |
-| `Environment.ALPHA` | `'alpha'` |
-| `Environment.BETA` | `'beta'` |
-| `Environment.STAGING` | `'staging'` |
-| `Environment.PRODUCTION` | `'production'` |
-
-All stages are collected in `Environment.COMMON_ENVS` (a `Set<string>`), which is used internally by the Logger to determine whether debug logging should be active.
+| Constant | Value | Development stage |
+|----------|-------|-------------------|
+| `Environment.LOCAL` | `'local'` | yes |
+| `Environment.DEBUG` | `'debug'` | yes |
+| `Environment.DEVELOPMENT` | `'development'` | yes |
+| `Environment.DEV` | `'dev'` | yes - the short spelling of `development` |
+| `Environment.SIT` | `'sit'` | yes |
+| `Environment.UAT` | `'uat'` | no |
+| `Environment.ALPHA` | `'alpha'` | no |
+| `Environment.BETA` | `'beta'` | no |
+| `Environment.STAGING` | `'staging'` | no |
+| `Environment.PRODUCTION` | `'production'` | no |
+
+All stages are collected in `Environment.COMMON_ENVS` (a `Set<string>`), which is used internally by the Logger to determine whether debug logging should be active. A `NODE_ENV` outside this set silences `DEBUG=true` entirely.
+
+#### `Environment.DEVELOPMENT_ENVS` - the error-detail boundary
+
+The stages marked "development stage" above form `Environment.DEVELOPMENT_ENVS`. IGNIS's error handler consults this set to decide whether an error response may carry internal detail - a stack trace, a SQL constraint name, a raw driver message.
+
+The rule is fail-closed. A leak is opt-in by an explicit development name, so **anything else is sanitized as production**, including:
+
+- `alpha`, `beta`, `uat`, `staging` - real users reach these
+- an unrecognized name (a typo, a stage nobody added to the set)
+- `NODE_ENV` left unset
+
+Running a local service under `NODE_ENV=alpha` therefore gives you the same stripped-down error responses your users see. If you want the details while developing, set `NODE_ENV` to `development`, `dev`, or `local`.
 
 ### Configuring the Prefix