@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/README.md

@@ -6,12 +6,12 @@
 
 [![npm](https://img.shields.io/npm/v/@venizia/ignis-docs.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@venizia/ignis-docs)
 [![License](https://img.shields.io/badge/License-MIT-3DA639.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-8B5CF6.svg?style=flat-square)](https://modelcontextprotocol.io/)
 
-VitePress-powered documentation site and an MCP server with 11 tools that gives AI assistants real-time access to IGNIS knowledge -- search docs, browse source code, and verify dependencies.
+VitePress-powered documentation site and an MCP server with 10 tools that gives AI assistants real-time access to IGNIS knowledge - search docs, browse source code, and verify dependencies.
 
-[Installation](#installation) • [MCP Setup](#mcp-server-setup) • [Available Tools](#available-mcp-tools) • [Online Docs](https://venizia-ai.github.io/ignis)
+[Installation](#installation) • [MCP Setup](#mcp-server-setup) • [Available Tools](#available-mcp-tools) • [Online Docs](https://ignis.venizia.ai)
 
 </div>
 
@@ -21,7 +21,7 @@ VitePress-powered documentation site and an MCP server with 11 tools that gives
 
 | | Feature | |
 | :---: | :--- | :--- |
-| **1** | **11 MCP Tools** | Search docs, browse code, verify deps from any AI assistant |
+| **1** | **10 MCP Tools** | Search docs, browse code, verify deps from any AI assistant |
 | **2** | **Fuzzy Search** | Fuse.js-powered search across all documentation |
 | **3** | **VitePress Site** | Full-featured docs with guides, API references, and tutorials |
 | **4** | **CLI Binary** | Ships as `ignis-docs-mcp` for easy MCP integration |
@@ -30,11 +30,11 @@ VitePress-powered documentation site and an MCP server with 11 tools that gives
 
 ## Features
 
-- **VitePress Documentation Site** -- Full-featured docs with guides, API references, tutorials, and best practices
-- **MCP Server** -- 11 tools for AI assistants to search docs, browse source code, and verify dependencies
-- **Fuzzy Search** -- Fuse.js-powered search across all documentation (title weight 0.7, content weight 0.3)
-- **GitHub Integration** -- Browse project files, search code, and verify dependency versions directly from AI tools
-- **CLI Binary** -- Ships as `ignis-docs-mcp` for easy integration with Claude Desktop and other MCP-compatible clients
+- **VitePress Documentation Site** - Full-featured docs with guides, API references, tutorials, and best practices
+- **MCP Server** - 10 tools for AI assistants to search docs, browse source code, and verify dependencies
+- **Fuzzy Search** - Fuse.js-powered search across all documentation (title weight 0.7, content weight 0.3)
+- **GitHub Integration** - Browse project files, search code, and verify dependency versions directly from AI tools
+- **CLI Binary** - Ships as `ignis-docs-mcp` for easy integration with Claude Desktop and other MCP-compatible clients
 
 ---
 
@@ -150,7 +150,7 @@ wiki/
 
 ### Online Documentation
 
-[https://venizia-ai.github.io/ignis](https://venizia-ai.github.io/ignis)
+[https://ignis.venizia.ai](https://ignis.venizia.ai)
 
 ---
 
@@ -184,10 +184,10 @@ bun run mcp:rebuild
 
 ## Related Links
 
-- [IGNIS Framework](https://github.com/VENIZIA-AI/ignis) -- Main repository
-- [Online Documentation](https://venizia-ai.github.io/ignis) -- Full documentation site
-- [MCP Server Guide](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/content/guides/reference/mcp-docs-server.md) -- Detailed setup guide
-- [Model Context Protocol](https://modelcontextprotocol.io/) -- MCP specification
+- [IGNIS Framework](https://github.com/VENIZIA-AI/ignis) - Main repository
+- [Online Documentation](https://ignis.venizia.ai) - Full documentation site
+- [MCP Server Guide](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/content/guides/reference/mcp-docs-server.md) - Detailed setup guide
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
 
 ---
 

package/content/best-practices/api-usage-examples.md

@@ -101,18 +101,22 @@ export class TestController extends BaseRestController {
   override binding(): ValueOrPromise<void> {
     // Using 'defineRoute'
     this.defineRoute({
-      configs: RouteConfigs.GET_HELLO,
+      configs: RouteConfigs.GET_TEST,
       handler: context => {
-        return context.json({ message: 'Hello' }, HTTP.ResultCodes.RS_2.Ok);
+        return context.json({ message: 'Hello', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
 
     // Using 'bindRoute' for a fluent API
     this.bindRoute({
-      configs: RouteConfigs.GET_GREETING,
+      configs: RouteConfigs.CREATE_ITEM,
     }).to({
       handler: context => {
-        return context.json({ message: 'Hello 3' }, HTTP.ResultCodes.RS_2.Ok);
+        const body = context.req.valid<{ name: string; age: number }>('json');
+        return context.json(
+          { id: crypto.randomUUID(), ...body },
+          HTTP.ResultCodes.RS_2.Ok,
+        );
       },
     });
   }
@@ -168,7 +172,7 @@ This automatically creates endpoints like `GET /configurations`, `POST /configur
 
 ## Repository (Data Access) Usage
 
-Repositories are used to interact with your database. The `DefaultCRUDRepository` provides a rich set of methods for data manipulation. Here are examples from the `postConfigure` method in `src/application.ts`, which demonstrates how to use an injected repository.
+Repositories are used to interact with your database. The `DefaultRelationalRepository` provides a rich set of methods for data manipulation. Here are examples from the `postConfigure` method in `src/application.ts`, which demonstrates how to use an injected repository.
 
 ```typescript
 // In src/application.ts
@@ -223,10 +227,11 @@ const updated = await configurationRepository.updateById({
 // --- Delete a Record by ID ---
 const deleted = await configurationRepository.deleteById({
   id: newRecord.data!.id,
-  options: { shouldReturn: true }, // Option to return the deleted record
 });
 ```
 
+Writes return `{ count, data }` and `shouldReturn` defaults to `true`. Pass `options: { shouldReturn: false }` to skip the `RETURNING` round-trip when you only need the count.
+
 ## Server-Side Rendering (JSX)
 
 IGNIS supports server-side rendering using Hono's JSX middleware. This is useful for returning HTML content, such as landing pages or simple admin views.
@@ -240,7 +245,10 @@ import { BaseRestController, controller, htmlResponse } from '@venizia/ignis';
 
 @controller({ path: '/pages' })
 export class PageController extends BaseRestController {
-  
+  constructor() {
+    super({ scope: PageController.name, path: '/pages' });
+  }
+
   override binding(): void {
     this.defineJSXRoute({
       configs: {
@@ -471,12 +479,12 @@ const result = await sessionRepository.deleteBy({
   where: { expiresAt: { lt: new Date() } },
 });
 
-// Delete with return values
-const deleted = await sessionRepository.deleteBy({
+// Count only - skips the RETURNING round-trip
+const purged = await sessionRepository.deleteBy({
   where: { userId: 'user-123' },
-  options: { shouldReturn: true },  // Returns deleted records
+  options: { shouldReturn: false },
 });
-// deleted.data = array of deleted records
+// purged.count = number of deleted rows; purged.data is null
 ```
 
 ### Batch Create
@@ -504,7 +512,7 @@ import { getError, HTTP } from '@venizia/ignis-helpers';
 
 // Basic error
 throw getError({ message: 'Something went wrong' });
-// Returns: { statusCode: 400, message: 'Something went wrong', messageCode: 'core.system_error' }
+// Returns: { statusCode: 400, message: 'Something went wrong', normalized: { text: 'Something went wrong', code: 'core.system_error', args: {} } }
 
 // With status code
 throw getError({
@@ -512,14 +520,21 @@ throw getError({
   message: 'User not found',
 });
 
-// With message code for i18n
+// Full message shape - { text, code, args } - for i18n
 throw getError({
-  statusCode: 404,
-  message: 'User not found',
-  messageCode: 'core.user.not_found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  message: {
+    text: 'User not found',
+    code: 'core.user.not_found',
+    args: { id },
+  },
 });
 ```
 
+The `{ text, code, args }` object is the one message shape used by error definitions, `getError` input, and the `normalized` field of every response. Read `normalized.code` on the client - there is no top-level `messageCode` in the response. Codes are lower-cased and default to `core.system_error`.
+
+Use `isApplicationError(error)` to test identity, never `instanceof` - the class has more than one identity across packages.
+
 ### Error Handling in Route Handlers
 
 ```typescript
@@ -548,8 +563,13 @@ All errors are automatically formatted:
 {
   "statusCode": 404,
   "message": "User not found",
-  "messageCode": "core.user.not_found",
-  "requestId": "abc123"
+  "normalized": {
+    "text": "User not found",
+    "code": "core.user.not_found",
+    "args": {}
+  },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/users/abc", "path": "/users/:id" }
 }
 ```
 
@@ -584,7 +604,7 @@ async processOrder(c: Context) {
   } catch (error) {
     this.logger.error('[processOrder] Failed: %s', error);
 
-    if (error instanceof ApplicationError) {
+    if (isApplicationError(error)) {
       throw error;  // Re-throw application errors
     }
 

package/content/best-practices/architectural-patterns.md

@@ -29,7 +29,7 @@ graph TD
 |-------|---------------|---------|
 | **Controllers** | Handle HTTP/gRPC - parse requests, validate, format responses | `ConfigurationController` (REST), `GreeterController` (gRPC) |
 | **Services** | Business logic - orchestrate operations | `AuthenticationService` (auth logic) |
-| **Repositories** | Data access - CRUD operations | `ConfigurationRepository` (extends `DefaultCRUDRepository`) |
+| **Repositories** | Data access - CRUD operations | `ConfigurationRepository` (extends `DefaultRelationalRepository`) |
 | **DataSources** | Database connections | `PostgresDataSource` (connects to PostgreSQL) |
 | **Models** | Data structure - Drizzle schemas + Entity classes | `Configuration`, `User` models |
 
@@ -205,12 +205,14 @@ IGNIS applications follow a predictable startup sequence with hooks for customiz
 │  │    - Register Components                            │    │
 │  └─────────────────────────────────────────────────────┘    │
 │                                                             │
-│  6. registerDataSources()  - Initialize DB connections      │
-│  7. registerComponents()   - Configure all components       │
-│  8. registerControllers()  - Mount routes to router         │
+│  6. hydrateSecrets()       - Resolve secrets into env        │
+│  7. registerDataSources()  - Initialize DB connections      │
+│  8. registerComponents()   - Configure all components       │
+│  9. wireSecretRotatables() - Attach rotation listeners      │
+│ 10. registerControllers()  - Mount routes to router         │
 │                                                             │
 │  ┌─────────────────────────────────────────────────────┐    │
-│  │ 9. postConfigure()  ← YOUR CODE HERE                │    │
+│  │ 11. postConfigure()  ← YOUR CODE HERE               │    │
 │  │    - Seed data                                      │    │
 │  │    - Start background jobs                          │    │
 │  │    - Custom initialization                          │    │
@@ -218,6 +220,8 @@ IGNIS applications follow a predictable startup sequence with hooks for customiz
 └─────────────────────────────────────────────────────────────┘
 ```
 
+`hydrateSecrets()` runs after `preConfigure()` so a secrets provider registered there is available, and before `registerDataSources()` so datasources read already-resolved values. `wireSecretRotatables()` runs after components, because a component may contribute the datasource a rotation lease points at.
+
 **Lifecycle Methods:**
 
 | Method | When | Purpose |
@@ -287,16 +291,20 @@ export class Application extends BaseApplication {
 **How registration works:**
 ```typescript
 // BaseApplication implements service() directly (no mixin composition):
-service<Base extends IService>(ctor: TClass<Base>): Binding<Base> {
+service<Base extends IService, Args extends AnyObject = any>(
+  ctor: TClass<Base>,
+  opts?: TMixinOpts<Args>,
+): Binding<Base> {
   return this.bind<Base>({
-    key: BindingKeys.build({
-      namespace: BindingNamespaces.SERVICE,
-      key: ctor.name,
-    }),
+    key: BindingKeys.build(
+      opts?.binding ?? { namespace: BindingNamespaces.SERVICE, key: ctor.name },
+    ),
   }).toClass(ctor);
 }
 ```
 
+Every registration method takes the same optional second argument - `opts.binding` overrides the derived `{ namespace, key }` when you need to register two classes under one contract.
+
 **Capability interfaces:**
 
 Each registration capability is declared as a TypeScript interface that `IRestApplication` (and therefore `BaseApplication`) implements. Reference these when you type your own application contracts:
@@ -304,8 +312,11 @@ Each registration capability is declared as a TypeScript interface that `IRestAp
 | Interface | Methods | Purpose |
 |-----------|---------|---------|
 | `IServiceMixin` | `service()` | Register service classes |
-| `IRepositoryMixin` | `repository()`, `dataSource()`, `registerDataSources()` | Register data layer |
+| `IRepositoryMixin` | `dataSource()`, `repository()` | Register data layer |
 | `IComponentMixin` | `component()`, `registerComponents()` | Register modular components |
+| `IControllerMixin` | `controller()`, `registerControllers()` | Register controllers and mount routes |
+| `IServerConfigMixin` | `staticConfigure()`, `preConfigure()`, `postConfigure()`, `getApplicationVersion()` | Lifecycle hooks |
+| `IStaticServeMixin` | `static()` | Serve static files |
 
 > [!NOTE]
 > Earlier releases also exported `ServiceMixin`, `RepositoryMixin`, and `ComponentMixin` as class-mixin **functions** you composed onto `AbstractApplication`. They duplicated `BaseApplication`'s own methods verbatim, drifted out of sync, and had no known consumers, so they were removed. The `IServiceMixin` / `IRepositoryMixin` / `IComponentMixin` **interfaces** remain - extend `BaseApplication` and call its registration methods directly.

package/content/best-practices/architecture-decisions.md

@@ -26,7 +26,7 @@ export class ItemController extends BaseRestController {
     @inject({ key: 'repositories.ItemRepository' })
     private itemRepository: ItemRepository,
   ) {
-    super({ scope: 'ItemController', path: '/items' });
+    super({ scope: ItemController.name, path: '/items' });
   }
 
   @get({ configs: RouteConfigs.GET_ITEM_BY_ID })
@@ -53,7 +53,7 @@ export class OrderController extends BaseRestController {
     @inject({ key: 'services.OrderService' })
     private orderService: OrderService,
   ) {
-    super({ scope: 'OrderController', path: '/orders' });
+    super({ scope: OrderController.name, path: '/orders' });
   }
 
   @post({ configs: RouteConfigs.CREATE_ORDER })
@@ -132,6 +132,10 @@ export class NotificationComponent extends BaseComponent {
 // Inline: Simple, one-off, no need for abstraction
 @controller({ path: '/health' })
 export class HealthController extends BaseRestController {
+  constructor() {
+    super({ scope: HealthController.name, path: '/health' });
+  }
+
   @get({ configs: RouteConfigs.HEALTH_CHECK })
   healthCheck(c: Context) {
     return c.json({ status: 'ok', timestamp: new Date() });
@@ -152,21 +156,26 @@ export class HealthController extends BaseRestController {
 
 ### Start with Standard CRUD
 
-Every repository gets these methods from `DefaultCRUDRepository`:
+Every repository gets these methods from `DefaultRelationalRepository`:
 
 ```typescript
 // Inherited methods (options-object API) - use these first
-find({ filter })            // List with filters
-findById({ id })            // Get by ID
-findOne({ filter })         // Get first match
-create({ data })            // Create new
-updateById({ id, data })    // Update existing
+find({ filter })            // List with filters -> T[]
+findById({ id })            // Get by ID -> T | null
+findOne({ filter })         // Get first match -> T | null
+count({ where })            // Count matches -> { count }
+existsWith({ where })       // Existence check -> boolean
+
+create({ data })            // Create new -> { count, data }
+createAll({ data })         // Create many -> { count, data }
+updateById({ id, data })    // Update existing -> { count, data }
 updateAll({ data, where })  // Bulk update (updateBy is an alias)
-deleteById({ id })          // Delete
+deleteById({ id })          // Delete -> { count, data }
 deleteAll({ where })        // Bulk delete (deleteBy is an alias)
-count({ where })            // Count matches
 ```
 
+Reads return the record(s) directly; writes return `{ count, data }`. Pass `options: { shouldReturn: false }` on a write to skip the `RETURNING` round-trip.
+
 ### Add Custom Methods When:
 
 1. **Query is complex and reusable**
@@ -175,7 +184,7 @@ count({ where })            // Count matches
 
 ```typescript
 // Custom repository methods
-export class OrderRepository extends DefaultCRUDRepository<typeof Order.schema> {
+export class OrderRepository extends DefaultRelationalRepository<typeof Order.schema> {
   // Complex query that's used in multiple places
   async findPendingOrdersOlderThan(hours: number) {
     const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);
@@ -230,8 +239,8 @@ export class UserController extends BaseRestController {
       const user = await this.userService.create(data);
       return c.json(user, 201);
     } catch (error) {
-      // Format error for API response -- messageCode is always lower-cased by ApplicationError
-      if (error instanceof ApplicationError && error.messageCode === 'app.user.duplicate_email') {
+      // Format error for API response -- the code is always lower-cased by ApplicationError
+      if (isApplicationError(error) && error.normalized.code === 'app.user.duplicate_email') {
         return c.json({ error: 'Email already exists' }, 400);
       }
       throw error; // Let global handler catch unknown errors
@@ -255,10 +264,14 @@ export class UserService extends BaseService {
     // Validate and throw domain-specific errors
     const existing = await this.userRepository.findByEmail(data.email);
     if (existing) {
+      // One message shape everywhere: { text, code, args }
       throw getError({
         statusCode: 400,
-        messageCode: MessageCode.build({ parts: ['app', 'user', 'duplicate_email'] }),
-        message: 'User with this email already exists',
+        message: {
+          text: 'User with this email already exists',
+          code: MessageCode.build({ parts: ['app', 'user', 'duplicate_email'] }),
+          args: { email: data.email },
+        },
       });
     }
 
@@ -273,7 +286,7 @@ export class UserService extends BaseService {
 ### Repository Level: Let Errors Bubble
 
 ```typescript
-export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+export class UserRepository extends DefaultRelationalRepository<typeof User.schema> {
   // Don't catch database errors here
   // Let them bubble up to service/controller
   async findByEmail(email: string) {

package/content/best-practices/code-style-standards/advanced-patterns.md

@@ -7,13 +7,13 @@ Advanced TypeScript patterns used throughout the IGNIS framework.
 Create reusable class extensions without deep inheritance:
 
 ```typescript
-import { LoggerFactory, TMixinTarget } from '@venizia/ignis-helpers';
+import { ILogger, LoggerFactory, TMixinTarget } from '@venizia/ignis-helpers';
 
 export const LoggableMixin = <BaseClass extends TMixinTarget<object>>(
   baseClass: BaseClass,
 ) => {
   return class extends baseClass {
-    protected logger = LoggerFactory.getLogger([this.constructor.name]);
+    protected logger: ILogger = LoggerFactory.getLogger([this.constructor.name]);
 
     log(message: string): void {
       this.logger.info(message);
@@ -62,37 +62,48 @@ Generate classes dynamically with configuration:
 
 ```typescript
 class ControllerFactory extends BaseHelper {
-  /** `TDataObject`/`TPersistObject` cannot be inferred from `entity` -
-   * pass them explicitly for typed CRUD handlers. */
   static defineCrudController<
-    TDataObject extends object = object,
-    TPersistObject extends object = TDataObject,
-  >(defOpts: ICrudControllerOptions) {
-    const { controller, entity } = defOpts;
+    TEntity extends AbstractEntity = AbstractEntity,
+    Routes extends ICustomizableRoutes = ICustomizableRoutes,
+    // DataObject/PersistObject default to the entity's inferred select/insert shapes
+    TDataObject extends object = TEntityDataObject<TEntity>,
+    TPersistObject extends object = TEntityPersistObject<TEntity>,
+  >(defOpts: ICrudControllerOptions<TEntity, Routes>) {
+    const { controller, entity, routes } = defOpts;
 
     // `entity` accepts a class directly or a resolver function
     const entityClass = isClass(entity) ? entity : entity();
     const entityInstance = new entityClass();
 
     // Derive request/response schemas + route configs from the entity instance
-    const routeDefinitions = buildRouteDefinitions({ entity: entityInstance });
-
-    return class extends BaseRestController {
-      repository: AbstractRepository<TDataObject, TPersistObject>;
-
+    const definitions = defineControllerRouteConfigs({
+      idType: entityInstance.getIdType(),
+      routes,
+      schema: {
+        select: entityInstance.getSchema({ type: SchemaTypes.SELECT }),
+        create: entityInstance.getSchema({ type: SchemaTypes.CREATE }),
+        update: entityInstance.getSchema({ type: SchemaTypes.UPDATE }),
+      },
+    });
+
+    return class extends PersistableCrudController<TEntity> {
       constructor(repository: AbstractRepository<TDataObject, TPersistObject>) {
-        super({ scope: controller.name, path: controller.basePath });
-        this.repository = repository;
+        super({
+          scope: controller.name,
+          path: controller.basePath,
+          repository,
+          definitions,
+        });
       }
 
       /** Registers all CRUD route handlers. */
       override binding(): ValueOrPromise<void> {
         this.defineRoute({
-          configs: routeDefinitions.FIND,
+          configs: definitions.FIND,
           handler: async context => this.find({ context }),
         });
         this.defineRoute({
-          configs: routeDefinitions.FIND_BY_ID,
+          configs: definitions.FIND_BY_ID,
           handler: async context => this.findById({ context }),
         });
         // ... more routes (count/findOne/create/updateById/deleteById/...)
@@ -101,11 +112,8 @@ class ControllerFactory extends BaseHelper {
   }
 }
 
-// Usage - type parameters are explicit, entity can be a class or a resolver
-type TUser = typeof User.schema.$inferSelect;
-type TNewUser = typeof User.schema.$inferInsert;
-
-const UserCrudController = ControllerFactory.defineCrudController<TUser, TNewUser>({
+// Usage - types come from the entity, entity can be a class or a resolver
+const UserCrudController = ControllerFactory.defineCrudController({
   controller: { name: 'UserController', basePath: '/users' },
   repository: { name: UserRepository.name },
   entity: () => User,
@@ -117,6 +125,10 @@ export class UserController extends UserCrudController {
 }
 ```
 
+> [!NOTE]
+> `controller.basePath` is required - `defineCrudController` throws via `getError` when it is
+> missing or left at the internal `'unknown_path'` placeholder.
+
 ## Value Resolver Pattern
 
 Support multiple input types that resolve to a single value:
@@ -132,16 +144,16 @@ export const resolveValue = <T>(valueOrResolver: TValueOrResolver<T>): T => {
     return valueOrResolver;  // Direct value
   }
 
-  if (isClass(valueOrResolver as Function)) {
+  if (isClass(valueOrResolver)) {
     return valueOrResolver as T;  // Class constructor (return as-is)
   }
 
   return (valueOrResolver as TResolver<T>)();  // Function resolver
 };
 
-// isClass (from @venizia/ignis-inversion, re-exported by helpers) - distinguishes class
+// isClass (declared in @venizia/ignis-inversion, re-exported by helpers) - distinguishes class
 // constructors from arrow/regular functions by testing the SOURCE against /^class[\s{]/,
-// since every non-arrow function has a prototype
+// since every non-arrow function has a prototype. Sound only on ES2020+ output.
 export const isClass = <T>(target: any): target is TClass<T> => {
   if (typeof target !== 'function' || target.prototype === undefined) {
     return false;
@@ -230,17 +242,17 @@ Centralized registration of components:
 
 ```typescript
 class StrategyRegistry<T> {
-  private strategies = new Map<string, T>();
+  private _strategies = new Map<string, T>();
 
   register(name: string, strategy: T): void {
-    if (this.strategies.has(name)) {
+    if (this._strategies.has(name)) {
       throw getError({ message: `[register] Strategy '${name}' already registered` });
     }
-    this.strategies.set(name, strategy);
+    this._strategies.set(name, strategy);
   }
 
   get(name: string): T {
-    const strategy = this.strategies.get(name);
+    const strategy = this._strategies.get(name);
     if (!strategy) {
       throw getError({ message: `[get] Strategy '${name}' not found` });
     }
@@ -248,11 +260,11 @@ class StrategyRegistry<T> {
   }
 
   has(name: string): boolean {
-    return this.strategies.has(name);
+    return this._strategies.has(name);
   }
 
   all(): Map<string, T> {
-    return new Map(this.strategies);
+    return new Map(this._strategies);
   }
 }
 

package/content/best-practices/code-style-standards/constants-configuration.md

@@ -86,7 +86,9 @@ interface IUser {
 }
 
 // Usage with validation
-function updateUserStatus(userId: string, status: string) {
+const updateUserStatus = (opts: { userId: string; status: string }) => {
+  const { status } = opts;
+
   if (!UserStatuses.isValid(status)) {
     throw getError({
       statusCode: HTTP.ResultCodes.RS_4.BadRequest,
@@ -94,7 +96,7 @@ function updateUserStatus(userId: string, status: string) {
     });
   }
   // status is validated at runtime
-}
+};
 ```
 
 ## Enum vs Static Class Comparison
@@ -198,7 +200,15 @@ constructor(options: IJWSTokenServiceOptions) {
 
 ## Environment Variables Management
 
-Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants.
+Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment`
+helper and define your keys as constants.
+
+Two constraints it enforces:
+
+- Only variables whose name starts with the prefix (`APP_ENV` by default, override with
+  `APPLICATION_ENV_PREFIX`) are visible. Anything else reads back as `undefined`.
+- Values are raw strings. A non-string type parameter is an assertion, not a conversion - pass
+  `transform` to actually convert.
 
 **Define Keys (`src/common/environments.ts`):**
 ```typescript
@@ -215,7 +225,12 @@ import { EnvironmentKeys } from '@/common/environments';
 
 // Correct usage
 const stripeKey = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_STRIPE_KEY);
-const retries = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_MAX_RETRIES);
+
+// Numbers need an explicit transform - the stored value is a string
+const retries = applicationEnvironment.get<number, string>(EnvironmentKeys.APP_ENV_MAX_RETRIES, {
+  transform: value => Number(value),
+  defaultValue: 3,
+});
 ```
 
 ## See Also

package/content/best-practices/code-style-standards/control-flow.md

@@ -108,20 +108,52 @@ this.logger.debug('[config] Server options: %j', this.serverOptions);
 ```
 
 > [!NOTE]
-> `%j` on an `Error` instance drops `message` and `stack` -- they are non-enumerable, so `JSON.stringify` never sees them. Use `%s` for errors, `%j`/`%o` for plain data objects. An object passed to `%s` is inspected up to `APP_ENV_LOGGER_INSPECT_DEPTH` levels deep (default `5`) instead of Node's hard-coded `depth: 0`, so nested fields print instead of collapsing to `[Object]`. See [Logger Helper](/extensions/helpers/logger/) for details.
+> `%j` on an `Error` instance drops `message` and `stack` - they are non-enumerable, so `JSON.stringify` never sees them. Use `%s` for errors, `%j`/`%o` for plain data objects. An object passed to `%s` is inspected up to `APP_ENV_LOGGER_INSPECT_DEPTH` levels deep (default `5`) instead of Node's hard-coded `depth: 0`, so nested fields print instead of collapsing to `[Object]`. See [Logger Helper](/extensions/helpers/logger/) for details.
 
 ### Log Levels
 
+Exactly five levels exist, each a direct method on `ILogger`:
+
 | Level | Use For |
 |-------|---------|
+| `emerg` | The process cannot continue |
 | `error` | Exceptions that need attention |
 | `warn` | Recoverable issues, deprecations |
 | `info` | Important business events |
 | `debug` | Detailed debugging information |
 
+> [!NOTE]
+> Secret-looking keys (token, password, apiKey, ...) are redacted to `[REDACTED]` before a line
+> reaches any transport. `APP_ENV_LOGGER_DO_REDACT=false` disables it - local debugging only.
+
+### Never Swallow a Catch
+
+An empty or comment-only `catch` is banned. Log, then rethrow or return a defined fallback.
+
+```typescript
+// ✅ GOOD
+try {
+  await syncRemote();
+} catch (error) {
+  this.logger.error('[syncRemote] Sync failed | Error: %s', error);
+  throw error;
+}
+
+// ❌ BAD - the failure disappears
+try {
+  await syncRemote();
+} catch {
+  // ignore
+}
+```
+
 ## Standardized Error Handling
 
 Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions.
+**Never `new Error`.** Across package boundaries test identity with `isApplicationError()`, never
+`instanceof` - the class has more than one identity in a monorepo.
+
+The normalized message is always one shape: `{ text, code, args }`, read from `error.normalized`.
 
 ### Basic Error