@venizia/ignis-docs 0.0.8 → 0.2.0

package/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/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/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/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/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/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/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/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/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/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/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
 

package/content/extensions/helpers/error/index.md

@@ -14,62 +14,108 @@ Standardized error class and factory for throwing HTTP-aware errors with machine
 #### Import Paths
 
 ```typescript
-import { ApplicationError, getError } from '@venizia/ignis-helpers';
+import { ApplicationError, getError, isApplicationError } from '@venizia/ignis-helpers';
 import { ErrorSchema } from '@venizia/ignis-helpers';
 import type { TError } from '@venizia/ignis-helpers';
 ```
 
 ## Creating an Instance
 
-`ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification.
+The canonical way to raise an error in IGNIS is the standalone `getError()` factory - use it everywhere (house rule: `getError`, never `new Error`). `ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification; `getError()` constructs one for you.
 
 ```typescript
-import { ApplicationError, HTTP } from '@venizia/ignis-helpers';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
-const error = new ApplicationError({
+throw getError({
   message: 'User not found',
   statusCode: HTTP.ResultCodes.RS_4.NotFound,
-  messageCode: 'USER_NOT_FOUND',
+  messageCode: 'core.user.not_found',
 });
 ```
 
-#### Constructor Options (`TError`)
+#### Options (`TError`)
+
+The same options apply to `getError()`, the `ApplicationError` constructor, and the static factory:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `message` | `string` | -- (required) | Human-readable error message |
 | `statusCode` | `number` | `400` | HTTP status code |
-| `messageCode` | `string` | `undefined` | Machine-readable error code for client-side handling |
-| `name` | `string` | `undefined` | Error name |
+| `messageCode` | `string` | `MessageCode.DEFAULT` (`'core.system_error'`) | Machine-readable error code for client-side handling. Always resolved through `MessageCode.resolve()` -- never left `undefined`, and lower-cased regardless of what was passed in |
+| `name` | `string` | `undefined` | Accepted by the schema but discarded by the constructor (the native `Error` name is kept) |
 
 > [!TIP]
-> The `TError` type is derived from `ErrorSchema` (a Zod schema) and uses `.catchall(z.any())`, so you can pass additional arbitrary properties beyond the four listed above.
+> The `TError` type is derived from `ErrorSchema` (a Zod schema) and uses `.catchall(z.any())`, so you can pass additional arbitrary properties beyond the four listed above. Extra properties are collected into the `extra` field on the resulting `ApplicationError` instance.
 
-#### `getError()` Factory Function
+#### `ApplicationError` Constructor and Static Factory
 
-For convenience, use the standalone `getError()` function instead of calling `new ApplicationError()` directly. This is the preferred pattern throughout the Ignis codebase.
+`getError()` is the canonical form. The class constructor and the static `ApplicationError.getError()` are legal equivalents - use them only when a direct class reference reads better:
 
 ```typescript
-import { getError, HTTP } from '@venizia/ignis-helpers';
+import { ApplicationError, HTTP } from '@venizia/ignis-helpers';
 
-throw getError({
+// Class constructor (equivalent to getError)
+const error = new ApplicationError({
+  message: 'Configuration missing',
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+});
+
+// Static factory (equivalent to getError)
+throw ApplicationError.getError({
   message: 'Invalid credentials',
   statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
-  messageCode: 'INVALID_CREDENTIALS',
+  messageCode: 'core.auth.invalid_credentials',
 });
 ```
 
-#### `ApplicationError.getError()` Static Method
+### MessageCode
 
-An equivalent static factory method on the class itself:
+`MessageCode` builds and normalizes the machine-readable codes carried on `ApplicationError.messageCode`. Every code an application throws should be constructed with `MessageCode.build()` rather than typed as a raw string literal -- a malformed code fails at module load (import time) instead of shipping dead into production.
 
 ```typescript
-throw ApplicationError.getError({
-  message: 'Configuration missing',
-  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
-});
+import { MessageCode } from '@venizia/ignis-helpers';
+
+export class UserErrorCodes {
+  static readonly NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
+  static readonly DUPLICATE_EMAIL = MessageCode.build({ parts: ['core', 'user', 'duplicate_email'] });
+}
+```
+
+| Member | Type | Value / Signature | Description |
+|--------|------|--------------------|-------------|
+| `DEFAULT` | `string` | `'core.system_error'` | The code `ApplicationError` falls back to when no `messageCode` is supplied |
+| `SEPARATOR` | `string` | `'.'` | Joins segments into a dotted code (e.g. `core.mail.send_failed`) |
+| `SEGMENT_PATTERN` | `RegExp` | `/^[a-z0-9]+(_[a-z0-9]+)*$/` | Each segment must be lower snake_case -- `a-z`, `0-9`, `_` |
+| `MIN_SEGMENTS` | `number` | `2` | A code needs at least a namespace and a reason (e.g. `core.not_found` is valid, `not_found` alone is not) |
+| `build(opts: { parts: Array<string> })` | `string` | -- | Joins `parts` with `SEPARATOR` and lower-cases the result. Throws (via `getError`) if `parts.length < MIN_SEGMENTS`, or if any segment fails `SEGMENT_PATTERN` |
+| `isValid(code: string)` | `boolean` | -- | Cheap structural check for a code arriving from outside the process |
+| `resolve(code?: string)` | `string` | -- | Normalizes an absent or empty code to `DEFAULT`; otherwise lower-cases `code` |
+
+> [!IMPORTANT]
+> `ApplicationError`'s constructor always calls `MessageCode.resolve(messageCode)` -- so `error.messageCode` is **never** `undefined`, and it is **always lower-cased** regardless of the casing passed to `getError()`. A comparison like `error.messageCode === 'DUPLICATE_EMAIL'` is always false; compare against `'duplicate_email'` (or the exact string returned by `MessageCode.build()`).
+
+## Checking for an Application Error
+
+Use `isApplicationError(error)` to recognize an application error by **shape** - an `Error` instance carrying a numeric `statusCode` - rather than by class identity:
+
+```typescript
+import { isApplicationError } from '@venizia/ignis-helpers';
+
+try {
+  await someOperation();
+} catch (error) {
+  if (isApplicationError(error)) {
+    // already shaped (has a statusCode) - surface as-is
+    throw error;
+  }
+  // an unknown failure - sanitize before rethrowing
+  throw getError({ message: 'Operation failed', statusCode: HTTP.ResultCodes.RS_5.InternalServerError });
+}
 ```
 
+> [!WARNING]
+> Never compare `ApplicationError` with `instanceof` across a package boundary. `inversion` ships **dual CJS + ESM** builds (its DI powers frontend libraries), so its error class deliberately has more than one runtime identity, and `helpers` keeps its own `ApplicationError` for the backend stack. Two objects that are both "an application error" can be instances of different classes, so `instanceof` gives false negatives. `isApplicationError` checks the shape and works regardless of which package threw. The search connectors use it to decide what is already shaped versus what must be sanitized as a `503`.
+
 ## Usage
 
 ### Throwing Errors in Services
@@ -109,23 +155,33 @@ throw getError({
 
 The built-in `appErrorHandler` middleware (from `@venizia/ignis`) catches `ApplicationError` instances and formats them into consistent JSON responses. The response shape differs by environment.
 
-#### Production Response
+#### Sanitized (Production-Class) Response
+
+The handler is **fail-closed**: it exposes internals only when `NODE_ENV` names a development environment - one of `local`, `debug`, `development`, `dev`, `sit` (`Environment.DEVELOPMENT_ENVS`). Everything else is sanitized as production: `production`, and also `alpha`, `beta`, `uat`, `staging`, an unrecognized name, and an unset `NODE_ENV`.
+
+In a sanitized response, `stack` and `cause` are omitted from `details`. For unexpected errors without a `statusCode` (i.e., not thrown via `getError`), the raw message is replaced with a generic `"Internal Server Error"`, and a database error keeps only its base message - no SQL detail, no table or constraint name.
 
 ```json
 {
   "message": "User not found",
+  "messageCode": "core.user.not_found",
   "statusCode": 404,
-  "requestId": "abc-123-def"
+  "requestId": "abc-123-def",
+  "details": {
+    "url": "http://localhost:3000/api/users/123",
+    "path": "/api/users/123"
+  }
 }
 ```
 
 #### Development Response
 
-In development (`NODE_ENV=development`), additional debugging fields are included:
+In a development environment (see the list above), `details` additionally includes debugging fields:
 
 ```json
 {
   "message": "User not found",
+  "messageCode": "core.user.not_found",
   "statusCode": 404,
   "requestId": "abc-123-def",
   "details": {
@@ -197,9 +253,9 @@ throw getError({
 
 ### Error response missing `stack` and `cause`
 
-**Cause:** The application is running in production mode. The `appErrorHandler` middleware strips `stack`, `cause`, `url`, and `path` from responses when `NODE_ENV` is not `development`.
+**Cause:** `NODE_ENV` is not one of the development environments, so the handler sanitized the response (`url` and `path` are always included). Note this is what happens on `alpha`/`staging`, on a typo'd name, and when `NODE_ENV` is unset - not only on `production`.
 
-**Fix:** Set `NODE_ENV=development` to see full error details during debugging.
+**Fix:** Set `NODE_ENV` to a development name - `development`, `dev`, `local`, `debug` or `sit`. Anything else stays sanitized by design.
 
 ### Errors returning 500 instead of expected status code