@quanticjs/create-app 0.1.1

package/templates/claude/hooks/on-compaction.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Notification hook: fires after context compaction.
+# Re-injects key context so Claude doesn't lose track of current work.
+set -uo pipefail
+
+echo "=== POST-COMPACTION CONTEXT ==="
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+if [[ -n "$BRANCH" ]]; then
+  echo "Branch: $BRANCH"
+fi
+
+COMMITS=$(git log --oneline -10 main..HEAD 2>/dev/null)
+if [[ -n "$COMMITS" ]]; then
+  echo ""
+  echo "Commits on this branch:"
+  echo "$COMMITS"
+fi
+
+CHANGES=$(git status --short 2>/dev/null | head -20)
+if [[ -n "$CHANGES" ]]; then
+  echo ""
+  echo "Uncommitted changes:"
+  echo "$CHANGES"
+fi
+
+echo ""
+echo "Re-read CLAUDE.md and .claude/rules/ for conventions."
+echo "=== END ==="

package/templates/claude/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@0.0.75"
+      ]
+    }
+  }
+}

package/templates/claude/rules/api-patterns.md

@@ -0,0 +1,86 @@
+---
+globs: "src/**/*.ts"
+---
+
+# API Documentation Patterns
+
+## OpenAPI 3.1 — Code-First with @nestjs/swagger
+
+| URL | Purpose |
+|-----|---------|
+| `/api/docs` | Swagger UI (interactive) |
+| `/api/docs-json` | OpenAPI 3.1 JSON spec |
+
+## Controller Decorators (MANDATORY)
+
+Every endpoint annotated with `@ApiOperation`, `@ApiResponse`, `@ApiBody`, `@ApiTags`.
+
+```typescript
+@ApiTags('items')
+@Controller('items')
+export class ItemsController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new item' })
+  @ApiResponse({ status: 201, type: ItemResponseDto })
+  @ApiResponse({ status: 400, type: ErrorResponseDto })
+  create(@Body() dto: CreateItemDto) { ... }
+}
+```
+
+## DTO Decorators
+
+DTOs use both `class-validator` (runtime) and `@ApiProperty` (docs):
+
+```typescript
+export class CreateItemDto {
+  @ApiProperty({ description: 'Item name', minLength: 1, maxLength: 200 })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  title: string;
+}
+```
+
+## Response DTOs
+
+All API responses use typed response DTOs — never raw entity objects.
+
+## Result<T> → HTTP Mapping (RFC 9457 Problem Details)
+
+Error responses use `Content-Type: application/problem+json` with RFC 9457 problem-details shape:
+
+```json
+{
+  "type": "https://arex.dev/errors/NOT_FOUND",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Item not found",
+  "instance": "/api/items/123",
+  "correlationId": "abc-123"
+}
+```
+
+| Result | HTTP |
+|--------|------|
+| `Result.success(value)` | 200/201 |
+| `ErrorType.ValidationError` | 400 |
+| `ErrorType.Unauthorized` | 401 |
+| `ErrorType.Forbidden` | 403 |
+| `ErrorType.NotFound` | 404 |
+| `ErrorType.Conflict` | 409 |
+| `ErrorType.UnprocessableEntity` | 422 |
+| `ErrorType.InternalError` | 500 |
+
+## Environment Availability
+
+| Env | Swagger UI | JSON Spec |
+|-----|-----------|-----------|
+| Local / Dev / Staging | Enabled | Enabled |
+| **Production** | **Disabled** | **Disabled** |
+
+## NEVER
+
+- **NEVER** maintain separate Markdown/Wiki API documentation
+- **NEVER** return raw entities from controllers — use response DTOs
+- **NEVER** leave endpoints undocumented
+- **NEVER** enable Swagger UI in production

package/templates/claude/rules/auth-patterns.md

@@ -0,0 +1,109 @@
+---
+globs: "src/bff/**/*.ts, client/src/**/*.{ts,tsx}"
+---
+
+# Authentication & Authorization Patterns
+
+## BFF Authentication (Backend-for-Frontend)
+
+All auth goes through the NestJS BFF module (`src/bff/`). Tokens stored server-side in Redis. Browser gets httpOnly cookies only.
+
+### BFF Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/auth/login` | GET | Redirect to Keycloak with PKCE. Query params: `provider`, `returnTo` |
+| `/auth/callback` | GET | OIDC callback — exchange code for tokens, set httpOnly cookie, redirect to SPA |
+| `/auth/refresh` | POST | Refresh access token using refresh token from Redis |
+| `/auth/logout` | POST | Clear cookies, revoke Keycloak session, invalidate Redis session |
+| `/auth/me` | GET | Return current user info + role + permissions |
+
+### Cookie Configuration
+
+```typescript
+{
+  httpOnly: true,       // invisible to JS — immune to XSS
+  secure: true,         // HTTPS only (except local dev)
+  sameSite: 'lax',      // CSRF protection
+  path: '/',
+  maxAge: 7 * 24 * 3600 // 7 days
+}
+```
+
+### Token Flow
+
+1. Browser sends request with httpOnly cookie (automatic — no JS involved)
+2. BFF middleware reads session ID from cookie, looks up access token in Redis
+3. If access token exists → inject `Authorization: Bearer` header
+4. If access token expired but refresh token exists → middleware calls Keycloak to get a new access token, stores it in Redis, injects it (transparent to frontend)
+5. If both expired → no header injected, `JwtAuthGuard` returns 401 (session dead, user must re-login)
+6. `JwtAuthGuard` validates the token as normal
+
+- Access tokens: Redis, short-lived (configured in Keycloak)
+- Refresh tokens: Redis, 7 days, rotating
+- Session cookie: browser httpOnly, 7 days
+
+### Token Storage (Mobile — React Native)
+
+- **Tier 1 (sensitive):** `expo-secure-store` or `react-native-keychain` — tokens, credentials
+- **Tier 2 (preferences):** `AsyncStorage` — theme, locale, onboarding flags
+- **Tier 3 (cached data):** TanStack Query persistence
+
+## Authorization — Backend is Source of Truth
+
+**Permissions are decided on the backend. Always.** The frontend is a hint layer, not a security boundary.
+
+### Frontend Permission Expression
+
+```tsx
+const { can } = usePermissions();
+if (can('invoice.delete')) { /* ... */ }
+
+<Can permission="invoice.delete">
+  <DeleteButton />
+</Can>
+```
+
+Permissions fetched from `/auth/me` on login, refreshed with session.
+
+### Frontend Auth State
+
+```typescript
+const { data: session } = useQuery({
+  queryKey: ['auth', 'session'],
+  queryFn: () => api.get('/auth/me'),
+  retry: false,
+});
+const isAuthenticated = !!session;
+```
+
+### Login/Logout
+
+```typescript
+// Login — redirect to Keycloak via BFF
+window.location.href = '/auth/login?provider=google&returnTo=/dashboard';
+
+// Logout
+await fetch('/auth/logout', { method: 'POST', credentials: 'include' });
+```
+
+### Socket.IO
+
+```typescript
+const socket = io({ withCredentials: true }); // cookie sent on handshake
+```
+
+## NEVER
+
+- **NEVER** store tokens in `localStorage` or `sessionStorage` (violates RFC 9700)
+- **NEVER** set `Authorization` headers from frontend code
+- **NEVER** read token claims in frontend JS — call `/auth/me`
+- **NEVER** pass tokens in URL query parameters
+- **NEVER** return raw tokens to the frontend
+- **NEVER** bypass the BFF for auth
+- **NEVER** use `AsyncStorage` for tokens on mobile
+- **NEVER** bundle secrets into the mobile app binary
+- **NEVER** implement frontend-only permission checks without backend enforcement
+- **NEVER** use `localStorage`/`sessionStorage` to mock auth in tests — mock `/auth/me` via TanStack Query or `page.route()`
+- **NEVER** implement token refresh logic in the frontend — the BFF middleware handles it server-side (RFC 9700)
+- **NEVER** add 401 retry/intercept logic in the frontend API client — a 401 means the session is dead, not that a token needs refreshing

package/templates/claude/rules/backend-patterns.md

@@ -0,0 +1,421 @@
+---
+globs: "src/**/*.ts"
+---
+
+# Backend Patterns
+
+## Modular Monolith
+
+Two deployable artifacts: one NestJS backend image, one React frontend image. No microservices.
+
+### Module Structure
+
+```
+src/
+  <module>/           # Domain module (e.g., identity, billing)
+  bff/                # BFF authentication
+  shared/             # Guards, filters, interceptors
+```
+
+### Module Boundary Rules
+
+- Modules communicate through `CommandBus`/`QueryBus` — never import another module's services or repositories
+- Each module owns its own PostgreSQL schema (e.g., `identity.*`, `billing.*`)
+- Async inter-module communication uses Redis Streams
+- Only commands, queries, and DTOs are exported from a module
+
+## POST-IMPLEMENTATION CHECKLIST (run after every command/handler pair)
+
+Before committing any command + handler:
+- [ ] Command class has `@Validate(XxxValidator)` decorator → grep the command file for `@Validate`
+- [ ] `.validator.ts` file exists with Zod schema + `ICommandValidator<T>`
+- [ ] Handler uses `getTransactionalRepo(this.xxxRepo)` — never `this.xxxRepo` directly
+- [ ] Handler does NOT contain `Result.validationError()` or any `if (x) return Result.failure(...)` validation
+- [ ] Controller only injects `CommandBus`/`QueryBus` — no services, no repositories
+
+## Controller Pattern (MANDATORY — thin controllers)
+
+Controllers ONLY parse the request and dispatch to command/query bus. No services, no repositories, no business logic.
+
+```typescript
+import { Controller, Post, Get, Body, Param } from '@nestjs/common';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+
+@Controller('items')
+export class ItemsController {
+  constructor(
+    private readonly commandBus: CommandBus,
+    private readonly queryBus: QueryBus,
+  ) {}
+
+  @Post()
+  async create(@Body() dto: CreateItemDto) {
+    return this.commandBus.execute(new CreateItemCommand(dto.name, dto.description));
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string) {
+    return this.queryBus.execute(new GetItemByIdQuery(id));
+  }
+}
+```
+
+## CQRS Handler Pattern
+
+Every feature is a **Command class + CommandHandler** pair. Controllers are thin — they only
+parse the request and dispatch to the command/query bus.
+
+All commands are **transactional by default** (UnitOfWork pattern). Nested commands share one transaction.
+
+```typescript
+import { Validate, DistributedLock, getTransactionalRepo, Result } from '@nestjs-cqrs/quanticjs';
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+// Command class — MUST have @Validate decorator (without it, .validator.ts is dead code)
+@Validate(CreateItemValidator)           // ← MANDATORY — this wires the validator
+@DistributedLock('create-item:{name}')
+export class CreateItemCommand {
+  static readonly logExclude = ['largeField']; // optional: exclude fields from @Log output
+  constructor(public readonly name: string, public readonly description: string) {}
+}
+
+// Handler — uses getTransactionalRepo for UnitOfWork participation
+// ⚠️ NEVER put validation logic in handlers — use @Validate + .validator.ts
+@CommandHandler(CreateItemCommand)
+export class CreateItemHandler implements ICommandHandler<CreateItemCommand> {
+  constructor(@InjectRepository(Item) private readonly itemRepo: Repository<Item>) {}
+  async execute(command: CreateItemCommand): Promise<Result<ItemDto>> {
+    const itemRepo = getTransactionalRepo(this.itemRepo);
+    const item = itemRepo.create({ name: command.name, description: command.description });
+    await itemRepo.save(item);
+    return Result.success(toDto(item));
+  }
+}
+```
+
+## Pipeline Behavior Chains
+
+**Commands:** `Log (global) → FeatureFlag → Validate → Cache → DistributedLock → Transactional (auto) → Handler`
+**Queries:** `Log (global) → FeatureFlag → Validate → Cache → Handler`
+
+- `@Log` — global, single structured log per command (payload, duration, result, auto-truncated)
+- `@FeatureFlag('flag-name')` — Unleash feature flag check before execution (see Feature Flags section below)
+- `@Validate(ValidatorClass)` — Zod validation via separate `.validator.ts` class
+- `@Cache('key:{prop}', { ttlSeconds: 60 })` — Redis caching with key interpolation
+- `@DistributedLock('key:{prop}')` — Redis distributed lock for concurrency protection
+- **Transactional** — automatic for all commands (UnitOfWork). Nested commands share one tx
+- `@IsolatedTransaction()` — opt-out: runs in own transaction (audit logs, notifications)
+
+### Decorator Reference
+```typescript
+// @Validate — MANDATORY for ALL commands (without it, the .validator.ts is dead code!)
+@Validate(CreateItemValidator)
+export class CreateItemCommand { ... }
+
+// @DistributedLock — concurrency protection
+@DistributedLock('create-item:{name}')
+export class CreateItemCommand { ... }
+
+// @Cache — read-heavy queries
+@Cache('items:list:{orgId}', { ttlSeconds: 60 })
+export class ListItemsQuery { ... }
+
+// @FeatureFlag — see Feature Flags section for naming + fallback rules
+@FeatureFlag('release-billing-premium-export', { fallback: 'throw' })
+export class ExportReportCommand { ... }
+
+// @IsolatedTransaction — independent commit (audit, notifications)
+@IsolatedTransaction()
+export class WriteAuditLogCommand { ... }
+```
+
+## Validation Pattern (MANDATORY)
+
+**Two layers — never mix them:**
+
+| Layer | Tool | Where |
+|-------|------|-------|
+| DTO (controller) | class-validator decorators | `*.dto.ts` |
+| Command (pipeline) | Zod + `@Validate(ValidatorClass)` | `*.validator.ts` |
+
+**CRITICAL:** Creating a `.validator.ts` file is NOT enough. The command class MUST have `@Validate(XxxValidator)` decorator or the validator never executes.
+
+**Handlers MUST NOT contain validation logic.** No `if (x < y) return Result.validationError(...)` in handlers. ALL business rule validation belongs in the Zod validator:
+
+```typescript
+// ❌ WRONG — validation in handler
+async execute(cmd: RegisterUserCommand): Promise<Result<UserDto>> {
+  if (calculateAge(cmd.dateOfBirth) < 18) {
+    return Result.validationError('Must be at least 18');
+  }
+  // ...
+}
+
+// ✅ CORRECT — validation in .validator.ts via Zod, wired with @Validate on command
+import { z } from 'zod';
+import { ICommandValidator, validateCommand } from '@nestjs-cqrs/quanticjs';
+
+export class RegisterUserValidator implements ICommandValidator<RegisterUserCommand> {
+  private schema = z.object({
+    email: z.string().email(),
+    dateOfBirth: z.coerce.date().refine(
+      dob => calculateAge(dob) >= 18,
+      'Must be at least 18 years old'
+    ),
+    password: z.string().min(8).max(128),
+  });
+  validate(cmd: RegisterUserCommand) { return validateCommand(this.schema, cmd); }
+}
+```
+
+## UnitOfWork — Nested Command Transactions
+
+All commands share an ambient transaction via `AsyncLocalStorage`. Nested commands automatically join the outer transaction — all commit or rollback together.
+
+```typescript
+@CommandHandler(OnboardCustomerCommand)
+export class OnboardCustomerHandler {
+  async execute(cmd: OnboardCustomerCommand): Promise<Result<void>> {
+    const user = await this.commandBus.execute(new CreateUserCommand(...));
+    if (!user.isSuccess) return user;  // triggers rollback of everything
+    const org = await this.commandBus.execute(new CreateOrgCommand(...));
+    if (!org.isSuccess) return org;    // triggers rollback of everything (including user)
+    return Result.success();           // commits everything atomically
+  }
+}
+```
+
+Use `@IsolatedTransaction()` to opt out (audit logs, notifications that must commit independently).
+
+## Result<T> Usage
+
+Handlers return `Result<T>` — never throw for business errors.
+
+```typescript
+// Creating results
+Result.success(value)                              // happy path
+Result.failure(ErrorType.NotFound, 'message')      // typed error
+Result.notFound('message')                         // shorthand
+Result.conflict('message')                         // shorthand
+Result.forbidden('message')                        // shorthand
+Result.unauthorized('message')                     // shorthand
+Result.unprocessableEntity('message')              // shorthand
+Result.validationError('message')                  // ONLY from validators, never handlers
+
+// Using results
+result.isSuccess                                   // boolean check
+result.value                                       // access value (undefined if failure)
+result.unwrap()                                    // get value or throw if failure
+result.map(item => toDto(item))                    // transform value, preserving error state
+```
+
+## Entity Patterns
+
+All entities extend `BaseEntity` from `@nestjs-cqrs/quanticjs`:
+- `id` (UUID, auto-generated)
+- `createdAt` (timestamp)
+- `updatedAt` (timestamp)
+
+Tenant-scoped entities extend `TenantBaseEntity` (adds `organizationId`).
+
+```typescript
+import { BaseEntity, TenantBaseEntity, Result } from '@nestjs-cqrs/quanticjs';
+```
+
+## Redis Streams — Inter-Module Events
+
+- Use `RedisStreamConsumer` base class for consumers (handles connection isolation)
+- Every consumer uses a **dedicated cloned connection** for blocking XREADGROUP
+- Shared `REDIS_CLIENT` is for non-blocking ops only (cache, XADD, locks)
+- `onModuleInit()` for setup; `onApplicationBootstrap()` for polling loops
+- Events published after transaction commits
+
+### Retry and Dead-Letter Policy
+
+- **Max retries:** 5 with exponential backoff + jitter (`min(1s × 2^attempt + random(0,1000ms), 30s)`)
+- **Dead-letter stream:** `{stream}:dlq` (e.g., `orders:events:dlq`) with `MAXLEN ~ 100000`
+- Failed events are never silently dropped — retry or dead-letter
+
+## NestJS Module Patterns — Singletons and Lifecycle
+
+### .forRoot() Modules — Import ONCE in app.module.ts
+
+Modules with `.forRoot()` (ScheduleModule, LoggerModule, BullModule, etc.) MUST be imported
+**exactly once** in `app.module.ts`. Feature modules import the regular module (no `.forRoot()`).
+
+```typescript
+// ❌ WRONG — .forRoot() in every feature module
+@Module({ imports: [ScheduleModule.forRoot()] })
+export class ActivityModule {}
+
+@Module({ imports: [ScheduleModule.forRoot()] })
+export class BillingModule {}
+
+// ✅ CORRECT — .forRoot() once in app.module.ts
+@Module({
+  imports: [
+    ScheduleModule.forRoot(),        // once here
+    LoggerModule.forRoot(pinoConfig), // once here
+    BullModule.forRoot({ redis }),    // once here
+    ActivityModule,
+    BillingModule,
+  ],
+})
+export class AppModule {}
+
+// Feature modules just use the schedule decorators — no .forRoot() needed
+@Module({ providers: [ActivityCleanupService] })
+export class ActivityModule {}
+```
+
+**Common .forRoot() modules that must be in app.module.ts only:**
+- `ScheduleModule.forRoot()` — @nestjs/schedule
+- `LoggerModule.forRoot()` — nestjs-pino
+- `BullModule.forRoot()` — @nestjs/bull
+- `EventEmitterModule.forRoot()` — @nestjs/event-emitter
+- `ThrottlerModule.forRoot()` — @nestjs/throttler
+
+### Lifecycle Hooks — Setup vs. Async Work
+
+**`onModuleInit()`** — for synchronous setup (create consumer groups, register handlers).
+**`onApplicationBootstrap()`** — for starting async work (polling loops, listeners).
+
+```typescript
+// ❌ WRONG — blocking poll loop in onModuleInit prevents app.listen()
+@Injectable()
+export class EventConsumer implements OnModuleInit {
+  async onModuleInit() {
+    await this.createConsumerGroup();
+    while (true) {                      // 🔥 blocks forever — app never starts
+      await this.redis.xreadgroup('GROUP', 'mygroup', 'consumer', 'BLOCK', 5000, ...);
+    }
+  }
+}
+
+// ✅ CORRECT — setup in onModuleInit, polling in onApplicationBootstrap
+@Injectable()
+export class EventConsumer implements OnModuleInit, OnApplicationBootstrap {
+  async onModuleInit() {
+    // Synchronous setup only — create consumer groups, register handlers
+    await this.createConsumerGroup();
+  }
+
+  async onApplicationBootstrap() {
+    // App is fully started — safe to begin async polling
+    this.startPolling();  // non-blocking — fires and forgets
+  }
+
+  private async startPolling() {
+    while (this.isRunning) {
+      const messages = await this.redis.xreadgroup(...);
+      // process messages
+    }
+  }
+}
+```
+
+**Why this matters:** Multiple Redis stream consumers each calling `XREADGROUP BLOCK` in `onModuleInit()` cascade-block the entire startup. The app never reaches `app.listen()`.
+
+### Redis Connection Isolation — Blocking vs. Non-Blocking
+
+`XREADGROUP BLOCK` monopolizes the TCP connection for the block duration. If consumers share
+the `REDIS_CLIENT` singleton, non-blocking callers (cache GET/SET, distributed lock SET NX,
+XADD publish) queue behind the blocked read — causing multi-second latency spikes.
+
+**Rule:** Every stream consumer MUST use a **dedicated cloned connection** for blocking reads.
+The shared `REDIS_CLIENT` is for non-blocking ops only.
+
+```typescript
+// ❌ WRONG — blocking read on the shared client starves cache/locks
+@Injectable()
+export class EventConsumer {
+  constructor(@Inject(REDIS_CLIENT) private readonly redis: Redis) {}
+
+  async poll() {
+    await this.redis.xreadgroup('GROUP', 'g', 'c', 'BLOCK', 5000, 'STREAMS', 'key', '>');
+  }
+}
+
+// ✅ CORRECT — RedisStreamConsumer base class handles this automatically
+// It clones a dedicated connection via redis.duplicate() for blocking XREADGROUP,
+// while using the shared REDIS_CLIENT for XGROUP CREATE, XACK, and other non-blocking ops.
+@Injectable()
+export class EventConsumer extends RedisStreamConsumer {
+  // Just extend RedisStreamConsumer — connection isolation is built in
+}
+```
+
+**Connection budget:** 1 shared `REDIS_CLIENT` + 1 dedicated connection per consumer.
+For a service with 3 consumers, that's 4 total Redis connections.
+
+### Module Exports — Only Export What You Provide
+
+A module can only export providers it declares or imports. Exporting a class that isn't a provider in the module causes a runtime error.
+
+```typescript
+// ❌ WRONG — RedisStreamPublisher not declared as provider
+@Module({
+  providers: [EventStreamService],
+  exports: [EventStreamService, RedisStreamPublisher],  // 🔥 RedisStreamPublisher not provided
+})
+export class EventBusModule {}
+
+// ✅ CORRECT — only export what's in providers (or re-exported modules)
+@Module({
+  providers: [EventStreamService],
+  exports: [EventStreamService],
+})
+export class EventBusModule {}
+```
+
+## Feature Flags
+
+Uses `@FeatureFlag()` decorator with Unleash. Three categories:
+
+| Category | Naming | Lifetime | Default fallback |
+|---|---|---|---|
+| **Release** | `release-{module}-{feature}` | Remove within 30 days of full rollout | `throw` (Forbidden) |
+| **Kill switch** | `kill-{module}-{feature}` | Permanent — stays in code | `throw` (Forbidden) |
+| **Experiment** | `experiment-{module}-{feature}` | Remove within 90 days | `default` (control variant) |
+
+**Fallback strategies** when a flag is disabled:
+
+| Strategy | Behavior |
+|---|---|
+| `throw` (default) | Returns `Result.forbidden('Feature disabled: {flag}')` |
+| `skip` | Returns `Result.success(undefined)` — for optional features |
+| `default` | Returns `Result.success(defaultValue)` — for experiments |
+
+```typescript
+@FeatureFlag('release-billing-invoices')                                    // throw if disabled
+@FeatureFlag('kill-payments-processing')                                    // throw if disabled
+@FeatureFlag('experiment-scoring-v2', { fallback: 'default', defaultValue: oldResult })
+@FeatureFlag('release-notifications-email', { fallback: 'skip' })           // silently skip
+```
+
+**Graceful degradation:** If `UNLEASH_URL` is not set, all flags pass (features enabled by default). Local dev and tests work without Unleash.
+
+## NEVER
+
+- **NEVER** inject services or repositories into controllers — dispatch to the bus only
+- **NEVER** put business logic in controllers
+- **NEVER** put validation logic in handlers — use `@Validate` + `.validator.ts`
+- **NEVER** use Joi, Yup, or other validation libraries — class-validator for DTOs, Zod for commands
+- **NEVER** create a `.validator.ts` file without `@Validate(XxxValidator)` on the command class — it's dead code
+- **NEVER** throw `HttpException` from handlers — return `Result<T>`
+- **NEVER** use `Result.validationError()` in handlers
+- **NEVER** ignore Result values from nested commands
+- **NEVER** call `.unwrap()` inside handlers
+- **NEVER** manually manage transactions — use `getTransactionalRepo()`
+- **NEVER** share Redis connection for blocking XREADGROUP reads
+- **NEVER** start blocking poll loops in `onModuleInit()` — use `onApplicationBootstrap()`
+- **NEVER** publish events before the transaction commits
+- **NEVER** silently drop failed stream events — retry with backoff or dead-letter
+- **NEVER** use `NestJS EventEmitter` for inter-module events
+- **NEVER** use global singletons for shared business state across modules — use Redis or the database
+- **NEVER** import `.forRoot()` modules in feature modules
+- **NEVER** use feature flags on infrastructure code (migrations, middleware, module config) — use env vars
+- **NEVER** nest multiple `@FeatureFlag` decorators on one handler — one handler, one flag
+- **NEVER** use flags as permanent configuration — if always needs on/off, use env vars