@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

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

@@ -117,7 +117,7 @@ REST controllers extend `BaseRestController`, while gRPC controllers extend `Bas
 
 ## 3. Component-Based Modularity
 
-Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories, essentially functioning as a mini-application that can be easily "plugged in" to any IGNIS project.
+Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories. It functions as a mini-application that plugs into any IGNIS project.
 
 **Built-in Components:**
 - `AuthenticateComponent` - JWT authentication
@@ -140,7 +140,7 @@ export class Application extends BaseApplication {
   }
 }
 ```
-This architecture keeps the main `Application` class clean and focused on high-level assembly, while the details of each feature are neatly encapsulated within their respective components.
+This architecture keeps the main `Application` class clean and focused on high-level assembly. The details of each feature stay neatly encapsulated within their respective components.
 
 ## 4. Custom Components
 
@@ -303,7 +303,7 @@ service<Base extends IService, Args extends AnyObject = any>(
 }
 ```
 
-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.
+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:**
 

package/content/best-practices/code-style-standards/naming-conventions.md

@@ -115,7 +115,7 @@ interface IAuthService {
 
 // Type aliases use 'T' prefix
 type TSignInRequest = z.infer<typeof SignInRequestSchema>;
-type TAuthStrategy = TConstValue<typeof AuthenticateStrategy>;
+type TJWKSMode = TConstValue<typeof JWKSModes>;
 
 // ❌ Never a bare string-literal union for an enumerable set - it has no runtime
 // values to validate against. Use a const class + TConstValue instead.

package/content/best-practices/contribution-workflow.md

@@ -161,8 +161,8 @@ make lint-all
 # Build all packages (from root)
 make build
 
-# Run tests (from a package directory, e.g. packages/core or packages/boot)
-cd packages/core && bun test
+# Run tests (from a package directory, e.g. packages/core-server or packages/boot)
+cd packages/core-server && bun test
 ```
 
 > [!WARNING]

package/content/best-practices/error-handling.md

@@ -1,28 +1,37 @@
 # Error Handling
 
-Comprehensive guide to handling errors gracefully in IGNIS applications.
-
-## Error Handling Philosophy
-
-| Principle | Description |
-|-----------|-------------|
-| **Fail Fast** | Detect and report errors as early as possible |
-| **Don't Swallow** | Never catch errors without logging or re-throwing |
-| **User-Friendly** | Return clear, actionable messages to clients |
-| **Debuggable** | Include context for debugging in logs |
-
-## 1. Using `getError` Helper
-
-IGNIS provides `getError` for creating consistent, structured errors.
+Every error in IGNIS ends up as one shape: `statusCode`, `message`, `normalized`, `requestId`, and `details`. `getError` builds that shape at the throw site. A global handler catches whatever you don't.
 
 ```typescript
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
-// Basic error
 throw getError({
   statusCode: HTTP.ResultCodes.RS_4.NotFound,
   message: 'User not found',
 });
+```
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| Throw an error with debugging context | [Throw a structured error](#throw-a-structured-error) |
+| Add an i18n error a client can branch on | [Catalog a domain error](#catalog-a-domain-error) |
+| Pick the right HTTP status code | [Choose the right status code](#choose-the-right-status-code) |
+| Handle errors in a service, controller, or repository | [Handle errors by layer](#handle-errors-by-layer) |
+| Customize the global error response | [Customize the global handler](#customize-the-global-handler) |
+| Read the exact JSON a client receives | [The error response shape](#the-error-response-shape) |
+| Log an error without losing the stack | [Log errors](#log-errors) |
+| Handle a rejected promise or a fire-and-forget call | [Handle async errors](#handle-async-errors) |
+| Roll back a transaction safely | [Roll back a transaction on failure](#roll-back-a-transaction-on-failure) |
+| Parse an error response on the client | [Parse errors on the client](#parse-errors-on-the-client) |
+
+## Throw a structured error
+
+`getError` is the one function every throw in IGNIS goes through. Give it a status code and a message, and it returns an `ApplicationError` ready to throw.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
 
 // Error with context - any key the framework does not model lands in `extra`
 throw getError({
@@ -48,14 +57,16 @@ throw getError({
 });
 ```
 
+Any key `getError` does not model rides into `extra`. That's how a throw site attaches context the framework knows nothing about.
+
 > [!NOTE]
-> Any key `getError` does not model rides into `extra` - that is how a throw site attaches context the framework knows nothing about. The trade is that a **misspelling** goes the same way: `getError({ message, statuscode: 503 })` compiles, `statusCode` stays `400`, and `503` sits in `extra.statuscode`. The framework cannot tell your context from your typo.
+> The trade-off: a **misspelling** rides the same path. `getError({ message, statuscode: 503 })` compiles. `statusCode` stays `400`, and `503` sits in `extra.statuscode`. The framework can't tell your context from your typo - spell option keys carefully.
 
-### Catalogue a domain failure, raise the rest free-form
+## Catalog a domain error
 
-The form above is right for a failure that carries no i18n code: an invariant, a misconfiguration, a seed guard. Nobody translates `'[UserService][create] Database connection failed'`.
+A free-form `getError` call like that is right for a failure with no i18n code: an invariant, a misconfiguration, a seed guard. Nobody translates `'[UserService][create] Database connection failed'`.
 
-A **domain** failure - one a client localizes and branches on - belongs in a catalog instead. Retyping its code and status at each throw is how two call sites end up raising `category.create.duplicate_name` and `category.duplicate_name` for the same thing:
+But a **domain** failure - one a client localizes and branches on - belongs in a catalog instead. Retyping its code and status at each throw is how two call sites end up raising `category.create.duplicate_name` and `category.duplicate_name` for the same thing.
 
 ```typescript
 import { ErrorScopes, getError, HTTP } from '@venizia/ignis-helpers';
@@ -81,15 +92,15 @@ declare module '@venizia/ignis-helpers' {
 throw getError({ error: UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } });
 ```
 
-Pass the definition as `error` - **never spread it**. `getError({ ...UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } })` reads naturally and is wrong: spreading skips the `error:` field entirely, so `category` and `description` - fields only modeled inside a definition - fall through into `extra` instead of staying structured. `statusCode` and `message` happen to still resolve correctly only because their shapes collide with what `getError` expects standalone; nothing catches the rest for you.
+Pass the definition as `error` - never spread it. `getError({ ...UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } })` looks equivalent. It isn't.
 
-See the [Error helper reference](/extensions/helpers/error/) for the full surface.
+Spreading skips the `error:` field entirely. `category` and `description` are fields only a definition models, so they fall into `extra` instead of staying structured. `statusCode` and `message` still resolve correctly, but only because their shapes happen to match what `getError` expects standalone - nothing catches the rest for you.
 
-## 2. HTTP Status Code Reference
+See the [Error helper reference](/extensions/helpers/error/) for the full surface.
 
-Use the correct status code for each error type:
+## Choose the right status code
 
-| Code | Constant | Use When |
+| Code | Constant | Use when |
 |------|----------|----------|
 | 400 | `RS_4.BadRequest` | Invalid input format, missing required fields, database constraint violations (auto-handled) |
 | 401 | `RS_4.Unauthorized` | Missing or invalid authentication |
@@ -102,13 +113,15 @@ Use the correct status code for each error type:
 | 502 | `RS_5.BadGateway` | External service failed |
 | 503 | `RS_5.ServiceUnavailable` | Service temporarily down |
 
-:::tip Automatic Database Error Handling
-Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are automatically converted to HTTP 400 by the global error middleware. Transient conflicts (`40001` serialization failure, `40P01` deadlock) become HTTP 409 with a retryable message. You don't need to catch these manually. Other classes (e.g. syntax / undefined column) stay 500, and production responses are sanitized - see [Repository Layer Errors](#repository-layer-errors).
+:::tip Automatic database error handling
+The global error middleware converts constraint violations to HTTP 400 on its own, no try/catch needed - SQLSTATE class `22` (data exception), `23` (integrity constraint: unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation). Transient conflicts (`40001` serialization failure, `40P01` deadlock) become HTTP 409 with a retryable message instead. Other classes (for example, class `42` undefined column) stay 500, and production responses are sanitized - see [Repository layer](#repository-layer).
 :::
 
-## 3. Error Handling Patterns
+## Handle errors by layer
 
-### Service Layer Errors
+### Service layer
+
+A service decides what's wrong and throws with `getError`. It doesn't catch what it can't handle.
 
 ```typescript
 import { BaseService } from '@venizia/ignis';
@@ -160,9 +173,11 @@ export class UserService extends BaseService {
 }
 ```
 
-### Controller Layer Errors
+Notice `findOne` and `findById` return the record or `null` - there's no separate "not found" exception to catch. You check for `null` and throw.
+
+### Controller layer
 
-Controllers should delegate to services and let the global error handler catch exceptions:
+Controllers stay thin. Call the service, return the response, and let the global handler catch what the service throws.
 
 ```typescript
 import { BaseRestController, controller, get, post } from '@venizia/ignis';
@@ -192,9 +207,9 @@ export class UserController extends BaseRestController {
 }
 ```
 
-### Repository Layer Errors
+### Repository layer
 
-Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are **automatically handled** by the global error middleware and return HTTP 400. Transient conflicts (`40001` serialization failure, `40P01` deadlock) return HTTP 409 with a generic retryable message. Codes outside those classes (e.g. class `42` undefined column - an application/SQL bug) correctly stay 500.
+The global middleware already converts constraint violations for you (see [Choose the right status code](#choose-the-right-status-code)), so most repository methods need no try/catch at all. Skip it unless you want a message tailored to one specific constraint.
 
 **Non-production** returns the full driver context for debugging:
 
@@ -217,7 +232,7 @@ Database errors in SQLSTATE classes `22` (data exception), `23` (integrity const
 ```
 
 :::warning Production sanitizes database internals
-In production the message is the **base message only** - `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
+In production the message is the **base message only**. `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` and server logs to diagnose.
 
 ```json
 {
@@ -230,13 +245,13 @@ In production the message is the **base message only** - `Detail:` (which echoes
 ```
 :::
 
-You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
+If you need a custom message for one constraint, catch it explicitly and re-throw everything else:
 
 ```typescript
-import { DefaultRelationalRepository, type TCount } from '@venizia/ignis';
+import { DefaultCRUDRepository, type TCount } from '@venizia/ignis';
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
-export class UserRepository extends DefaultRelationalRepository<typeof User.schema> {
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
   async createWithCustomError(data: TCreateUser): Promise<TCount & { data: TUser }> {
     try {
       return await this.create({ data });
@@ -254,9 +269,9 @@ export class UserRepository extends DefaultRelationalRepository<typeof User.sche
 }
 ```
 
-## 4. Global Error Handler
+## Customize the global handler
 
-IGNIS wires a built-in handler by default - `AppErrorMiddleware` from `@venizia/ignis` is a class, registered as `new AppErrorMiddleware({ logger, rootKey }).value()`, and `value()` returns the Hono `ErrorHandler`. You rarely need to replace it; when you do, keep the same response contract:
+IGNIS wires a built-in handler by default. `AppErrorMiddleware` from `@venizia/ignis` is a class, registered as `new AppErrorMiddleware({ logger, rootKey }).value()`, and `value()` returns the Hono `ErrorHandler`. You rarely need to replace it. When you do, keep the same response contract:
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
@@ -309,9 +324,7 @@ export class Application extends BaseApplication {
 }
 ```
 
-## 5. Error Response Format
-
-All errors should follow a consistent format:
+## The error response shape
 
 ```typescript
 interface ErrorResponse {
@@ -334,12 +347,11 @@ interface ErrorResponse {
 }
 ```
 
-There is no top-level `messageCode` - read `normalized.code`. `extra` never mirrors `messageArgs`; the resolved interpolation values live at `normalized.args`.
+There's no top-level `messageCode` - read `normalized.code`. `extra` never mirrors `messageArgs`; the resolved interpolation values live at `normalized.args`.
 
-**Example Responses:**
+**400 Bad Request:**
 
 ```json
-// 400 Bad Request
 {
   "message": "Invalid request body",
   "statusCode": 400,
@@ -347,10 +359,11 @@ There is no top-level `messageCode` - read `normalized.code`. `extra` never mirr
   "requestId": "abc123",
   "details": { "url": "http://localhost:3000/users", "path": "/users" }
 }
+```
 
-// 404 Not Found
-// Extra keys passed to getError(...) (e.g. `details`) surface under `extra`;
-// the top-level `details` object is reserved for middleware context (url, path, stack, cause).
+**404 Not Found:** extra keys passed to `getError(...)` (for example `details`) surface under the top-level `extra`. The top-level `details` object is reserved for middleware context (url, path, stack, cause) - the two never share a key.
+
+```json
 {
   "message": "User not found",
   "statusCode": 404,
@@ -359,11 +372,11 @@ There is no top-level `messageCode` - read `normalized.code`. `extra` never mirr
   "extra": { "details": { "id": "user-uuid" } },
   "details": { "url": "http://localhost:3000/users/user-uuid", "path": "/users/:id" }
 }
+```
+
+**422 Validation Error:** `message` and `normalized.code` come from the first failing issue - its `params.code` if the schema set one, otherwise the raw Zod code (for example `invalid_type`, `too_small`). `normalized.args` is always empty for a Zod issue; the full list of issues stays in `details.cause`.
 
-// 422 Validation Error
-// `message`/`normalized.code` come from the first failing issue - its `params.code` if the schema
-// set one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). `normalized.args` is
-// always empty for a Zod issue; the full list of issues stays in `details.cause`.
+```json
 {
   "message": "Invalid email format",
   "statusCode": 422,
@@ -381,53 +394,44 @@ There is no top-level `messageCode` - read `normalized.code`. `extra` never mirr
     ]
   }
 }
-
-// 500 Internal Error (production)
-{
-  "message": "Internal server error",
-  "statusCode": 500,
-  "normalized": { "text": "Internal server error", "code": "core.system_error", "args": {} },
-  "requestId": "abc123",
-  "details": { "url": "http://localhost:3000/orders", "path": "/orders" }
-}
 ```
 
-## 6. Logging Errors
+## Log errors
 
-### `%s`, Never `%j`, for an `Error`
+### Use `%s`, never `%j`, for an Error
 
 `message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
 
 ```typescript
-// ✅ Good - %s prints message + stack
+// Good - %s prints message + stack
 this.logger.error('[createOrder] Failed | error: %s', error);
 
-// ❌ Bad - %j drops the stack
+// Bad - %j drops the stack
 this.logger.error('[createOrder] Failed | error: %j', error);
 ```
 
 > [!NOTE]
-> An `ApplicationError` logged with `%j` does show its message text, because the text rides inside the enumerable `normalized.text`. That is incidental, not a reprieve: the **stack** is still gone, which is the reason the rule exists. A plain `Error` under `%j` still logs little more than `{}`.
+> An `ApplicationError` logged with `%j` does show its message text, because the text rides inside the enumerable `normalized.text`. That's incidental, not a reprieve - the **stack** is still gone, which is the reason the rule exists. A plain `Error` under `%j` still logs little more than `{}`.
 
-### What to Log
+### What to log
 
 ```typescript
-// ✅ Good - Context for debugging. `%s` on the error itself carries message + stack
+// Good - context for debugging. `%s` on the error itself carries message + stack
 this.logger.error('[createOrder] Failed | userId: %s | orderId: %s | error: %s',
   userId, orderId, error);
 
-// ❌ Bad - No context, and `.message` throws the stack away
+// Bad - no context, and `.message` throws the stack away
 this.logger.error(error.message);
 
-// ❌ Bad - Sensitive data
+// Bad - sensitive data
 this.logger.error('Login failed for user | password: %s', password);
 ```
 
-### Log Levels
+### Log levels
 
-`ILogger` has exactly five levels, each a direct method. `alert`, `http`, `verbose` and `silly` do not exist.
+`ILogger` has exactly five levels, each a direct method. `alert`, `http`, `verbose`, and `silly` don't exist.
 
-| Level | Use For |
+| Level | Use for |
 |-------|---------|
 | `emerg` | The process cannot continue - unrecoverable |
 | `error` | Exceptions that need attention |
@@ -449,18 +453,20 @@ this.logger.info('[order] Created | orderId: %s | userId: %s', orderId, userId);
 this.logger.debug('[query] Executing | sql: %s | params: %j', sql, params);
 ```
 
-## 7. Async Error Handling
+## Handle async errors
 
 ### Promises
 
+`async`/`await` propagates errors on its own - most of the time, you write no error handling at all.
+
 ```typescript
-// ✅ Good - Errors propagate naturally with async/await
+// Good - errors propagate naturally with async/await
 const processOrder = async (orderId: string) => {
   const order = await orderRepository.findById({ id: orderId }); // Throws if fails
   return paymentService.charge(order); // Throws if fails
 };
 
-// ✅ Good - Explicit catch when you need to handle
+// Good - explicit catch when you need to handle
 const processOrderWithFallback = async (order: TOrder) => {
   try {
     return await paymentService.charge(order);
@@ -470,7 +476,7 @@ const processOrderWithFallback = async (order: TOrder) => {
   }
 };
 
-// ❌ Bad - Swallowing errors
+// Bad - swallowing errors
 const processOrderSilently = async () => {
   try {
     await dangerousOperation();
@@ -480,22 +486,24 @@ const processOrderSilently = async () => {
 };
 ```
 
-### Fire-and-Forget with Error Handling
+### Fire-and-forget
+
+But a call you don't `await` needs its own `.catch()`, or a rejection crashes the process as an unhandled rejection.
 
 ```typescript
-// ✅ Good - Log errors from fire-and-forget operations
+// Good - log errors from fire-and-forget operations
 this.sendNotification(userId).catch(error => {
   this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error);
 });
 
-// ✅ Good - Use void to indicate intentional fire-and-forget
+// Good - use void to indicate intentional fire-and-forget
 void this.analytics.track('order_created', { orderId });
 
-// ❌ Bad - Unhandled promise rejection
+// Bad - unhandled promise rejection
 this.sendNotification(userId); // If this rejects, crash!
 ```
 
-## 8. Transaction Error Handling
+## Roll back a transaction on failure
 
 ```typescript
 import { getError, HTTP } from '@venizia/ignis-helpers';
@@ -525,13 +533,11 @@ const transferFunds = async (opts: { from: string; to: string; amount: number })
 ```
 
 > [!NOTE]
-> `rollback()` throws on failure, so it belongs in the `catch` exactly as above - never after a
-> `commit()` you already awaited outside one. A rollback that follows a **failed** commit is a
-> deliberate no-op: the transaction is already torn down, so this canonical shape stays safe.
+> `rollback()` throws on failure, so it belongs in the `catch` block exactly as shown here - never after a `commit()` you already awaited outside one. A rollback that follows a **failed** commit is a deliberate no-op: the transaction is already torn down, so this canonical shape stays safe.
 
-## 9. Client-Side Error Handling
+## Parse errors on the client
 
-Guide for API consumers:
+Branch on `normalized.code` - it's always present. There's no top-level `messageCode`.
 
 ```typescript
 // TypeScript client example
@@ -545,7 +551,6 @@ const createUser = async (data: TCreateUserRequest): Promise<TUser> => {
   if (!response.ok) {
     const error = await response.json();
 
-    // Branch on `normalized.code` - it is always present. There is no top-level `messageCode`.
     switch (response.status) {
       case 400: {
         // Context passed to getError(...) arrives under `extra`, not `details`
@@ -579,7 +584,7 @@ const createUser = async (data: TCreateUserRequest): Promise<TUser> => {
 };
 ```
 
-## Error Handling Checklist
+## Checklist
 
 | Category | Check |
 |----------|-------|
@@ -592,7 +597,7 @@ const createUser = async (data: TCreateUserRequest): Promise<TUser> => {
 | **Responses** | Consistent error format returned |
 | **Security** | No sensitive data in error messages |
 
-## See Also
+## See also
 
 - [Common Pitfalls](./common-pitfalls) - Error handling mistakes
 - [Testing Strategies](./testing-strategies) - Testing error scenarios

package/content/best-practices/security-guidelines.md

@@ -25,12 +25,12 @@ bun -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toSt
 
 ### Redaction at Log Time
 
-Never hard-coding a secret is not enough on its own - an options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
+Never hard-coding a secret is not enough on its own. An options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
 
 | Function | Use For | Behavior |
 |----------|---------|----------|
 | `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name with `'[REDACTED]'` |
-| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section (`mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`); a value that doesn't parse as a URL, or one with no password, is returned unchanged |
+| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section: `mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`. A value that doesn't parse as a URL, or one with no password, is returned unchanged |
 
 ```typescript
 import { redactSecrets, redactUrlCredentials } from '@venizia/ignis-helpers';
@@ -46,9 +46,9 @@ this.logger.info('[connect] Broker: %s', redactUrlCredentials(brokerUrl));
 - Vault wire keys: `client_token`, `secret_id`, `role_id`
 - HTTP header spellings: `x-api-key`, `x-vault-token`, `cookie`, `set-cookie`, `proxy-authorization`, `www-authenticate`
 
-It also handles the shapes naive redaction breaks on: an `Error` is reprojected so its non-enumerable `message`/`stack` survive, cycles become `'[Circular]'`, and buffers/typed arrays are summarized as `[Binary N bytes]` instead of serialized.
+It also handles the shapes naive redaction breaks on. An `Error` is reprojected so its non-enumerable `message`/`stack` survive. Cycles become `'[Circular]'`, and buffers/typed arrays are summarized as `[Binary N bytes]` instead of serialized.
 
-These are the primitives the framework itself uses - outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+These are the primitives the framework itself uses. Outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
 
 > [!WARNING]
 > `APP_ENV_LOGGER_DO_REDACT=false` turns both functions into the identity function. It is a local-debugging kill-switch and must never be set in production. The check is fail-closed - only the literal string `false` disables redaction - and is read per call, so it can be flipped at runtime.
@@ -495,7 +495,7 @@ Deliberate `getError` messages are always returned verbatim, in every environmen
 - Admin actions
 
 > [!NOTE]
-> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw - see [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
+> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw. See [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
 
 ## Security Checklist
 

package/content/extensions/components/api-reference.md

@@ -1,9 +1,9 @@
 # API Reference
 
-Automatic interactive API documentation generated from OpenAPI specs, rendered by a pluggable UI provider - Scalar by default, or classic Swagger UI.
+Automatic interactive API documentation generated from your OpenAPI spec. A pluggable UI provider renders it - Scalar by default, or classic Swagger UI.
 
 > [!NOTE] Renamed from SwaggerComponent
-> Swagger UI is just one of the pluggable UI providers, so the component carries a vendor-neutral name. `SwaggerComponent`, `ISwaggerOptions`, and `SwaggerBindingKeys` remain available as deprecated aliases - existing applications keep working unchanged.
+> Swagger UI is one of the pluggable UI providers, not the only one, so the component carries a vendor-neutral name. The deprecated `Swagger*` aliases are **removed**: use `ApiReferenceComponent`, `IApiReferenceOptions` and `ApiReferenceBindingKeys.API_REFERENCE_OPTIONS`.
 
 ## Quick Reference
 
@@ -27,7 +27,7 @@ import type { IApiReferenceOptions, IUIProvider, IUIConfig, IGetProviderParams }
 
 ## In one example
 
-Register the component - the docs UI comes up at `/doc/explorer`, the raw spec at `/doc/openapi.json`. No configuration required.
+Register the component - no configuration required. The docs UI comes up at `<app base path>/doc/explorer`, the raw spec at `<app base path>/doc/openapi.json`. With the `/api` base path used throughout the getting-started guide, that's `/api/doc/explorer`.
 
 ```typescript
 // src/application.ts
@@ -79,13 +79,14 @@ export class HelloController extends BaseRestController {
 
 ## How it works
 
-- **Options merge group by group.** `binding()` reads the bound `IApiReferenceOptions`, then shallow-merges `base`, `doc`, and `ui` each against their own defaults - overriding `ui.type` alone still keeps `ui.path` and every `base`/`doc` field.
-- **`explorer.info` is always overwritten.** The component unconditionally reads your `package.json` (via `application.getAppInfo()`) and replaces `explorer.info` with `{ title, version, description, contact }` - any `explorer.info` you bind is discarded. Edit `package.json` instead.
-- **`explorer.servers` fills in only when empty.** A supplied server entry is kept as-is; otherwise the component builds one from `application.getServerAddress()` plus the base path.
-- **UI type resolution uses `??`, not `||`.** The source is `restOptions.ui.type ?? DocumentUITypes.SWAGGER` - only `null`/`undefined` falls back, and it falls back to `'swagger'`, not the configured default `'scalar'`. An explicit empty string is NOT repaired by this fallback - it fails `DocumentUITypes.isValid()` and the component throws `Invalid document UI Type` immediately.
-- **UI libraries load lazily.** `SwaggerUIProvider`/`ScalarUIProvider` each `await import()` their rendering library inside `render()`, on the first request to the docs UI - not at application startup. Only the configured provider's library is ever loaded.
-- **`ScalarUIProvider` renames `title` to `pageTitle`.** A quirk to know if you inspect the rendered output or write a custom UI provider: Scalar's own API takes `pageTitle`, not `title`.
-- **Security schemes are always registered.** JWT (`bearer`) and Basic security schemes are added to the OpenAPI registry unconditionally, so routes using `authenticate: { strategies: ['jwt'] }` or `['basic']` render the correct auth UI.
+- **Options merge group by group.** `binding()` reads the bound `IApiReferenceOptions`, then shallow-merges `base`, `doc`, and `ui` each against their own defaults. Overriding `ui.type` alone still keeps `ui.path` and every `base`/`doc` field.
+- **`explorer.info` is always overwritten.** The component reads your `package.json` via `application.getAppInfo()`. It replaces `explorer.info` with `{ title, version, description, contact }` - any `explorer.info` you bind is discarded. Edit `package.json` instead.
+- **`explorer.servers` fills in only when empty.** A supplied server entry is kept as-is. Otherwise, the component builds one from `application.getServerAddress()` plus the base path.
+- **UI type resolution uses `??`, not `||`.** The source is `restOptions.ui.type ?? DocumentUITypes.SWAGGER`. Only `null`/`undefined` falls back, and it falls back to `'swagger'` - not the configured default `'scalar'`.
+  - An explicit empty string is NOT repaired by this fallback: it fails `DocumentUITypes.isValid()` and the component throws `Invalid document UI Type` immediately.
+- **UI libraries load lazily.** `SwaggerUIProvider`/`ScalarUIProvider` each `await import()` their rendering library inside `render()`. That happens on the first request to the docs UI, not at application startup. Only the configured provider's library is ever loaded.
+- **`ScalarUIProvider` renames `title` to `pageTitle`.** Scalar's own render API takes `pageTitle`, not `title` - worth knowing if you inspect the rendered output or write a custom UI provider.
+- **Security schemes are always registered.** JWT (`bearer`) and Basic security schemes are added to the OpenAPI registry unconditionally. Routes using `authenticate: { strategies: ['jwt'] }` or `['basic']` render the correct auth UI as a result.
 
 ## Common tasks
 
@@ -102,10 +103,10 @@ this.bind<IApiReferenceOptions>({
   key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS,
 }).toValue({ restOptions: { base: { path: '/api-docs' } } });
 ```
-Result: UI at `/api-docs/explorer`, spec at `/api-docs/openapi.json` - the group merge keeps `doc.path`/`ui.path` defaults.
+Result: UI at `<app base path>/api-docs/explorer`, spec at `<app base path>/api-docs/openapi.json`. The group merge keeps `doc.path`/`ui.path` defaults.
 
 ### Set the info block shown in the UI
-`explorer.info` always comes from `package.json` - update `name`, `version`, `description`, and `author` there; binding `explorer.info` directly has no effect.
+`explorer.info` always comes from `package.json`. Update `name`, `version`, `description`, and `author` there - binding `explorer.info` directly has no effect.
 
 ### Register a custom UI provider
 `UIProviderFactory.register()` only understands `'swagger'`/`'scalar'`. Register a custom provider directly on the factory before `ApiReferenceComponent.binding()` runs:
@@ -154,7 +155,7 @@ export interface IApiReferenceOptions {
 |-----|----------|------|----------|---------|
 | `@app/api-reference/options` | `ApiReferenceBindingKeys.API_REFERENCE_OPTIONS` | `IApiReferenceOptions` | No | See Options table |
 
-`SwaggerBindingKeys.SWAGGER_OPTIONS` is a deprecated alias whose VALUE is the same `'@app/api-reference/options'` string - there is no separate binding under the literal `'@app/swagger/options'`.
+`SwaggerBindingKeys.SWAGGER_OPTIONS` is removed. It was only ever an alias for the key above - there was never a separate binding under the literal `'@app/swagger/options'`, so nothing needs rebinding.
 
 **Default value:**
 ```typescript
@@ -179,12 +180,12 @@ const DEFAULT_API_REFERENCE_OPTIONS: IApiReferenceOptions = {
 > The `explorer.info` values above are never used at runtime - `binding()` unconditionally overwrites `explorer.info` from `package.json`. They exist only as structural defaults.
 
 ### API endpoints
-| Method | Path (default) | Description |
+| Method | Path (default, relative to app base) | Description |
 |--------|-----------------|-------------|
 | `GET` | `/doc/explorer` | Documentation UI (Scalar by default) |
 | `GET` | `/doc/openapi.json` | Raw OpenAPI specification |
 
-Actual paths shift with `restOptions.base.path`, `restOptions.ui.path`, and `restOptions.doc.path`.
+These paths are mounted under your application's own base path - `path.base` in `IApplicationConfigs`. With the `/api` base path from the getting-started guide, that's `GET /api/doc/explorer`. They also shift with `restOptions.base.path`, `restOptions.ui.path`, and `restOptions.doc.path`.
 
 ### UIProviderFactory
 | Method | Signature | Description |
@@ -208,7 +209,7 @@ class DocumentUITypes {
 }
 ```
 
-`TDocumentUIType` is derived via `TConstValue`, which extracts the union of every `static readonly` string on `DocumentUITypes` - the type stays in sync with the constants automatically.
+`TDocumentUIType` is derived via `TConstValue`, which extracts the union of every `static readonly` string on `DocumentUITypes`. The type stays in sync with the constants automatically.
 
 ### Component lifecycle (`binding()`)
 1. **Resolve options** - reads `ApiReferenceBindingKeys.API_REFERENCE_OPTIONS` with `isOptional: true`, then merges `base`/`doc`/`ui` each against `DEFAULT_API_REFERENCE_OPTIONS`
@@ -260,8 +261,8 @@ class DocumentUITypes {
 
 **Files:**
 
-- [`packages/core/src/components/api-reference/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/api-reference/component.ts) - `ApiReferenceComponent`
-- [`packages/core/src/components/api-reference/ui-factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/api-reference/ui-factory.ts) - `UIProviderFactory`, `SwaggerUIProvider`, `ScalarUIProvider`
-- [`packages/core/src/components/api-reference/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/api-reference/common/types.ts) - `IApiReferenceOptions`, `IUIProvider`, `IUIConfig`
-- [`packages/core/src/components/api-reference/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/api-reference/common/keys.ts) - `ApiReferenceBindingKeys`
-- [`packages/core/src/components/api-reference/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/api-reference/common/constants.ts) - `DocumentUITypes`
+- [`packages/core-server/src/components/api-reference/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/api-reference/component.ts) - `ApiReferenceComponent`
+- [`packages/core-server/src/components/api-reference/ui-factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/api-reference/ui-factory.ts) - `UIProviderFactory`, `SwaggerUIProvider`, `ScalarUIProvider`
+- [`packages/core-server/src/components/api-reference/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/api-reference/common/types.ts) - `IApiReferenceOptions`, `IUIProvider`, `IUIConfig`
+- [`packages/core-server/src/components/api-reference/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/api-reference/common/keys.ts) - `ApiReferenceBindingKeys`
+- [`packages/core-server/src/components/api-reference/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/api-reference/common/constants.ts) - `DocumentUITypes`