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

package/content/guides/get-started/setup.md

@@ -1,59 +1,51 @@
-# Setup
+# Set Up Your Development Environment
 
-Everything you need to start building with IGNIS. This guide covers installation for macOS, Linux, and Windows (via WSL2).
+Get your machine ready to build with IGNIS: a runtime, a database, and an editor. This guide
+covers macOS, Linux, and Windows through WSL2.
 
 ## Requirements
 
-| Tool | Version | Required | Notes |
-|------|---------|----------|-------|
-| **Bun** | >= 1.3 | Yes | Primary runtime, fastest performance |
-| **Node.js** | >= 18 | Alternative | Use if Bun isn't available |
-| **PostgreSQL** | >= 14 | Yes | Primary database |
-| **VS Code** | Latest | Recommended | Best IDE experience with extensions |
+| Tool | Version | Required | Why |
+|------|---------|----------|-----|
+| **Bun** | >= 1.3 | Yes | Installs packages and runs every build; IGNIS never uses npm, yarn, or pnpm |
+| **PostgreSQL** | >= 14 | Yes | Primary database; the repository system assumes Drizzle + `pg` |
+| **VS Code** | Latest | Optional | Best editor support, through ESLint and Prettier extensions |
 
-## Install Runtime
+> IGNIS apps can also run on Node.js 18+ in production, through `@hono/node-server`. That is a
+> deployment choice, not a setup choice - Bun still installs packages and runs every command in
+> this guide.
 
-### Bun (Recommended)
+## Preconditions
 
-```bash
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (use WSL2)
-# First install WSL2: wsl --install
-# Then run the curl command above in WSL
+- A terminal with permission to install packages (`sudo` on Linux, admin rights on Windows).
+- On Windows, WSL2 installed (`wsl --install`). Run every command in this guide inside WSL2.
 
-# Verify
-bun --version  # Should be 1.3+
-```
-
-### Node.js (Alternative)
+## Step 1: Install Bun
 
 ```bash
-# macOS (Homebrew)
-brew install node@18
+curl -fsSL https://bun.sh/install | bash
+```
 
-# Ubuntu/Debian
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-sudo apt-get install -y nodejs
+On Windows, run this command inside WSL2.
 
-# Windows
-# Download from https://nodejs.org/
+Reload your shell, then confirm the version:
 
-# Verify
-node --version  # Should be 18+
+```bash
+bun --version   # >= 1.3
 ```
 
-## Install PostgreSQL
+## Step 2: Install PostgreSQL
+
+Install and start the server for your OS.
 
-### macOS
+macOS:
 
 ```bash
 brew install postgresql@14
 brew services start postgresql@14
 ```
 
-### Ubuntu/Debian
+Ubuntu/Debian:
 
 ```bash
 sudo apt-get update
@@ -61,11 +53,11 @@ sudo apt-get install postgresql-14
 sudo service postgresql start
 ```
 
-### Windows
+Windows: download the installer from
+[postgresql.org/download/windows](https://www.postgresql.org/download/windows/), or install
+inside WSL2 with the Ubuntu/Debian commands above.
 
-Download from [postgresql.org/download/windows](https://www.postgresql.org/download/windows/) or use WSL2.
-
-### Create Database
+Then create a database for local development:
 
 ```bash
 # macOS
@@ -73,29 +65,20 @@ psql postgres -c "CREATE DATABASE my_app_db;"
 
 # Linux (Ubuntu/Debian)
 sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
-
-# Verify
-psql my_app_db -c "SELECT 1;"  # Should return 1
 ```
 
-## VS Code Setup (Recommended)
+## Step 3: Configure Your Editor (Optional)
 
-### Extensions
+Install the extensions that match IGNIS' ESLint and Prettier setup:
 
 ```bash
-# Essential
 code --install-extension dbaeumer.vscode-eslint
 code --install-extension esbenp.prettier-vscode
-
-# Recommended
 code --install-extension usernamehw.errorlens
 code --install-extension humao.rest-client
-code --install-extension prisma.prisma  # Works with Drizzle too
 ```
 
-### Settings
-
-Create `.vscode/settings.json`:
+Create `.vscode/settings.json` in your project:
 
 ```json
 {
@@ -107,51 +90,47 @@ Create `.vscode/settings.json`:
 }
 ```
 
-## Verify Setup
+## Verify Your Setup
 
 ```bash
-bun --version      # >= 1.3 (or node --version >= 18)
-psql --version     # >= 14
+bun --version                   # >= 1.3
+psql my_app_db -c "SELECT 1;"   # returns 1
 ```
 
+Both commands must succeed before you continue.
+
 ## Troubleshooting
 
-### Bun not found after install
+### Bun command not found after install
+
+Add Bun to your shell profile, then reload it:
 
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
 export BUN_INSTALL="$HOME/.bun"
 export PATH="$BUN_INSTALL/bin:$PATH"
-
-# Then reload
-source ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc   # or ~/.zshrc
 ```
 
-### PostgreSQL permission denied
+### PostgreSQL: permission denied for database
+
+Run the command as the `postgres` user:
 
 ```bash
-# Linux: Use sudo -u postgres
 sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
-
-# macOS: Check if PostgreSQL is running
-brew services list | grep postgresql
 ```
 
-### PostgreSQL connection refused
+### PostgreSQL: connection refused
+
+Check that the server is running, then start it:
 
 ```bash
-# Check if running
 pg_isready
 
-# Start service
-# macOS
-brew services start postgresql@14
-
-# Linux
-sudo service postgresql start
+brew services start postgresql@14   # macOS
+sudo service postgresql start       # Linux
 ```
 
-## Next Steps
+## See Also
 
-- [5-Minute Quickstart](./5-minute-quickstart.md) - Build your first API
-- [Complete Installation](../tutorials/complete-installation.md) - Full project setup
+- [5-Minute Quickstart](./5-minute-quickstart.md) - build your first API
+- [Complete Installation](../tutorials/complete-installation.md) - full project setup

package/content/guides/migrations/redis-helpers-migration.md

@@ -99,15 +99,16 @@ function useRedis(connection: IRedisHelper) { /* ... */ }
 
 ### instanceof checks and concrete bindings
 
-Use the concrete base class (you cannot `instanceof` an interface):
+Use the `isRedisHelper` brand check (you cannot `instanceof` an interface, and `instanceof` against
+the base class answers `false` for a helper built by a second installed copy of the package):
 
 ```typescript
 // Before
 if (connection instanceof DefaultRedisHelper) { /* ... */ }
 
 // After
-import { AbstractRedisHelper } from '@venizia/ignis-helpers';
-if (connection instanceof AbstractRedisHelper) { /* ... */ }
+import { isRedisHelper } from '@venizia/ignis-helpers';
+if (isRedisHelper(connection)) { /* ... */ }
 ```
 
 ### Options type rename

package/content/guides/migrations/scoped-rbac-migration.md

@@ -47,18 +47,18 @@ Both are described below with exact before/after.
 
 When you bump ignis, these stop compiling/working:
 
-1. **`packages/core/src/security/application-casbin-adapter.ts`**
+1. **`packages/core-server/src/security/application-casbin-adapter.ts`**
    - `extends DrizzleCasbinAdapter` → class removed.
    - `import { DrizzleCasbinAdapter, IDrizzleCasbinAdapterOptions, ICasbinPolicyFilter } from '@venizia/ignis'` → first two removed; `ICasbinPolicyFilter` still exists but its **shape changed**.
    - `filter.principalValue` / `filter.principalType` → now `filter.principal.id` / `filter.principal.type`.
    - `CasbinRuleVariants.GROUP` / `CasbinRuleVariants.POLICY` → removed.
    - `this.entities.role.principalType` / `this.entities.permission.principalType` → `entities` no longer provided by the base.
 
-2. **`packages/core/src/repositories/public/policy-definition.repository.ts`**
+2. **`packages/core-server/src/repositories/public/policy-definition.repository.ts`**
    - Many `eq(pd.variant, CasbinRuleVariants.GROUP)` / `.POLICY` → constant removed. This file is the
      biggest single breakage surface outside the adapter.
 
-3. **`packages/core/src/application/verifier.ts`** (enforcer registration)
+3. **`packages/core-server/src/application/verifier.ts`** (enforcer registration)
    - The Redis-absent fallback uses `CasbinEnforcerCachedDrivers.IN_MEMORY` → removed. You must pick
      Redis or `{ use: false }`.
 
@@ -78,7 +78,7 @@ your `group`/`policy` variant values, and all bespoke logic (global roles, HQ-ow
 Own these strings locally so you are decoupled from ignis's casbin-prefix enum:
 
 ```ts
-// packages/core/src/security/policy-variant.ts
+// packages/core-server/src/security/policy-variant.ts
 export class PolicyDefinitionVariant {
   /** user→role assignment + user→merchant membership rows. */
   static readonly GROUP = 'group';
@@ -292,7 +292,7 @@ the bespoke adapter and gain resource/action/domain hierarchies for free.
 
 ## 7. Reference - current nx-seller wiring (before)
 
-For context, the current registration (`packages/core/src/application/verifier.ts`) uses:
+For context, the current registration (`packages/core-server/src/application/verifier.ts`) uses:
 `ApplicationCasbinAdapter` (subclass of removed `DrizzleCasbinAdapter`), `CASBIN_RBAC_MODEL` (flat
 `g + p`, exact `r.obj == p.obj`), a Redis-or-in-memory `cached`, `domainMatching { roleDefinition: 'g',
 fn: keyMatch }`, and a `normalizePayloadFn` mapping subject/domain via

package/content/guides/migrations/unified-connectors-migration.md

@@ -7,7 +7,7 @@ description: What changed in @venizia/ignis 0.0.11-0 / @venizia/ignis-helpers 0.
 
 **Target audience:** the BANA (nx-seller) team, and any application upgrading from `@venizia/ignis@0.0.10-x` / `@venizia/ignis-helpers@0.0.9-x`.
 
-**Verification status:** every step below was validated against a full copy of BANA's `packages/core` source compiled against the release tarballs - the migration ends at **zero compile errors**. The search branch was additionally validated end to end against a live 3-node Typesense cluster.
+**Verification status:** every step below was validated against a full copy of BANA's `packages/core-server` source compiled against the release tarballs. The migration ends at **zero compile errors**. The search branch was additionally validated end to end against a live 3-node Typesense cluster.
 
 ## What changed (summary)
 
@@ -15,7 +15,8 @@ IGNIS core was restructured around ONE engine-neutral repository family:
 
 - `src/base` now holds a single `AbstractRepository` / `AbstractDataSource` / `AbstractEntity` family. Every engine implements it under `src/connectors/{postgres,typesense}`.
 - Postgres remains re-exported from the root barrel - **your imports keep working unchanged**. Every connector is also addressable explicitly: `@venizia/ignis/postgres`, `@venizia/ignis/typesense` (typesense is subpath-only; its client is an optional peer).
-- Canonical class names are the paradigm-family names (`BaseRelationalDataSource`, `BaseRelationalEntity`, `DefaultRelationalRepository`, ...); the engine name appears only at the concrete datasource (`TypesenseDataSource`) and the query dialect (`PostgresQueryOperators`). The historical names (`BaseDataSource`, `BaseEntity`, `BasePostgresDataSource`, `BasePostgresEntity`, `RDBQueryOperators`, `DefaultCRUDRepository`, ...) all remain as alias re-exports of the SAME classes - `instanceof`, metadata, and bindings are unaffected. No action required; prefer the family names in new code.
+- Canonical class names are the paradigm-family names (`BaseRelationalDataSource`, `BaseRelationalEntity`, `DefaultRelationalRepository`, ...). The engine name appears only at the concrete datasource (`TypesenseDataSource`) and the query dialect (`PostgresQueryOperators`).
+- The historical names (`BaseDataSource`, `BaseEntity`, `BasePostgresDataSource`, `BasePostgresEntity`, `RDBQueryOperators`, `DefaultCRUDRepository`, ...) all keep resolving from the same import paths. Most are alias re-exports of the SAME classes; the five repository names (`PostgresBaseRepository`, `ReadableRepository`, `PersistableRepository`, `DefaultCRUDRepository`, `SoftDeletableRepository`) are Postgres subclasses of the neutral chain, so they are distinct class objects from their neutral parents. `instanceof`, metadata, and bindings are unaffected. No action required.
 - New capabilities model: `dataSource.getCapabilities()` and a standardized NotSupported error (HTTP 501, `normalized.code` `core.not_supported`) for engine gaps (e.g. transactions on search engines).
 - New engine: the **Typesense search branch** (`BaseSearchEntity`, `defineSearchCollection`, typed `TSearchDocument`, `DefaultSearchRepository`). It does not affect existing postgres code.
 
@@ -38,7 +39,7 @@ grep -rl 'ITransaction\|IExtraOptions' packages/*/src --include='*.ts' \
   | xargs sed -i 's/\bITransaction\b/IDatabaseTransaction/g; s/\bIExtraOptions\b/IDatabaseExtraOptions/g'
 ```
 
-Note: `options?.transaction?.connector` inside `DefaultCRUDRepository` (alias of `DefaultRelationalRepository`) subclasses needs NO change - the postgres tiers now default their options generic to `IDatabaseExtraOptions`, so that path stays typed automatically.
+Note: `options?.transaction?.connector` inside `DefaultCRUDRepository` (alias of `DefaultRelationalRepository`) subclasses needs NO change. The postgres tiers now default their options generic to `IDatabaseExtraOptions`, so that path stays typed automatically.
 
 ### 2. `applicationEnvironment.get` - options object
 
@@ -68,7 +69,7 @@ New helpers: `toDelimitedArray(input, separator?)` (split + trim + drop empties)
 
 ### 3. Purge stale TypeScript build info
 
-The package's `exports` map changed; stale incremental caches replay phantom diagnostics for unchanged files (a page of bogus "missing property" errors while new files compile clean):
+The package's `exports` map changed. Stale incremental caches replay phantom diagnostics for unchanged files - a page of bogus "missing property" errors while new files compile clean:
 
 ```bash
 find . -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete
@@ -78,7 +79,7 @@ Run this once after the version bump, before trusting the first `tsc` run.
 
 ### 4. Auth endpoint error contract (only if you assert on it)
 
-The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with `normalized.code` `core.not_supported` and message `[AuthController] <feature> is not supported.` (previously a plain `Method not implemented`). BANA was scanned: no code asserts on the old string - listed for completeness.
+The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with `normalized.code` `core.not_supported` and message `[AuthController] <feature> is not supported.`. Previously this was a plain `Method not implemented`. BANA was scanned: no code asserts on the old string - listed for completeness.
 
 ## Strongly recommended (not compile-blocking)
 
@@ -109,5 +110,5 @@ All IGNIS examples now declare these explicitly.
 
 - No import-path changes: root-barrel imports of `BaseDataSource`, `BaseEntity`, `DefaultCRUDRepository`, decorators, etc. all keep working (dual-door export model + compatibility aliases).
 - No repository/generic signature changes: `DefaultCRUDRepository<Schema, DataObject, PersistObject, ...>` call sites are unchanged (a 4th options generic was APPENDED with a default).
-- No runtime behavior changes on the postgres path: the whole pre-existing RDB behavior suite runs unchanged inside the release gates, and every behavior delta was verified to have no trigger inside BANA (`@model` tableName divergence: 0 occurrences; message-string assertions: 0).
+- No runtime behavior changes on the postgres path: the whole pre-existing RDB behavior suite runs unchanged inside the release gates. Every behavior delta was verified to have no trigger inside BANA (`@model` tableName divergence: 0 occurrences; message-string assertions: 0).
 - Nothing search-related: BANA imports zero search symbols today.

package/content/guides/tutorials/realtime-chat.md

@@ -973,7 +973,7 @@ export class ChatService extends BaseService {
 ```
 
 > [!IMPORTANT]
-> **Lazy getter pattern**: `SocketIOServerHelper` is bound via a post-start hook, so it's not available during DI construction. The `private get socketIOHelper()` getter resolves it lazily on first access. See [Socket.IO Component](/extensions/components/socket-io/#step-3-use-in-servicescontrollers) for details.
+> **Lazy getter pattern**: `SocketIOServerHelper` is bound via a post-start hook, so it's not available during DI construction. The `private get socketIOHelper()` getter resolves it lazily on first access. See [Send a message from a service](/extensions/components/socket-io/#send-a-message-from-a-service) for details.
 
 ## 6. Application Setup
 

package/content/references/base/application.md

@@ -1,35 +1,40 @@
 ---
 title: Application Reference
-description: Technical reference for AbstractApplication and BaseApplication classes
+description: Technical reference for the four application layers - AbstractApplication, RestApplication, ServerApplication and BaseApplication
 difficulty: beginner
 ---
 
 # Deep Dive: Application
 
-Technical reference for `AbstractApplication` and `BaseApplication` - the foundation classes for every IGNIS application.
+Extend `BaseApplication`. The three classes above it exist so a host that cannot open a socket - a browser Worker, a test harness - can still serve the same controllers.
 
 **Files:**
-- `packages/core/src/base/applications/abstract.ts`
-- `packages/core/src/base/applications/base.ts`
-- `packages/core/src/base/applications/types.ts`
+- `packages/kernel/src/base/applications/abstract.ts`
+- `packages/kernel/src/base/applications/rest.ts`
+- `packages/core-server/src/base/applications/server.ts`
+- `packages/core-server/src/base/applications/base.ts`
+- `packages/kernel/src/base/applications/types.ts`
 
 ## Quick Reference
 
-| Class | Purpose | Key Methods |
-|-------|---------|-------------|
-| **AbstractApplication** | Base class with lifecycle management, server start/stop | `start()`, `stop()`, `init()`, `validateEnvs()` |
-| **BaseApplication** | Concrete implementation with resource registration and boot support | `component()`, `controller()`, `service()`, `repository()`, `dataSource()`, `boot()` |
+Each layer adds one capability. The first two ship from `@venizia/ignis-kernel` and touch no node builtin; the last two ship from `@venizia/ignis`.
+
+| Class | Adds | Key Methods |
+|-------|------|-------------|
+| **AbstractApplication** | config, lifecycle hooks, the DI container | `init()`, `registerPostStartHook()`, `registerPostStopHook()` |
+| **RestApplication** | the two `OpenAPIHono` routers | `getServer()`, `getRootRouter()`, `inspectRoutes()` |
+| **ServerApplication** | the socket | `start()`, `stop()`, `getServerHost()`, `getServerPort()`, `getServerAddress()` |
+| **BaseApplication** | resource registration, secrets, boot | `component()`, `controller()`, `service()`, `repository()`, `dataSource()`, `boot()`, `validateEnvs()` |
+
+> [!NOTE]
+> Every symbol still resolves from `@venizia/ignis` - `packages/core-server` re-exports the kernel wholesale. The split changed no import path.
 
 ## `AbstractApplication`
 
-Base class responsible for core lifecycle and server management. Extends `Container` (IoC container) and implements `IApplication`.
+Config, lifecycle and the container. No router, no server. Extends `Container`.
 
 ```typescript
-abstract class AbstractApplication<
-  AppEnv extends Env = Env,
-  AppSchema extends Schema = {},
-  BasePath extends string = '/',
-> extends Container implements IApplication<AppEnv, AppSchema, BasePath>
+abstract class AbstractApplication extends Container
 ```
 
 ### Constructor
@@ -39,10 +44,47 @@ constructor(opts: { scope: string; config: IApplicationConfigs })
 ```
 
 The constructor:
-1. Merges the provided config with defaults (host from `HOST` or `APP_ENV_SERVER_HOST` env, port from `PORT` or `APP_ENV_SERVER_PORT` env, defaults to `localhost:3000`)
-2. Enables `asyncContext` by default (`{ enable: true }`)
-3. Sets `strictPath` to `true` by default for the Hono instance
-4. Creates two `OpenAPIHono` instances: the main server and a `rootRouter`
+1. Merges the provided config with defaults, taking host and port from `getEnvServerHost()` / `getEnvServerPort()` and falling back to `localhost:3000`
+2. Resolves `asyncContext.enable` from `getDefaultAsyncContextEnabled()`
+3. Sets `projectRoot` from `getProjectRoot()`
+
+Port `0` survives that merge on purpose - it asks the operating system for an ephemeral port.
+
+The constructor binds nothing. `registerCoreBindings()` runs from `init()`, and `init()` is not called for you - see [Lifecycle](#lifecycle) below.
+
+### The four constructor hooks
+
+`getEnvServerHost()`, `getEnvServerPort()`, `getDefaultAsyncContextEnabled()` and `getProjectRoot()` return `undefined`, `undefined`, `false` and `''` here. `ServerApplication` overrides all four to restore server behaviour - `process.env.HOST`, `process.env.PORT`, `true`, and `process.cwd()`. The kernel layers read no `process`, because a browser Worker has none.
+
+> [!WARNING]
+> All four run inside this constructor, before any subclass field is assigned. An override must return a literal or read module-level state only. Reading `this.something` from one yields `undefined`, silently. `getProjectRoot()` is the one applications most often override - keep it free of instance state.
+
+## `RestApplication`
+
+Adds the routers, and nothing that opens a socket.
+
+```typescript
+abstract class RestApplication<
+  AppEnv extends Env = Env,
+  AppSchema extends Schema = {},
+  BasePath extends string = '/',
+> extends AbstractApplication
+```
+
+It builds the two `OpenAPIHono` instances - the main server and the `rootRouter` - and binds them as `APPLICATION_SERVER` and `APPLICATION_ROOT_ROUTER`.
+
+## `ServerApplication`
+
+Adds `start()`, `stop()` and the runtime detection that picks `Bun.serve` or `@hono/node-server`.
+
+```typescript
+abstract class ServerApplication<
+  AppEnv extends Env = Env,
+  AppSchema extends Schema = {},
+  BasePath extends string = '/',
+> extends RestApplication<AppEnv, AppSchema, BasePath>
+  implements IApplication<AppEnv, AppSchema, BasePath>
+```
 5. Auto-detects the runtime (Bun or Node.js)
 
 ### Key Features
@@ -120,11 +162,11 @@ protected server:
 
 ## `BaseApplication`
 
-Extends `AbstractApplication` with concrete lifecycle implementations, resource registration, and boot support. Implements `IRestApplication` and `IBootableApplication`.
+Extends `ServerApplication` with concrete lifecycle implementations, resource registration, secrets hydration and boot support. Implements `IRestApplication` and `IBootableApplication`. This is the class your application extends.
 
 ```typescript
 abstract class BaseApplication
-  extends AbstractApplication
+  extends ServerApplication
   implements IRestApplication, IBootableApplication
 ```
 

package/content/references/base/components.md

@@ -8,7 +8,7 @@ difficulty: advanced
 
 Technical reference for `BaseComponent`-the foundation for creating reusable, pluggable features in IGNIS. Components are powerful containers that can group together multiple providers, services, controllers, repositories, and even entire mini-applications into a single, redistributable module.
 
-**File:** `packages/core/src/base/components/base.ts`
+**File:** `packages/core-server/src/base/components/base.ts`
 
 ## Quick Reference
 
@@ -379,7 +379,7 @@ If gRPC controllers are discovered but the `'grpc'` transport is not in the `tra
 
 ### `RestComponent`
 
-**File:** `packages/core/src/components/controller/rest/rest.component.ts`
+**File:** `packages/core-server/src/components/controller/rest/rest.component.ts`
 
 Discovers all controller bindings tagged with `BindingNamespaces.CONTROLLER`, skips any whose metadata has `transport === ControllerTransports.GRPC`, and configures the rest as REST controllers.
 
@@ -422,7 +422,7 @@ export class RestBindingKeys {
 
 ### `GrpcComponent`
 
-**File:** `packages/core/src/components/controller/grpc/grpc.component.ts`
+**File:** `packages/core-server/src/components/controller/grpc/grpc.component.ts`
 
 Discovers all controller bindings tagged with `BindingNamespaces.CONTROLLER`, skips any whose metadata does **not** have `transport === ControllerTransports.GRPC`, and configures gRPC controllers.
 

package/content/references/base/connectors.md

@@ -6,13 +6,13 @@ difficulty: intermediate
 
 # Connectors
 
-A connector is how IGNIS adds a storage engine - PostgreSQL, Typesense, Meilisearch - behind one engine-neutral contract, so `DataSource`, `Entity`, and `Repository` mean the same thing no matter which engine backs them.
+A connector is how IGNIS adds a storage engine - PostgreSQL, Typesense, Meilisearch - behind one engine-neutral contract. `DataSource`, `Entity`, and `Repository` mean the same thing no matter which engine backs them.
 
-"A connector" (this page) means an engine-integration module; "the connector" means the Drizzle instance exposed as `this.connector` on a datasource or repository - the two senses are unrelated despite the shared word.
+"A connector" (this page) means an engine-integration module. "The connector" means the Drizzle instance exposed as `this.connector` on a datasource or repository. The two senses are unrelated despite the shared word.
 
 ## In one example
 
-The neutral `AbstractDataSource` has no SQL, no pool, no Drizzle - the postgres connector's `BasePostgresDataSource` adds all of that, and `@datasource({ driver })` names the concrete client class:
+The neutral `AbstractDataSource` has no SQL, no pool, no Drizzle. The postgres connector's `BasePostgresDataSource` adds all of that, and `@datasource({ driver })` names the concrete client class:
 
 ```typescript
 import { Pool } from 'pg';
@@ -45,7 +45,7 @@ A Typesense datasource follows the same shape but extends the search connector's
 
 ## How it works
 
-- **Three engine-neutral roots.** `packages/core/src/base` declares three roots every connector implements:
+- **Three engine-neutral roots.** `packages/core-server/src/base` declares three roots every connector implements:
 
 | Root | Purpose | Neutral default |
 |---|---|---|
@@ -53,16 +53,16 @@ A Typesense datasource follows the same shape but extends the search connector's
 | `AbstractEntity` | Model/schema contract | `name`, `getSchema()`, `getIdType()` |
 | `AbstractRepository` | Data access contract | Generics named for role (data/persist/options), not any one engine's vocabulary |
 
-- **Connectors narrow the roots into a real engine.** `packages/core/src/connectors/<engine>` adds engine-specific members:
+- **Connectors narrow the roots into a real engine.** `packages/core-server/src/connectors/<engine>` adds engine-specific members:
 
 | Connector | Adds | `getCapabilities()` |
 |---|---|---|
 | **postgres** (`connectors/postgres`) | `pool`, Drizzle `connector`, SQL-shaped `TWhere`/`TFilter`, real transactions with isolation levels | `{ transactions: true }` |
 | **search** (`connectors/search`) | Engine-neutral search base - no SQL, no transactions. Both typesense and meilisearch extend it (not `AbstractDataSource` directly), sharing one query-dialect and capability shape | inherited neutral default |
 
-- **`@datasource({ driver })` picks the concrete client, within an engine.** Postgres takes a driver **class** (`NodePostgresDriver` or `PostgresJsDriver`), never a driver-name string - a bundler packages values, not text, so a string would leave the peer dependency uninstalled.
+- **`@datasource({ driver })` picks the concrete client, within an engine.** Postgres takes a driver **class** (`NodePostgresDriver` or `PostgresJsDriver`), never a driver-name string. A bundler packages values, not text, so a string would leave the peer dependency uninstalled.
 - **All engine clients stay optional peer dependencies.** Importing `@venizia/ignis/postgres` alone loads zero client libraries.
-- **Search connectors are subpath-only.** `@venizia/ignis/typesense` and `@venizia/ignis/meilisearch` are excluded from the root `@venizia/ignis` barrel, so an app that never touches search never pulls a search client into its bundle.
+- **Search connectors are subpath-only.** `@venizia/ignis/typesense` and `@venizia/ignis/meilisearch` are excluded from the root `@venizia/ignis` barrel. An app that never touches search never pulls a search client into its bundle.
 
 **Canonical names and aliases**
 
@@ -98,9 +98,9 @@ import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
 
 ### Add a new engine connector
 
-- **Mirror the shape.** Under `src/connectors/<engine>/`: a `datasources/` extending `AbstractDataSource`, a `models/` extending `AbstractEntity` (if the engine needs entity definitions), and a `repositories/core/` extending `AbstractRepository` with a `Readable`/`Persistable`/`DefaultCRUD`-style tier ladder.
+- **Mirror the shape.** Under `src/connectors/<engine>/`, add a `datasources/` extending `AbstractDataSource` and a `repositories/core/` extending `AbstractRepository` with a `Readable`/`Persistable`/`DefaultCRUD`-style tier ladder. Add a `models/` extending `AbstractEntity` too, if the engine needs entity definitions.
 - **Override transactions only if supported.** Override `getCapabilities()` and `beginTransaction()` only if the engine truly supports transactions - otherwise inherit the neutral `NotSupported` default.
-- **Export as a subpath.** Add the connector to `package.json` `exports` as `./<engine>`; if its driver is an optional peer dependency, keep it out of `connectors/index.ts` and register it as a subpath-only export instead, mirroring typesense and meilisearch.
+- **Export as a subpath.** Add the connector to `package.json` `exports` as `./<engine>`. If its driver is an optional peer dependency, keep it out of `connectors/index.ts` and register it as a subpath-only export instead, mirroring typesense and meilisearch.
 
 ## See also
 
@@ -114,8 +114,8 @@ import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
 
 **Files:**
 
-- [`packages/core/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
-- [`packages/core/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/base.ts) - neutral `AbstractEntity`
-- [`packages/core/src/base/repositories/core/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/core/abstract.ts) - neutral `AbstractRepository`
-- [`packages/core/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/base.ts) - `BaseRelationalDataSource` (alias `BasePostgresDataSource`)
-- [`packages/core/src/connectors/search/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/search/datasources/base.ts) - `BaseSearchDataSource`, shared by typesense and meilisearch
+- [`packages/core-server/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
+- [`packages/core-server/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/base.ts) - neutral `AbstractEntity`
+- [`packages/core-server/src/base/repositories/core/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/repositories/core/abstract.ts) - neutral `AbstractRepository`
+- [`packages/core-server/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/base.ts) - `BaseRelationalDataSource` (alias `BasePostgresDataSource`)
+- [`packages/core-server/src/connectors/search/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/search/datasources/base.ts) - `BaseSearchDataSource`, shared by typesense and meilisearch

package/content/references/base/controllers.md

@@ -12,14 +12,14 @@ Technical reference for REST controller classes - the foundation for creating HT
 > This page covers **REST controllers** (HTTP/JSON). For gRPC controllers using ConnectRPC, see the [gRPC Controllers Reference](./grpc-controllers.md).
 
 **Files:**
-- `packages/core/src/base/controllers/rest/abstract.ts` - Abstract base class
-- `packages/core/src/base/controllers/rest/base.ts` - Concrete base class
-- `packages/core/src/base/controllers/common/types.ts` - Shared types and interfaces
-- `packages/core/src/base/controllers/common/constants.ts` - Transport constants and headers
-- `packages/core/src/base/metadata/routes/rest.ts` - Route decorators (`@api`, `@get`, `@post`, etc.)
-- `packages/core/src/base/metadata/routes/controller.ts` - `@controller` decorator
-- `packages/core/src/base/controllers/factory/controller.ts` - CRUD controller factory
-- `packages/core/src/components/controller/rest/rest.component.ts` - RestComponent
+- `packages/core-server/src/base/controllers/rest/abstract.ts` - Abstract base class
+- `packages/core-server/src/base/controllers/rest/base.ts` - Concrete base class
+- `packages/core-server/src/base/controllers/common/types.ts` - Shared types and interfaces
+- `packages/core-server/src/base/controllers/common/constants.ts` - Transport constants and headers
+- `packages/core-server/src/base/metadata/routes/rest.ts` - Route decorators (`@api`, `@get`, `@post`, etc.)
+- `packages/core-server/src/base/metadata/routes/controller.ts` - `@controller` decorator
+- `packages/core-server/src/base/controllers/factory/controller.ts` - CRUD controller factory
+- `packages/core-server/src/components/controller/rest/rest.component.ts` - RestComponent
 
 ## Quick Reference
 
@@ -89,7 +89,7 @@ During `registerControllers()`, the application creates a `RestComponent` for RE
 
 ## `RestComponent`
 
-**File:** `packages/core/src/components/controller/rest/rest.component.ts`
+**File:** `packages/core-server/src/components/controller/rest/rest.component.ts`
 
 The `RestComponent` is responsible for discovering, configuring, and mounting all REST controllers onto the application's root Hono router. It is automatically instantiated by `BaseApplication.registerControllers()` when the REST transport is enabled.
 
@@ -400,7 +400,7 @@ interface ICustomizableRoutes<
 
 ## Route Decorators
 
-**File:** `packages/core/src/base/metadata/routes/rest.ts`
+**File:** `packages/core-server/src/base/metadata/routes/rest.ts`
 
 ### `@controller` Decorator
 
@@ -618,7 +618,7 @@ request: {
 
 ## Standard Headers and Constants
 
-**File:** `packages/core/src/base/controllers/common/constants.ts`
+**File:** `packages/core-server/src/base/controllers/common/constants.ts`
 
 ### `RestPaths`
 
@@ -644,7 +644,7 @@ class RestPaths {
 
 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`
+**File:** `packages/core-server/src/base/controllers/factory/controller.ts`
 
 ### `static defineCrudController<TDataObject, TPersistObject = TDataObject, Routes extends ICustomizableRoutes = ICustomizableRoutes>(opts: ICrudControllerOptions<Routes>)`