@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki → content}/guides/get-started/5-minute-quickstart.md

@@ -1,6 +1,6 @@
 # 5-Minute Quickstart
 
-Build your first Ignis API endpoint in 5 minutes. No database, no complex setup - just a working "Hello World" API.
+Build your first IGNIS API endpoint in 5 minutes. No database, no complex setup - just a working "Hello World" API.
 
 **Time to Complete:** ~5 minutes
 
@@ -64,7 +64,7 @@ node_modules
 ## Step 3: Write Your API (2 minutes)
 
 :::info What is a Decorator?
-A decorator is a TypeScript feature that adds behavior to classes, methods, or properties. It's the `@something` syntax you see before definitions (like `@controller`, `@get`, `@inject`). Decorators in Ignis handle routing, dependency injection, and API documentation automatically.
+A decorator is a TypeScript feature that adds behavior to classes, methods, or properties. It's the `@something` syntax you see before definitions (like `@controller`, `@get`, `@inject`). Decorators in IGNIS handle routing, dependency injection, and API documentation automatically.
 
 [Learn more →](/guides/reference/glossary#decorators)
 :::
@@ -86,7 +86,7 @@ import {
   get,
   IApplicationInfo,
   jsonContent,
-  SwaggerComponent,
+  ApiReferenceComponent,
 } from "@venizia/ignis";
 import { HTTP } from "@venizia/ignis-helpers";
 import { Context } from "hono";
@@ -115,7 +115,7 @@ class HelloController extends BaseRestController {
     },
   })
   sayHello(c: Context) {
-    return c.json({ message: "Hello from Ignis!" }, HTTP.ResultCodes.RS_2.Ok);
+    return c.json({ message: "Hello from IGNIS!" }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 
@@ -130,7 +130,7 @@ class App extends BaseApplication {
   }
 
   preConfigure() {
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
     this.controller(HelloController);
   }
 
@@ -177,18 +177,18 @@ Update `package.json` to add build scripts:
     "server:prod": "NODE_ENV=production bun run dist/index.js"
   },
   "dependencies": {
-    "hono": "^4.12.1",
+    "hono": "^4.12.25",
     "@hono/zod-openapi": "latest",
     "@scalar/hono-api-reference": "latest",
     "@venizia/ignis": "latest",
     "@venizia/ignis-helpers": "latest"
   },
   "devDependencies": {
-    "typescript": "^5.5.3",
+    "typescript": "^6.0.3",
     "@types/bun": "latest",
     "@venizia/dev-configs": "latest",
-    "eslint": "^9.36.0",
-    "prettier": "^3.6.2",
+    "eslint": "^10.5.0",
+    "prettier": "^3.8.4",
     "tsc-alias": "^1.8.10"
   }
 }
@@ -222,7 +222,7 @@ Visit `http://localhost:3000/api/hello` in your browser!
 **Response:**
 
 ```json
-{ "message": "Hello from Ignis!" }
+{ "message": "Hello from IGNIS!" }
 ```
 
 ## View API Docs
@@ -240,27 +240,27 @@ Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI document
 | `Zod schema` | Validates request/response and auto-generates OpenAPI docs |
 | `BaseRestController` | Provides lifecycle hooks, route binding, and OpenAPI integration for REST controllers |
 | `BaseApplication` | Manages dependency injection, middleware, and server startup |
-| `SwaggerComponent` | Generates interactive API docs at `/doc/explorer` |
+| `ApiReferenceComponent` | Generates interactive API docs at `/doc/explorer` |
 | `app.start()` | Runs the full lifecycle (preConfigure → register resources → middlewares) then starts HTTP server on port 3000 |
 
 ### Why Development Configs?
 
 You might wonder why we set up TypeScript, ESLint, and Prettier configs in a "quickstart". Here's why:
 
-**Ignis is opinionated about code quality.** We believe clean, consistent code from day one prevents technical debt later. The `@venizia/dev-configs` package provides pre-configured settings that:
+**IGNIS is opinionated about code quality.** We believe clean, consistent code from day one prevents technical debt later. The `@venizia/dev-configs` package provides pre-configured settings that:
 
 | Config | Purpose |
 |--------|---------|
-| `tsconfig.json` | Strict TypeScript settings optimized for Ignis decorators and path aliases |
+| `tsconfig.json` | Strict TypeScript settings optimized for IGNIS decorators and path aliases |
 | `eslint.config.mjs` | Catches common errors, enforces best practices, works with TypeScript |
-| `.prettierrc.mjs` | Consistent formatting across your team — no more style debates |
+| `.prettierrc.mjs` | Consistent formatting across your team - no more style debates |
 
-**Benefits of starting with Ignis code style:**
+**Benefits of starting with IGNIS code style:**
 
-- **Consistency** — Same patterns across all Ignis projects
-- **IDE Support** — Better autocomplete, error detection, and refactoring
-- **Team Ready** — New developers can onboard faster with familiar structure
-- **CI/CD Friendly** — Lint and format checks work out of the box
+- **Consistency** - Same patterns across all IGNIS projects
+- **IDE Support** - Better autocomplete, error detection, and refactoring
+- **Team Ready** - New developers can onboard faster with familiar structure
+- **CI/CD Friendly** - Lint and format checks work out of the box
 
 > [!TIP]
 > All configs extend from `@venizia/dev-configs`, so you get updates automatically. Customize by overriding specific rules in your local config files.

package/{wiki → content}/guides/get-started/philosophy.md

@@ -1,6 +1,6 @@
 # Philosophy: The Best of Two Worlds
 
-Ignis combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
+IGNIS combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
 
 <div class="philosophy-hero">
 <div class="hero-content">
@@ -34,7 +34,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="landscape-card balanced">
 <div class="card-header">
-<h3>Ignis, Ts.ED</h3>
+<h3>IGNIS, Ts.ED</h3>
 <span class="card-badge">Balanced</span>
 </div>
 <p class="card-motto">Structure with lighter footprint</p>
@@ -86,7 +86,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="perf-row highlight">
 <div class="perf-info">
-<span class="perf-name">Ignis</span>
+<span class="perf-name">IGNIS</span>
 <span class="perf-meta">~30ms startup · ~30MB</span>
 </div>
 <div class="perf-bar-container">
@@ -162,7 +162,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Aspect</th>
 <th>Minimal (Hono/Express)</th>
 <th>Enterprise (NestJS/LoopBack)</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -221,7 +221,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Feature</th>
 <th>Minimal</th>
 <th>Enterprise</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -274,7 +274,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Aspect</th>
 <th>Hono</th>
 <th>NestJS</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -330,7 +330,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 </table>
 </div>
 
-## The Ignis Synthesis
+## The IGNIS Synthesis
 
 <div class="synthesis">
 
@@ -359,7 +359,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="synthesis-operator">=</div>
 
 <div class="synthesis-box result">
-<h4>Ignis</h4>
+<h4>IGNIS</h4>
 <ul>
 <li>DI + Speed</li>
 <li>Structure + Simplicity</li>
@@ -400,7 +400,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 </div>
 
 <div class="excel-card ignis">
-<h3>Ignis</h3>
+<h3>IGNIS</h3>
 <p class="excel-subtitle">The balanced choice</p>
 <div class="excel-pros">
 <h4>Strengths</h4>
@@ -452,7 +452,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 </div>
 
-## When Should You Use Ignis?
+## When Should You Use IGNIS?
 
 <div class="decision-matrix">
 
@@ -530,7 +530,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="perfect-card">
 <h4>Production APIs</h4>
-<p>10-100+ endpoints with enterprise patterns. Controllers, services, repositories — all built-in and ready.</p>
+<p>10-100+ endpoints with enterprise patterns. Controllers, services, repositories - all built-in and ready.</p>
 </div>
 
 <div class="perfect-card">
@@ -557,42 +557,42 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="choose-card">
 <h3>Use Hono/Fastify/Express When:</h3>
 <ul>
-<li><strong>Simple webhook handler</strong> — No structure overhead needed</li>
-<li><strong>Edge/serverless functions</strong> — Minimal cold start, tiny bundle</li>
-<li><strong>Rapid prototyping</strong> — Get something running in minutes</li>
-<li><strong>1-5 endpoint microservices</strong> — Structure adds complexity</li>
-<li><strong>Maximum control needed</strong> — No conventions to follow</li>
-<li><strong>Learning web development</strong> — Simpler mental model</li>
+<li><strong>Simple webhook handler</strong> - No structure overhead needed</li>
+<li><strong>Edge/serverless functions</strong> - Minimal cold start, tiny bundle</li>
+<li><strong>Rapid prototyping</strong> - Get something running in minutes</li>
+<li><strong>1-5 endpoint microservices</strong> - Structure adds complexity</li>
+<li><strong>Maximum control needed</strong> - No conventions to follow</li>
+<li><strong>Learning web development</strong> - Simpler mental model</li>
 </ul>
 </div>
 
 <div class="choose-card">
 <h3>Use NestJS/LoopBack When:</h3>
 <ul>
-<li><strong>Large team (10+ developers)</strong> — Strong conventions prevent chaos</li>
-<li><strong>Enterprise with strict standards</strong> — Mature, battle-tested, auditable</li>
-<li><strong>Extensive ecosystem needed</strong> — Many official and community modules</li>
-<li><strong>Complex microservices</strong> — Built-in support for messaging, CQRS</li>
-<li><strong>Hiring is a priority</strong> — Large talent pool familiar with it</li>
-<li><strong>Long-term support critical</strong> — Corporate backing, LTS versions</li>
+<li><strong>Large team (10+ developers)</strong> - Strong conventions prevent chaos</li>
+<li><strong>Enterprise with strict standards</strong> - Mature, battle-tested, auditable</li>
+<li><strong>Extensive ecosystem needed</strong> - Many official and community modules</li>
+<li><strong>Complex microservices</strong> - Built-in support for messaging, CQRS</li>
+<li><strong>Hiring is a priority</strong> - Large talent pool familiar with it</li>
+<li><strong>Long-term support critical</strong> - Corporate backing, LTS versions</li>
 </ul>
 </div>
 
 <div class="choose-card highlight">
-<h3>Use Ignis When:</h3>
+<h3>Use IGNIS When:</h3>
 <ul>
-<li><strong>Any size API (10-100+ endpoints)</strong> — Structure without heavy overhead</li>
-<li><strong>Any team size</strong> — Scales from solo dev to enterprise teams</li>
-<li><strong>Performance matters</strong> — Hono's speed with enterprise patterns</li>
-<li><strong>Modern stack preferred</strong> — ESM native, Bun optimized, TypeScript-first</li>
-<li><strong>Coming from NestJS/LoopBack</strong> — Familiar patterns, better performance</li>
-<li><strong>Need built-in features</strong> — DI, validation, OpenAPI, auth ready to use</li>
+<li><strong>Any size API (10-100+ endpoints)</strong> - Structure without heavy overhead</li>
+<li><strong>Any team size</strong> - Scales from solo dev to enterprise teams</li>
+<li><strong>Performance matters</strong> - Hono's speed with enterprise patterns</li>
+<li><strong>Modern stack preferred</strong> - ESM native, Bun optimized, TypeScript-first</li>
+<li><strong>Coming from NestJS/LoopBack</strong> - Familiar patterns, better performance</li>
+<li><strong>Need built-in features</strong> - DI, validation, OpenAPI, auth ready to use</li>
 </ul>
 </div>
 
 </div>
 
-## Why Choose Ignis
+## Why Choose IGNIS
 
 <div class="tradeoffs">
 
@@ -603,7 +603,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <li><span class="highlight-text">Built-in DI</span>, validation, OpenAPI, auth</li>
 <li><span class="highlight-text">Structured codebase</span> from day one</li>
 <li><span class="highlight-text">Easier testing</span> with dependency injection</li>
-<li><span class="highlight-text">Single file build</span> — compile to one executable with Bun</li>
+<li><span class="highlight-text">Single file build</span> - compile to one executable with Bun</li>
 <li><span class="highlight-text">Scales</span> from solo dev to enterprise teams</li>
 </ul>
 </div>
@@ -611,10 +611,10 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="tradeoff cost">
 <h3>What's Growing</h3>
 <ul>
-<li><span class="highlight-text">Community</span> — expanding every day</li>
-<li><span class="highlight-text">Documentation</span> — continuously improving</li>
-<li><span class="highlight-text">Ecosystem</span> — core features ready, plugins coming</li>
-<li><span class="highlight-text">LTS</span> — planning for long-term support</li>
+<li><span class="highlight-text">Community</span> - expanding every day</li>
+<li><span class="highlight-text">Documentation</span> - continuously improving</li>
+<li><span class="highlight-text">Ecosystem</span> - core features ready, plugins coming</li>
+<li><span class="highlight-text">LTS</span> - planning for long-term support</li>
 </ul>
 </div>
 

package/{wiki → content}/guides/get-started/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-Everything you need to start building with Ignis. This guide covers installation for macOS, Linux, and Windows (via WSL2).
+Everything you need to start building with IGNIS. This guide covers installation for macOS, Linux, and Windows (via WSL2).
 
 ## Requirements
 
@@ -153,5 +153,5 @@ sudo service postgresql start
 
 ## Next Steps
 
-- [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/{wiki → content}/guides/index.md

@@ -1,6 +1,6 @@
-# Getting Started with Ignis
+# Getting Started with IGNIS
 
-Welcome to Ignis — a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, gRPC service, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
+Welcome to IGNIS - a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, gRPC service, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
 
 <div class="guide-cards">
 
@@ -31,7 +31,7 @@ Welcome to Ignis — a TypeScript framework that combines enterprise architectur
 
 <a href="./get-started/philosophy" class="guide-card">
 <h3>Philosophy</h3>
-<p>Why Ignis? Design decisions explained</p>
+<p>Why IGNIS? Design decisions explained</p>
 </a>
 
 </div>

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

@@ -0,0 +1,177 @@
+---
+title: Migrating to the new Redis Helper API
+description: Breaking changes and migration steps for the IGNIS Redis helper refactor - folder-per-topology, AbstractRedisHelper, camelCase methods, Sentinel, and the createRedisHelper factory
+---
+
+# Migrating to the new Redis Helper API
+
+> **Audience:** any application upgrading `@venizia/ignis-helpers` (and `@venizia/ignis`) across the Redis helper refactor release. This guide describes exactly what breaks and how to migrate. It applies to every consumer - it is not specific to any one app.
+
+---
+
+## 0. TL;DR
+
+The IGNIS Redis module was restructured into one base class plus three topologies (single / cluster / sentinel) behind a segregated `IRedisHelper` interface. Several public symbols were **renamed with no back-compat aliases (clean break)**, and the lowercase hash/multi methods were removed in favor of camelCase. Your project **will not compile** against the new version until you apply the renames in §1.
+
+Nothing in your data or Redis server changes - this is a code-level rename plus a few additive features. The single and cluster connection behavior is byte-for-byte identical to before; only the new `RedisSentinelHelper` introduces new behavior.
+
+| Effort | What |
+|--------|------|
+| **Low - mechanical renames** | Apply the rename table in §1 and the method renames in §1.2. Compiler-guided: every stale reference becomes a type error. |
+
+---
+
+## 1. What changed (breaking)
+
+### 1.1 Class and type renames (no aliases)
+
+| Old (removed) | New |
+|---------------|-----|
+| `DefaultRedisHelper` | `AbstractRedisHelper` |
+| `RedisHelper` | `RedisSingleHelper` |
+| `IRedisHelperOptions` | `IRedisSingleHelperOptions` |
+| `IRedisHelperProps` | `IRedisSingleHelperProps` |
+
+`RedisClusterHelper` is **unchanged** in name and behavior.
+
+`AbstractRedisHelper` is the base class (never constructed directly). Use it only where you need an `instanceof` check or a concrete-class binding; for plain typing prefer the `IRedisHelper` interface.
+
+### 1.2 Lowercase methods removed - use camelCase
+
+The duplicate lowercase aliases were removed. The camelCase forms are now the only API.
+
+| Old (removed) | New |
+|---------------|-----|
+| `.hset(...)` | `.hSet(...)` |
+| `.hgetall(...)` | `.hGetAll(...)` |
+| `.mset(...)` | `.mSet(...)` |
+| `.mget(...)` | `.mGet(...)` |
+
+Single-word methods (`get`, `set`, `del`, `keys`, `publish`, `subscribe`) are unchanged.
+
+### 1.3 Callback type narrowed
+
+`IRedisHelperCallbacks.onError` now receives `error: unknown` (was `error: any`). This only affects you if you access properties on `error` without narrowing first.
+
+---
+
+## 2. Find every affected site
+
+Run this in your project root. Every match is a site to migrate:
+
+```bash
+grep -rnE 'DefaultRedisHelper|\bRedisHelper\b|IRedisHelper(Options|Props)\b|\.(hset|mset|hgetall|mget)\(' src
+```
+
+`\bRedisHelper\b` matches the bare class only - it will not match `RedisClusterHelper` / `RedisSingleHelper`.
+
+After migrating, re-run it; a clean result plus a green `tsc` means you are done.
+
+---
+
+## 3. Migration steps (before / after)
+
+### Constructing a single-node connection
+
+```typescript
+// Before
+import { RedisHelper } from '@venizia/ignis-helpers';
+const redis = new RedisHelper({ name: 'cache', host, port, password });
+
+// After
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
+const redis = new RedisSingleHelper({ name: 'cache', host, port, password });
+```
+
+### Typing a Redis connection (config, fields, params)
+
+Prefer the interface for plain typing:
+
+```typescript
+// Before
+import { DefaultRedisHelper } from '@venizia/ignis-helpers';
+function useRedis(connection: DefaultRedisHelper) { /* ... */ }
+
+// After
+import type { IRedisHelper } from '@venizia/ignis-helpers';
+function useRedis(connection: IRedisHelper) { /* ... */ }
+```
+
+### instanceof checks and concrete bindings
+
+Use the concrete base class (you cannot `instanceof` an interface):
+
+```typescript
+// Before
+if (connection instanceof DefaultRedisHelper) { /* ... */ }
+
+// After
+import { AbstractRedisHelper } from '@venizia/ignis-helpers';
+if (connection instanceof AbstractRedisHelper) { /* ... */ }
+```
+
+### Options type rename
+
+```typescript
+// Before
+import type { IRedisHelperOptions } from '@venizia/ignis-helpers';
+
+// After
+import type { IRedisSingleHelperOptions } from '@venizia/ignis-helpers';
+```
+
+### Hash and multi-key calls
+
+```typescript
+// Before
+await redis.hset({ key, value });
+const all = await redis.hgetall({ key });
+await redis.mset({ payload });
+const many = await redis.mget({ keys });
+
+// After
+await redis.hSet({ key, value });
+const all = await redis.hGetAll({ key });
+await redis.mSet({ payload });
+const many = await redis.mGet({ keys });
+```
+
+---
+
+## 4. Runtime behavior changes to verify
+
+These compile unchanged but behave slightly differently. All are strictly safer; verify only if your code depended on the old behavior.
+
+| Method | Old behavior | New behavior |
+|--------|--------------|--------------|
+| `subscribe` / `unsubscribe` | threw inside the ioredis callback on a subscription error (an unhandled async throw) | logs the error and returns; never throws |
+| `del` / `mGet` / `mSet` | forwarded empty input to Redis, which throws "wrong number of arguments" | empty input is a no-op: returns `0` / `[]` / void without a Redis call |
+
+If you wrapped `subscribe(...)` in a `try/catch` expecting it to throw, that branch no longer fires. If you relied on `del([])` throwing, it now returns `0`.
+
+---
+
+## 5. What you gain (additive - no action required)
+
+These are new and do not break anything:
+
+- **`RedisSentinelHelper`** - Redis Sentinel topology with automatic failover. See the [Redis Helper reference](/extensions/helpers/redis/) (Sentinel section).
+- **`createRedisHelper({ mode })`** - a factory that builds the right helper from `RedisModes.SINGLE | CLUSTER | SENTINEL`, so you can pick a topology from config.
+- **`RedisModes`** and **`RedisSentinelRoles`** - const-classes for the enumerable mode/role strings, with matching `TRedisMode` / `TRedisSentinelRole` types.
+- **Expanded data API** - key lifecycle and counters (`exists`, `expire`, `expireAt`, `ttl`, `persist`, `incr`, `decr`, `incrBy`, `decrBy`), hash completion (`hGet`, `hDel`, `hExists`, `hKeys`, `hVals`, `hIncrBy`, `hLen`), sets (`sAdd`, `sRem`, `sMembers`, `sIsMember`, `sCard`), and lists (`lPush`, `rPush`, `lPop`, `rPop`, `lRange`, `lLen`).
+- **`set` TTL option** - `set({ key, value, options: { expiresIn } })` where `expiresIn` is milliseconds (uses `PX`).
+- **All three topologies are interchangeable** - anywhere an `IRedisHelper` is accepted (BullMQ, Socket.IO, WebSocket, the Casbin cache), you can now pass a single, cluster, or sentinel helper without changing the consumer.
+
+---
+
+## 6. Migration checklist
+
+- [ ] Run the grep in §2; note every match.
+- [ ] Apply the §1.1 class/type renames.
+- [ ] Apply the §1.2 lowercase to camelCase method renames.
+- [ ] Switch plain-typed connection references to `IRedisHelper`; keep `AbstractRedisHelper` for `instanceof` / concrete bindings.
+- [ ] Narrow `onError` usage if you read fields off `error`.
+- [ ] Review §4 if you relied on subscribe throwing or empty-input throwing.
+- [ ] Re-run the grep (clean) and `tsc` (green); run your test suite.
+
+When the grep is clean and the build is green, the migration is complete - there is no data or server-side change to perform.

package/{wiki → content}/guides/migrations/scoped-rbac-migration.md

@@ -16,8 +16,8 @@ You have two paths:
 
 | Path | Effort | When |
 |------|--------|------|
-| **B — Bridge** (re-base your custom adapter on `BaseFilteredAdapter`, keep your flat model) | Low — code only, **no data migration** | Do this first to unblock the upgrade |
-| **A — Adopt scoped** (delete your custom adapter, use `ScopedCasbinAdapter` + scoped model) | High — needs a **data migration** | The intended long-term target |
+| **B - Bridge** (re-base your custom adapter on `BaseFilteredAdapter`, keep your flat model) | Low - code only, **no data migration** | Do this first to unblock the upgrade |
+| **A - Adopt scoped** (delete your custom adapter, use `ScopedCasbinAdapter` + scoped model) | High - needs a **data migration** | The intended long-term target |
 
 Both are described below with exact before/after.
 
@@ -67,9 +67,9 @@ When you bump ignis, these stop compiling/working:
 
 ---
 
-## 3. Path B — Bridge (recommended first step, no data migration)
+## 3. Path B - Bridge (recommended first step, no data migration)
 
-Goal: compile against new ignis with **identical runtime behavior** — keep your flat `CASBIN_RBAC_MODEL`,
+Goal: compile against new ignis with **identical runtime behavior** - keep your flat `CASBIN_RBAC_MODEL`,
 your `group`/`policy` variant values, and all bespoke logic (global roles, HQ-owner expansion).
 
 ### 3.1 Define your own variant constants
@@ -147,24 +147,24 @@ Key swaps inside the class:
 - `filter.principalValue` → `filter.principal.id`; `filter.principalType` → `filter.principal.type`.
 - `this.entities.role.principalType` / `this.entities.permission.principalType` → from your own
   `entities` (pass the same values you pass today; drop the `tableName`/`policyDefinition` parts the
-  base used to require — you import the Drizzle tables directly already).
+  base used to require - you import the Drizzle tables directly already).
 - `CasbinRuleVariants.GROUP/.POLICY` → `PolicyDefinitionVariant.GROUP/.POLICY` (§3.1).
 
 ### 3.3 Fix the cache fallback in `verifier.ts`
 
 ```ts
-// BEFORE — in-memory fallback (driver removed)
+// BEFORE - in-memory fallback (driver removed)
 const cached: ICasbinEnforcerOptions['cached'] = redis
   ? { use: true, driver: CasbinEnforcerCachedDrivers.REDIS, options: { ... } }
   : { use: true, driver: CasbinEnforcerCachedDrivers.IN_MEMORY, options: { expiresIn: 5*60*1000 } };
 
-// AFTER — Redis or no cache
+// AFTER - Redis or no cache
 const cached: ICasbinEnforcerOptions['cached'] = redis
   ? { use: true, driver: CasbinEnforcerCachedDrivers.REDIS, options: { connection: redis, expiresIn: 5*60*1000, keyFn: ({ user }) => `casbin:${user.principalType}:${user.userId}` } }
   : { use: false };
 ```
 
-> **Decide:** in prod, **always provide Redis** — without it every request rebuilds the policy from the
+> **Decide:** in prod, **always provide Redis** - without it every request rebuilds the policy from the
 > DB (no per-user cache). The pool still protects you from the concurrency race, but you lose the line cache.
 
 ### 3.4 Adapter construction (`verifier.ts`)
@@ -187,7 +187,7 @@ stays. **Result: behavior identical, compiles on new ignis, zero data migration.
 
 ---
 
-## 4. Path A — Adopt the scoped model (target state)
+## 4. Path A - Adopt the scoped model (target state)
 
 This deletes `ApplicationCasbinAdapter` entirely and uses the generic `ScopedCasbinAdapter`. The
 bespoke logic moves from **code** into **data (edges)**. Do this once Path B has unblocked you.
@@ -221,7 +221,7 @@ const adapter = new ScopedCasbinAdapter({
 //                                  pass the request domain via the provider's domain resolver instead)
 ```
 
-### 4.2 Data migration — the `variant` column
+### 4.2 Data migration - the `variant` column
 
 The scoped adapter filters on `AuthorizationPolicyVariants.*.action`, not `group`/`policy`. You must
 re-classify rows:
@@ -234,11 +234,11 @@ re-classify rows:
 | `policy` (role→perm or user→perm) | `grant` | permission grant |
 
 New edge types you may need to **add** (no equivalent today):
-- `domain_inherits` (Merchant ⊂ Organizer / HQ) — **this replaces the bespoke `queryHqOwnerOrgMerchants`
+- `domain_inherits` (Merchant ⊂ Organizer / HQ) - **this replaces the bespoke `queryHqOwnerOrgMerchants`
   JOIN**. Materialize one row per Merchant→Organizer (or →HQ-merchant) relationship; the scoped model's
   `g3` then cascades a grant on the parent domain to all child merchants automatically. Maintain these
   rows when merchants/organizers are created or moved.
-- `resource_inherits` (`g4`) / `action_inherits` (`g5`) — only if you want resource/action hierarchies.
+- `resource_inherits` (`g4`) / `action_inherits` (`g5`) - only if you want resource/action hierarchies.
 
 ### 4.3 Re-express bespoke behavior as data
 
@@ -249,7 +249,7 @@ New edge types you may need to **add** (no equivalent today):
 | HQ-owner expansion (live JOIN) | `domain_inherits` (`g3`) edges (see §4.2) |
 | Domain-agnostic role permissions (`p, Role, *, ...`) | Grant rows with domain `ANY_MEMBER` (default when `domain` is NULL) |
 
-### 4.4 Behavioral caveat — resource matching changes
+### 4.4 Behavioral caveat - resource matching changes
 
 Your flat model uses exact `r.obj == p.obj`. The scoped model uses **`objectMatch`** (dotted-prefix +
 wildcard): a grant on `Order` will now **also** match `Order.findById`, and `p.obj = '*'` matches any
@@ -277,20 +277,20 @@ the bespoke adapter and gain resource/action/domain hierarchies for free.
 
 ## 6. Verification checklist (either path)
 
-- [ ] `bun run build` (or `tsc -p .`) is clean — no references to `DrizzleCasbinAdapter`,
+- [ ] `bun run build` (or `tsc -p .`) is clean - no references to `DrizzleCasbinAdapter`,
       `IDrizzleCasbinAdapterOptions`, `CasbinRuleVariants.GROUP/.POLICY`, `CasbinEnforcerCachedDrivers.IN_MEMORY`,
       `IAuthorizationCacheInvalidator`.
 - [ ] `SELECT DISTINCT variant FROM identity."PolicyDefinition"` matches what your adapter filters on
       (`group`/`policy` for Path B; the new `*.action` set for Path A).
 - [ ] A request for a user with a role-inherited / per-merchant / global permission resolves the same
-      ALLOW/DENY as before the upgrade (pick 3–4 representative users and diff).
+      ALLOW/DENY as before the upgrade (pick 3-4 representative users and diff).
 - [ ] If `cached.use: true`, Redis is reachable; if a permission changes, call
-      `enforcer.invalidateUserCache({ user })` (or rely on TTL) — see the ignis authorization docs.
+      `enforcer.invalidateUserCache({ user })` (or rely on TTL) - see the ignis authorization docs.
 - [ ] Super-admin / always-allow-roles still short-circuit (these run in the provider before the enforcer).
 
 ---
 
-## 7. Reference — current nx-seller wiring (before)
+## 7. Reference - current nx-seller wiring (before)
 
 For context, the current registration (`packages/core/src/application/verifier.ts`) uses:
 `ApplicationCasbinAdapter` (subclass of removed `DrizzleCasbinAdapter`), `CASBIN_RBAC_MODEL` (flat