@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/references/base/connectors.md

@@ -0,0 +1,178 @@
+---
+title: Connectors Reference
+description: How IGNIS separates engine-neutral base classes from per-engine connectors, dual-door exports, and adding a new engine
+difficulty: advanced
+---
+
+# Deep Dive: Connectors
+
+IGNIS's persistence layer is split into two layers: an **engine-neutral root** and a set of **connectors**, one per storage engine. This page documents that architecture, the dual-door export strategy, naming symmetry between engines, and how to add a new connector.
+
+**Files:** `packages/core/src/base/**` (neutral) and `packages/core/src/connectors/{postgres,typesense,meilisearch,search}/**` (per-engine)
+
+## Why the split
+
+Before the restructure, `AbstractDataSource`/`AbstractRepository`/`AbstractEntity` were PostgreSQL-and-Drizzle-aware from the start - `pool`, `connector` (Drizzle instance), and SQL-shaped `TWhere`/`TFilter` lived directly in `src/base`. Adding typesense (a document search engine, not a relational database) exposed the coupling: it has no connection pool, doesn't speak SQL, and doesn't support transactions or row-level locking.
+
+The fix moves everything engine-specific out of `src/base` and into `src/connectors/<engine>/`, leaving `src/base` with only what every engine can implement:
+
+| Concept | Neutral (`src/base`) | PostgreSQL (`connectors/postgres`) | Typesense (`connectors/typesense`) |
+|---|---|---|---|
+| DataSource | `AbstractDataSource` | `AbstractPostgresDataSource` → `BasePostgresDataSource` | `AbstractSearchDataSource` → `BaseSearchDataSource` → `TypesenseDataSource` |
+| Entity | `AbstractEntity` | `BasePostgresEntity` (alias `BaseEntity`) | `BaseSearchEntity` |
+| Repository | `AbstractRepository` | `PostgresBaseRepository` → `ReadableRepository`/`PersistableRepository`/`DefaultCRUDRepository`/`SoftDeletableRepository` | `TypesenseBaseRepository` → `ReadableSearchRepository`/`PersistableSearchRepository`/`DefaultSearchRepository` |
+| Transactions | throws `NotSupported` by default | real transactions, 3 isolation levels | throws `NotSupported` |
+| Filtering | neutral `TWhere`/`TFilter` | SQL WHERE via Drizzle | typesense query DSL via `TypesenseQueryDialect` |
+
+## The neutral contract
+
+### `AbstractDataSource`
+
+`packages/core/src/base/datasources/abstract.ts` declares:
+
+```typescript
+abstract class AbstractDataSource<
+  Settings extends object = {},
+  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,
+  ConfigurableOptions extends object = {},
+> extends BaseHelper implements IDataSource<Settings, Schema, ConfigurableOptions> {
+  abstract configure(opts?: ConfigurableOptions): ValueOrPromise<void>;
+
+  getCapabilities(): IDataSourceCapabilities {
+    return { transactions: false };
+  }
+
+  async beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction> {
+    return throwNotSupported({
+      scope: this.constructor.name,
+      feature: 'Transactions',
+      logger: this.logger,
+    });
+  }
+}
+```
+
+No `pool`, no `connector`, no SQL types. Every engine either overrides `getCapabilities()`/`beginTransaction()` (PostgreSQL) or accepts the neutral default (typesense).
+
+### `AbstractEntity`
+
+`packages/core/src/base/models/base.ts` declares the minimal entity contract, including `getIdType()`:
+
+```typescript
+abstract class AbstractEntity extends BaseHelper {
+  getIdType(): TIdSchemaType {
+    return 'string';
+  }
+}
+```
+
+`BasePostgresEntity` overrides `getIdType()` based on the Drizzle column's actual data type; other engines can override it per their own ID representation.
+
+### `AbstractRepository`
+
+`packages/core/src/base/repositories/core/abstract.ts`:
+
+```typescript
+abstract class AbstractRepository<
+  TDataObject extends object,
+  TPersistObject extends object = TDataObject,
+  TOptions extends IExtraOptions = IExtraOptions,
+> extends BaseHelper implements IPersistableRepository<TDataObject, TPersistObject, TOptions>
+```
+
+Notice the generic parameters are named for their role (`TDataObject`, `TPersistObject`, `TOptions`), not for Drizzle concepts (`EntitySchema`, `TTableObject`) - those Drizzle-flavored names now belong to `PostgresBaseRepository` and its subclasses, which narrow `AbstractRepository`'s generics into a `TTableSchemaWithId`-based signature. `AbstractRepository` does **not** compose `FieldsVisibilityMixin`/`DefaultFilterMixin` - see [Repository Mixins](./repositories/mixins) for what happened to those.
+
+### Neutral `TFilter`/`TWhere` and `ITransaction`
+
+`packages/core/src/base/repositories/common/types.ts` and `packages/core/src/base/datasources/common/types.ts` define engine-neutral filter and transaction shapes shared by both connectors. `ITransaction` has no `connector` field - each engine that supports transactions (currently only PostgreSQL) narrows it with `IDatabaseTransaction`, whose `connector` is a `TRelationalConnector<Schema>` bound to the transaction's dedicated connection (the older `TNodePostgresTransactionConnector` name is kept as a `@deprecated` alias). Its `commit()`/`rollback()` **throw** on failure (a failed `COMMIT` no longer resolves as success) and destroy the poisoned connection rather than pooling it under the `node-postgres` driver; a failed `BEGIN` likewise destroys the acquired connection instead of leaking it. See [Transactions](/guides/core-concepts/persistent/transactions).
+
+## Dual-door exports
+
+IGNIS ships both a **root barrel** (backward-compatible default) and **per-engine subpaths** (opt-in, tree-shakeable). Both resolve to the exact same compiled classes - there is no duplicated implementation.
+
+```json
+// packages/core/package.json - exports map (persistence-relevant entries)
+{
+  ".": "dist/index.js",                                        // framework + postgres (compatibility default)
+  "./postgres": "dist/connectors/postgres/index.js",           // relational connector - loads ZERO client library
+  "./postgres/node-postgres": "dist/connectors/postgres/drivers/node-postgres.js", // concrete driver (value-imports `pg`)
+  "./postgres/postgres-js": "dist/connectors/postgres/drivers/postgres-js.js",     // concrete driver (value-imports `postgres`)
+  "./postgres/supabase": "dist/connectors/postgres/supabase/index.js",             // Supabase pooler + RLS helpers
+  "./search": "dist/connectors/search/index.js",               // engine-neutral search paradigm (no engine client)
+  "./typesense": "dist/connectors/typesense/index.js",         // subpath-only, optional peer
+  "./meilisearch": "dist/connectors/meilisearch/index.js"      // subpath-only, optional peer
+}
+```
+
+> [!IMPORTANT] Concrete Postgres drivers are sub-path only
+> `pg` and `postgres` are **both optional peer dependencies** (`peerDependenciesMeta.pg.optional` / `.postgres.optional`). The root barrel, `@venizia/ignis/postgres`, and the drivers barrel (`connectors/postgres/drivers/index.ts`) load **zero** `pg`/`postgres` modules - the drivers barrel exports only the neutral `IRelationalDriver` contract. A concrete driver value-imports its own client, so reach it by its own sub-path only: `@venizia/ignis/postgres/node-postgres` or `@venizia/ignis/postgres/postgres-js`. There is no structural client sniffing: `@datasource({ driver })` names the driver **class** directly (`NodePostgresDriver`/`PostgresJsDriver`), and the base datasource's `wireDriverFromMetadata()` instantiates that named class over `this.client` lazily, on first `getConnector()`/`beginTransaction()`. Naming a class rather than a driver-name string is what carries `pg`/`postgres` into the app's bundle - a bundler only packages a real value reference, never text, and a bare side-effect import would not survive `sideEffects: false`. This is what keeps IGNIS from forcing a database client on a project that does not use one. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+
+> [!NOTE] `internal/` modules are not public API
+> The search connectors (`search`/`typesense`/`meilisearch`) no longer re-export their `internal/` barrels (`SearchConnectorInternal`, `TypesenseInternal`, `MeilisearchInternal`) from the connector barrel. There is no sub-path export for them either, and package `exports` blocks deep imports - so no specifier reaches them from outside the package. They are implementation detail; if you need what they do, ask for a supported API.
+
+```typescript
+// packages/core/src/index.ts - root barrel
+export * from './base';
+export * from './common';
+export * from './components';
+export * from './connectors';   // -> connectors/index.ts: export * from './postgres';
+export * from './helpers';
+export * from './utilities';
+```
+
+- **Root (`@venizia/ignis`)** re-exports the framework plus the `postgres` connector - existing code that imports `BaseDataSource`/`DefaultCRUDRepository` from the root keeps working unchanged.
+- **`@venizia/ignis/postgres`** re-exports the same connector in isolation, for code that wants to be explicit about which engine it depends on.
+- **`@venizia/ignis/typesense`** is **subpath-only** - it is deliberately excluded from the root barrel because `typesense` is an optional peer dependency (`"peerDependenciesMeta": { "typesense": { "optional": true } }`). Importing from the root must never force-install the typesense client for apps that don't use search.
+
+```typescript
+// Both of these resolve to the same BasePostgresDataSource class:
+import { BaseDataSource } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+
+// Typesense must be imported from its subpath - not available at the root:
+import { TypesenseDataSource, defineSearchCollection } from '@venizia/ignis/typesense';
+```
+
+## Naming symmetry and compatibility aliases
+
+Each connector's canonical class names carry the engine name (`BasePostgresDataSource`, `BasePostgresEntity`), matching the pattern typesense follows (`TypesenseDataSource`). PostgreSQL additionally re-exports the pre-restructure names as aliases, so existing imports do not break:
+
+```typescript
+// packages/core/src/connectors/postgres/datasources/index.ts
+export { BasePostgresDataSource as BaseDataSource } from './base-datasource';
+
+// packages/core/src/connectors/postgres/models/index.ts
+export { BasePostgresEntity as BaseEntity } from './base';
+```
+
+| Canonical (new, engine-carrying) | Alias (compatibility) | Notes |
+|---|---|---|
+| `BasePostgresDataSource` | `BaseDataSource` | Same class, re-exported |
+| `BasePostgresEntity` | `BaseEntity` | Same class, re-exported |
+
+Write new code against the canonical names - they make it unambiguous which engine a class belongs to once you have more than one connector in play. Existing code using the aliases needs no changes.
+
+## Adding a new engine connector
+
+To add a third connector (e.g. a Redis-backed cache connector), follow the shape the two existing connectors share:
+
+1. **`src/connectors/<engine>/datasources/`** - `Abstract<Engine>DataSource extends AbstractDataSource`, then `Base<Engine>DataSource` (or a single concrete `<Engine>DataSource` if there's no useful abstract/base split) implementing `configure()`/`getConnectionString()`. Override `getCapabilities()` and `beginTransaction()` only if the engine truly supports transactions - otherwise inherit the neutral `NotSupported` default.
+2. **`src/connectors/<engine>/models/`** (if the engine needs entity definitions beyond plain objects) - extend `AbstractEntity`, override `getIdType()` if the engine's ID representation differs from the neutral default.
+3. **`src/connectors/<engine>/repositories/core/`** - `<Engine>BaseRepository extends AbstractRepository`, narrowing the generics to the engine's data/persist/options shapes, followed by a `Readable`/`Persistable`/`DefaultCRUD`-style tier ladder mirroring the postgres and typesense connectors. Any operation the engine cannot support (transactions, locks) should call `throwNotSupported({ scope, feature, logger: this.logger })` for consistency.
+4. **`src/connectors/<engine>/index.ts`** - barrel export for the connector.
+5. **`src/connectors/index.ts`** - add `export * from './<engine>'` **only if** the engine has no optional runtime peer dependency (mirroring `postgres`). If the engine driver is an optional peer (like `typesense`), leave it out of `connectors/index.ts` and register it as a subpath-only export in `package.json`.
+6. **`package.json` `exports`** - add `"./​<engine>": "dist/connectors/<engine>/index.js"`. If the driver is an optional peer, add it to `peerDependencies` + `peerDependenciesMeta.<driver>.optional: true`.
+
+## See Also
+
+- **Related Concepts:**
+  - [DataSources](./datasources) - Full DataSource reference (neutral contract + PostgreSQL connector)
+  - [Models & Enrichers](./models) - Entity reference (neutral `AbstractEntity` + PostgreSQL `BasePostgresEntity`)
+  - [Repositories](./repositories/) - Repository hierarchy reference
+  - [Repository Mixins](./repositories/mixins) - Legacy mixins, now orphaned from the public API
+
+- **Guides:**
+  - [Search & Typesense](/guides/core-concepts/persistent/search-typesense) - The typesense connector in depth
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - Layered architecture and separation of concerns

package/content/references/base/controllers.md

@@ -6,7 +6,7 @@ difficulty: beginner
 
 # Deep Dive: REST Controllers
 
-Technical reference for REST controller classes - the foundation for creating HTTP/JSON API endpoints in Ignis.
+Technical reference for REST controller classes - the foundation for creating HTTP/JSON API endpoints in IGNIS.
 
 > [!NOTE]
 > This page covers **REST controllers** (HTTP/JSON). For gRPC controllers using ConnectRPC, see the [gRPC Controllers Reference](./grpc-controllers.md).
@@ -32,7 +32,7 @@ Technical reference for REST controller classes - the foundation for creating HT
 
 ## Controller Transport System
 
-Ignis supports multiple controller transports. The `@controller` decorator accepts a `transport` field to distinguish between REST and gRPC controllers.
+IGNIS supports multiple controller transports. The `@controller` decorator accepts a `transport` field to distinguish between REST and gRPC controllers.
 
 ### `ControllerTransports`
 
@@ -57,7 +57,7 @@ interface IBaseControllerMetadata {
 }
 
 interface IRestControllerMetadata extends IBaseControllerMetadata {
-  transport?: typeof ControllerTransports.REST; // Optional — defaults to REST
+  transport?: typeof ControllerTransports.REST; // Optional - defaults to REST
 }
 
 interface IGrpcControllerMetadata<ServiceType = unknown> extends IBaseControllerMetadata {
@@ -68,7 +68,7 @@ interface IGrpcControllerMetadata<ServiceType = unknown> extends IBaseController
 type TControllerMetadata = IRestControllerMetadata | IGrpcControllerMetadata;
 ```
 
-REST controllers do not need to specify `transport` explicitly — it defaults to REST when omitted.
+REST controllers do not need to specify `transport` explicitly - it defaults to REST when omitted.
 
 ### Application Transport Configuration
 
@@ -130,7 +130,7 @@ export class RestComponent extends BaseComponent {
 
 ## `AbstractRestController`
 
-Base class integrating Hono routing with Ignis DI, authentication/authorization middleware, and OpenAPI generation.
+Base class integrating Hono routing with IGNIS DI, authentication/authorization middleware, and OpenAPI generation.
 
 **Generic Parameters:**
 
@@ -153,7 +153,7 @@ constructor(opts: IControllerOptions)
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `scope` | `string` | Required | Logger scope name |
-| `path` | `string` | — | Route base path. Falls back to `@controller` decorator path if not provided |
+| `path` | `string` | - | Route base path. Falls back to `@controller` decorator path if not provided |
 | `isStrict` | `boolean` | `true` | When `true`, `/users` and `/users/` are different routes |
 
 Path resolution priority: `@controller` decorator metadata > constructor `path` option. Throws if neither provides a path.
@@ -171,7 +171,7 @@ Path resolution priority: `@controller` decorator metadata > constructor `path`
 
 #### `configure(opts?): Promise<OpenAPIHono>`
 
-Configures the controller. Idempotent — returns the router immediately if already configured.
+Configures the controller. Idempotent - returns the router immediately if already configured.
 
 1. Calls `binding()` (your manual route definitions)
 2. Calls `registerRoutesFromRegistry()` (decorator-based routes)
@@ -281,7 +281,11 @@ interface IControllerOptions {
 Lightweight typed context that provides type-safe `req.valid()` calls:
 
 ```typescript
-type TRouteContext<RouteEnv extends Env = Env> = TContext<RouteEnv, keyof IValidRequestProps>;
+type TRouteContext<RouteEnv extends Env = Env, ResponseBody = unknown> = TContext<
+  RouteEnv,
+  keyof IValidRequestProps,
+  ResponseBody
+>;
 ```
 
 Where `IValidRequestProps` supports: `json`, `query`, `param`, `header`, `cookie`, `form`.
@@ -290,7 +294,7 @@ Where `IValidRequestProps` supports: `json`, `query`, `param`, `header`, `cookie
 
 ```typescript
 type TRouteHandler<ResponseType = unknown, RouteEnv extends Env = Env> = (
-  context: TRouteContext<RouteEnv>,
+  context: TRouteContext<RouteEnv, ResponseType>,
 ) => ValueOrPromise<Response | TypedResponse<ResponseType>>;
 ```
 
@@ -361,6 +365,8 @@ Per-route customization for CRUD controller endpoints:
 
 ```typescript
 type TCustomizableRouteConfig = TRouteAuthConfig & {
+  /** Whether this route is registered. Defaults to true. */
+  enabled?: boolean;
   request?: {
     params?: TAnyObjectSchema;
     query?: TAnyObjectSchema;
@@ -416,7 +422,8 @@ export class UserController extends BaseRestController { ... }
 Generic route decorator. Registers route config in the metadata registry.
 
 ```typescript
-import { api, BaseRestController, controller, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { api, BaseRestController, controller, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const MyRouteConfig = {
@@ -448,7 +455,8 @@ Each decorator calls `@api` internally with the appropriate `HTTP.Methods.*` val
 **Example using `@get` and `@post`:**
 
 ```typescript
-import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { get, post, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const UserRoutes = {
@@ -508,12 +516,12 @@ const UserRoutes = {
 
 - The `binding()` method is not required if you use only decorator-based routing
 - Routes are discovered and registered during `configure()` via `registerRoutesFromRegistry()`
-- TypeScript automatically infers and validates return types against the OpenAPI response schema — no need for explicit `TRouteResponse` annotations
+- TypeScript automatically infers and validates return types against the OpenAPI response schema - no need for explicit `TRouteResponse` annotations
 - Use `as const` on route config objects for strict type inference
 
 ## Manual Route Definition
 
-For advanced use cases — dynamic routes, feature flags, programmatic control — define routes inside `binding()`.
+For advanced use cases - dynamic routes, feature flags, programmatic control - define routes inside `binding()`.
 
 ### `defineRoute` Example
 
@@ -524,7 +532,7 @@ this.defineRoute({
     path: '/status',
     responses: jsonResponse({ schema: z.object({ ok: z.boolean() }) }),
     authenticate: { strategies: ['jwt'] },
-    authorize: { resource: 'status', scopes: ['read'] },
+    authorize: { action: 'read', resource: 'status' },
   },
   handler: async (context) => {
     return context.json({ ok: true }, 200);
@@ -626,21 +634,21 @@ class RestPaths {
 
 | Constant | Headers Included |
 | :--- | :--- |
-| `trackableHeaders` | `x-request-id`, `x-request-channel`, `x-request-device-info` (all optional) |
-| `countableHeaders` | `x-request-count` — controls `{count, data}` vs data-only response format |
+| `trackableHeaders` | `x-request-id`, `x-request-channel`, `x-device-info` (all optional) |
+| `countableHeaders` | `x-request-count` - controls `{count, data}` vs data-only response format |
 | `defaultRequestHeaders` | `trackableHeaders` + `countableHeaders` combined |
 | `commonResponseHeaders` | `x-request-id` (echo), `x-response-count`, `x-response-format` |
 | `findResponseHeaders` | `commonResponseHeaders` + `content-range` for pagination |
 
 ## `ControllerFactory`
 
-The `ControllerFactory` provides a static method `defineCrudController` to quickly generate a pre-configured CRUD controller for any given `BaseEntity` and its corresponding repository.
+The `ControllerFactory` provides a static method `defineCrudController` to quickly generate a pre-configured CRUD controller for any given `AbstractEntity` subclass (e.g. `BaseEntity` for Postgres) and its corresponding repository.
 
 **File:** `packages/core/src/base/controllers/factory/controller.ts`
 
-### `static defineCrudController<EntitySchema>(opts: ICrudControllerOptions<EntitySchema>)`
+### `static defineCrudController<TDataObject, TPersistObject = TDataObject, Routes extends ICustomizableRoutes = ICustomizableRoutes>(opts: ICrudControllerOptions<Routes>)`
 
-Returns a `BaseRestController` subclass with standard CRUD endpoints pre-configured. The returned class is dynamically named using `controller.name` from the options.
+Returns a `BaseRestController` subclass with standard CRUD endpoints pre-configured. The returned class is dynamically named using `controller.name` from the options. `TDataObject`/`TPersistObject` can't be inferred from `entity` - pass them explicitly for typed fields.
 
 | Route Name | Method | Path | Description |
 | :--- | :--- | :--- | :--- |
@@ -654,15 +662,16 @@ Returns a `BaseRestController` subclass with standard CRUD endpoints pre-configu
 | `deleteById` | `DELETE` | `/{id}` | Delete a record by its ID |
 | `deleteBy` | `DELETE` | `/` | Bulk delete records matching a `where` filter |
 
-### `ICrudControllerOptions<EntitySchema>`
+### `ICrudControllerOptions<Routes>`
 
 | Option | Type | Description |
 | :--- | :--- | :--- |
-| `entity` | `TClass<BaseEntity<EntitySchema>> \| TResolver<TClass<BaseEntity<EntitySchema>>>` | Entity class or resolver function returning it. Used to derive request/response schemas |
+| `entity` | `TClass<AbstractEntity> \| TResolver<TClass<AbstractEntity>>` | Entity class or resolver function returning it. Used to derive request/response schemas |
 | `repository.name` | `string` | Repository binding key name in the IoC container (e.g., `'ConfigurationRepository'`) |
 | `controller.name` | `string` | Unique name for the generated controller (e.g., `'ConfigurationController'`) |
 | `controller.basePath` | `string` | Base path for all routes (e.g., `'/configurations'`). Required |
 | `controller.readonly` | `boolean` | If `true`, only read operations (count, find, findOne, findById) are generated. Defaults to `false` |
+| `controller.enabledRoutes` | `Array<keyof ICustomizableRoutes>` | Whitelist of routes to register; overrides per-route `enabled` flags in `routes` when set |
 | `controller.isStrict` | `{ path?: boolean; requestSchema?: boolean }` | `path` (default `true`): strict path matching. `requestSchema` (default `true`): strict query parameter validation |
 | `authenticate` | `{ strategies?: TAuthStrategy[]; mode?: TAuthMode }` | Authentication config applied to all routes (unless overridden per-route) |
 | `authorize` | `IAuthorizationSpec \| IAuthorizationSpec[]` | Authorization config applied to all routes (unless overridden per-route) |
@@ -679,6 +688,8 @@ type TRouteAuthConfig = {
 };
 
 type TCustomizableRouteConfig = TRouteAuthConfig & {
+  /** Whether this route is registered. Defaults to true. */
+  enabled?: boolean;
   request?: {
     params?: TAnyObjectSchema;
     query?: TAnyObjectSchema;
@@ -708,16 +719,16 @@ type TCustomizableRouteConfig = TRouteAuthConfig & {
 
 When resolving authentication for a route:
 
-1. **Endpoint `authenticate: { skip: true }`** — No auth (ignores controller `authenticate`)
-2. **Endpoint `authenticate: { strategies }`** — Override controller (empty array = no auth)
-3. **Controller `authenticate`** — Default fallback
+1. **Endpoint `authenticate: { skip: true }`** - No auth (ignores controller `authenticate`)
+2. **Endpoint `authenticate: { strategies }`** - Override controller (empty array = no auth)
+3. **Controller `authenticate`** - Default fallback
 
 When resolving authorization for a route:
 
-1. **Endpoint `authenticate: { skip: true }`** — No authorize (auth skipped entirely)
-2. **Endpoint `authorize: { skip: true }`** — No authorize (explicitly skipped)
-3. **Endpoint `authorize: { ... }`** — Override controller authorize
-4. **Controller `authorize`** — Default fallback
+1. **Endpoint `authenticate: { skip: true }`** - No authorize (auth skipped entirely)
+2. **Endpoint `authorize: { skip: true }`** - No authorize (explicitly skipped)
+3. **Endpoint `authorize: { ... }`** - Override controller authorize
+4. **Controller `authorize`** - Default fallback
 
 ### Authentication Examples
 
@@ -763,14 +774,14 @@ const OrderController = ControllerFactory.defineCrudController({
   repository: { name: 'OrderRepository' },
   controller: { name: 'OrderController', basePath: '/orders' },
   authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-  authorize: { resource: 'orders', scopes: ['read'] },
+  authorize: { action: 'read', resource: 'orders' },
   routes: {
     find: {
       authenticate: { skip: true },
       response: { schema: CustomOrderListSchema },
     },
     create: {
-      authorize: { resource: 'orders', scopes: ['write'] },
+      authorize: { action: 'write', resource: 'orders' },
       request: { body: CustomOrderCreateSchema },
       response: { schema: CustomOrderResponseSchema },
     },