@venizia/ignis-docs 0.0.1-4 → 0.0.1-6

package/mcp-server/dist/tools/github/view-source-file.tool.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewSourceFileTool = void 0;
+const helpers_1 = require("@/mcp-server/helpers");
+const tools_1 = require("@mastra/core/tools");
+const zod_1 = require("zod");
+const base_tool_1 = require("../base.tool");
+// ----------------------------------------------------------------------------
+// DESCRIPTIONS
+// ----------------------------------------------------------------------------
+const TOOL_DESCRIPTION = `
+Retrieves the full source code content of a specific file from the Ignis GitHub repository.
+
+PURPOSE:
+Read contents of a source file. Primary method for inspecting implementation details,
+understanding logic, and viewing exact code.
+
+WHEN TO USE:
+- After finding a relevant file with listProjectFiles or searchCode
+- When you need to see implementation of a specific class, function, or component
+- To verify details not present in documentation
+- To extract specific code examples or snippets
+
+WHEN NOT TO USE:
+- For discovering files (use listProjectFiles to browse, or searchCode to find by keyword)
+- Do not use on non-text files (images, binaries) or very large files unless necessary
+- For documentation content (use getDocContent instead)
+`;
+const FILE_PATH_DESCRIPTION = `
+The full path to the file from the root of the repository.
+
+HOW TO OBTAIN:
+- Use listProjectFiles to browse the project and find valid file paths
+- Use searchCode to find files containing specific keywords or patterns
+- Navigate from root directory down to the specific file
+
+EXAMPLES:
+- "packages/core/src/application.ts"
+- "examples/5-mins-qs/src/index.ts"
+- "package.json"
+`;
+// ----------------------------------------------------------------------------
+// SCHEMAS
+// ----------------------------------------------------------------------------
+const InputSchema = zod_1.z.object({
+    filePath: zod_1.z.string().min(1).describe(FILE_PATH_DESCRIPTION),
+});
+const OutputSchema = zod_1.z.object({
+    filePath: zod_1.z.string(),
+    content: zod_1.z.string().optional().describe('The full source code content of the file.'),
+    error: zod_1.z
+        .string()
+        .optional()
+        .describe('An error message if the file could not be read (e.g., not found).'),
+});
+// ----------------------------------------------------------------------------
+// TOOL CLASS
+// ----------------------------------------------------------------------------
+class ViewSourceFileTool extends base_tool_1.BaseTool {
+    constructor() {
+        super(...arguments);
+        this.id = 'viewSourceFile';
+        this.description = TOOL_DESCRIPTION;
+        this.inputSchema = InputSchema;
+        this.outputSchema = OutputSchema;
+    }
+    async execute(opts) {
+        const result = await helpers_1.GithubHelper.getFileContent({ filePath: opts.filePath });
+        if ('error' in result) {
+            return {
+                filePath: opts.filePath,
+                error: result.error,
+            };
+        }
+        return {
+            filePath: opts.filePath,
+            content: result.content,
+        };
+    }
+    getTool() {
+        return (0, tools_1.createTool)({
+            id: this.id,
+            description: this.description,
+            inputSchema: this.inputSchema,
+            outputSchema: this.outputSchema,
+            execute: async ({ context }) => this.execute(context),
+        });
+    }
+}
+exports.ViewSourceFileTool = ViewSourceFileTool;
+//# sourceMappingURL=view-source-file.tool.js.map

package/mcp-server/dist/tools/github/view-source-file.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-source-file.tool.js","sourceRoot":"","sources":["../../../tools/github/view-source-file.tool.ts"],"names":[],"mappings":";;;AAAA,kDAAoD;AACpD,8CAAgD;AAChD,6BAAwB;AACxB,4CAAqD;AAErD,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;CAiBxB,CAAC;AAEF,MAAM,qBAAqB,GAAG;;;;;;;;;;;;CAY7B,CAAC;AAEF,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,MAAM,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;CAC5D,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACpF,KAAK,EAAE,OAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,mEAAmE,CAAC;CACjF,CAAC,CAAC;AAEH,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,MAAa,kBAAmB,SAAQ,oBAAiD;IAAzF;;QACW,OAAE,GAAG,gBAAgB,CAAC;QACtB,gBAAW,GAAG,gBAAgB,CAAC;QAC/B,gBAAW,GAAG,WAAW,CAAC;QAC1B,iBAAY,GAAG,YAAY,CAAC;IA2BvC,CAAC;IAzBC,KAAK,CAAC,OAAO,CAAC,IAAiC;QAC7C,MAAM,MAAM,GAAG,MAAM,sBAAY,CAAC,cAAc,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE9E,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;YACtB,OAAO;gBACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,IAAA,kBAAU,EAAC;YAChB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;SACtD,CAAC,CAAC;IACL,CAAC;CACF;AA/BD,gDA+BC"}

package/mcp-server/dist/tools/index.d.ts

@@ -1,8 +1,4 @@
-export { BaseTool } from './base.tool';
-export type { TMastraTool as MastraTool } from './base.tool';
-export { SearchDocsTool } from './search-docs.tool';
-export { GetDocContentTool } from './get-doc-content.tool';
-export { GetDocMetadataTool } from './get-doc-metadata.tool';
-export { ListDocsTool } from './list-docs.tool';
-export { ListCategoriesTool } from './list-categories.tool';
+export * from './base.tool';
+export * from './docs';
+export * from './github';
 //# sourceMappingURL=index.d.ts.map

package/mcp-server/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,WAAW,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../tools/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAG5B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/mcp-server/dist/tools/index.js

@@ -1,18 +1,22 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ListCategoriesTool = exports.ListDocsTool = exports.GetDocMetadataTool = exports.GetDocContentTool = exports.SearchDocsTool = exports.BaseTool = void 0;
 // Base class
-var base_tool_1 = require("./base.tool");
-Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return base_tool_1.BaseTool; } });
+__exportStar(require("./base.tool"), exports);
 // Tool classes
-var search_docs_tool_1 = require("./search-docs.tool");
-Object.defineProperty(exports, "SearchDocsTool", { enumerable: true, get: function () { return search_docs_tool_1.SearchDocsTool; } });
-var get_doc_content_tool_1 = require("./get-doc-content.tool");
-Object.defineProperty(exports, "GetDocContentTool", { enumerable: true, get: function () { return get_doc_content_tool_1.GetDocContentTool; } });
-var get_doc_metadata_tool_1 = require("./get-doc-metadata.tool");
-Object.defineProperty(exports, "GetDocMetadataTool", { enumerable: true, get: function () { return get_doc_metadata_tool_1.GetDocMetadataTool; } });
-var list_docs_tool_1 = require("./list-docs.tool");
-Object.defineProperty(exports, "ListDocsTool", { enumerable: true, get: function () { return list_docs_tool_1.ListDocsTool; } });
-var list_categories_tool_1 = require("./list-categories.tool");
-Object.defineProperty(exports, "ListCategoriesTool", { enumerable: true, get: function () { return list_categories_tool_1.ListCategoriesTool; } });
+__exportStar(require("./docs"), exports);
+__exportStar(require("./github"), exports);
 //# sourceMappingURL=index.js.map

package/mcp-server/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../tools/index.ts"],"names":[],"mappings":";;;AAAA,aAAa;AACb,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AAGjB,eAAe;AACf,uDAAoD;AAA3C,kHAAA,cAAc,OAAA;AACvB,+DAA2D;AAAlD,yHAAA,iBAAiB,OAAA;AAC1B,iEAA6D;AAApD,2HAAA,kBAAkB,OAAA;AAC3B,mDAAgD;AAAvC,8GAAA,YAAY,OAAA;AACrB,+DAA4D;AAAnD,0HAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../tools/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,aAAa;AACb,8CAA4B;AAE5B,eAAe;AACf,yCAAuB;AACvB,2CAAyB"}

package/package.json

@@ -1,14 +1,31 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.1-4",
+  "version": "0.0.1-6",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",
+    "documentation",
+    "docs",
+    "guide",
+    "wiki",
+    "examples",
+    "vitepress",
     "mcp",
     "model-context-protocol",
-    "documentation",
+    "mastra",
+    "mastra-mcp",
     "ai",
-    "framework"
+    "ai-gateway",
+    "llm-gateway",
+    "model-router",
+    "ai-development",
+    "llm-development",
+    "server",
+    "cli",
+    "tooling",
+    "dev-tools",
+    "framework",
+    "venizia"
   ],
   "main": "./mcp-server/dist/index.js",
   "types": "./mcp-server/dist/index.d.ts",
@@ -37,7 +54,8 @@
     "README.md",
     "LICENSE.md",
     "mcp-server/dist",
-    "wiki"
+    "wiki",
+    "!**/*.tsbuildinfo"
   ],
   "publishConfig": {
     "access": "public"
@@ -46,6 +64,7 @@
     "bun": ">=1.3"
   },
   "scripts": {
+    "force-update": "sh ./scripts/force-update.sh",
     "eslint": "eslint --report-unused-disable-directives .",
     "lint": "bun run eslint && bun run prettier:cli",
     "lint:fix": "bun run eslint --fix && bun run prettier:fix",
@@ -76,7 +95,7 @@
   "bugs": {
     "url": "https://github.com/VENIZIA-AI/ignis/issues"
   },
-  "homepage": "https://github.com/VENIZIA-AI/ignis/wiki",
+  "homepage": "https://venizia-ai.github.io/ignis",
   "license": "MIT",
   "dependencies": {
     "@mastra/core": "^0.24.6",
@@ -92,7 +111,7 @@
     "@braintree/sanitize-url": "^7.1.1",
     "@types/bun": "^1.3.4",
     "@types/glob": "^8.1.0",
-    "@venizia/dev-configs": "latest",
+    "@venizia/dev-configs": "^0.0.1-4",
     "eslint": "^9.36.0",
     "glob": "^10.4.2",
     "prettier": "^3.6.2",

package/wiki/get-started/best-practices/api-usage-examples.md

@@ -219,4 +219,46 @@ const deleted = await configurationRepository.deleteById({
   id: newRecord.data!.id,
   options: { shouldReturn: true }, // Option to return the deleted record
 });
+
+## 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.
+
+**Usage:**
+
+Use `defineJSXRoute` in your controller and `htmlResponse` for documentation.
+
+```typescript
+import { BaseController, controller, htmlResponse } from '@venizia/ignis';
+
+@controller({ path: '/pages' })
+export class PageController extends BaseController {
+  
+  override binding(): void {
+    this.defineJSXRoute({
+      configs: {
+        method: 'get',
+        path: '/welcome',
+        description: 'Welcome Page',
+        responses: htmlResponse({ description: 'HTML Welcome Page' }),
+      },
+      handler: (c) => {
+        const title = 'Welcome to Ignis';
+        
+        // Return JSX directly
+        return c.html(
+          <html>
+            <head><title>{title}</title></head>
+            <body>
+              <h1>{title}</h1>
+              <p>Server-side rendered content.</p>
+            </body>
+          </html>
+        );
+      },
+    });
+  }
+}
+```
+
 ```

package/wiki/get-started/best-practices/architectural-patterns.md

@@ -126,4 +126,45 @@ 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, while the details of each feature are neatly encapsulated within their respective components.
+
+## 4. Custom Components
+
+You can encapsulate your own logic or third-party integrations (like Socket.IO, Redis, specific Cron jobs) into reusable Components.
+
+**Structure of a Component:**
+1.  Extend `BaseComponent`.
+2.  Define default `bindings` (optional configuration/options).
+3.  Implement `binding()` to register services, providers, or attach logic to the application.
+
+**Example (`SocketIOComponent`):**
+
+```typescript
+import { BaseComponent, inject, CoreBindings, Binding } from '@venizia/ignis';
+
+export class MySocketComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
+  ) {
+    super({
+      scope: MySocketComponent.name,
+      // Automatically register bindings when component is loaded
+      initDefault: { enable: true, container: application },
+      bindings: {
+        // Define default configuration binding
+        'my.socket.options': Binding.bind({ key: 'my.socket.options' }).toValue({ port: 8080 }),
+      },
+    });
+  }
+
+  // The binding method is called during application startup (preConfigure)
+  override binding(): void {
+    const options = this.application.get({ key: 'my.socket.options' });
+    
+    this.logger.info('Initializing Socket.IO with options: %j', options);
+    
+    // Perform setup logic, register other services, etc.
+    // this.application.bind(...).toValue(...);
+  }
+}
+```

package/wiki/get-started/best-practices/code-style-standards.md

@@ -120,3 +120,44 @@ Use the centralized TypeScript configs:
 - `skipLibCheck: true` - Faster compilation
 
 See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs.md) for full details.
+
+## Environment Variables Management
+
+Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants. This ensures type safety and centralized management.
+
+**Define Keys (`src/common/environments.ts`):**
+```typescript
+export class EnvironmentKeys {
+  static readonly APP_ENV_STRIPE_KEY = 'APP_ENV_STRIPE_KEY';
+  static readonly APP_ENV_MAX_RETRIES = 'APP_ENV_MAX_RETRIES';
+}
+```
+
+**Usage:**
+```typescript
+import { applicationEnvironment } from '@venizia/ignis';
+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);
+```
+
+## Standardized Error Handling
+
+Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions that the framework's error handler can process correctly.
+
+**Example:**
+```typescript
+import { getError, HTTP } from '@venizia/ignis';
+
+if (!record) {
+  throw getError({
+    statusCode: HTTP.ResultCodes.RS_4.NotFound,
+    message: 'Record not found',
+    // Optional details
+    details: { id: requestedId }
+  });
+}
+```
+

package/wiki/get-started/best-practices/contribution-workflow.md

@@ -32,13 +32,45 @@ feature/*, fix/*, docs/* (your work)
 git clone https://github.com/YOUR_USERNAME/ignis.git
 cd ignis
 
-# 3. Install dependencies
-bun install
+# 3. Install dependencies (this also runs force-update to fetch latest from NPM)
+make install
+# Or: bun install
 
 # 4. Add upstream remote
 git remote add upstream https://github.com/VENIZIA-AI/ignis.git
 ```
 
+## Makefile Commands
+
+The project uses a Makefile for common development tasks:
+
+| Command | Description |
+|---------|-------------|
+| `make install` | Install dependencies and force-update from NPM |
+| `make update` | Force update all packages from NPM registry |
+| `make build` | Rebuild all packages in correct order |
+| `make clean` | Clean build artifacts from all packages |
+| `make lint` | Lint all packages |
+| `make help` | Show all available commands |
+
+**Individual package builds:**
+```bash
+make core          # Build @venizia/ignis (after dependencies)
+make helpers       # Build @venizia/ignis-helpers
+make inversion     # Build @venizia/ignis-inversion
+make dev-configs   # Build @venizia/dev-configs
+make docs          # Build documentation
+```
+
+**Force update individual packages:**
+```bash
+make update-core
+make update-helpers
+make update-inversion
+make update-dev-configs
+make update-docs
+```
+
 ## 2. Development Workflow
 
 ### Step 1: Create Branch
@@ -92,11 +124,13 @@ git commit -m "chore: upgrade Hono to v4.0"
 ### Step 4: Validate
 
 ```bash
-# Lint and format
-bun run lint:fix
+# Lint and format (from root)
+make lint
+# Or: bun run lint:fix
 
-# Build TypeScript
-bun run build
+# Build all packages
+make build
+# Or: bun run build
 
 # Run tests
 bun run test

package/wiki/get-started/best-practices/data-modeling.md

@@ -0,0 +1,126 @@
+# Data Modeling
+
+Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers and "enrichers" that reduce boilerplate code for common schema patterns.
+
+## 1. Base Entity
+
+All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
+
+**Example (`src/models/entities/configuration.model.ts`):**
+
+```typescript
+import {
+  BaseEntity,
+  model,
+  TTableObject,
+} from '@venizia/ignis';
+import { configurationTable } from './schema'; // Your Drizzle schema
+
+// Define types for TypeScript inference
+export type TConfigurationSchema = typeof configurationTable;
+export type TConfiguration = TTableObject<TConfigurationSchema>;
+
+@model({ type: 'entity', skipMigrate: false })
+export class Configuration extends BaseEntity<TConfigurationSchema> {
+  static readonly TABLE_NAME = Configuration.name;
+
+  constructor() {
+    super({
+      name: Configuration.TABLE_NAME,
+      schema: configurationTable,
+    });
+  }
+}
+```
+
+## 2. Schema Enrichers
+
+Instead of manually defining common columns like primary keys, timestamps, or audit fields in every table, use Ignis "enrichers".
+
+**Available Enrichers:**
+
+| Enricher | Description | Columns Added |
+|----------|-------------|---------------|
+| `generateIdColumnDefs` | Adds a Primary Key | `id` (string/UUID or number/Serial) |
+| `generateTzColumnDefs` | Adds timestamps | `createdAt`, `modifiedAt` (auto-updating) |
+| `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` |
+| `generateDataTypeColumnDefs` | Adds generic value fields | `nValue` (number), `tValue` (text), `jValue` (json), etc. |
+| `generatePrincipalColumnDefs` | Adds polymorphic relation fields | `principalType`, `principalId` |
+
+**Usage Example:**
+
+```typescript
+import {
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+  generateUserAuditColumnDefs,
+} from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+
+export const configurationTable = pgTable(
+  'Configuration',
+  {
+    // 1. Auto-generate UUID Primary Key
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+
+    // 2. Auto-generate createdAt / modifiedAt
+    ...generateTzColumnDefs(),
+
+    // 3. Auto-generate createdBy / modifiedBy
+    ...generateUserAuditColumnDefs({
+      created: { dataType: 'string', columnName: 'created_by' },
+      modified: { dataType: 'string', columnName: 'modified_by' },
+    }),
+
+    // 4. Your custom columns
+    code: text('code').notNull(),
+    description: text('description'),
+    group: text('group').notNull(),
+  },
+  (table) => [
+    // Define indexes/constraints here
+    unique('UQ_code').on(table.code),
+  ]
+);
+```
+
+## 3. Defining Relations
+
+Use the `createRelations` helper to define relationships cleanly. This abstracts the Drizzle `relations` function and makes it easy to bind to repositories.
+
+**Example:**
+
+```typescript
+import { createRelations, RelationTypes } from '@venizia/ignis';
+import { userTable } from './user.model';
+
+export const configurationRelations = createRelations({
+  source: configurationTable,
+  relations: [
+    {
+      name: 'creator',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: {
+        fields: [configurationTable.createdBy],
+        references: [userTable.id],
+      },
+    },
+  ],
+});
+```
+
+This configuration is then passed directly to your Repository:
+
+```typescript
+@repository({})
+export class ConfigurationRepository extends DefaultCRUDRepository<TConfigurationSchema> {
+  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
+    super({
+      dataSource,
+      entityClass: Configuration,
+      relations: configurationRelations.definitions, // <-- Injected here
+    });
+  }
+}
+```

package/wiki/get-started/core-concepts/dependency-injection.md

@@ -50,7 +50,7 @@ Before a dependency can be injected, it must be **bound** to the container. This
 
 The `Application` class provides helper methods for common resource types. These automatically create a binding with a conventional key.
 
-| Method | Example Key |
+| Method | Default Key |
 | :--- | :--- |
 | `app.service(UserService)` | `services.UserService` |
 | `app.repository(UserRepository)` | `repositories.UserRepository` |
@@ -58,6 +58,18 @@ The `Application` class provides helper methods for common resource types. These
 | `app.controller(UserController)` | `controllers.UserController` |
 | `app.component(MyComponent)` | `components.MyComponent` |
 
+All these methods accept an optional second parameter to customize the binding key:
+
+```typescript
+// Default binding (key: 'controllers.UserController')
+app.controller(UserController);
+
+// Custom binding key
+app.controller(UserController, {
+  binding: { namespace: 'controllers', key: 'CustomUserController' }
+});
+```
+
 ### Custom Bindings
 
 For other values or more complex setups, use the `bind` method directly.