@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/dist/mcp-server/common/paths.d.ts

@@ -1,13 +1,15 @@
 export declare class Paths {
     static readonly WIKI: string;
+    static readonly GUIDES: string;
     static readonly GET_STARTED: string;
-    static readonly BEST_PRACTICES: string;
     static readonly CORE_CONCEPTS: string;
+    static readonly BEST_PRACTICES: string;
     static readonly REFERENCES: string;
     static readonly BASE: string;
+    static readonly UTILITIES: string;
+    static readonly EXTENSIONS: string;
     static readonly COMPONENTS: string;
     static readonly HELPERS: string;
     static readonly SOURCE_DETAILS: string;
-    static readonly UTILITIES: string;
 }
 //# sourceMappingURL=paths.d.ts.map

package/dist/mcp-server/common/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":"AAOA,qBAAa,KAAK;IAChB,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAgC;IAEpD,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAuC;IAClE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAAiD;IAC/E,MAAM,CAAC,QAAQ,CAAC,aAAa,SAAgD;IAE7E,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAsC;IAC1D,MAAM,CAAC,QAAQ,CAAC,UAAU,SAA4C;IACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAyC;IAChE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA6C;IAC3E,MAAM,CAAC,QAAQ,CAAC,SAAS,SAA2C;CACrE"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":"AAOA,qBAAa,KAAK;IAChB,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAgC;IAEpD,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAkC;IACxD,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAyC;IACpE,MAAM,CAAC,QAAQ,CAAC,aAAa,SAA2C;IACxE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA0C;IAExE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAsC;IAC1D,MAAM,CAAC,QAAQ,CAAC,SAAS,SAA2C;IAEpE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAA4C;IACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAyC;IAChE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA6C;CAC5E"}

package/dist/mcp-server/common/paths.js

@@ -11,15 +11,17 @@ const MCP_ROOT = __dirname;
 const DOCS_ROOT = node_path_1.default.resolve(MCP_ROOT, '..', '..', '..');
 class Paths {
     static { this.WIKI = node_path_1.default.join(DOCS_ROOT, 'wiki'); }
-    static { this.GET_STARTED = node_path_1.default.join(this.WIKI, 'get-started'); }
-    static { this.BEST_PRACTICES = node_path_1.default.join(this.GET_STARTED, 'best-practices'); }
-    static { this.CORE_CONCEPTS = node_path_1.default.join(this.GET_STARTED, 'core-concepts'); }
+    static { this.GUIDES = node_path_1.default.join(this.WIKI, 'guides'); }
+    static { this.GET_STARTED = node_path_1.default.join(this.GUIDES, 'get-started'); }
+    static { this.CORE_CONCEPTS = node_path_1.default.join(this.GUIDES, 'core-concepts'); }
+    static { this.BEST_PRACTICES = node_path_1.default.join(this.WIKI, 'best-practices'); }
     static { this.REFERENCES = node_path_1.default.join(this.WIKI, 'references'); }
     static { this.BASE = node_path_1.default.join(this.REFERENCES, 'base'); }
-    static { this.COMPONENTS = node_path_1.default.join(this.REFERENCES, 'components'); }
-    static { this.HELPERS = node_path_1.default.join(this.REFERENCES, 'helpers'); }
-    static { this.SOURCE_DETAILS = node_path_1.default.join(this.REFERENCES, 'src-details'); }
     static { this.UTILITIES = node_path_1.default.join(this.REFERENCES, 'utilities'); }
+    static { this.EXTENSIONS = node_path_1.default.join(this.WIKI, 'extensions'); }
+    static { this.COMPONENTS = node_path_1.default.join(this.EXTENSIONS, 'components'); }
+    static { this.HELPERS = node_path_1.default.join(this.EXTENSIONS, 'helpers'); }
+    static { this.SOURCE_DETAILS = node_path_1.default.join(this.EXTENSIONS, 'src-details'); }
 }
 exports.Paths = Paths;
 //# sourceMappingURL=paths.js.map

package/dist/mcp-server/common/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,MAAM,QAAQ,GAAG,SAAS,CAAC;AAC3B,qDAAqD;AACrD,6EAA6E;AAC7E,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE3D,MAAa,KAAK;aACA,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;aAEpC,gBAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;aAClD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;aAC/D,kBAAa,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;aAE7D,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;aAC1C,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;aACtD,YAAO,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;aAChD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;aAC3D,cAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;;AAZtE,sBAaC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,MAAM,QAAQ,GAAG,SAAS,CAAC;AAC3B,qDAAqD;AACrD,6EAA6E;AAC7E,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE3D,MAAa,KAAK;aACA,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;aAEpC,WAAM,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;aACxC,gBAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;aACpD,kBAAa,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;aACxD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;aAExD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;aAC1C,cAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;aAEpD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;aACtD,YAAO,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;aAChD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;;AAf7E,sBAgBC"}

package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts

@@ -10,7 +10,7 @@ declare const OutputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare class GetDocContentTool extends BaseTool<typeof InputSchema, typeof OutputSchema> {
     readonly id = "getDocumentContent";
-    readonly description = "\nRetrieves the complete markdown content of a specific Ignis Framework documentation file.\n\nPURPOSE:\nUse this tool to fetch the full text of a documentation page when you need detailed information\nbeyond what search snippets provide. This is your primary tool for reading documentation content.\n\nWHEN TO USE:\n- After searchDocs returns relevant results and you need full content\n- When user asks for detailed explanation of a specific topic\n- To read code examples, API references, or configuration guides\n- When you need to quote or reference specific documentation sections\n\nWHEN NOT TO USE:\n- Don't use this for discovery - use searchDocs or listDocs first\n- Don't fetch multiple documents blindly - review search results first\n\nDOCUMENT ID FORMAT:\nThe 'id' parameter is the relative file path from the wiki root:\n- \"get-started/quickstart.md\" - Quickstart guide\n- \"references/components/http-server.md\" - HTTP Server component reference\n- \"get-started/core-concepts/dependency-injection.md\" - DI concepts\n\nHOW TO GET VALID IDs:\n1. Use searchDocs to find documents by keyword\n2. Use listDocs to browse all available documents\n3. Use listCategories + listDocs(category) for structured browsing\n\nOUTPUT:\nReturns full markdown content suitable for:\n- Answering user questions with accurate information\n- Extracting code examples\n- Understanding API usage patterns\n- Providing step-by-step guidance\n";
+    readonly description = "\nRetrieves the complete markdown content of a specific Ignis Framework documentation file.\n\nPURPOSE:\nUse this tool to fetch the full text of a documentation page when you need detailed information\nbeyond what search snippets provide. This is your primary tool for reading documentation content.\n\nWHEN TO USE:\n- After searchDocs returns relevant results and you need full content\n- When user asks for detailed explanation of a specific topic\n- To read code examples, API references, or configuration guides\n- When you need to quote or reference specific documentation sections\n\nWHEN NOT TO USE:\n- Don't use this for discovery - use searchDocs or listDocs first\n- Don't fetch multiple documents blindly - review search results first\n\nDOCUMENT ID FORMAT:\nThe 'id' parameter is the relative file path from the wiki root:\n- \"guides/get-started/5-minute-quickstart.md\" - Quickstart guide\n- \"extensions/helpers/redis/index.md\" - Redis helper reference\n- \"references/base/dependency-injection.md\" - DI reference\n\nHOW TO GET VALID IDs:\n1. Use searchDocs to find documents by keyword\n2. Use listDocs to browse all available documents\n3. Use listCategories + listDocs(category) for structured browsing\n\nOUTPUT:\nReturns full markdown content suitable for:\n- Answering user questions with accurate information\n- Extracting code examples\n- Understanding API usage patterns\n- Providing step-by-step guidance\n";
     readonly inputSchema: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strip>;

package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-document-content.tool.d.ts","sourceRoot":"","sources":["../../../../mcp-server/tools/docs/get-document-content.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA6ExC,QAAA,MAAM,WAAW;;iBAEf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;iBAOhB,CAAC;AAEH,qBAAa,iBAAkB,SAAQ,QAAQ,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,CAAC;IACtF,QAAQ,CAAC,EAAE,wBAAwB;IACnC,QAAQ,CAAC,WAAW,o6CAAoB;IACxC,QAAQ,CAAC,WAAW;;sBAAe;IACnC,QAAQ,CAAC,YAAY;;;;sBAAgB;IAE/B,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;IAUvF,OAAO;;;;;;;CASR"}
+{"version":3,"file":"get-document-content.tool.d.ts","sourceRoot":"","sources":["../../../../mcp-server/tools/docs/get-document-content.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA6ExC,QAAA,MAAM,WAAW;;iBAEf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;iBAOhB,CAAC;AAEH,qBAAa,iBAAkB,SAAQ,QAAQ,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,CAAC;IACtF,QAAQ,CAAC,EAAE,wBAAwB;IACnC,QAAQ,CAAC,WAAW,+5CAAoB;IACxC,QAAQ,CAAC,WAAW;;sBAAe;IACnC,QAAQ,CAAC,YAAY;;;;sBAAgB;IAE/B,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;IAUvF,OAAO;;;;;;;CASR"}

package/dist/mcp-server/tools/docs/get-document-content.tool.js

@@ -24,9 +24,9 @@ WHEN NOT TO USE:
 
 DOCUMENT ID FORMAT:
 The 'id' parameter is the relative file path from the wiki root:
-- "get-started/quickstart.md" - Quickstart guide
-- "references/components/http-server.md" - HTTP Server component reference
-- "get-started/core-concepts/dependency-injection.md" - DI concepts
+- "guides/get-started/5-minute-quickstart.md" - Quickstart guide
+- "extensions/helpers/redis/index.md" - Redis helper reference
+- "references/base/dependency-injection.md" - DI reference
 
 HOW TO GET VALID IDs:
 1. Use searchDocs to find documents by keyword
@@ -46,10 +46,10 @@ Unique document identifier - the relative file path from the wiki root directory
 FORMAT: "<category>/<subcategory>/<filename>.md"
 
 EXAMPLES:
-- "get-started/quickstart.md"
-- "get-started/core-concepts/dependency-injection.md"
-- "references/components/http-server.md"
-- "references/helpers/redis.md"
+- "guides/get-started/5-minute-quickstart.md"
+- "references/base/dependency-injection.md"
+- "extensions/helpers/redis/index.md"
+- "extensions/components/authentication/index.md"
 
 HOW TO OBTAIN:
 - From searchDocs results (the 'id' field)

package/dist/mcp-server/tools/docs/get-document-metadata.tool.js

@@ -52,9 +52,9 @@ Unique document identifier - the relative file path from the wiki root directory
 FORMAT: "<category>/<subcategory>/<filename>.md"
 
 EXAMPLES:
-- "get-started/quickstart.md"
-- "references/components/http-server.md"
-- "get-started/core-concepts/dependency-injection.md"
+- "guides/get-started/5-minute-quickstart.md"
+- "extensions/helpers/redis/index.md"
+- "references/base/dependency-injection.md"
 
 HOW TO OBTAIN:
 - From searchDocs results (the 'id' field)

package/dist/mcp-server/tools/docs/get-package-overview.tool.d.ts

@@ -18,7 +18,7 @@ declare const OutputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare class GetPackageOverviewTool extends BaseTool<typeof InputSchema, typeof OutputSchema> {
     readonly id = "getPackageOverview";
-    readonly description = "\nReturns an overview of Ignis packages from the source details documentation.\n\nPURPOSE:\nProvides AI agents with comprehensive understanding of the Ignis monorepo structure,\npackage purposes, main exports, and directory layouts. This is essential for helping\nusers understand which package to use for specific features.\n\nWHEN TO USE:\n- When user asks \"what packages does Ignis have?\"\n- When user needs to understand project structure\n- When user asks which package provides a specific feature\n- Before helping user implement a feature (to know where code should go)\n- When user asks about imports or package dependencies\n\nWHEN NOT TO USE:\n- For specific API documentation (use getDocContent with references/ docs)\n- For code examples (use searchCode or getDocContent)\n- For troubleshooting (use searchDocs)\n\nOUTPUT:\nReturns package name, description, main directories, and key components.\nThe content comes from wiki/references/src-details/ documentation.\n";
+    readonly description = "\nReturns an overview of Ignis packages from the source details documentation.\n\nPURPOSE:\nProvides AI agents with comprehensive understanding of the Ignis monorepo structure,\npackage purposes, main exports, and directory layouts. This is essential for helping\nusers understand which package to use for specific features.\n\nWHEN TO USE:\n- When user asks \"what packages does Ignis have?\"\n- When user needs to understand project structure\n- When user asks which package provides a specific feature\n- Before helping user implement a feature (to know where code should go)\n- When user asks about imports or package dependencies\n\nWHEN NOT TO USE:\n- For specific API documentation (use getDocContent with references/ docs)\n- For code examples (use searchCode or getDocContent)\n- For troubleshooting (use searchDocs)\n\nOUTPUT:\nReturns package name, description, main directories, and key components.\nThe content comes from wiki/extensions/src-details/ documentation.\n";
     readonly inputSchema: z.ZodObject<{
         packageName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;

package/dist/mcp-server/tools/docs/get-package-overview.tool.js

@@ -35,7 +35,7 @@ WHEN NOT TO USE:
 
 OUTPUT:
 Returns package name, description, main directories, and key components.
-The content comes from wiki/references/src-details/ documentation.
+The content comes from wiki/extensions/src-details/ documentation.
 `;
 const PACKAGE_NAME_DESCRIPTION = `
 Optional: Name of specific package to get details for.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.7-2",
+  "version": "0.0.8-0",
   "description": "Interactive documentation site and MCP (Model Context Protocol) server for the Ignis Framework. Includes a VitePress-powered documentation site with guides, API references, and best practices. Ships an MCP server (CLI: ignis-docs-mcp) with 11 tools for AI assistants to search docs, browse source code, verify dependencies, and access real-time framework knowledge. Built with Mastra MCP SDK and Fuse.js fuzzy search.",
   "keywords": [
     "ai",

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

@@ -48,7 +48,7 @@ Then, use the decorators in your controller class.
 **`src/controllers/test/controller.ts`**
 ```typescript
 import {
-  BaseController,
+  BaseRestController,
   controller,
   get,
   post,
@@ -57,8 +57,8 @@ import {
 import { HTTP } from '@venizia/ignis-helpers';
 import { RouteConfigs } from './definitions';
 
-@controller({ path: '/test' })
-export class TestController extends BaseController {
+@controller({ path: '/test' }) // transport defaults to 'rest'
+export class TestController extends BaseRestController {
   // ...
 
   @get({ configs: RouteConfigs.GET_TEST })
@@ -91,12 +91,12 @@ You can also define routes manually within the controller's `binding()` method u
 
 **`src/controllers/test/controller.ts`**
 ```typescript
-import { BaseController, controller, ValueOrPromise } from '@venizia/ignis';
+import { BaseRestController, controller, ValueOrPromise } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 import { RouteConfigs } from './definitions';
 
 @controller({ path: '/test' })
-export class TestController extends BaseController {
+export class TestController extends BaseRestController {
   // ...
   override binding(): ValueOrPromise<void> {
     // Using 'defineRoute'
@@ -236,10 +236,10 @@ Ignis supports server-side rendering using Hono's JSX middleware. This is useful
 Use `defineJSXRoute` in your controller and `htmlResponse` for documentation.
 
 ```typescript
-import { BaseController, controller, htmlResponse } from '@venizia/ignis';
+import { BaseRestController, controller, htmlResponse } from '@venizia/ignis';
 
 @controller({ path: '/pages' })
-export class PageController extends BaseController {
+export class PageController extends BaseRestController {
   
   override binding(): void {
     this.defineJSXRoute({
@@ -330,7 +330,7 @@ Apply middleware to specific routes in your controller:
 
 ```typescript
 @controller({ path: '/admin' })
-export class AdminController extends BaseController {
+export class AdminController extends BaseRestController {
   constructor() {
     super({ scope: AdminController.name, path: '/admin' });
   }
@@ -412,7 +412,7 @@ export class UserService extends BaseService {
 
 ```typescript
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor(
     @inject({
       key: BindingKeys.build({

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

@@ -10,7 +10,7 @@ Each layer has a single responsibility. Ignis supports **two architectural appro
 graph TD
     Client[Client/API Consumer]
 
-    Client -->|HTTP Request| Controller[Controllers]
+    Client -->|HTTP/gRPC Request| Controller[Controllers]
 
     Controller -->|Simple CRUD| Repo[Repositories]
     Controller -->|Complex Logic| Service[Services]
@@ -27,7 +27,7 @@ graph TD
 
 | Layer | Responsibility | Example |
 |-------|---------------|---------|
-| **Controllers** | Handle HTTP - parse requests, validate, format responses | `ConfigurationController` (uses `ControllerFactory`) |
+| **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`) |
 | **DataSources** | Database connections | `PostgresDataSource` (connects to PostgreSQL) |
@@ -79,7 +79,7 @@ Classes declare dependencies in their constructor - the framework automatically
 - Easy to test (mock dependencies)
 - Easy to swap implementations
 
-**Example:**
+**Example (REST controller):**
 ```typescript
 @controller({ path: BASE_PATH })
 export class ConfigurationController extends _Controller {
@@ -99,6 +99,22 @@ export class ConfigurationController extends _Controller {
 }
 ```
 
+**Controller Transports:**
+
+The `@controller` decorator supports a `transport` field to distinguish between REST and gRPC controllers:
+
+```typescript
+// REST controller (default - transport can be omitted)
+@controller({ path: '/users' })
+export class UserController extends BaseRestController { ... }
+
+// gRPC controller (transport is required)
+@controller({ path: '/greeter', transport: 'grpc', service: GreeterService })
+export class GreeterController extends BaseGrpcController { ... }
+```
+
+REST controllers extend `BaseRestController`, while gRPC controllers extend `BaseGrpcController`. The application must enable the appropriate transport(s) in its configuration.
+
 ## 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.

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

@@ -21,9 +21,9 @@ This guide helps you make informed architectural decisions when building applica
 ```typescript
 // Simple CRUD with no business logic
 @controller({ path: '/items' })
-export class ItemController extends BaseController {
+export class ItemController extends BaseRestController {
   constructor(
-    @inject('repositories.ItemRepository')
+    @inject({ key: 'repositories.ItemRepository' })
     private itemRepo: ItemRepository,
   ) {
     super({ scope: 'ItemController', path: '/items' });
@@ -48,9 +48,9 @@ export class ItemController extends BaseController {
 ```typescript
 // Complex business logic needs a service
 @controller({ path: '/orders' })
-export class OrderController extends BaseController {
+export class OrderController extends BaseRestController {
   constructor(
-    @inject('services.OrderService')
+    @inject({ key: 'services.OrderService' })
     private orderService: OrderService,
   ) {
     super({ scope: 'OrderController', path: '/orders' });
@@ -125,7 +125,7 @@ export class NotificationComponent extends BaseComponent {
 ```typescript
 // Inline: Simple, one-off, no need for abstraction
 @controller({ path: '/health' })
-export class HealthController extends BaseController {
+export class HealthController extends BaseRestController {
   @get({ configs: { path: '/' } })
   healthCheck(c: Context) {
     return c.json({ status: 'ok', timestamp: new Date() });
@@ -209,7 +209,7 @@ export class OrderRepository extends BaseRepository<Order> {
 
 ```typescript
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   @post({ configs: { path: '/' } })
   async createUser(c: Context) {
     try {

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

@@ -65,7 +65,7 @@ class ControllerFactory {
   static defineCrudController<Schema extends TTableSchemaWithId>(
     opts: ICrudControllerOptions<Schema>,
   ) {
-    return class extends BaseController {
+    return class extends BaseRestController {
       constructor(repository: AbstractRepository<Schema>) {
         super({ scope: opts.controller.name });
         this.repository = repository;

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

@@ -241,5 +241,5 @@ import { QueryBuilder } from '../query';
 ## See Also
 
 - [Error Handling](../error-handling) - Comprehensive error patterns
-- [Logging Reference](../../references/helpers/logger/) - Logger API
+- [Logging Reference](../../extensions/helpers/logger/) - Logger API
 - [Function Patterns](./function-patterns) - Method organization

package/wiki/best-practices/code-style-standards/function-patterns.md

@@ -100,9 +100,9 @@ export class JWTTokenService extends BaseService {
   }
 }
 
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor() {
-    super({ scope: UserController.name });
+    super({ scope: UserController.name, path: '/users' });
   }
 }
 ```

package/wiki/best-practices/code-style-standards/index.md

@@ -53,9 +53,9 @@ interface IUserService { }
 type TUserRequest = { };
 
 // Classes use PascalCase with suffix
-class UserController extends BaseController { }
+class UserController extends BaseRestController { }
 class UserService extends BaseService { }
-class UserRepository extends BaseRepository { }
+class UserRepository extends DefaultCRUDRepository { }
 ```
 
 ### File Structure

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

@@ -121,7 +121,7 @@ export class SocketIOBindingKeys {
 Use underscore prefix (`_`) for private and protected class fields to distinguish them from public fields and method parameters.
 
 ```typescript
-class MyRepository extends BaseRepository {
+class MyRepository extends DefaultCRUDRepository {
   // Private fields with underscore prefix
   private _dataSource: IDataSource;
   private _entity: BaseEntity;

package/wiki/best-practices/code-style-standards/route-definitions.md

@@ -41,7 +41,7 @@ export const RouteConfigs = {
 
 ```typescript
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
 
   @api({ configs: RouteConfigs.GET_USERS })
   list(context: TRouteContext) {
@@ -60,7 +60,7 @@ export class UserController extends BaseController {
 
 ```typescript
 @controller({ path: '/health' })
-export class HealthCheckController extends BaseController {
+export class HealthCheckController extends BaseRestController {
   constructor() {
     super({ scope: HealthCheckController.name });
 
@@ -75,7 +75,7 @@ export class HealthCheckController extends BaseController {
 
 ```typescript
 @controller({ path: '/health' })
-export class HealthCheckController extends BaseController {
+export class HealthCheckController extends BaseRestController {
   constructor() {
     super({ scope: HealthCheckController.name });
 
@@ -147,4 +147,4 @@ export const RouteConfigs = {
 
 - [API Usage Examples](../api-usage-examples) - Full API patterns
 - [Controllers Reference](../../references/base/controllers) - Controller API
-- [Swagger Component](../../references/components/swagger) - OpenAPI setup
+- [Swagger Component](../../extensions/components/swagger) - OpenAPI setup

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

@@ -405,7 +405,7 @@ export class User extends BaseEntity<typeof User.schema> {
 - Explicit `static AUTHORIZATION_SUBJECT = '...'` on the class takes precedence
 - The `authorize` settings are extensible via index signature for custom metadata
 
-> **Reference:** See [Model-Based Resource References](../references/components/authorization/usage#model-based-resource-references) for full authorization integration.
+> **Reference:** See [Model-Based Resource References](../extensions/components/authorization/usage#model-based-resource-references) for full authorization integration.
 
 ## 7. Database Migrations
 

package/wiki/best-practices/deployment-strategies.md

@@ -668,7 +668,7 @@ Add Prometheus metrics endpoint:
 ```typescript
 // src/controllers/metrics.controller.ts
 @controller({ path: '/metrics' })
-export class MetricsController extends BaseController {
+export class MetricsController extends BaseRestController {
   @get({ configs: { path: '/' } })
   getMetrics(c: Context) {
     return c.text(`

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

@@ -119,10 +119,10 @@ export class UserService extends BaseService {
 Controllers should delegate to services and let the global error handler catch exceptions:
 
 ```typescript
-import { BaseController, controller, get, post } from '@venizia/ignis';
+import { BaseRestController, controller, get, post } from '@venizia/ignis';
 
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
 
   @post({ configs: RouteConfigs.CREATE_USER })
   async createUser(c: TRouteContext) {

package/wiki/best-practices/performance-optimization.md

@@ -32,7 +32,7 @@ Prevent blocking the event loop with Worker Threads:
 - Large file/data processing
 - Any synchronous task > 5ms
 
-> **Deep Dive:** See [Worker Thread Helper](../references/helpers/worker-thread/) for implementation guide.
+> **Deep Dive:** See [Worker Thread Helper](../extensions/helpers/worker-thread/) for implementation guide.
 
 ## 3. Optimize Database Queries
 
@@ -127,7 +127,7 @@ Reduce database load with caching:
 
 | Cache Type | Use Case | Implementation |
 |-----------|----------|----------------|
-| **Redis** | Distributed cache, session storage | [Redis Helper](../references/helpers/redis/) |
+| **Redis** | Distributed cache, session storage | [Redis Helper](../extensions/helpers/redis/) |
 | **In-Memory** | Single-process cache | `MemoryStorageHelper` |
 
 **Example:**
@@ -390,7 +390,7 @@ logger.log('info', MSG_ORDER_FILLED);
 - Use background flushing to avoid I/O blocking
 - HfLogger uses a lock-free ring buffer (64K entries, 16MB)
 
-> **Deep Dive:** See [Logger Helper](../references/helpers/logger/) for complete HfLogger API.
+> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for complete HfLogger API.
 
 ## Performance Checklist
 

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

@@ -68,7 +68,7 @@ const SecureRoute = {
 };
 ```
 
-> **Deep Dive:** See [Authentication Component](../references/components/authentication/) for full setup guide.
+> **Deep Dive:** See [Authentication Component](../extensions/components/authentication/) for full setup guide.
 
 **Access user in protected routes:**
 ```typescript
@@ -463,6 +463,6 @@ Before deploying to production, verify:
 
 ## See Also
 
-- [Authentication Component](../references/components/authentication/) - JWT setup and configuration
+- [Authentication Component](../extensions/components/authentication/) - JWT setup and configuration
 - [Common Pitfalls](./common-pitfalls) - Security-related mistakes to avoid
 - [Deployment Strategies](./deployment-strategies) - Secure deployment practices

package/wiki/best-practices/troubleshooting-tips.md

@@ -118,7 +118,7 @@ cat .env | grep APP_ENV
 - Use `try-catch` blocks to catch and log errors
 - Check database queries with Drizzle's logging: `{ logger: true }`
 
-> **Deep Dive:** See [Logger Helper](../references/helpers/logger/) for advanced logging configuration.
+> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for advanced logging configuration.
 
 ## 6. Request ID Tracking
 

package/wiki/{references → extensions}/components/authentication/api.md

@@ -179,7 +179,7 @@ export const authenticate = (opts: { strategies: string[]; mode?: TAuthMode }) =
 This is the primary export for creating auth middleware. It creates an `AuthenticationProvider` instance and calls `.value()` to get the middleware factory. The provider uses `AuthenticationStrategyRegistry.getInstance()` internally to resolve strategies.
 
 > [!NOTE]
-> In `all` mode, if every strategy passes but the final user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode **discards errors** from each failing strategy (logs at debug level) and only throws after all strategies are exhausted.
+> In `all` mode, the **first** strategy's user payload is used as the identity source — all strategies must succeed but the first one wins for identity. If every strategy passes but the first user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode **discards errors** from each failing strategy (logs at debug level) and only throws after all strategies are exhausted.
 
 ## Service Class Hierarchy
 
@@ -531,7 +531,7 @@ Serves the JWKS endpoint (default path `/certs`). This endpoint is **intentional
 **File:** `packages/core/src/components/auth/authenticate/controllers/jwks/controller.ts`
 
 ```typescript
-class JWKSController extends BaseController {
+class JWKSController extends BaseRestController {
   constructor(
     @inject({
       key: BindingKeys.build({
@@ -646,43 +646,35 @@ type TPermissionCommonColumns = {
   code: NotNull<PgTextBuilderInitial<...>>;
   name: NotNull<PgTextBuilderInitial<...>>;
   subject: NotNull<PgTextBuilderInitial<...>>;
-  pType: NotNull<PgTextBuilderInitial<...>>;
   action: NotNull<PgTextBuilderInitial<...>>;
   scope: NotNull<PgTextBuilderInitial<...>>;
 };
 ```
 
-### Permission Mapping Types
+### Policy Definition Types
 
 ```typescript
-type TPermissionMappingOptions = {
+type TPolicyDefinitionOptions = {
   idType?: 'string' | 'number';
 };
 
-type TPermissionMappingCommonColumns = {
-  effect: PgTextBuilderInitial<...>;
+type TPolicyDefinitionCommonColumns = {
+  variant: ReturnType<typeof text>;
+  subjectType: ReturnType<typeof text>;
+  targetType: ReturnType<typeof text>;
+  action: ReturnType<typeof text>;
+  effect: ReturnType<typeof text>;
+  domain: ReturnType<typeof text>;
 };
 ```
 
-### User Role Types
-
-```typescript
-type TUserRoleOptions = {
-  idType?: 'string' | 'number';
-};
-
-type TUserRoleCommonColumns = ReturnType<
-  typeof generatePrincipalColumnDefs<'principal', 'string' | 'number'>
->;
-```
-
 ## Controller Factory
 
 The `defineAuthController()` function dynamically creates a controller class at runtime using decorator composition:
 
 **How it works:**
 
-1. **Class creation:** A new class is created dynamically with `class AuthController extends BaseController {}` inside the factory closure
+1. **Class creation:** A new class is created dynamically with `class AuthController extends BaseRestController {}` inside the factory closure
 2. **Decorator application:** The `@controller({ path: restPath })` decorator is applied to set the base path. The controller is created with `isStrict: true`
 3. **Service injection:** The auth service is injected via `inject({ key: serviceKey })(AuthController, undefined, 0)` after class definition -- this programmatically applies `@inject` to constructor parameter 0
    - Service key is provided via `controllerOpts.serviceKey` (required)

package/wiki/{references → extensions}/components/authentication/errors.md

@@ -209,7 +209,7 @@ The middleware that executes strategies in the configured mode.
 | Error Message | Status | Method | When |
 |---------------|--------|--------|------|
 | <code v-pre>Authentication failed. Tried strategies: {{strategies}}</code> | 401 | `executeAnyMode` | All strategies failed in `'any'` mode — each strategy threw during `authenticate()` |
-| `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies succeeded in `'all'` mode but the final `authUser.userId` is falsy |
+| `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies succeeded in `'all'` mode but the first strategy's `authUser.userId` is falsy |
 | <code v-pre>Invalid authentication mode &#124; mode: {{mode}}</code> | 500 | `createAuthenticateMiddleware` | `mode` is not `'any'` or `'all'` |
 
 ---

package/wiki/{references → extensions}/components/authentication/index.md

@@ -178,17 +178,14 @@ import {
   extraUserColumns,
   extraRoleColumns,
   extraPermissionColumns,
-  extraPermissionMappingColumns,
-  extraUserRoleColumns,
+  extraPolicyDefinitionColumns,
 } from '@venizia/ignis';
 
 import type {
   TPermissionOptions,
   TPermissionCommonColumns,
-  TPermissionMappingOptions,
-  TPermissionMappingCommonColumns,
-  TUserRoleOptions,
-  TUserRoleCommonColumns,
+  TPolicyDefinitionOptions,
+  TPolicyDefinitionCommonColumns,
 } from '@venizia/ignis';
 ```
 
@@ -866,13 +863,13 @@ type TAuthMode = TConstValue<typeof AuthenticationModes>;
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) -- Component system basics
-  - [Controllers](/guides/core-concepts/controllers) -- Protecting routes with auth
+  - [REST Controllers](/guides/core-concepts/rest-controllers) | [gRPC Controllers](/guides/core-concepts/grpc-controllers) -- Protecting routes with auth
 
 - **Components:**
   - [All Components](../index) -- Built-in components list
 
 - **Helpers:**
-  - [Crypto Helper](/references/helpers/crypto/) -- Password hashing utilities
+  - [Crypto Helper](/extensions/helpers/crypto/) -- Password hashing utilities
 
 - **References:**
   - [Middlewares](/references/base/middlewares) -- Custom authentication middleware