@forinda/kickjs-cli 5.0.2 → 5.2.0

package/dist/generator-extension-DRNQpoZP.mjs

@@ -0,0 +1,4380 @@
+/**
+ * @forinda/kickjs-cli v5.2.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { createRequire } from "node:module";
+import { dirname, extname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import * as clack from "@clack/prompts";
+import pc from "picocolors";
+import pkg from "pluralize";
+import { execSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/utils/fs.ts
+let _dryRun = false;
+/** Enable/disable dry run mode globally for all writeFileSafe calls */
+function setDryRun(enabled) {
+	_dryRun = enabled;
+}
+/** Extensions oxfmt can format. Anything else is written verbatim. */
+const FORMATTABLE = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".json",
+	".md"
+]);
+/**
+* Write a file, creating parent directories if needed.
+*
+* After write, runs oxfmt against the file when:
+*   - format-on-write is enabled (default)
+*   - the extension is in {@link FORMATTABLE}
+*   - oxfmt resolves from the user's project (or our own cwd)
+*
+* Failures (missing oxfmt, unparseable source, formatter crash) are
+* swallowed silently — formatting is a polish step, not a correctness
+* gate. The pre-commit hook still catches anything we couldn't format.
+*
+* Skips writing entirely in dry run mode.
+*/
+async function writeFileSafe(filePath, content) {
+	if (_dryRun) return;
+	await mkdir(dirname(filePath), { recursive: true });
+	await writeFile(filePath, content, "utf-8");
+	if (FORMATTABLE.has(extname(filePath))) await formatFile(filePath, content).catch(() => {});
+}
+let _oxfmt = void 0;
+/** Resolve oxfmt from the user's project; cache the result (or null) for the process. */
+async function resolveOxfmt(cwd) {
+	if (_oxfmt !== void 0) return _oxfmt;
+	try {
+		_oxfmt = await import(createRequire(join(cwd, "package.json")).resolve("oxfmt"));
+	} catch {
+		_oxfmt = null;
+	}
+	return _oxfmt;
+}
+async function formatFile(filePath, content) {
+	const oxfmt = await resolveOxfmt(process.cwd());
+	if (!oxfmt) return;
+	const options = await loadOxfmtConfig(filePath);
+	if (options === null) return;
+	const result = await oxfmt.format(filePath, content, options);
+	if (result.code === content) return;
+	await writeFile(filePath, result.code, "utf-8");
+}
+const _oxfmtConfigCache = /* @__PURE__ */ new Map();
+/**
+* Walk up from `filePath`'s directory looking for `.oxfmtrc.json`.
+* Returns `null` when no config is found anywhere on the path —
+* generators then leave the raw template alone (which already
+* follows project conventions). Cached per starting directory so
+* the walk is one-shot per generator run.
+*/
+async function loadOxfmtConfig(filePath) {
+	let dir = dirname(filePath);
+	const startDir = dir;
+	if (_oxfmtConfigCache.has(startDir)) return _oxfmtConfigCache.get(startDir);
+	while (true) {
+		const configPath = join(dir, ".oxfmtrc.json");
+		if (existsSync(configPath)) try {
+			const raw = await readFile(configPath, "utf-8");
+			const parsed = JSON.parse(raw);
+			delete parsed["$schema"];
+			delete parsed.ignorePatterns;
+			_oxfmtConfigCache.set(startDir, parsed);
+			return parsed;
+		} catch {
+			_oxfmtConfigCache.set(startDir, null);
+			return null;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			_oxfmtConfigCache.set(startDir, null);
+			return null;
+		}
+		dir = parent;
+	}
+}
+/** Check if a file exists */
+async function fileExists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/utils/colors.ts
+const METHOD_COLOR_MAP = {
+	GET: pc.green,
+	POST: pc.cyan,
+	PUT: pc.yellow,
+	PATCH: pc.magenta,
+	DELETE: pc.red
+};
+/** Color an HTTP method string for terminal display */
+function httpMethodColor(method) {
+	return (METHOD_COLOR_MAP[method] ?? pc.dim)(method.padEnd(7));
+}
+/** Color a severity tag for terminal display (padded to 10 chars) */
+function severityColor(severity) {
+	const tag = `[${severity}]`.padEnd(10);
+	switch (severity) {
+		case "CRITICAL": return pc.red(tag);
+		case "WARNING": return pc.yellow(tag);
+		case "INFO": return pc.blue(pc.dim(tag));
+		default: return tag;
+	}
+}
+pc.green("✓"), pc.red("✖"), pc.yellow("⚠"), pc.blue("ℹ");
+/** Show branded intro banner */
+function intro(title) {
+	clack.intro(pc.bgCyan(pc.black(` ${title} `)));
+}
+/** Show closing message */
+function outro(message) {
+	clack.outro(message);
+}
+/** Handle cancellation — print message and exit */
+function handleCancel(value) {
+	if (clack.isCancel(value)) {
+		clack.cancel("Operation cancelled.");
+		process.exit(0);
+	}
+}
+/** Text input prompt */
+async function text(opts) {
+	const value = await clack.text(opts);
+	handleCancel(value);
+	return value;
+}
+/** Single select prompt */
+async function select(opts) {
+	const value = await clack.select(opts);
+	handleCancel(value);
+	return value;
+}
+/** Multi-select prompt with checkboxes */
+async function multiSelect(opts) {
+	const value = await clack.multiselect(opts);
+	handleCancel(value);
+	return value;
+}
+/** Yes/no confirmation prompt */
+async function confirm(opts) {
+	const value = await clack.confirm(opts);
+	handleCancel(value);
+	return value;
+}
+/** Create a spinner for progress indication */
+function spinner() {
+	return clack.spinner();
+}
+/** Log utilities for styled messages inside clack flow */
+const log = clack.log;
+//#endregion
+//#region src/utils/naming.ts
+/** Convert a name to PascalCase */
+function toPascalCase(name) {
+	return name.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^(.)/, (c) => c.toUpperCase());
+}
+/** Convert a name to camelCase */
+function toCamelCase(name) {
+	const pascal = toPascalCase(name);
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/** Convert a name to kebab-case */
+function toKebabCase(name) {
+	return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+/**
+* Pluralize a kebab-case name for directory/file names.
+* Uses the `pluralize` npm package for correct English pluralization
+* including irregulars (person → people, status → statuses, child → children).
+*/
+function pluralize(name) {
+	return pkg.plural(name);
+}
+/**
+* Pluralize a PascalCase name for class identifiers.
+* Used for `List${pluralPascal}UseCase` to avoid `ListUserssUseCase`.
+*/
+function pluralizePascal(name) {
+	return pkg.plural(name);
+}
+//#endregion
+//#region src/generators/templates/module-index.ts
+const repoLabelMap = {
+	inmemory: "in-memory",
+	drizzle: "Drizzle",
+	prisma: "Prisma"
+};
+function toPascalRepoType(repo) {
+	return repo.charAt(0).toUpperCase() + repo.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toKebabRepoType(repo) {
+	return repo.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function repoLabel(repo) {
+	return repoLabelMap[repo] ?? toPascalRepoType(repo);
+}
+function repoMaps(pascal, kebab, repo) {
+	const repoClassMap = {
+		inmemory: `InMemory${pascal}Repository`,
+		drizzle: `Drizzle${pascal}Repository`,
+		prisma: `Prisma${pascal}Repository`
+	};
+	const repoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	return {
+		repoClass: repoClassMap[repo] ?? `${toPascalRepoType(repo)}${pascal}Repository`,
+		repoFile: repoFileMap[repo] ?? `${toKebabRepoType(repo)}-${kebab}`
+	};
+}
+/** DDD module index — nested folders, use-cases, domain services */
+function generateModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const { repoClass, repoFile } = repoMaps(pascal, kebab, repo);
+	return `/**
+ * ${pascal} Module
+ *
+ * Self-contained feature module following Domain-Driven Design (DDD).
+ * Registers dependencies in the DI container and declares HTTP routes.
+ *
+ * Structure:
+ *   presentation/    — HTTP controllers (entry points)
+ *   application/     — Use cases (orchestration) and DTOs (validation)
+ *   domain/          — Entities, value objects, repository interfaces, domain services
+ *   infrastructure/  — Repository implementations (currently ${repoLabel(repo)})
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './domain/repositories/${kebab}.repository'
+import { ${repoClass} } from './infrastructure/repositories/${repoFile}.repository'
+import { ${pascal}Controller } from './presentation/${kebab}.controller'
+
+// Eagerly load decorated classes so @Service()/@Repository() decorators register in the DI container
+import.meta.glob(
+  ['./domain/services/**/*.ts', './application/use-cases/**/*.ts', '!./**/*.test.ts'],
+  { eager: true },
+)
+
+export class ${pascal}Module implements AppModule {
+  /**
+   * Register module dependencies in the DI container.
+   * Bind repository interface tokens to their implementations here.
+   * Currently wired to ${repoLabel(repo)}. To swap implementations, change the factory target.
+   */
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  /**
+   * Declare HTTP routes for this module.
+   * The path is prefixed with the global apiPrefix and version (e.g. /api/v1/${plural}).
+   * Passing 'controller' enables automatic OpenAPI spec generation via SwaggerAdapter.
+   */
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** REST module index — flat folder, service + controller, no use-cases */
+function generateRestModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const { repoClass, repoFile } = repoMaps(pascal, kebab, repo);
+	return `/**
+ * ${pascal} Module
+ *
+ * REST module with a flat folder structure.
+ * Controller delegates to service, service wraps the repository.
+ *
+ * Structure:
+ *   ${kebab}.controller.ts  — HTTP routes (CRUD)
+ *   ${kebab}.service.ts     — Business logic
+ *   ${kebab}.repository.ts  — Repository interface
+ *   ${repoFile}.repository.ts — Repository implementation
+ *   dtos/                   — Request/response schemas
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './${kebab}.repository'
+import { ${repoClass} } from './${repoFile}.repository'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+// Eagerly load decorated classes so @Service()/@Repository() decorators register in the DI container
+import.meta.glob(['./**/*.service.ts', './**/*.repository.ts', '!./**/*.test.ts'], { eager: true })
+
+export class ${pascal}Module implements AppModule {
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** Minimal module index — just controller, no service/repo */
+function generateMinimalModuleIndex(ctx) {
+	const { pascal, kebab, plural = "" } = ctx;
+	return `import { type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+export class ${pascal}Module implements AppModule {
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/controller.ts
+/** DDD controller — injects use-cases, nested import paths */
+function generateController$1(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { Create${pascal}UseCase } from '../application/use-cases/create-${kebab}.use-case'
+import { Get${pascal}UseCase } from '../application/use-cases/get-${kebab}.use-case'
+import { List${pluralPascal}UseCase } from '../application/use-cases/list-${plural}.use-case'
+import { Update${pascal}UseCase } from '../application/use-cases/update-${kebab}.use-case'
+import { Delete${pascal}UseCase } from '../application/use-cases/delete-${kebab}.use-case'
+import { create${pascal}Schema } from '../application/dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from '../application/dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from '../constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly create${pascal}UseCase!: Create${pascal}UseCase
+  @Autowired() private readonly get${pascal}UseCase!: Get${pascal}UseCase
+  @Autowired() private readonly list${pluralPascal}UseCase!: List${pluralPascal}UseCase
+  @Autowired() private readonly update${pascal}UseCase!: Update${pascal}UseCase
+  @Autowired() private readonly delete${pascal}UseCase!: Delete${pascal}UseCase
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.list${pluralPascal}UseCase.execute(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.get${pascal}UseCase.execute(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.create${pascal}UseCase.execute(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.update${pascal}UseCase.execute(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.delete${pascal}UseCase.execute(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+/** REST controller — injects service directly, flat import paths */
+function generateRestController(ctx) {
+	const { pascal, kebab } = ctx;
+	const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { ${pascal}Service } from './${kebab}.service'
+import { create${pascal}Schema } from './dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from './dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from './${kebab}.constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly ${camel}Service!: ${pascal}Service
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.${camel}Service.findPaginated(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.${camel}Service.findById(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.${camel}Service.create(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.${camel}Service.update(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.${camel}Service.delete(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/constants.ts
+function generateConstants(ctx) {
+	const { pascal } = ctx;
+	return `import type { QueryParamsConfig } from '@forinda/kickjs'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: QueryParamsConfig = {
+  filterable: ['name'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name'],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/dtos.ts
+function generateCreateDTO(ctx) {
+	const { pascal } = ctx;
+	return `import { z } from 'zod'
+
+/**
+ * Create ${pascal} DTO — Zod schema for validating POST request bodies.
+ * This schema is passed to @Post('/', { body: create${pascal}Schema }) for automatic validation.
+ * It also generates OpenAPI request body docs when SwaggerAdapter is used.
+ *
+ * Add more fields as needed. Supported Zod types:
+ *   z.string(), z.number(), z.boolean(), z.enum([...]),
+ *   z.array(), z.object(), .optional(), .default(), .transform()
+ */
+export const create${pascal}Schema = z.object({
+  name: z.string().min(1, 'Name is required').max(200),
+})
+
+export type Create${pascal}DTO = z.infer<typeof create${pascal}Schema>
+`;
+}
+function generateUpdateDTO(ctx) {
+	const { pascal } = ctx;
+	return `import { z } from 'zod'
+
+export const update${pascal}Schema = z.object({
+  name: z.string().min(1).max(200).optional(),
+})
+
+export type Update${pascal}DTO = z.infer<typeof update${pascal}Schema>
+`;
+}
+function generateResponseDTO(ctx) {
+	const { pascal } = ctx;
+	return `export interface ${pascal}ResponseDTO {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/use-cases.ts
+function generateUseCases(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return [
+		{
+			file: `create-${kebab}.use-case.ts`,
+			content: `/**
+ * Create ${pascal} Use Case
+ *
+ * Application layer — orchestrates a single business operation.
+ * Use cases are thin: validate input (via DTO), call domain/repo, return response.
+ * Keep business rules in the domain service, not here.
+ */
+import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Create${pascal}DTO } from '../dtos/create-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Create${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.create(dto)
+  }
+}
+`
+		},
+		{
+			file: `get-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Get${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+}
+`
+		},
+		{
+			file: `list-${plural}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+@Service()
+export class List${pluralPascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+}
+`
+		},
+		{
+			file: `update-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Update${pascal}DTO } from '../dtos/update-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Update${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.update(id, dto)
+  }
+}
+`
+		},
+		{
+			file: `delete-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+
+@Service()
+export class Delete${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<void> {
+    await this.repo.delete(id)
+  }
+}
+`
+		}
+	];
+}
+//#endregion
+//#region src/generators/templates/repository.ts
+function generateRepositoryInterface(ctx) {
+	const { pascal, kebab, dtoPrefix = "../../application/dtos", tokenScope = "app" } = ctx;
+	return `/**
+ * ${pascal} Repository Interface
+ *
+ * Defines the contract for data access.
+ * The interface declares what operations are available;
+ * implementations (in-memory, Drizzle, Prisma) fulfill the contract.
+ *
+ * To swap implementations, change the factory in the module's register() method.
+ */
+import { createToken } from '@forinda/kickjs'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+export interface I${pascal}Repository {
+  findById(id: string): Promise<${pascal}ResponseDTO | null>
+  findAll(): Promise<${pascal}ResponseDTO[]>
+  findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }>
+  create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO>
+  update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO>
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Collision-safe DI token bound to \`I${pascal}Repository\`.
+ * \`container.resolve(${pascal.toUpperCase()}_REPOSITORY)\` and
+ * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
+ * interface — no manual generic, no \`any\` cast.
+ *
+ * The \`'${tokenScope}/'\` prefix matches the project scope so
+ * \`kick-lint\`'s \`token-reserved-prefix\` rule never fires —
+ * adopters must NOT use the reserved \`'kick/'\` namespace.
+ */
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${tokenScope}/${kebab}/repository')
+`;
+}
+function generateInMemoryRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	return `/**
+ * In-Memory ${pascal} Repository
+ *
+ * Implements the repository interface using a Map.
+ * Useful for prototyping and testing. Replace with a database implementation
+ * (Drizzle, Prisma, etc.) for production use.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { randomUUID } from 'node:crypto'
+import { Repository, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class InMemory${pascal}Repository implements I${pascal}Repository {
+  private store = new Map<string, ${pascal}ResponseDTO>()
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.store.get(id) ?? null
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return Array.from(this.store.values())
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    const all = Array.from(this.store.values())
+    const data = all.slice(parsed.pagination.offset, parsed.pagination.offset + parsed.pagination.limit)
+    return { data, total: all.length }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const now = new Date().toISOString()
+    const entity: ${pascal}ResponseDTO = {
+      id: randomUUID(),
+      name: dto.name,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.store.set(entity.id, entity)
+    return entity
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const existing = this.store.get(id)
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    const updated = { ...existing, ...dto, updatedAt: new Date().toISOString() }
+    this.store.set(id, updated)
+    return updated
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.store.has(id)) throw HttpException.notFound('${pascal} not found')
+    this.store.delete(id)
+  }
+}
+`;
+}
+function generateCustomRepository(ctx) {
+	const { pascal, kebab, repoType = "", repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	const repoTypePascal = repoType.charAt(0).toUpperCase() + repoType.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+	return `/**
+ * ${repoTypePascal} ${pascal} Repository
+ *
+ * Stub implementation for a custom '${repoType}' repository.
+ * Implements the repository interface using an in-memory Map as a placeholder.
+ *
+ * TODO: Replace the in-memory Map with your ${repoType} data-access logic.
+ * See I${pascal}Repository for the interface contract.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { randomUUID } from 'node:crypto'
+import { Repository, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class ${repoTypePascal}${pascal}Repository implements I${pascal}Repository {
+  // TODO: Replace with your ${repoType} client/connection
+  private store = new Map<string, ${pascal}ResponseDTO>()
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    // TODO: Implement with ${repoType}
+    return this.store.get(id) ?? null
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    // TODO: Implement with ${repoType}
+    return Array.from(this.store.values())
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    // TODO: Implement with ${repoType}
+    const all = Array.from(this.store.values())
+    const data = all.slice(parsed.pagination.offset, parsed.pagination.offset + parsed.pagination.limit)
+    return { data, total: all.length }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with ${repoType}
+    const now = new Date().toISOString()
+    const entity: ${pascal}ResponseDTO = {
+      id: randomUUID(),
+      name: dto.name,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.store.set(entity.id, entity)
+    return entity
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with ${repoType}
+    const existing = this.store.get(id)
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    const updated = { ...existing, ...dto, updatedAt: new Date().toISOString() }
+    this.store.set(id, updated)
+    return updated
+  }
+
+  async delete(id: string): Promise<void> {
+    // TODO: Implement with ${repoType}
+    if (!this.store.has(id)) throw HttpException.notFound('${pascal} not found')
+    this.store.delete(id)
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/domain.ts
+function generateDomainService(ctx) {
+	const { pascal, kebab } = ctx;
+	return `/**
+ * ${pascal} Domain Service
+ *
+ * Domain layer — contains business rules that don't belong to a single entity.
+ * Use this for cross-entity logic, validation rules, and domain invariants.
+ * Keep it free of HTTP/framework concerns.
+ */
+import { Service, Inject, HttpException } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../repositories/${kebab}.repository'
+
+@Service()
+export class ${pascal}DomainService {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async ensureExists(id: string): Promise<void> {
+    const entity = await this.repo.findById(id)
+    if (!entity) {
+      throw HttpException.notFound('${pascal} not found')
+    }
+  }
+}
+`;
+}
+function generateEntity(ctx) {
+	const { pascal, kebab } = ctx;
+	return `/**
+ * ${pascal} Entity
+ *
+ * Domain layer — the core business object.
+ * Uses a private constructor with static factory methods (create, reconstitute)
+ * to enforce invariants. Properties are accessed via getters to maintain encapsulation.
+ *
+ * Patterns used:
+ *   - Private constructor: prevents direct instantiation
+ *   - create(): factory for new entities (generates ID, sets timestamps)
+ *   - reconstitute(): factory for rebuilding from persistence (no side effects)
+ *   - changeName(): mutation method that enforces business rules
+ */
+import { ${pascal}Id } from '../value-objects/${kebab}-id.vo'
+
+interface ${pascal}Props {
+  id: ${pascal}Id
+  name: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export class ${pascal} {
+  private constructor(private props: ${pascal}Props) {}
+
+  static create(params: { name: string }): ${pascal} {
+    const now = new Date()
+    return new ${pascal}({
+      id: ${pascal}Id.create(),
+      name: params.name,
+      createdAt: now,
+      updatedAt: now,
+    })
+  }
+
+  static reconstitute(props: ${pascal}Props): ${pascal} {
+    return new ${pascal}(props)
+  }
+
+  get id(): ${pascal}Id {
+    return this.props.id
+  }
+  get name(): string {
+    return this.props.name
+  }
+  get createdAt(): Date {
+    return this.props.createdAt
+  }
+  get updatedAt(): Date {
+    return this.props.updatedAt
+  }
+
+  changeName(name: string): void {
+    if (!name || name.trim().length === 0) {
+      throw new Error('Name cannot be empty')
+    }
+    this.props.name = name.trim()
+    this.props.updatedAt = new Date()
+  }
+
+  toJSON() {
+    return {
+      id: this.props.id.toString(),
+      name: this.props.name,
+      createdAt: this.props.createdAt.toISOString(),
+      updatedAt: this.props.updatedAt.toISOString(),
+    }
+  }
+}
+`;
+}
+function generateValueObject(ctx) {
+	const { pascal } = ctx;
+	return `/**
+ * ${pascal} ID Value Object
+ *
+ * Domain layer — wraps a primitive ID with type safety and validation.
+ * Value objects are immutable and compared by value, not reference.
+ *
+ *   ${pascal}Id.create()    — generate a new UUID
+ *   ${pascal}Id.from(id)    — wrap an existing ID string (validates non-empty)
+ *   id.equals(other)  — compare two IDs by value
+ */
+import { randomUUID } from 'node:crypto'
+
+export class ${pascal}Id {
+  private constructor(private readonly value: string) {}
+
+  static create(): ${pascal}Id {
+    return new ${pascal}Id(randomUUID())
+  }
+
+  static from(id: string): ${pascal}Id {
+    if (!id || id.trim().length === 0) {
+      throw new Error('${pascal}Id cannot be empty')
+    }
+    return new ${pascal}Id(id)
+  }
+
+  toString(): string {
+    return this.value
+  }
+
+  equals(other: ${pascal}Id): boolean {
+    return this.value === other.value
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/tests.ts
+function generateControllerTest(ctx) {
+	const { pascal, kebab, plural = "" } = ctx;
+	return `import { describe, it, expect, beforeEach } from 'vitest'
+import { Container } from '@forinda/kickjs'
+
+describe('${pascal}Controller', () => {
+  beforeEach(() => {
+    Container.reset()
+  })
+
+  it('should be defined', () => {
+    expect(true).toBe(true)
+  })
+
+  describe('POST /${plural}', () => {
+    it('should create a new ${kebab}', async () => {
+      // TODO: Set up test module, call create endpoint, assert 201
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('GET /${plural}', () => {
+    it('should return paginated ${plural}', async () => {
+      // TODO: Set up test module, call list endpoint, assert { data, meta }
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('GET /${plural}/:id', () => {
+    it('should return a ${kebab} by id', async () => {
+      // TODO: Create a ${kebab}, then fetch by id, assert match
+      expect(true).toBe(true)
+    })
+
+    it('should return 404 for non-existent ${kebab}', async () => {
+      // TODO: Fetch non-existent id, assert 404
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('PUT /${plural}/:id', () => {
+    it('should update an existing ${kebab}', async () => {
+      // TODO: Create, update, assert changes
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('DELETE /${plural}/:id', () => {
+    it('should delete a ${kebab}', async () => {
+      // TODO: Create, delete, assert gone
+      expect(true).toBe(true)
+    })
+  })
+})
+`;
+}
+function generateRepositoryTest(ctx) {
+	const { pascal, kebab, plural = "", repoPrefix = `../infrastructure/repositories/in-memory-${kebab}.repository` } = ctx;
+	return `import { describe, it, expect, beforeEach } from 'vitest'
+import { InMemory${pascal}Repository } from '${repoPrefix}'
+
+describe('InMemory${pascal}Repository', () => {
+  let repo: InMemory${pascal}Repository
+
+  beforeEach(() => {
+    repo = new InMemory${pascal}Repository()
+  })
+
+  it('should create and retrieve a ${kebab}', async () => {
+    const created = await repo.create({ name: 'Test ${pascal}' })
+    expect(created).toBeDefined()
+    expect(created.name).toBe('Test ${pascal}')
+    expect(created.id).toBeDefined()
+
+    const found = await repo.findById(created.id)
+    expect(found).toEqual(created)
+  })
+
+  it('should return null for non-existent id', async () => {
+    const found = await repo.findById('non-existent')
+    expect(found).toBeNull()
+  })
+
+  it('should list all ${plural}', async () => {
+    await repo.create({ name: '${pascal} 1' })
+    await repo.create({ name: '${pascal} 2' })
+
+    const all = await repo.findAll()
+    expect(all).toHaveLength(2)
+  })
+
+  it('should return paginated results', async () => {
+    await repo.create({ name: '${pascal} 1' })
+    await repo.create({ name: '${pascal} 2' })
+    await repo.create({ name: '${pascal} 3' })
+
+    const result = await repo.findPaginated({
+      filters: [],
+      sort: [],
+      search: '',
+      pagination: { page: 1, limit: 2, offset: 0 },
+    })
+
+    expect(result.data).toHaveLength(2)
+    expect(result.total).toBe(3)
+  })
+
+  it('should update a ${kebab}', async () => {
+    const created = await repo.create({ name: 'Original' })
+    const updated = await repo.update(created.id, { name: 'Updated' })
+    expect(updated.name).toBe('Updated')
+  })
+
+  it('should delete a ${kebab}', async () => {
+    const created = await repo.create({ name: 'To Delete' })
+    await repo.delete(created.id)
+    const found = await repo.findById(created.id)
+    expect(found).toBeNull()
+  })
+})
+`;
+}
+//#endregion
+//#region src/generators/templates/rest-service.ts
+/** REST service — wraps repository with CRUD methods, replaces use-cases for flat pattern */
+function generateRestService(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import { Service, Inject, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from './${kebab}.repository'
+import type { ${pascal}ResponseDTO } from './dtos/${kebab}-response.dto'
+import type { Create${pascal}DTO } from './dtos/create-${kebab}.dto'
+import type { Update${pascal}DTO } from './dtos/update-${kebab}.dto'
+
+@Service()
+export class ${pascal}Service {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return this.repo.findAll()
+  }
+
+  async findPaginated(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.create(dto)
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.update(id, dto)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.repo.delete(id)
+  }
+}
+`;
+}
+/** REST constants — query config for flat pattern */
+function generateRestConstants(ctx) {
+	const { pascal } = ctx;
+	return `import type { QueryFieldConfig } from '@forinda/kickjs'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: QueryFieldConfig = {
+  filterable: ['name'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name'],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/cqrs.ts
+/** CQRS module index — commands, queries, events, WebSocket + queue integration */
+function generateCqrsModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const repoClassMap = {
+		inmemory: `InMemory${pascal}Repository`,
+		drizzle: `Drizzle${pascal}Repository`,
+		prisma: `Prisma${pascal}Repository`
+	};
+	const repoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const repoClass = repoClassMap[repo] ?? repoClassMap.inmemory;
+	const repoFile = repoFileMap[repo] ?? repoFileMap.inmemory;
+	return `/**
+ * ${pascal} Module — CQRS Pattern
+ *
+ * Separates read (queries) and write (commands) operations.
+ * Events are emitted after state changes and can be handled via
+ * WebSocket broadcasts, queue jobs, or ETL pipelines.
+ *
+ * Structure:
+ *   commands/       — Write operations (create, update, delete)
+ *   queries/        — Read operations (get, list)
+ *   events/         — Domain events + handlers (WS broadcast, queue dispatch)
+ *   dtos/           — Request/response schemas
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './${kebab}.repository'
+import { ${repoClass} } from './${repoFile}.repository'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+// Eagerly load decorated classes
+import.meta.glob(
+  [
+    './commands/**/*.ts',
+    './queries/**/*.ts',
+    './events/**/*.ts',
+    '!./**/*.test.ts',
+  ],
+  { eager: true },
+)
+
+export class ${pascal}Module implements AppModule {
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** CQRS controller — dispatches to command/query handlers */
+function generateCqrsController(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { Create${pascal}Command } from './commands/create-${kebab}.command'
+import { Update${pascal}Command } from './commands/update-${kebab}.command'
+import { Delete${pascal}Command } from './commands/delete-${kebab}.command'
+import { Get${pascal}Query } from './queries/get-${kebab}.query'
+import { List${pluralPascal}Query } from './queries/list-${plural}.query'
+import { create${pascal}Schema } from './dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from './dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from './${kebab}.constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly create${pascal}Command!: Create${pascal}Command
+  @Autowired() private readonly update${pascal}Command!: Update${pascal}Command
+  @Autowired() private readonly delete${pascal}Command!: Delete${pascal}Command
+  @Autowired() private readonly get${pascal}Query!: Get${pascal}Query
+  @Autowired() private readonly list${pluralPascal}Query!: List${pluralPascal}Query
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.list${pluralPascal}Query.execute(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.get${pascal}Query.execute(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.create${pascal}Command.execute(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.update${pascal}Command.execute(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.delete${pascal}Command.execute(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+/** CQRS commands — write operations that emit events */
+function generateCqrsCommands(ctx) {
+	const { pascal, kebab } = ctx;
+	return [
+		{
+			file: `create-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { Create${pascal}DTO } from '../dtos/create-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Create${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const result = await this.repo.create(dto)
+    this.events.emit('${kebab}.created', result)
+    return result
+  }
+}
+`
+		},
+		{
+			file: `update-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { Update${pascal}DTO } from '../dtos/update-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Update${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const result = await this.repo.update(id, dto)
+    this.events.emit('${kebab}.updated', result)
+    return result
+  }
+}
+`
+		},
+		{
+			file: `delete-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Delete${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(id: string): Promise<void> {
+    await this.repo.delete(id)
+    this.events.emit('${kebab}.deleted', { id })
+  }
+}
+`
+		}
+	];
+}
+/** CQRS queries — read operations */
+function generateCqrsQueries(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return [{
+		file: `get-${kebab}.query.ts`,
+		content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Get${pascal}Query {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+}
+`
+	}, {
+		file: `list-${plural}.query.ts`,
+		content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+@Service()
+export class List${pluralPascal}Query {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+}
+`
+	}];
+}
+/** CQRS events — domain event emitter + handler with WS/queue integration */
+function generateCqrsEvents(ctx) {
+	const { pascal, kebab } = ctx;
+	return [{
+		file: `${kebab}.events.ts`,
+		content: `import { Service } from '@forinda/kickjs'
+import { EventEmitter } from 'node:events'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+/**
+ * ${pascal} domain event types.
+ *
+ * These events are emitted by commands after state changes.
+ * Subscribe to them in event handlers for side effects:
+ *   - WebSocket broadcasts (real-time UI updates)
+ *   - Queue jobs (async processing, ETL pipelines)
+ *   - Audit logging
+ *   - Cache invalidation
+ */
+export interface ${pascal}EventMap {
+  '${kebab}.created': ${pascal}ResponseDTO
+  '${kebab}.updated': ${pascal}ResponseDTO
+  '${kebab}.deleted': { id: string }
+}
+
+@Service()
+export class ${pascal}Events {
+  private emitter = new EventEmitter()
+
+  emit<K extends keyof ${pascal}EventMap>(event: K, data: ${pascal}EventMap[K]): void {
+    this.emitter.emit(event, data)
+  }
+
+  on<K extends keyof ${pascal}EventMap>(event: K, handler: (data: ${pascal}EventMap[K]) => void): void {
+    this.emitter.on(event, handler)
+  }
+
+  off<K extends keyof ${pascal}EventMap>(event: K, handler: (data: ${pascal}EventMap[K]) => void): void {
+    this.emitter.off(event, handler)
+  }
+}
+`
+	}, {
+		file: `on-${kebab}-change.handler.ts`,
+		content: `import { Service, Autowired } from '@forinda/kickjs'
+import { ${pascal}Events } from './${kebab}.events'
+
+/**
+ * ${pascal} Change Event Handler
+ *
+ * Reacts to domain events emitted by commands.
+ * Wire up side effects here:
+ *
+ * 1. WebSocket broadcast — notify connected clients in real-time
+ *    import { WsGateway } from '@forinda/kickjs-ws'
+ *    this.ws.broadcast('${kebab}-channel', { event, data })
+ *
+ * 2. Queue dispatch — offload heavy processing to background workers
+ *    import { QueueService } from '@forinda/kickjs-queue'
+ *    this.queue.add('${kebab}-etl', { action: event, payload: data })
+ *
+ * 3. ETL pipeline — transform and load data to external systems
+ *    await this.etlPipeline.process(data)
+ */
+@Service()
+export class On${pascal}ChangeHandler {
+  @Autowired() private events!: ${pascal}Events
+
+  // Uncomment to inject WebSocket and Queue services:
+  // @Autowired() private ws!: WsGateway
+  // @Autowired() private queue!: QueueService
+
+  onInit(): void {
+    this.events.on('${kebab}.created', (data) => {
+      console.log('[${pascal}] Created:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.created', data })
+      // TODO: Dispatch to queue for async processing / ETL
+      // this.queue.add('${kebab}-etl', { action: 'create', payload: data })
+    })
+
+    this.events.on('${kebab}.updated', (data) => {
+      console.log('[${pascal}] Updated:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.updated', data })
+    })
+
+    this.events.on('${kebab}.deleted', (data) => {
+      console.log('[${pascal}] Deleted:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.deleted', data })
+    })
+  }
+}
+`
+	}];
+}
+//#endregion
+//#region src/generators/templates/drizzle/index.ts
+function generateDrizzleRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	return `/**
+ * Drizzle ${pascal} Repository
+ *
+ * Implements the repository interface using Drizzle ORM.
+ * Uses buildFromColumns() with Column objects for type-safe query building.
+ *
+ * TODO: Update the schema import to match your Drizzle schema file.
+ * TODO: Replace DRIZZLE_DB injection token with your actual database token.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { eq, ne, gt, gte, lt, lte, ilike, inArray, between, and, or, asc, desc, count, sql } from 'drizzle-orm'
+import { Repository, HttpException, Inject } from '@forinda/kickjs'
+import { DRIZZLE_DB, DrizzleQueryAdapter } from '@forinda/kickjs-drizzle'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from '../../constants'
+
+// TODO: Import your Drizzle schema table — e.g.:
+// import { ${kebab}s } from '@/db/schema'
+
+const queryAdapter = new DrizzleQueryAdapter({
+  eq, ne, gt, gte, lt, lte, ilike, inArray, between, and, or, asc, desc,
+})
+
+@Repository()
+export class Drizzle${pascal}Repository implements I${pascal}Repository {
+  constructor(@Inject(DRIZZLE_DB) private db: any) {}
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    // TODO: Implement with Drizzle
+    // const row = this.db.select().from(${kebab}s).where(eq(${kebab}s.id, id)).get()
+    // return row ?? null
+    throw new Error('Drizzle ${pascal} repository not yet implemented — update schema imports and queries')
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    // TODO: Implement with Drizzle
+    // return this.db.select().from(${kebab}s).all()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    // TODO: Use buildFromColumns() with your query config for type-safe filtering
+    // const query = queryAdapter.buildFromColumns(parsed, ${pascal.toUpperCase()}_QUERY_CONFIG)
+    //
+    // const data = this.db
+    //   .select().from(${kebab}s).$dynamic()
+    //   .where(query.where).orderBy(...query.orderBy)
+    //   .limit(query.limit).offset(query.offset).all()
+    //
+    // const totalResult = this.db
+    //   .select({ count: count() }).from(${kebab}s)
+    //   .$dynamic().where(query.where).get()
+    //
+    // return { data, total: totalResult?.count ?? 0 }
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with Drizzle
+    // return this.db.insert(${kebab}s).values(dto).returning().get()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with Drizzle
+    // const row = this.db.update(${kebab}s).set(dto).where(eq(${kebab}s.id, id)).returning().get()
+    // if (!row) throw HttpException.notFound('${pascal} not found')
+    // return row
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async delete(id: string): Promise<void> {
+    // TODO: Implement with Drizzle
+    // this.db.delete(${kebab}s).where(eq(${kebab}s.id, id)).run()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+}
+`;
+}
+function generateDrizzleConstants(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import type { DrizzleQueryParamsConfig } from '@forinda/kickjs-drizzle'
+// TODO: Import your schema table and reference actual columns for type safety
+// import { ${kebab}s } from '@/db/schema'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: DrizzleQueryParamsConfig = {
+  columns: {
+    // Replace with actual Drizzle Column references for type-safe filtering:
+    // name: ${kebab}s.name,
+    // status: ${kebab}s.status,
+  },
+  sortable: {
+    // name: ${kebab}s.name,
+    // createdAt: ${kebab}s.createdAt,
+  },
+  searchColumns: [
+    // ${kebab}s.name,
+  ],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/prisma/index.ts
+function generatePrismaRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	const camel = kebab.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+	return `/**
+ * Prisma ${pascal} Repository
+ *
+ * Implements the repository interface using Prisma Client.
+ * Requires a PrismaClient instance injected via the DI container.
+ *
+ * Ensure your Prisma schema has a '${pascal}' model defined.
+ *
+ * For full Prisma field-level type safety, replace PrismaModelDelegate with your PrismaClient:
+ *   @Inject(PRISMA_CLIENT) private prisma!: PrismaClient
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { Repository, HttpException, Inject } from '@forinda/kickjs'
+import { PRISMA_CLIENT, type PrismaModelDelegate } from '@forinda/kickjs-prisma'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class Prisma${pascal}Repository implements I${pascal}Repository {
+  @Inject(PRISMA_CLIENT) private prisma!: { ${camel}: PrismaModelDelegate }
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.prisma.${camel}.findUnique({ where: { id } }) as Promise<${pascal}ResponseDTO | null>
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return this.prisma.${camel}.findMany() as Promise<${pascal}ResponseDTO[]>
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    const [data, total] = await Promise.all([
+      this.prisma.${camel}.findMany({
+        skip: parsed.pagination.offset,
+        take: parsed.pagination.limit,
+      }) as Promise<${pascal}ResponseDTO[]>,
+      this.prisma.${camel}.count(),
+    ])
+    return { data, total }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.prisma.${camel}.create({ data: dto as Record<string, unknown> }) as Promise<${pascal}ResponseDTO>
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const existing = await this.prisma.${camel}.findUnique({ where: { id } })
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    return this.prisma.${camel}.update({ where: { id }, data: dto as Record<string, unknown> }) as Promise<${pascal}ResponseDTO>
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.${camel}.deleteMany({ where: { id } })
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/project-app.ts
+/**
+* Generate src/index.ts entry file with template-specific bootstrap.
+*
+* All templates export the app for the Vite plugin (dev mode).
+* In production, bootstrap() auto-starts the HTTP server when
+* `globalThis.__kickjs_httpServer` is not set.
+*/
+function generateEntryFile(name, template, version, packages = []) {
+	switch (template) {
+		case "cqrs": {
+			const cqrsImports = [];
+			const cqrsAdapters = [];
+			if (packages.includes("devtools")) {
+				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
+				cqrsAdapters.push(`    DevToolsAdapter(),`);
+			}
+			if (packages.includes("swagger")) {
+				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
+				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+			}
+			return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
+import { bootstrap } from '@forinda/kickjs'
+// import { WsAdapter } from '@forinda/kickjs-ws'
+// import { QueueAdapter, BullMQProvider } from '@forinda/kickjs-queue'
+${cqrsImports.length ? cqrsImports.join("\n") + "\n" : ""}import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({
+  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
+})
+`;
+		}
+		case "minimal": {
+			const imports = [];
+			const adapters = [];
+			if (packages.includes("swagger")) {
+				imports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
+				adapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+			}
+			if (packages.includes("devtools")) {
+				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
+				adapters.push(`    DevToolsAdapter(),`);
+			}
+			return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
+import { bootstrap } from '@forinda/kickjs'
+${imports.length ? imports.join("\n") + "\n" : ""}import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters: [\n${adapters.join("\n")}\n  ]` : ""} })
+`;
+		}
+		default: {
+			const restImports = [];
+			const restAdapters = [];
+			if (packages.includes("devtools")) {
+				restImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
+				restAdapters.push(`    DevToolsAdapter(),`);
+			}
+			if (packages.includes("swagger")) {
+				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
+				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+			}
+			return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
+import express from 'express'
+import {
+  bootstrap,
+  requestId,
+  requestLogger,
+  helmet,
+  cors,
+} from '@forinda/kickjs'
+${restImports.length ? restImports.join("\n") + "\n" : ""}import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({
+  modules,${restAdapters.length ? `\n  adapters: [\n${restAdapters.join("\n")}\n  ],` : ""}
+  middleware: [
+    helmet(),
+    cors({ origin: '*' }),
+    requestId(),
+    requestLogger(),
+    express.json(),
+  ],
+})
+`;
+		}
+	}
+}
+/** Generate src/modules/index.ts module registry */
+function generateModulesIndex() {
+	return `import type { AppModuleClass } from '@forinda/kickjs'
+import { HelloModule } from './hello/hello.module'
+
+// Remove HelloModule and run: kick g module <name>
+export const modules: AppModuleClass[] = [HelloModule]
+`;
+}
+/**
+* Generate `src/config/index.ts` — the project's typed env schema.
+*
+* Default-exports a `defineEnv(...)` schema so `kick typegen` can
+* infer it into the global `KickEnv` registry, and *also* calls
+* `loadEnv(envSchema)` as a module-load side effect so `ConfigService`
+* and `@Value()` see the extended shape from the very first DI
+* resolution. The companion `src/index.ts` template adds
+* `import './config'` immediately after `reflect-metadata` so the
+* registration runs before `bootstrap()` constructs anything.
+*
+* After typegen runs:
+*
+*   @Value('DATABASE_URL') private url!: Env<'DATABASE_URL'>
+*   process.env.DATABASE_URL  // typed as string
+*
+* Both autocomplete and type-check at compile time.
+*/
+function generateEnvFile() {
+	return `import { defineEnv, loadEnv } from '@forinda/kickjs/config'
+import { z } from 'zod'
+
+/**
+ * Project environment schema.
+ *
+ * Extend the base schema with your application's variables. The
+ * default export is the contract \`kick typegen\` reads to populate
+ * the global \`KickEnv\` registry — that's what makes \`@Value('FOO')\`
+ * autocomplete and \`process.env.FOO\` typed.
+ *
+ * @example
+ *   DATABASE_URL: z.string().url(),
+ *   JWT_SECRET: z.string().min(32),
+ *   REDIS_URL: z.string().url().optional(),
+ */
+const envSchema = defineEnv((base) =>
+  base.extend({
+    // DATABASE_URL: z.string().url(),
+  }),
+)
+
+/**
+ * IMPORTANT — side effect: register the schema with kickjs's env cache
+ * **at module-load time**. \`ConfigService\` and \`@Value()\` both consume
+ * this cache, and they will fall back to the base schema (or undefined)
+ * if no extended schema has been registered before they're resolved.
+ *
+ * As long as \`src/index.ts\` imports this file (\`import './env'\`) at the
+ * top — before \`bootstrap()\` runs — every controller and service in the
+ * app sees the typed extended values.
+ */
+export const env = loadEnv(envSchema)
+
+export default envSchema
+`;
+}
+/** Generate src/modules/hello/hello.service.ts */
+function generateHelloService() {
+	return `import { Service } from '@forinda/kickjs'
+
+@Service()
+export class HelloService {
+  greet(name: string) {
+    return { message: \`Hello \${name} from KickJS!\`, timestamp: new Date().toISOString() }
+  }
+
+  healthCheck() {
+    return { status: 'ok', uptime: process.uptime() }
+  }
+}
+`;
+}
+/** Generate src/modules/hello/hello.controller.ts */
+function generateHelloController() {
+	return `import { Controller, Get, Autowired, type Ctx } from '@forinda/kickjs'
+import { HelloService } from './hello.service'
+
+// \`Ctx<KickRoutes.HelloController['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`). The first run after a fresh
+// scaffold creates \`.kickjs/types/routes.ts\` so this file typechecks.
+// See https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class HelloController {
+  @Autowired() private readonly helloService!: HelloService
+
+  @Get('/')
+  index(ctx: Ctx<KickRoutes.HelloController['index']>) {
+    ctx.json(this.helloService.greet('World'))
+  }
+
+  @Get('/health')
+  health(ctx: Ctx<KickRoutes.HelloController['health']>) {
+    ctx.json(this.helloService.healthCheck())
+  }
+}
+`;
+}
+/** Generate src/modules/hello/hello.module.ts */
+function generateHelloModule() {
+	return `import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
+import { HelloController } from './hello.controller'
+
+export class HelloModule implements AppModule {
+  // \`register(container)\` is optional — only implement it when you need
+  // to bind a token to a concrete implementation, e.g.
+  //   register(container) {
+  //     container.registerFactory(USER_REPOSITORY, () => container.resolve(InMemoryUserRepository))
+  //   }
+  // The HelloService uses @Service() so the decorator handles registration.
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/hello',
+      router: buildRoutes(HelloController),
+      controller: HelloController,
+    }
+  }
+}
+`;
+}
+/** Generate kick.config.ts CLI configuration */
+function generateKickConfig(template, defaultRepo = "inmemory", packageManager = "pnpm") {
+	return `import { defineConfig } from '@forinda/kickjs-cli'
+
+export default defineConfig({
+  pattern: '${template}',
+  // Pinned so \`kick add\` and other dep-installing commands always use the
+  // project's intended package manager, regardless of which lockfile exists.
+  packageManager: '${packageManager}',
+  modules: {
+    dir: 'src/modules',
+    repo: ${[
+		"drizzle",
+		"inmemory",
+		"prisma"
+	].includes(defaultRepo) ? `'${defaultRepo}'` : `{ name: '${defaultRepo}' }`},
+    pluralize: true,
+  },
+
+  // \`kick typegen\` populates \`.kickjs/types/\` so \`Ctx<KickRoutes.X['method']>\`
+  // resolves to fully-typed params/body/query. Auto-runs on \`kick dev\`.
+  // Set \`schemaValidator: false\` to skip schema-driven body typing entirely.
+  typegen: {
+    schemaValidator: 'zod',
+  },
+
+  commands: [
+    {
+      name: 'test',
+      description: 'Run tests with Vitest',
+      steps: 'npx vitest run',
+    },
+    {
+      name: 'format',
+      description: 'Format code with Prettier',
+      steps: 'npx prettier --write src/',
+    },
+    {
+      name: 'format:check',
+      description: 'Check formatting without writing',
+      steps: 'npx prettier --check src/',
+    },
+    {
+      name: 'ci:check',
+      description: 'Run typecheck + format check',
+      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
+      aliases: ['verify'],
+    },
+  ],
+})
+`;
+}
+//#endregion
+//#region src/generators/patterns/minimal.ts
+async function generateMinimalFiles(ctx) {
+	const { pascal, kebab, plural, write } = ctx;
+	await write(`${kebab}.module.ts`, generateMinimalModuleIndex({
+		pascal,
+		kebab,
+		plural
+	}));
+	await write(`${kebab}.controller.ts`, `import { Controller, Get, type Ctx } from '@forinda/kickjs'
+
+// \`Ctx<KickRoutes.${pascal}Controller['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`).
+
+@Controller()
+export class ${pascal}Controller {
+  @Get('/')
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    ctx.json({ message: '${pascal} list' })
+  }
+}
+`);
+}
+//#endregion
+//#region src/generators/patterns/rest.ts
+async function generateRestFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noTests, prismaClientPath, tokenScope, write } = ctx;
+	await write(`${kebab}.module.ts`, generateRestModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write(`${kebab}.constants.ts`, generateRestConstants({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.controller.ts`, generateRestController({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`${kebab}.service.ts`, generateRestService({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab,
+		dtoPrefix: "./dtos",
+		tokenScope
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos",
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo,
+		repoPrefix: ".",
+		dtoPrefix: "./dtos"
+	}));
+	await write(`${repoFile}.repository.ts`, repoGenerator());
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural,
+			repoPrefix: `../${builtinRepoFileMap.inmemory ?? `in-memory-${kebab}`}.repository`
+		}));
+	}
+}
+//#endregion
+//#region src/generators/patterns/cqrs.ts
+async function generateCqrsFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noTests, prismaClientPath, tokenScope, write } = ctx;
+	await write(`${kebab}.module.ts`, generateCqrsModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write(`${kebab}.constants.ts`, generateRestConstants({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.controller.ts`, generateCqrsController({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	const commands = generateCqrsCommands({
+		pascal,
+		kebab
+	});
+	for (const cmd of commands) await write(`commands/${cmd.file}`, cmd.content);
+	const queries = generateCqrsQueries({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	});
+	for (const q of queries) await write(`queries/${q.file}`, q.content);
+	const events = generateCqrsEvents({
+		pascal,
+		kebab
+	});
+	for (const e of events) await write(`events/${e.file}`, e.content);
+	await write(`${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab,
+		dtoPrefix: "./dtos",
+		tokenScope
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos",
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo,
+		repoPrefix: ".",
+		dtoPrefix: "./dtos"
+	}));
+	await write(`${repoFile}.repository.ts`, repoGenerator());
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural,
+			repoPrefix: `../${builtinRepoFileMap.inmemory ?? `in-memory-${kebab}`}.repository`
+		}));
+	}
+}
+//#endregion
+//#region src/generators/patterns/ddd.ts
+async function generateDddFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noEntity, noTests, prismaClientPath, tokenScope, write } = ctx;
+	await write(`${kebab}.module.ts`, generateModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write("constants.ts", repo === "drizzle" ? generateDrizzleConstants({
+		pascal,
+		kebab
+	}) : generateConstants({
+		pascal,
+		kebab
+	}));
+	await write(`presentation/${kebab}.controller.ts`, generateController$1({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`application/dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`application/dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`application/dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	const useCases = generateUseCases({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	});
+	for (const uc of useCases) await write(`application/use-cases/${uc.file}`, uc.content);
+	await write(`domain/repositories/${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab,
+		tokenScope
+	}));
+	await write(`domain/services/${kebab}-domain.service.ts`, generateDomainService({
+		pascal,
+		kebab
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo
+	}));
+	await write(`infrastructure/repositories/${repoFile}.repository.ts`, repoGenerator());
+	if (!noEntity) {
+		await write(`domain/entities/${kebab}.entity.ts`, generateEntity({
+			pascal,
+			kebab
+		}));
+		await write(`domain/value-objects/${kebab}-id.vo.ts`, generateValueObject({
+			pascal,
+			kebab
+		}));
+	}
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`infrastructure/repositories/in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural
+		}));
+	}
+}
+//#endregion
+//#region src/generators/module.ts
+/** Resolve a RepoTypeConfig (from kick.config.ts) into a flat repo type string */
+function resolveRepoType(config) {
+	if (!config) return "inmemory";
+	if (typeof config === "string") return config;
+	return config.name;
+}
+/**
+* Generate a module — structure depends on the project pattern.
+*
+* Patterns:
+*   rest         — flat folder: controller + service + DTOs + repo
+*   ddd          — nested DDD: presentation/ application/ domain/ infrastructure/
+*   cqrs         — commands, queries, events with WS/queue integration
+*   minimal      — just controller + module index
+*/
+async function generateModule(options) {
+	const { name, modulesDir, noEntity, noTests, repo = "inmemory", force, dryRun } = options;
+	const shouldPluralize = options.pluralize !== false;
+	let pattern = options.pattern ?? "ddd";
+	if (options.minimal) pattern = "minimal";
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const plural = shouldPluralize ? pluralize(kebab) : kebab;
+	const pluralPascal = shouldPluralize ? pluralizePascal(pascal) : pascal;
+	const moduleDir = join(modulesDir, plural);
+	const files = [];
+	let overwriteAll = force ?? false;
+	const write = async (relativePath, content) => {
+		const fullPath = join(moduleDir, relativePath);
+		if (dryRun) {
+			files.push(fullPath);
+			return;
+		}
+		if (!overwriteAll && await fileExists(fullPath)) {
+			if (!await confirm({
+				message: `File exists: ${pc.dim(relativePath)}. Overwrite?`,
+				initialValue: false
+			})) {
+				log.warn(`Skipped: ${relativePath}`);
+				return;
+			}
+		}
+		await writeFileSafe(fullPath, content);
+		files.push(fullPath);
+	};
+	const ctx = {
+		kebab,
+		pascal,
+		plural,
+		pluralPascal,
+		moduleDir,
+		repo,
+		noEntity: noEntity ?? false,
+		noTests: noTests ?? false,
+		prismaClientPath: options.prismaClientPath ?? "@prisma/client",
+		tokenScope: options.tokenScope ?? "app",
+		write,
+		files
+	};
+	switch (pattern) {
+		case "minimal":
+			await generateMinimalFiles(ctx);
+			break;
+		case "rest":
+			await generateRestFiles(ctx);
+			break;
+		case "cqrs":
+			await generateCqrsFiles(ctx);
+			break;
+		default:
+			await generateDddFiles(ctx);
+			break;
+	}
+	if (!dryRun) await autoRegisterModule(modulesDir, pascal, plural, kebab);
+	return files;
+}
+/** Add the new module to src/modules/index.ts */
+async function autoRegisterModule(modulesDir, pascal, plural, kebab) {
+	const indexPath = join(modulesDir, "index.ts");
+	const exists = await fileExists(indexPath);
+	const importPath = `./${plural}/${kebab}.module`;
+	if (!exists) {
+		await writeFileSafe(indexPath, `import type { AppModuleClass } from '@forinda/kickjs'
+import { ${pascal}Module } from '${importPath}'
+
+export const modules: AppModuleClass[] = [${pascal}Module]
+`);
+		return;
+	}
+	let content = await readFile(indexPath, "utf-8");
+	const importLine = `import { ${pascal}Module } from '${importPath}'`;
+	if (!content.includes(`${pascal}Module`)) {
+		const lastImportIdx = content.lastIndexOf("import ");
+		if (lastImportIdx !== -1) {
+			const lineEnd = content.indexOf("\n", lastImportIdx);
+			content = content.slice(0, lineEnd + 1) + importLine + "\n" + content.slice(lineEnd + 1);
+		} else content = importLine + "\n" + content;
+		content = content.replace(/(=\s*\[)([\s\S]*?)(])/, (_match, open, existing, close) => {
+			const trimmed = existing.trim();
+			if (!trimmed) return `${open}${pascal}Module${close}`;
+			const needsComma = trimmed.endsWith(",") ? "" : ",";
+			return `${open}${existing.trimEnd()}${needsComma} ${pascal}Module${close}`;
+		});
+	}
+	await writeFile(indexPath, content, "utf-8");
+}
+//#endregion
+//#region src/generators/adapter.ts
+/**
+* Scaffold a `defineAdapter()` factory under `src/adapters/<name>.adapter.ts`.
+*
+* v4 dropped the `class implements AppAdapter` pattern in favour of the
+* `defineAdapter()` factory (architecture.md §21.3.4). The generated
+* template uses the new factory shape so adopters get a working
+* adapter with all four lifecycle hooks (beforeMount, beforeStart,
+* afterStart, shutdown), a typed config object with defaults, and the
+* factory's call / `.scoped()` / `.async()` surfaces — without
+* writing a single class.
+*/
+async function generateAdapter(options) {
+	const { name, outDir } = options;
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.adapter.ts`);
+	await writeFileSafe(filePath, `import {
+  defineAdapter,
+  type AdapterContext,
+  type AdapterMiddleware,
+  type ContributorRegistrations,
+  type Constructor,
+} from '@forinda/kickjs'
+
+/**
+ * Configuration for the ${pascal} adapter.
+ *
+ * Adapters typically take a small config object so callers can tune
+ * behaviour at bootstrap time. Keep the shape narrow — anything
+ * derived from the environment should be read inside the build
+ * function via getEnv(), not forced onto the caller.
+ */
+export interface ${pascal}AdapterConfig {
+  // Add your adapter configuration here, e.g.:
+  // enabled?: boolean
+  // apiKey?: string
+}
+
+/**
+ * ${pascal} adapter — built via \`defineAdapter()\` so callers get the
+ * factory's call / \`.scoped()\` / \`.async()\` surfaces for free.
+ *
+ * Hooks into the Application lifecycle to add middleware, routes,
+ * Context Contributors, or external service connections.
+ *
+ * Every lifecycle hook below is OPTIONAL. The scaffold emits all of
+ * them so adopters can browse what's available and delete what they
+ * don't need — \`build()\` returning \`{}\` is also valid for an adapter
+ * that only contributes config defaults.
+ *
+ * @example
+ * \`\`\`ts
+ * import { bootstrap } from '@forinda/kickjs'
+ * import { ${pascal}Adapter } from './adapters/${kebab}.adapter'
+ *
+ * bootstrap({
+ *   modules,
+ *   adapters: [${pascal}Adapter({ /* config overrides *\\/ })],
+ * })
+ * \`\`\`
+ */
+export const ${pascal}Adapter = defineAdapter<${pascal}AdapterConfig>({
+  name: '${pascal}Adapter',
+  defaults: {
+    // Default config values go here. The adopter's overrides shallow-merge
+    // on top of these before \`build()\` runs.
+  },
+  build: (_config, { name: _name }) => {
+    // Closures inside \`build()\` are how each adapter instance owns its
+    // own state (database client, Map, timer handle, …). The same
+    // \`_config\` is visible to every hook below.
+
+    return {
+      /**
+       * Express middleware entries the Application mounts at named phases.
+       *
+       * \`phase\` controls where each handler sits in the pipeline:
+       *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'.
+       *
+       * \`path\` (optional) scopes the entry to a path prefix.
+       *
+       * Delete this hook entirely if you don't add middleware.
+       */
+      middleware(): AdapterMiddleware[] {
+        return [
+          // Example: add a custom header to all responses
+          // {
+          //   phase: 'beforeGlobal',
+          //   handler: (_req, res, next) => {
+          //     res.setHeader('X-${pascal}', 'true')
+          //     next()
+          //   },
+          // },
+          // Example: scope a rate limiter to one path prefix
+          // {
+          //   phase: 'beforeRoutes',
+          //   path: '/api/v1/auth',
+          //   handler: rateLimit({ max: 10 }),
+          // },
+        ]
+      },
+
+      /**
+       * Runs BEFORE global middleware. Mount routes that should bypass the
+       * middleware stack — health checks, docs UI, static assets, OAuth
+       * callbacks. Anything you want reachable even if a global middleware
+       * later in the chain rejects requests.
+       *
+       * Delete this hook if you have no early routes.
+       */
+      beforeMount(_ctx: AdapterContext): void {
+        // Example:
+        // _ctx.app.get('/${kebab}/status', (_req, res) => res.json({ status: 'ok' }))
+      },
+
+      /**
+       * Fires once per controller class as the router mounts. Use this to
+       * collect route metadata for OpenAPI specs, dependency graphs, route
+       * inventories, devtools dashboards.
+       *
+       * Delete this hook unless your adapter introspects the route registry.
+       */
+      onRouteMount(_controllerClass: Constructor, _mountPath: string): void {
+        // Example (Swagger-style): collect routes for the spec.
+        // openApiSpec.addController(_controllerClass, _mountPath)
+      },
+
+      /**
+       * Runs AFTER modules + routes are wired, BEFORE the server starts.
+       * Right place for late-stage DI registrations or final config validation.
+       *
+       * Delete this hook if there's nothing to wire post-modules.
+       */
+      beforeStart(_ctx: AdapterContext): void {
+        // Example: _ctx.container.registerInstance(MY_TOKEN, new MyService(_config))
+      },
+
+      /**
+       * Runs AFTER the HTTP server is listening. The raw \`http.Server\` is
+       * available on \`ctx.server\` — attach upgrade handlers (Socket.IO,
+       * gRPC, GraphQL subscriptions), warm caches, log a banner.
+       *
+       * Delete this hook if you don't need the running server reference.
+       */
+      afterStart(_ctx: AdapterContext): void {
+        // Example: const io = new Server(_ctx.server)
+      },
+
+      /**
+       * Returns Context Contributors to merge into every route's pipeline
+       * at the \`'adapter'\` precedence level. Per-route handlers can
+       * override the value at the method / class / module level.
+       *
+       * Delete this hook unless your adapter ships typed per-request values
+       * (auth user, tenant, locale, feature flags, geo, etc).
+       */
+      contributors(): ContributorRegistrations {
+        return [
+          // Example:
+          // import { defineHttpContextDecorator } from '@forinda/kickjs'
+          // declare module '@forinda/kickjs' { interface ContextMeta { ${kebab}: { id: string } } }
+          // const Load${pascal} = defineHttpContextDecorator({
+          //   key: '${kebab}',
+          //   resolve: (ctx) => ({ id: ctx.req.headers['x-${kebab}-id'] as string }),
+          // })
+          // return [Load${pascal}.registration]
+        ]
+      },
+
+      /**
+       * Runs on graceful shutdown (SIGINT/SIGTERM). Clean up long-lived
+       * resources the adapter owns: close connections, flush buffers,
+       * cancel timers. The framework runs every adapter's \`shutdown\`
+       * concurrently via \`Promise.allSettled\` — one failure won't block
+       * sibling adapters.
+       *
+       * Delete this hook if your adapter holds no resources.
+       */
+      async shutdown(): Promise<void> {
+        // Example: await this.pool.end()
+        // Example: clearInterval(this.heartbeatTimer)
+      },
+    }
+  },
+})
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/utils/resolve-out-dir.ts
+/**
+* DDD folder mapping — nested layered architecture.
+*/
+const DDD_FOLDER_MAP = {
+	controller: "presentation",
+	service: "domain/services",
+	dto: "application/dtos",
+	guard: "presentation/guards",
+	middleware: "middleware"
+};
+/**
+* Flat folder mapping — REST/GraphQL/minimal patterns.
+* Files live at the module root or in minimal subdirectories.
+*/
+const FLAT_FOLDER_MAP = {
+	controller: "",
+	service: "",
+	dto: "dtos",
+	guard: "guards",
+	middleware: "middleware"
+};
+/**
+* CQRS folder mapping — commands, queries, events.
+*/
+const CQRS_FOLDER_MAP = {
+	controller: "",
+	service: "",
+	dto: "dtos",
+	guard: "guards",
+	middleware: "middleware",
+	command: "commands",
+	query: "queries",
+	event: "events"
+};
+/**
+* Resolve the output directory for a generator artifact.
+*
+* Priority:
+*   1. Explicit --out flag (always wins)
+*   2. --module flag → maps into module's folder (DDD or flat based on pattern)
+*   3. Standalone default directory
+*/
+function resolveOutDir(options) {
+	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd", shouldPluralize = true } = options;
+	if (outDir) return resolve(outDir);
+	if (moduleName) {
+		const folderMap = pattern === "ddd" ? DDD_FOLDER_MAP : pattern === "cqrs" ? CQRS_FOLDER_MAP : FLAT_FOLDER_MAP;
+		const kebab = toKebabCase(moduleName);
+		const folder = shouldPluralize ? pluralize(kebab) : kebab;
+		const subfolder = folderMap[type] ?? "";
+		const base = join(modulesDir, folder);
+		return resolve(subfolder ? join(base, subfolder) : base);
+	}
+	return resolve(defaultDir);
+}
+//#endregion
+//#region src/generators/middleware.ts
+async function generateMiddleware(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "middleware",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/middleware",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const camel = toCamelCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.middleware.ts`);
+	await writeFileSafe(filePath, `import type { Request, Response, NextFunction } from 'express'
+
+export interface ${toPascalCase(name)}Options {
+  // Add configuration options here
+}
+
+/**
+ * ${toPascalCase(name)} middleware.
+ *
+ * Usage in bootstrap:
+ *   middleware: [${camel}()]
+ *
+ * Usage with adapter:
+ *   middleware() { return [{ handler: ${camel}(), phase: 'afterGlobal' }] }
+ *
+ * Usage with @Middleware decorator:
+ *   @Middleware(${camel}())
+ */
+export function ${camel}(options: ${toPascalCase(name)}Options = {}) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Implement your middleware logic here
+    next()
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/guard.ts
+async function generateGuard(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "guard",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/guards",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const camel = toCamelCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.guard.ts`);
+	await writeFileSafe(filePath, `import { Container, HttpException } from '@forinda/kickjs'
+import type { RequestContext } from '@forinda/kickjs'
+
+/**
+ * ${pascal} guard.
+ *
+ * Guards protect routes by checking conditions before the handler runs.
+ * Return early with an error response to block access.
+ *
+ * Usage:
+ *   @Middleware(${camel}Guard)
+ *   @Get('/protected')
+ *   async handler(ctx: RequestContext) { ... }
+ */
+export async function ${camel}Guard(ctx: RequestContext, next: () => void): Promise<void> {
+  // Example: check for an authorization header
+  const header = ctx.headers.authorization
+  if (!header?.startsWith('Bearer ')) {
+    ctx.res.status(401).json({ message: 'Missing or invalid authorization header' })
+    return
+  }
+
+  const token = header.slice(7)
+
+  try {
+    // Verify the token using a service from the DI container
+    // const container = Container.getInstance()
+    // const authService = container.resolve(AuthService)
+    // const payload = authService.verifyToken(token)
+    // ctx.set('auth', payload)
+
+    next()
+  } catch {
+    ctx.res.status(401).json({ message: 'Invalid or expired token' })
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/service.ts
+async function generateService(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "service",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/services",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.service.ts`);
+	await writeFileSafe(filePath, `import { Service } from '@forinda/kickjs'
+
+@Service()
+export class ${pascal}Service {
+  // Inject dependencies via constructor
+  // constructor(
+  //   @Inject(MY_REPO) private readonly repo: IMyRepository,
+  // ) {}
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/controller.ts
+async function generateController(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "controller",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/controllers",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.controller.ts`);
+	await writeFileSafe(filePath, `import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
+
+// \`Ctx<KickRoutes.${pascal}Controller['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`). After the first run, your IDE
+// will autocomplete \`ctx.params\`, \`ctx.body\`, and \`ctx.query\`.
+// See https://forinda.github.io/kick-js/guide/typegen for details.
+
+@Controller()
+export class ${pascal}Controller {
+  // @Autowired() private readonly myService!: MyService
+
+  @Get('/')
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    ctx.json({ message: '${pascal} list' })
+  }
+
+  @Post('/')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    ctx.created({ message: '${pascal} created', data: ctx.body })
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/dto.ts
+async function generateDto(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "dto",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/dtos",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const camel = toCamelCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.dto.ts`);
+	await writeFileSafe(filePath, `import { z } from 'zod'
+
+export const ${camel}Schema = z.object({
+  // Define your schema fields here
+  name: z.string().min(1).max(200),
+})
+
+export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/templates/project-config.ts
+/** Map of optional package names to their npm package identifiers */
+const PACKAGE_DEPS = {
+	auth: "@forinda/kickjs-auth",
+	swagger: "@forinda/kickjs-swagger",
+	ws: "@forinda/kickjs-ws",
+	queue: "@forinda/kickjs-queue",
+	devtools: "@forinda/kickjs-devtools"
+};
+/** Generate package.json with template-aware dependencies */
+function generatePackageJson(name, template, kickjsVersion, packages = []) {
+	const baseDeps = {
+		"@forinda/kickjs": kickjsVersion,
+		dotenv: "^17.3.1",
+		express: "^5.1.0",
+		"reflect-metadata": "^0.2.2",
+		zod: "^4.3.6",
+		pino: "^10.3.1",
+		"pino-pretty": "^13.1.3"
+	};
+	for (const pkg of packages) {
+		const dep = PACKAGE_DEPS[pkg];
+		if (dep && !baseDeps[dep]) baseDeps[dep] = kickjsVersion;
+	}
+	return JSON.stringify({
+		name,
+		version: kickjsVersion.replace("^", ""),
+		type: "module",
+		scripts: {
+			dev: "vite",
+			"dev:debug": "kick dev:debug",
+			build: "kick build",
+			start: "kick start",
+			test: "vitest run",
+			"test:watch": "vitest",
+			typecheck: "tsc --noEmit",
+			typegen: "kick typegen",
+			lint: "eslint src/",
+			format: "prettier --write src/"
+		},
+		dependencies: baseDeps,
+		devDependencies: {
+			"@forinda/kickjs-cli": kickjsVersion,
+			"@forinda/kickjs-vite": kickjsVersion,
+			"@swc/core": "^1.15.21",
+			"@types/express": "^5.0.6",
+			"@types/node": "^25.0.0",
+			"unplugin-swc": "^1.5.9",
+			vite: "^8.0.3",
+			vitest: "^4.1.2",
+			typescript: "^6.0.3",
+			prettier: "^3.8.1"
+		}
+	}, null, 2);
+}
+/**
+* Generate vite.config.ts with the KickJS Vite plugin.
+*
+* The plugin handles:
+* - SSR environment setup for backend Node.js code
+* - Virtual module generation (virtual:kickjs/app)
+* - Module auto-discovery (scans *.module.ts files)
+* - HMR with selective container invalidation
+* - Express mounting via configureServer() post-hook
+* - httpServer piping to adapters (WsAdapter, Socket.IO, etc.)
+*/
+function generateViteConfig() {
+	return `import { defineConfig } from 'vite'
+import { resolve } from 'node:path'
+import swc from 'unplugin-swc'
+import { kickjsVitePlugin, envWatchPlugin } from '@forinda/kickjs-vite'
+
+export default defineConfig({
+  oxc: false,
+  plugins: [
+    swc.vite(),
+    kickjsVitePlugin({ entry: 'src/index.ts' }),
+    // Watches .env files and triggers a full reload on change so the
+    // dev server picks up env tweaks without a manual restart.
+    envWatchPlugin(),
+  ],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  ssr: {
+    // Don't bundle pino — its worker-thread transport needs Node.js resolution
+    // to find pino-pretty at runtime for colored log output
+    external: ['pino', 'pino-pretty'],
+  },
+  build: {
+    target: 'node20',
+    ssr: true,
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      input: resolve(__dirname, 'src/index.ts'),
+      output: { format: 'esm' },
+    },
+  },
+})
+`;
+}
+/** Generate tsconfig.json with decorator support */
+function generateTsConfig() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			module: "ESNext",
+			moduleResolution: "bundler",
+			lib: ["ES2022"],
+			types: ["node", "vite/client"],
+			strict: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+			sourceMap: true,
+			declaration: true,
+			experimentalDecorators: true,
+			emitDecoratorMetadata: true,
+			outDir: "dist",
+			paths: { "@/*": ["./src/*"] }
+		},
+		include: [
+			"src",
+			".kickjs/types/**/*.d.ts",
+			".kickjs/types/**/*.ts"
+		]
+	}, null, 2);
+}
+/** Generate .prettierrc with project formatting rules */
+function generatePrettierConfig() {
+	return JSON.stringify({
+		semi: false,
+		singleQuote: true,
+		trailingComma: "all",
+		printWidth: 100,
+		tabWidth: 2
+	}, null, 2);
+}
+/** Generate .editorconfig for consistent editor settings */
+function generateEditorConfig() {
+	return `# https://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+`;
+}
+/** Generate .gitignore with common Node.js patterns */
+function generateGitIgnore() {
+	return `node_modules/
+dist/
+.env
+coverage/
+.DS_Store
+*.tsbuildinfo
+.kickjs/
+`;
+}
+/** Generate .gitattributes for consistent line endings */
+function generateGitAttributes() {
+	return `# Auto-detect text files and normalise line endings to LF
+* text=auto eol=lf
+
+# Explicitly mark generated / binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+
+# Lock files — treat as generated
+pnpm-lock.yaml -diff linguist-generated
+yarn.lock -diff linguist-generated
+package-lock.json -diff linguist-generated
+`;
+}
+/** Generate .env file with default environment variables */
+function generateEnv() {
+	return `PORT=3000
+NODE_ENV=development
+`;
+}
+/** Generate .env.example file as a template */
+function generateEnvExample() {
+	return `PORT=3000
+NODE_ENV=development
+`;
+}
+/** Generate vitest.config.ts for test configuration */
+function generateVitestConfig() {
+	return `import { defineConfig } from 'vitest/config'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  plugins: [swc.vite()],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})
+`;
+}
+//#endregion
+//#region src/generators/templates/project-docs.ts
+/** Generate README.md with project documentation */
+function generateReadme(name, template, pm) {
+	const templateLabels = {
+		rest: "REST API",
+		ddd: "Domain-Driven Design",
+		cqrs: "CQRS + Event-Driven",
+		minimal: "Minimal"
+	};
+	const packages = ["@forinda/kickjs", "@forinda/kickjs-vite"];
+	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
+	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws");
+	return `# ${name}
+
+A **${templateLabels[template] ?? "REST API"}** built with [KickJS](https://forinda.github.io/kick-js/) — a decorator-driven Node.js framework on Express 5 and TypeScript.
+
+## Getting Started
+
+\`\`\`bash
+${pm} install
+kick dev
+\`\`\`
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| \`kick dev\` | Start dev server with Vite HMR |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`${pm} run test\` | Run tests with Vitest |
+| \`kick g module <name>\` | Generate a DDD module |
+| \`kick g scaffold <name> <fields...>\` | Generate CRUD from field definitions |
+| \`kick add <package>\` | Add a KickJS package |
+
+## Project Structure
+
+\`\`\`
+src/
+├── index.ts           # Application entry point
+├── modules/           # Feature modules (controllers, services, repos)
+│   └── index.ts       # Module registry
+└── ...
+\`\`\`
+
+## Packages
+
+${packages.map((p) => `- \`${p}\``).join("\n")}
+
+## Adding Features
+
+\`\`\`bash
+kick add auth          # Authentication (JWT, API key, OAuth)
+kick add swagger       # OpenAPI documentation
+kick add ws            # WebSocket support
+kick add queue         # Background job processing
+kick add --list        # Show all available packages
+\`\`\`
+
+For email, scheduled tasks, multi-tenancy, OpenTelemetry, GraphQL, and notifications use the BYO recipes in the [KickJS guides](https://forinda.github.io/kick-js/guide/) — they wire the upstream library through \`defineAdapter()\` / \`definePlugin()\` directly, so you keep control of the integration.
+
+## Environment Variables
+
+Copy \`.env.example\` to \`.env\` and configure:
+
+| Variable | Default | Description |
+|---|---|---|
+| \`PORT\` | \`3000\` | Server port |
+| \`NODE_ENV\` | \`development\` | Environment |
+
+## Learn More
+
+- [KickJS Documentation](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+`;
+}
+/**
+* Generate CLAUDE.md.
+*
+* v4 update: this file is intentionally thin. AGENTS.md is the
+* canonical, multi-agent project reference (Claude / Copilot /
+* Codex / Gemini / etc.) — duplicating it here meant two files
+* drifting out of sync after every framework change. The generated
+* CLAUDE.md now redirects there + adds Claude-specific affordances
+* only.
+*/
+function generateClaude(name, _template, pm) {
+	return `# CLAUDE.md — ${name}
+
+**Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
+reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
+project conventions, structure, decorator patterns, env wiring, CLI
+generators, every gotcha.
+
+**Then read \`./kickjs-skills.md\`.** That file is the task-oriented
+skill index — short, rigid recipes keyed to triggers ("add-module",
+"write-controller-test", "bootstrap-export", "deny-list", …). Use it
+as the playbook when executing common KickJS workflows.
+
+This file is a thin Claude-specific layer on top of those two; when
+they disagree on anything substantive, treat \`AGENTS.md\` as
+authoritative and flag the discrepancy.
+
+## Why two files
+
+\`AGENTS.md\` is what every agent reads. \`CLAUDE.md\` is what
+Claude Code automatically loads as project context on each
+conversation. Keeping CLAUDE.md slim avoids two files drifting; the
+redirect above ensures Claude pulls the canonical content without
+us copy-pasting.
+
+## Claude-specific notes
+
+- **Slash commands** — \`/help\` for Claude Code commands; \`/init\`
+  to refresh project memory if AGENTS.md changes substantially.
+- **Feedback** — file issues at <https://github.com/anthropics/claude-code/issues>.
+- **Persistent memory** — Claude maintains user/feedback/project/
+  reference memories under \`.claude/memory/\`. If you ask for
+  something that contradicts a remembered preference, Claude flags
+  it before acting; corrections update memory automatically.
+- **Long-running tasks** — \`/loop\` and \`/schedule\` for recurring
+  or background work. Useful for "wait for the deploy then open a
+  cleanup PR" or "every Monday triage the issue board" patterns.
+
+## Quick reference (full version in AGENTS.md)
+
+\`\`\`bash
+${pm} install            # Install dependencies
+kick dev                 # Dev server with HMR + typegen
+kick build && kick start # Production
+${pm} run test           # Vitest
+${pm} run typecheck      # tsc --noEmit
+${pm} run format         # Prettier
+\`\`\`
+
+## v4 framework reminders
+
+When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`AGENTS.md\`:
+
+- **Adapters**: \`defineAdapter()\` factory — never \`class implements AppAdapter\`.
+- **Plugins**: \`definePlugin()\` factory — never plain function returning \`KickPlugin\`.
+- **DI tokens**: slash-delimited \`<scope>/<area>/<key>\` (e.g. \`'app/users/repository'\`). First-party uses the reserved \`'kick/'\` prefix; this project owns its own scope.
+- **Decorators**: \`@Controller()\` (no path arg — mount prefix comes from \`routes().path\`).
+- **Module entry file** MUST be named \`<name>.module.ts\` and live under \`src/modules/<name>/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed \`projects.ts\` silently degrades every save into a full restart.
+- **Env**: schema lives in \`src/config/index.ts\`; \`import './config'\` MUST be the first import in \`src/index.ts\` (side-effect registers the schema before any \`@Value\` resolves).
+- **Assets**: drop new template files into \`src/templates/<namespace>/\`; the dev watcher auto-rebuilds the \`KickAssets\` augmentation + \`assets.x.y()\` re-walks on next call. No restart, no manual build.
+- **Context Contributors** (\`defineContextDecorator\`) over \`@Middleware()\` for ctx-population work.
+- **Repos under tests**: \`Container.create()\` for isolation — never \`new Container()\` or \`getInstance().reset()\`.
+- **Bootstrap export**: \`src/index.ts\` must end with \`export const app = await bootstrap({ ... })\`. The Vite plugin and \`createTestApp\` import the named \`app\`; without the export, HMR silently degrades to full restarts.
+- **Thin entry file**: aggregate \`modules\`, \`middleware\`, \`plugins\`, \`adapters\` in their own folders (\`src/modules/index.ts\`, \`src/middleware/index.ts\`, …) and pass them by name to \`bootstrap()\` — never inline the lists in \`src/index.ts\`.
+- **Refresh these files**: \`kick g agents -f\` regenerates \`AGENTS.md\` + \`CLAUDE.md\` from the latest CLI templates. Hand-edited content is overwritten — keep customisation in \`AGENTS.local.md\`.
+
+For everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \`AGENTS.md\`.
+`;
+}
+/** Generate AGENTS.md with AI agent guide */
+function generateAgents(name, template, pm) {
+	return `# AGENTS.md — AI Agent Guide for ${name}
+
+This guide is the **canonical, multi-agent reference** for this KickJS
+application — Claude, Copilot, Codex, Gemini, etc. all read it first.
+Per-agent files (\`CLAUDE.md\`, \`GEMINI.md\`, etc.) are thin layers that
+add tool-specific affordances on top.
+
+## Before You Start
+
+1. Run \`${pm} install\` to install dependencies
+2. Run \`kick dev\` to verify the app starts
+3. Read the [KickJS documentation](https://forinda.github.io/kick-js/) for framework details
+
+## v4 Conventions (don't skip)
+
+KickJS v4 made a handful of structural changes from v3. Internalise these
+before generating or modifying code — they are the source of most agent
+mistakes:
+
+- **Adapters** — \`defineAdapter()\` factory. Never write \`class Foo implements AppAdapter\`.
+
+  \`\`\`ts
+  export const MyAdapter = defineAdapter<MyOptions>({
+    name: 'MyAdapter',
+    defaults: { ... },
+    build: (config) => ({
+      beforeMount({ app }) { /* ... */ },
+      afterStart({ server }) { /* ... */ },
+    }),
+  })
+  \`\`\`
+
+- **Plugins** — \`definePlugin()\` factory. Same shape, never plain function returning \`KickPlugin\`.
+
+- **DI tokens** — slash-delimited \`<scope>/<area>/<key>\`, lower-case, no \`:\` separators:
+
+  \`\`\`ts
+  const USERS_REPO = createToken<UsersRepo>('app/users/repository')
+  const DB         = createToken<Database>('app/db/connection')
+  \`\`\`
+
+  The \`kick/\` prefix is reserved for first-party packages; this project
+  owns its own scope (\`app/\`, your domain name, etc.).
+
+- **\`@Controller()\`** takes **no path argument**. Mount prefix comes from
+  the module's \`routes()\` return value, not the decorator. \`@Controller('/users')\`
+  is a v3 leftover; the linter and codegen reject it.
+
+- **Env wiring** — \`src/config/index.ts\` calls \`loadEnv(envSchema)\` as a
+  side effect. \`src/index.ts\` MUST have \`import './config'\` as its **first**
+  import (before \`bootstrap()\`). Without it, \`ConfigService.get('YOUR_KEY')\`
+  returns \`undefined\` and \`@Value()\` only works via raw \`process.env\` fallback
+  (Zod coercion + defaults silently skipped).
+
+- **Module entry files MUST be named \`<name>.module.ts\`** — see the Vite
+  HMR contract at the top of "Module Pattern" below. The CLI enforces this;
+  hand-rolled files must too.
+
+- **Assets** — drop new template files into \`src/templates/<namespace>/\`
+  (or wherever \`kick.config.ts\` points). The dev watcher auto-rebuilds the
+  \`KickAssets\` augmentation; \`assets.x.y()\` re-walks on next call. No restart,
+  no manual build step.
+
+- **Context over \`@Middleware()\`** — when a middleware's only job is to
+  populate \`ctx.set('key', value)\`, use \`defineHttpContextDecorator()\`
+  (HTTP) or \`defineContextDecorator()\` (transport-agnostic) instead.
+  Typed via \`ContextMeta\`, ordered via \`dependsOn\`, validated at boot.
+  Reserve \`@Middleware()\` for response short-circuit / stream mutation /
+  pre-route-matching work.
+
+  Two ground rules around the data flow — both stem from the fact that
+  every per-request stage gets its OWN \`RequestContext\` instance, all
+  reading/writing the SAME \`AsyncLocalStorage\`-backed Map:
+  - **\`resolve\` and \`onError\` must RETURN the value.** The runner
+    writes it via \`ctx.set(reg.key, value)\` on your behalf. Direct
+    property assignment (\`ctx.tenant = …\`) sticks to the contributor
+    instance only — the handler instance never sees it.
+  - **Read across instances via \`ctx.set\` / \`ctx.get\`** (or
+    \`getRequestValue(key)\` from a service that has no \`ctx\` reference
+    — typed via \`MetaValue<K>\`). \`ctx.req\` works because the underlying
+    Express request is shared; bespoke property assignments don't.
+
+- **Test isolation** — default to \`Container.create()\` for fresh DI state.
+  Never \`new Container()\` and never \`getInstance().reset()\` — both leak
+  registrations between tests.
+
+  \`\`\`ts
+  const container = Container.create()
+  // ... register test-scoped providers, run, discard
+  \`\`\`
+
+- **Bootstrap export** — \`src/index.ts\` MUST end with
+  \`export const app = await bootstrap({ ... })\`. The Vite plugin imports
+  the named \`app\` symbol to drive HMR module swaps; testing helpers
+  (\`createTestApp\`) and the OpenAPI introspector also rely on it. Drop
+  the \`export\` and \`kick dev\` will silently fall back to a full restart
+  on every save while \`createTestApp\` complains about a missing handle.
+
+- **Keep \`src/index.ts\` thin** — collect plugins, modules, middleware, and
+  adapters in dedicated folders and re-export aggregated arrays. Do **not**
+  inline registration in the entry file:
+
+  \`\`\`ts
+  // src/modules/index.ts
+  export const modules: AppModuleClass[] = [HelloModule, UsersModule, ...]
+
+  // src/middleware/index.ts
+  export const middleware = [helmet(), cors(), requestId(), ...]
+
+  // src/plugins/index.ts
+  export const plugins = [MetricsPlugin(), AuditPlugin()]
+
+  // src/adapters/index.ts
+  export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
+  \`\`\`
+
+  \`\`\`ts
+  // src/index.ts — stays small; one import per category
+  import 'reflect-metadata'
+  import './config'
+  import { bootstrap } from '@forinda/kickjs'
+  import { modules } from './modules'
+  import { middleware } from './middleware'
+  import { plugins } from './plugins'
+  import { adapters } from './adapters'
+
+  export const app = await bootstrap({ modules, middleware, plugins, adapters })
+  \`\`\`
+
+  This keeps the entry file diff-friendly, scales to dozens of modules
+  without git churn, and lets each domain own its own registration list.
+  The generators (\`kick g module\`, \`kick g middleware\`, \`kick g plugin\`,
+  \`kick g adapter\`) follow this layout — manual additions should too.
+
+Everything else (controllers, services, modules, RequestContext API, generators,
+package additions, env access patterns, troubleshooting) is detailed below.
+
+## Where to Find Things
+
+### Application Structure
+
+| What | Where |
+|------|-------|
+| Entry point | \`src/index.ts\` |
+| Module registry | \`src/modules/index.ts\` |
+| Feature modules | \`src/modules/<module-name>/\` |
+| **Module entry file** | \`src/modules/<name>/<name>.module.ts\` (filename suffix is required — see Vite HMR contract below) |
+| Env values | \`.env\` |
+| Env schema (Zod) | \`src/config/index.ts\` |
+| TypeScript config | \`tsconfig.json\` |
+| Vite config (HMR) | \`vite.config.ts\` |
+| Vitest config | \`vitest.config.ts\` |
+| Prettier config | \`.prettierrc\` |
+| CLI config | \`kick.config.ts\` |
+
+### Module Pattern (${template.toUpperCase()})
+
+> **Vite HMR auto-discovery contract:** module files **must** be named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and live under \`src/modules/\`. The Vite plugin scans for \`*.module.[tj]sx?\` to drive graceful HMR rebuilds; renaming a file to \`projects.ts\` (no \`.module\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\`kick g module <name>\`) follows the convention; manual files must too.
+
+Each module in \`src/modules/<name>/\` typically contains:
+
+${template === "ddd" ? `\`\`\`
+<name>/
+├── <name>.controller.ts     # HTTP routes (@Controller)
+├── <name>.service.ts        # Business logic (@Service)
+├── <name>.repository.ts     # Data access (@Repository)
+├── <name>.dto.ts            # Request/response schemas (Zod)
+├── <name>.entity.ts         # Domain entity (optional)
+└── <name>.module.ts         # Module definition (implements AppModule)
+\`\`\`
+` : template === "cqrs" ? `\`\`\`
+<name>/
+├── commands/                # Write operations
+│   ├── create-<name>.command.ts
+│   └── create-<name>.handler.ts
+├── queries/                 # Read operations
+│   ├── get-<name>.query.ts
+│   └── get-<name>.handler.ts
+├── events/                  # Domain events
+│   └── <name>-created.event.ts
+├── <name>.controller.ts     # HTTP routes
+├── <name>.repository.ts     # Data access
+└── <name>.module.ts         # Module definition (implements AppModule)
+\`\`\`
+` : template === "rest" ? `\`\`\`
+<name>/
+├── <name>.controller.ts     # HTTP routes (@Controller)
+├── <name>.service.ts        # Business logic (@Service)
+├── <name>.dto.ts            # Request/response schemas (Zod)
+└── <name>.module.ts         # Module definition (implements AppModule)
+\`\`\`
+` : `\`\`\`
+src/
+├── index.ts                 # Add routes here
+└── ...                      # Custom structure
+\`\`\`
+`}
+
+## Checklist: Adding a Feature
+
+### New Module (Recommended)
+
+Use the CLI generator for consistency:
+
+\`\`\`bash
+kick g module <name>              # Generate full module
+# or
+kick g scaffold <name> <fields>   # Generate CRUD from fields
+\`\`\`
+
+Then:
+- [ ] Review generated files in \`src/modules/<name>/\`
+- [ ] Verify module is registered in \`src/modules/index.ts\`
+- [ ] Update DTOs in \`<name>.dto.ts\` if needed
+- [ ] Implement business logic in \`<name>.service.ts\`
+- [ ] Run \`kick dev\` to test with HMR
+- [ ] Write tests in \`<name>.test.ts\`
+
+### Manual Controller
+
+If not using generators:
+
+- [ ] Create \`src/modules/<name>/<name>.controller.ts\`
+- [ ] Add \`@Controller()\` decorator
+- [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
+- [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
+- [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
+- [ ] Test with \`kick dev\`
+
+### Manual Service
+
+- [ ] Create \`src/modules/<name>/<name>.service.ts\`
+- [ ] Add \`@Service()\` decorator
+- [ ] Inject dependencies with \`@Autowired()\`
+- [ ] Inject via \`@Autowired()\` where needed
+- [ ] Write unit tests
+
+### New Middleware
+
+- [ ] Create \`src/middleware/<name>.middleware.ts\`
+- [ ] Export middleware function (Express format)
+- [ ] Register in \`src/index.ts\` or attach to routes with \`@Middleware()\`
+- [ ] Test with sample requests
+
+### Adding a Package
+
+Use \`kick add\` to install KickJS packages with correct peer dependencies:
+
+- [ ] Run \`kick add <package>\` (e.g., \`kick add auth\`)
+- [ ] Follow package-specific setup in terminal output
+- [ ] Update \`src/index.ts\` to register adapter (if needed)
+- [ ] Configure environment variables in \`.env\`
+- [ ] Test integration with \`kick dev\`
+
+## Common Tasks
+
+### Generate CRUD Module
+
+\`\`\`bash
+kick g scaffold user name:string email:string:optional age:number
+\`\`\`
+
+Append \`:optional\` for optional fields (shell-safe, no quoting needed).
+Quoted \`?\` syntax also works: \`"email:string?"\` or \`"email?:string"\`.
+
+This creates a full CRUD module with:
+- Controller with GET, POST, PUT, DELETE routes
+- Service with business logic
+- Repository with data access
+- DTOs with Zod validation
+
+### Add Authentication
+
+\`\`\`bash
+kick add auth
+\`\`\`
+
+Then configure in \`src/index.ts\`:
+
+\`\`\`ts
+import { AuthAdapter, JwtStrategy } from '@forinda/kickjs-auth'
+
+bootstrap({
+  modules,
+  adapters: [
+    AuthAdapter({
+      strategies: [JwtStrategy({ secret: process.env.JWT_SECRET! })],
+    }),
+  ],
+})
+\`\`\`
+
+### Add Database (Prisma)
+
+\`\`\`bash
+kick add prisma
+${pm} install prisma @prisma/client
+npx prisma init
+# Edit prisma/schema.prisma
+npx prisma migrate dev --name init
+kick g module user --repo prisma
+\`\`\`
+
+### Add WebSocket Support
+
+\`\`\`bash
+kick add ws
+\`\`\`
+
+Then add adapter in \`src/index.ts\`:
+
+\`\`\`ts
+import { WsAdapter } from '@forinda/kickjs-ws'
+
+bootstrap({
+  modules,
+  adapters: [WsAdapter()],
+})
+\`\`\`
+
+Create WebSocket controller:
+
+\`\`\`bash
+kick g controller chat --ws
+\`\`\`
+
+## Testing Guidelines
+
+All tests use Vitest:
+
+\`\`\`ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Container } from '@forinda/kickjs'
+import { createTestApp } from '@forinda/kickjs-testing'
+
+describe('UserController', () => {
+  it('should return users', async () => {
+    // Container.create() — isolated DI state per test, never new Container()
+    // and never getInstance().reset() (both leak registrations between tests).
+    const container = Container.create()
+    const app = await createTestApp([UserModule], { container })
+    const res = await app.get('/users')
+
+    expect(res.status).toBe(200)
+    expect(res.body).toHaveProperty('users')
+  })
+})
+\`\`\`
+
+Run tests:
+- \`${pm} run test\` — run all tests once
+- \`${pm} run test:watch\` — watch mode
+- Individual file: \`${pm} run test src/modules/user/user.test.ts\`
+
+## Environment Variables
+
+Schema is declared in \`src/config/index.ts\` (extends the base
+\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` shape via \`defineEnv\`) and registered
+with kickjs at module load. \`src/index.ts\` imports it via
+\`import './config'\` **before** \`bootstrap()\` so the cache is populated
+in time for DI. Add new keys to the schema, drop their values into
+\`.env\`, and they're typed everywhere.
+
+Access patterns:
+
+1. **@Value() decorator** (recommended for known-at-construction keys):
+\`\`\`ts
+@Value('DATABASE_URL')
+private dbUrl!: string
+\`\`\`
+
+2. **ConfigService** (recommended for dynamic / method-scoped access):
+\`\`\`ts
+@Autowired()
+private config!: ConfigService
+
+const port = this.config.get('PORT')  // typed: number
+\`\`\`
+
+3. **Standalone utilities** (no DI — works in scripts, CLI, plain files):
+\`\`\`ts
+import { loadEnv, getEnv, reloadEnv, resetEnvCache } from '@forinda/kickjs/config'
+
+const env = loadEnv(schema)         // Parse + validate all vars
+const port = getEnv('PORT')         // Single value lookup
+reloadEnv()                         // Re-read .env from disk
+resetEnvCache()                     // Full reset (for tests)
+\`\`\`
+
+4. **Direct \`process.env\`** — avoid in app code; bypasses Zod
+   coercion and the typed \`KickEnv\` registry.
+
+> **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
+> If the schema is not registered before DI runs, \`config.get()\`
+> returns \`undefined\` for user keys (the base shape only) and
+> \`@Value()\` only works because of its raw \`process.env\` fallback —
+> Zod coercion + schema defaults are silently skipped.
+
+## Standalone Utilities (No DI Required)
+
+These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller\`:
+
+| Utility | Import | Example |
+|---------|--------|---------|
+| \`Logger.for(name)\` | \`@forinda/kickjs\` | \`const log = Logger.for('MyScript')\` |
+| \`createLogger(name)\` | \`@forinda/kickjs\` | \`const log = createLogger('Worker')\` |
+| \`createToken<T>(name)\` | \`@forinda/kickjs\` | \`const TOKEN = createToken<string>('app/db/url')\` |
+| \`ref(value)\` | \`@forinda/kickjs\` | \`const count = ref(0)\` |
+| \`computed(fn)\` | \`@forinda/kickjs\` | \`const doubled = computed(() => count.value * 2)\` |
+| \`watch(source, cb)\` | \`@forinda/kickjs\` | \`watch(() => count.value, (v) => log(v))\` |
+| \`reactive(obj)\` | \`@forinda/kickjs\` | \`const state = reactive({ count: 0 })\` |
+| \`HttpException\` | \`@forinda/kickjs\` | \`throw new HttpException(404, 'Not found')\` |
+| \`HttpStatus\` | \`@forinda/kickjs\` | \`HttpStatus.NOT_FOUND // 404\` |
+
+## Key Decorators
+
+### HTTP Routes
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Controller()\` | Define route prefix |
+| \`@Get('/'), @Post('/')\` | HTTP method handlers |
+| \`@Middleware(fn)\` | Attach middleware |
+| \`@Public()\` | Skip auth (requires auth adapter) |
+| \`@Roles('admin')\` | Role-based access |
+
+### Dependency Injection
+| Decorator | Purpose |
+|-----------|---------|
+| \`AppModule\` interface | Define feature module (implements \`routes()\`) |
+| \`@Service()\` | Register singleton service |
+| \`@Repository()\` | Register repository |
+| \`@Autowired()\` | Property injection |
+| \`@Inject('token')\` | Token-based injection |
+| \`@Value('VAR')\` | Inject env variable |
+
+### Context Decorators
+
+Typed, ordered way to populate \`ctx.set/get\` keys before the handler runs.
+Use this **instead of \`@Middleware()\`** when the middleware's only output
+is a value other code reads off \`ctx\`.
+
+| Concept | Where it lives |
+|---------|----------------|
+| \`defineContextDecorator({ key, deps, dependsOn, optional, onError, resolve })\` | \`@forinda/kickjs\` |
+| Method/class decorator | \`@LoadX\` on a controller method/class |
+| Module hook | \`AppModule.contributors?(): ContributorRegistration[]\` |
+| Adapter hook | \`AppAdapter.contributors?(): ContributorRegistration[]\` |
+| Global registration | \`bootstrap({ contributors: [LoadX.registration] })\` |
+| Type augmentation | \`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\` |
+
+Precedence high → low: **method > class > module > adapter > global**.
+Cycles and missing \`dependsOn\` keys throw at \`app.setup()\` (boot fails
+fast). The \`onError\` hook is async-permitted.
+
+Full guide: <https://forinda.github.io/kick-js/guide/context-decorators>.
+
+${template === "cqrs" ? `### Background Jobs
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Job('name')\` | Queue job handler |
+| \`@Process('queue')\` | Queue processor |
+| \`@Cron('0 * * * *')\` | Cron schedule |
+| \`@WsController()\` | WebSocket controller |
+
+` : ""}## Common Pitfalls
+
+1. **Forgot to register module** — Add to \`src/modules/index.ts\` exports array
+2. **DI not working** — Ensure \`reflect-metadata\` is imported in \`src/index.ts\`
+3. **Tests failing randomly** — Sharing the global container between tests. Default to \`Container.create()\` per test (or per \`beforeEach\`) instead of \`new Container()\` / \`getInstance().reset()\`
+4. **Routes not found** — Check controller path and module registration
+5. **HMR not working** — Two checks: (a) \`vite.config.ts\` has \`hmr: true\`; (b) module file is named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and lives under \`src/modules/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed module file (e.g., \`projects.ts\`) silently degrades to a full restart on every save.
+6. **Decorators not working** — Check \`tsconfig.json\` has \`experimentalDecorators: true\`
+7. **\`config.get('YOUR_KEY')\` returns \`undefined\`** — \`src/index.ts\` is missing \`import './config'\`. That side-effect import registers the env schema with kickjs (\`loadEnv(envSchema)\` runs at module load). Without it, \`ConfigService\` falls back to the base schema (\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` only) and every user-defined key reads as \`undefined\`. \`@Value()\` may *appear* to work because of a raw \`process.env\` fallback, but Zod coercion and schema defaults are silently skipped — investigate \`src/index.ts\` and \`src/config/index.ts\` first.
+8. **Used \`@Middleware()\` to compute a value for \`ctx\`** — prefer \`defineContextDecorator()\` (see Context Decorators above). It's typed via \`ContextMeta\`, supports \`dependsOn\` for ordering, and validates the pipeline at boot. \`@Middleware()\` is for response short-circuiting, stream mutation, and pre-route-matching work.
+9. **Context contributor's \`dependsOn\` key not produced anywhere** — boot throws \`MissingContributorError\` naming the dependent and the route. Either remove the dep or register a contributor that produces the key (at any precedence level: method/class/module/adapter/global).
+10. **\`bootstrap()\` not exported** — \`src/index.ts\` calls \`await bootstrap({ ... })\` but discards the return value (no \`export const app = ...\`). Vite HMR can't locate the running instance, so module saves degrade to full restarts; \`createTestApp\`/\`@forinda/kickjs-testing\` consumers can't import the handle either. Always: \`export const app = await bootstrap({ ... })\`.
+11. **Refresh AGENTS.md / CLAUDE.md after a framework upgrade** — these files are scaffolded by the CLI and don't auto-update. Run \`kick g agents -f\` (or \`kick g agent-docs -f\`) to regenerate from the latest CLI templates after \`kick add\` / version bumps. Hand-edited sections will be overwritten — keep customisation in a separate file like \`AGENTS.local.md\`.
+
+## CLI Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| \`kick dev\` | Dev server with HMR |
+| \`kick dev:debug\` | Dev server with debugger |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`kick g module <names...>\` | Generate one or more modules |
+| \`kick g scaffold <name> <fields>\` | Generate CRUD |
+| \`kick g controller <name>\` | Generate controller |
+| \`kick g service <name>\` | Generate service |
+| \`kick g middleware <name>\` | Generate middleware |
+| \`kick add <package>\` | Add KickJS package |
+| \`kick add --list\` | List available packages |
+| \`kick rm module <names...>\` | Remove one or more modules |
+
+> **Note:** When using \`kick new\` in scripts or CI, pass \`-t\` (or \`--template\`) and \`-r\` (or \`--repo\`) flags to bypass interactive prompts:
+> \`\`\`bash
+> kick new my-api -t ddd -r prisma --pm ${pm} --no-git --no-install -f
+> \`\`\`
+
+## Learn More
+
+- [KickJS Docs](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
+- [DI System](https://forinda.github.io/kick-js/guide/dependency-injection.html)
+- [Testing](https://forinda.github.io/kick-js/api/testing.html)
+`;
+}
+/**
+* Generate `kickjs-skills.md` — task-oriented "skill" recipes for AI
+* agents (Claude superpowers, Copilot, etc.). Where AGENTS.md is the
+* narrative reference, this file lists short, rigid workflows the agent
+* should follow when it sees the corresponding trigger.
+*/
+function generateKickJsSkills(name, _template, pm) {
+	return `# kickjs-skills.md — Task Skills for AI Agents (${name})
+
+This file is the agent-facing **skills index** for KickJS work in this
+repo. Each block below is a short, rigid workflow keyed to a specific
+trigger ("user wants to add a module", "tests are leaking state", etc.).
+
+- Reference docs (narrative, exhaustive) → \`AGENTS.md\`.
+- Tool-specific notes → \`CLAUDE.md\`, \`GEMINI.md\`, etc.
+- **This file** → step-by-step recipes the agent should *execute*.
+
+Re-run \`kick g agents -f --only skills\` after framework upgrades to refresh.
+
+---
+
+## Skill: add-module
+
+\`\`\`yaml
+name: kickjs-add-module
+description: Use when the user asks to add a new feature module (controller + service + repo + DTOs).
+\`\`\`
+
+**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
+
+**Steps**:
+1. Run \`kick g module <name>\` (use plural form if the project pluralizes — check \`kick.config.ts\`).
+2. Verify the new folder under \`src/modules/<name>/\` contains \`<name>.module.ts\` (filename suffix is mandatory for HMR).
+3. Confirm the module appears in \`src/modules/index.ts\` exports — generator does this automatically; verify if you bypassed it.
+4. Open \`<name>.dto.ts\` and tighten the Zod schemas to real fields (the generator emits placeholders).
+5. Run \`${pm} run typecheck\` and \`${pm} run test\` before claiming done.
+
+**Red flags** (stop and ask):
+- File created as \`<name>.ts\` instead of \`<name>.module.ts\` — Vite won't HMR it.
+- Module not registered in \`src/modules/index.ts\`.
+- \`@Controller('/path')\` with a path argument — that's a v3 pattern; remove it (mount comes from \`routes().path\`).
+
+---
+
+## Skill: add-adapter
+
+\`\`\`yaml
+name: kickjs-add-adapter
+description: Use when wiring a new lifecycle integration (Swagger, DevTools, Auth, custom).
+\`\`\`
+
+**Steps**:
+1. \`kick g adapter <name>\` to scaffold the boilerplate, OR install via \`kick add <package>\` for first-party adapters.
+2. The generated file uses \`defineAdapter()\` — never \`class implements AppAdapter\`.
+3. Add the adapter instance to \`src/adapters/index.ts\` (don't inline in \`src/index.ts\`).
+4. If the adapter contributes to \`ctx.set/get\`, prefer \`AppAdapter.contributors?()\` over a wrapping middleware.
+5. Verify with \`kick dev\` that the adapter's lifecycle logs fire.
+
+**Red flags**:
+- Inlining the adapter list directly in \`src/index.ts\` (entry file should stay thin).
+- Returning a plain object instead of going through \`defineAdapter()\` — type inference for \`config\` will be wrong.
+
+---
+
+## Skill: write-controller-test
+
+\`\`\`yaml
+name: kickjs-write-controller-test
+description: Use when adding a Vitest test that exercises an HTTP route or DI graph.
+\`\`\`
+
+**Template** (copy/paste, adjust):
+
+\`\`\`ts
+import { describe, it, expect } from 'vitest'
+import { Container } from '@forinda/kickjs'
+import { createTestApp } from '@forinda/kickjs-testing'
+
+describe('UserController', () => {
+  it('returns users', async () => {
+    const container = Container.create()           // isolated DI per test
+    const app = await createTestApp([UserModule], { container })
+    const res = await app.get('/users')
+    expect(res.status).toBe(200)
+  })
+})
+\`\`\`
+
+**Red flags**:
+- \`new Container()\` — wrong; use \`Container.create()\`.
+- \`Container.getInstance().reset()\` — wrong; same fix.
+- Sharing a container across \`it()\` blocks — leaks registrations.
+
+---
+
+## Skill: env-wiring-check
+
+\`\`\`yaml
+name: kickjs-env-wiring-check
+description: Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.
+\`\`\`
+
+**Diagnosis**:
+1. Open \`src/index.ts\`. The **first non-\`reflect-metadata\`** import MUST be \`import './config'\`.
+2. Open \`src/config/index.ts\`. It MUST call \`loadEnv(envSchema)\` as a top-level side effect.
+3. The new key MUST be declared in the Zod schema there. \`@Value('NEW_KEY')\` won't work without a schema entry (it'll fall back to raw \`process.env\` and skip Zod coercion silently).
+
+**Fix**: add the key to the schema; ensure both side-effect imports above are present.
+
+---
+
+## Skill: bootstrap-export
+
+\`\`\`yaml
+name: kickjs-bootstrap-export
+description: Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.
+\`\`\`
+
+**Check** \`src/index.ts\`'s last line:
+
+\`\`\`ts
+// CORRECT
+export const app = await bootstrap({ ... })
+
+// WRONG (HMR degrades to full restart, createTestApp loses the handle)
+await bootstrap({ ... })
+\`\`\`
+
+The Vite plugin imports the named \`app\` symbol; testing helpers do too.
+
+---
+
+## Skill: thin-entry-file
+
+\`\`\`yaml
+name: kickjs-thin-entry-file
+description: Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.
+\`\`\`
+
+**Refactor target**:
+
+\`\`\`ts
+// src/modules/index.ts
+export const modules: AppModuleClass[] = [HelloModule, UsersModule, ...]
+
+// src/middleware/index.ts
+export const middleware = [helmet(), cors(), requestId(), ...]
+
+// src/plugins/index.ts
+export const plugins = [MetricsPlugin(), ...]
+
+// src/adapters/index.ts
+export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
+
+// src/index.ts — stays small
+import 'reflect-metadata'
+import './config'
+import { bootstrap } from '@forinda/kickjs'
+import { modules } from './modules'
+import { middleware } from './middleware'
+import { plugins } from './plugins'
+import { adapters } from './adapters'
+export const app = await bootstrap({ modules, middleware, plugins, adapters })
+\`\`\`
+
+**Red flags**: any \`new SomeAdapter()\` or \`SomePlugin()\` literal inside \`bootstrap({ ... })\` instead of imported from a category folder.
+
+---
+
+## Skill: context-contributor
+
+\`\`\`yaml
+name: kickjs-context-contributor
+description: Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).
+\`\`\`
+
+**Pattern** (HTTP — most common):
+
+\`\`\`ts
+import { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'
+
+const LoadTenant = defineHttpContextDecorator({
+  key: 'tenant',
+  deps: { repo: TENANT_REPO },
+  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),
+})
+
+const LoadProject = defineHttpContextDecorator({
+  key: 'project',
+  dependsOn: ['tenant'],
+  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),
+})
+
+@LoadTenant
+@LoadProject
+@Get('/projects/:id')
+getProject(ctx: RequestContext) { ctx.json(ctx.get('project')) }
+\`\`\`
+
+Use \`defineContextDecorator\` (no Http prefix) when authoring a contributor that must run across HTTP, WebSocket, queue, and cron transports — \`Ctx\` defaults to the smaller \`ExecutionContext\` surface (\`get\` / \`set\` / \`requestId\` only, no \`req\`).
+
+Precedence high → low: **method > class > module > adapter > global**.
+Cycles or unmet \`dependsOn\` keys throw \`MissingContributorError\` at boot.
+
+**Critical rules — all stem from the same shared-via-ALS instance model**:
+- Every per-request stage (middleware → contributors → handler) gets its OWN \`RequestContext\` instance, but they all read/write the SAME \`AsyncLocalStorage\`-backed bag.
+- **\`resolve\` and \`onError\` must RETURN the value** — the runner writes it via \`ctx.set(key, value)\`. Direct property assignment (\`ctx.tenant = …\`) sticks to one instance only and the handler instance never sees it.
+- \`ctx.set('tenant', x)\` then \`ctx.get('tenant')\` works across instances. \`ctx.req.headers[...]\` works (the underlying Express request is shared).
+- Services with no \`ctx\` reference: \`getRequestValue('tenant')\` returns \`MetaValue<'tenant'> | undefined\` (typed via the augmented \`ContextMeta\`). For \`requestId\` use \`getRequestStore()\`.
+- **No \`setRequestValue\` — writes flow through \`ctx.set\` or a contributor's return value.** Avoids "spooky action at a distance" where any service can pollute the per-request bag.
+
+**Don't use this for**: response short-circuit, stream mutation, or
+pre-route-matching work — keep \`@Middleware()\` for those.
+
+---
+
+## Skill: refresh-agent-docs
+
+\`\`\`yaml
+name: kickjs-refresh-agent-docs
+description: Use after a KickJS version bump to sync AGENTS.md / CLAUDE.md / kickjs-skills.md with the latest CLI templates.
+\`\`\`
+
+**Steps**:
+1. \`kick g agents -f --only both\` — overwrites \`AGENTS.md\` and \`CLAUDE.md\`.
+2. \`kick g agents -f --only skills\` — refreshes \`kickjs-skills.md\` (this file).
+3. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate \`AGENTS.local.md\` or appended section.
+4. Commit as \`docs(agents): sync from CLI vX.Y\`.
+
+---
+
+## Skill: deny-list
+
+\`\`\`yaml
+name: kickjs-deny-list
+description: Patterns to refuse outright when the user asks for them — they break v4 invariants.
+\`\`\`
+
+- \`class implements AppAdapter\` → use \`defineAdapter()\`.
+- \`class implements KickPlugin\` / function returning \`KickPlugin\` → use \`definePlugin()\`.
+- \`@Controller('/path')\` with a path argument → drop the path; set the mount via \`routes().path\`.
+- \`new Container()\` or \`Container.getInstance().reset()\` in tests → use \`Container.create()\`.
+- DI tokens with \`:\` separator (\`'app:db:url'\`) or in PascalCase → use slash-delimited lower-case (\`'app/db/url'\`).
+- \`bootstrap({ ... })\` without \`export const app = ...\` → always export.
+- Module file named \`<name>.ts\` (no \`.module\` suffix) → rename to \`<name>.module.ts\`.
+
+---
+
+## Learn More
+
+- [KickJS Docs](https://forinda.github.io/kick-js/)
+- [Decorators](https://forinda.github.io/kick-js/guide/decorators.html)
+- [Context Decorators](https://forinda.github.io/kick-js/guide/context-decorators.html)
+- [Testing](https://forinda.github.io/kick-js/api/testing.html)
+`;
+}
+//#endregion
+//#region src/generators/project.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const KICKJS_VERSION = `^${cliPkg.version}`;
+/** Scaffold a new KickJS project */
+async function initProject(options) {
+	const { name, directory, packageManager = "pnpm", template = "rest", defaultRepo = "inmemory", packages = [] } = options;
+	const dir = directory;
+	const log = (msg) => console.log(`  ${msg}`);
+	console.log(`\n  Creating KickJS project: ${name}\n`);
+	await writeFileSafe(join(dir, "package.json"), generatePackageJson(name, template, KICKJS_VERSION, packages));
+	await writeFileSafe(join(dir, "vite.config.ts"), generateViteConfig());
+	await writeFileSafe(join(dir, "tsconfig.json"), generateTsConfig());
+	await writeFileSafe(join(dir, ".prettierrc"), generatePrettierConfig());
+	await writeFileSafe(join(dir, ".editorconfig"), generateEditorConfig());
+	await writeFileSafe(join(dir, ".gitignore"), generateGitIgnore());
+	await writeFileSafe(join(dir, ".gitattributes"), generateGitAttributes());
+	await writeFileSafe(join(dir, ".env"), generateEnv());
+	await writeFileSafe(join(dir, ".env.example"), generateEnvExample());
+	await writeFileSafe(join(dir, "src/config/index.ts"), generateEnvFile());
+	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version, packages));
+	await writeFileSafe(join(dir, "src/modules/index.ts"), generateModulesIndex());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.controller.ts"), generateHelloController());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.module.ts"), generateHelloModule());
+	await writeFileSafe(join(dir, "kick.config.ts"), generateKickConfig(template, defaultRepo, packageManager));
+	await writeFileSafe(join(dir, "vitest.config.ts"), generateVitestConfig());
+	await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
+	await writeFileSafe(join(dir, "CLAUDE.md"), generateClaude(name, template, packageManager));
+	await writeFileSafe(join(dir, "AGENTS.md"), generateAgents(name, template, packageManager));
+	await writeFileSafe(join(dir, "kickjs-skills.md"), generateKickJsSkills(name, template, packageManager));
+	if (options.installDeps) {
+		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
+		try {
+			execSync(`${packageManager} install`, {
+				cwd: dir,
+				stdio: "inherit"
+			});
+			console.log("\n  Dependencies installed successfully!");
+		} catch {
+			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
+		}
+	}
+	try {
+		const { runTypegen } = await import("./typegen-DugZmi-0.mjs").then((n) => n.n);
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
+	if (options.initGit) try {
+		execSync("git init", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git branch -M main", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git add -A", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git commit -m \"chore: initial commit from kick new\"", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		log("Git repository initialized");
+	} catch {
+		log("Warning: git init failed (git may not be installed)");
+	}
+	console.log("\n  Project scaffolded successfully!");
+	console.log();
+	const needsCd = dir !== process.cwd();
+	log("Next steps:");
+	if (needsCd) log(`  cd ${name}`);
+	if (!options.installDeps) log(`  ${packageManager} install`);
+	const genHint = {
+		rest: "kick g module user",
+		ddd: "kick g module user --repo drizzle",
+		cqrs: "kick g module user --pattern cqrs",
+		minimal: "# add your routes to src/index.ts"
+	};
+	log(`  ${genHint[template] ?? genHint.rest}`);
+	log("  kick dev");
+	log("");
+	log("Commands:");
+	log("  kick dev                  Start dev server with Vite HMR");
+	log("  kick build                Production build via Vite");
+	log("  kick start                Run production build");
+	log("");
+	log("Generators:");
+	log("  kick g module <name>      Full DDD module (controller, DTOs, use-cases, repo)");
+	log("  kick g scaffold <n> <f..> CRUD module from field definitions");
+	log("  kick g controller <name>  Standalone controller");
+	log("  kick g service <name>     @Service() class");
+	log("  kick g middleware <name>   Express middleware");
+	log("  kick g guard <name>       Route guard (auth, roles, etc.)");
+	log("  kick g adapter <name>     AppAdapter with lifecycle hooks");
+	log("  kick g dto <name>         Zod DTO schema");
+	if (template === "cqrs") log("  kick g job <name>         Queue job processor");
+	log("  kick g config             Generate kick.config.ts");
+	log("");
+	log("Add packages:");
+	log("  kick add <pkg>            Install a KickJS package + peers");
+	log("  kick add --list           Show all available packages");
+	log("");
+	log("Available: auth, swagger, drizzle, prisma, ws, queue, devtools, mcp, testing");
+	log("");
+}
+//#endregion
+//#region src/generator-extension/define.ts
+/**
+* Identity factory — returns the spec verbatim. Exists for type
+* inference and forward-compatibility (future fields can be added with
+* defaults).
+*
+* @example
+* ```ts
+* import { defineGenerator } from '@forinda/kickjs-cli'
+*
+* export default [
+*   defineGenerator({
+*     name: 'command',
+*     description: 'Generate a CQRS command + handler',
+*     files: (ctx) => [
+*       {
+*         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,
+*         content: `// command for ${ctx.pascal}`,
+*       },
+*     ],
+*   }),
+* ]
+* ```
+*/
+function defineGenerator(spec) {
+	return spec;
+}
+//#endregion
+//#region src/generator-extension/context.ts
+/** Convert any string to snake_case (`UserPost` / `user-post` → `user_post`). */
+function toSnakeCase(name) {
+	return toKebabCase(name).replace(/-/g, "_");
+}
+/**
+* Build a {@link GeneratorContext} from the raw name + invocation
+* arguments. Centralises the case-transformation logic so every plugin
+* generator sees the same shape regardless of how the name was typed
+* on the command line (`Post` vs `post` vs `user_post`).
+*/
+function buildGeneratorContext(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const usePlural = input.pluralize ?? true;
+	const pascal = toPascalCase(input.name);
+	const camel = toCamelCase(input.name);
+	const kebab = toKebabCase(input.name);
+	const snake = toSnakeCase(input.name);
+	const ctx = {
+		name: input.name,
+		pascal,
+		camel,
+		kebab,
+		snake,
+		modulesDir: input.modulesDir ?? "src/modules",
+		cwd,
+		args: input.args ?? [],
+		flags: input.flags ?? {}
+	};
+	if (usePlural) {
+		const pluralKebab = pluralize(kebab);
+		ctx.pluralKebab = pluralKebab;
+		ctx.pluralPascal = toPascalCase(pluralKebab);
+		ctx.pluralCamel = toCamelCase(pluralKebab);
+	}
+	return ctx;
+}
+/** Resolve a generator output path against the context's cwd. */
+function resolveGeneratorPath(ctx, path) {
+	return resolve(ctx.cwd, path);
+}
+/**
+* Dynamic-import a generator manifest file. Wraps `pathToFileURL` so
+* callers don't have to think about Windows/Unix path quirks.
+*/
+async function importManifest(absPath) {
+	return import(pathToFileURL(absPath).href);
+}
+//#endregion
+//#region src/generator-extension/discover.ts
+/**
+* Discover generator manifests shipped by every kickjs plugin in the
+* project's direct deps. Spec rationale: walking the
+* `node_modules/@scope/kickjs-name/` tree is one option, but reading
+* the project's own `package.json` and resolving each dep through
+* Node's module resolver gives:
+*
+*   1. Predictable scoping — only deps the project actually declared
+*      get scanned, no surprises from transitive packages
+*   2. pnpm `.pnpm` store compatibility — `createRequire().resolve()`
+*      handles the symlinked layout correctly
+*   3. Clear error attribution — the source package name is always
+*      known before the import happens
+*
+* The walk is shallow (direct deps only). Transitive plugins that want
+* to expose generators must be re-exported by a direct dep.
+*
+* Caches per-cwd inside one CLI invocation so a single `kick g` call
+* does the disk + import work exactly once even when multiple
+* generators dispatch through the same registry.
+*/
+const cache = /* @__PURE__ */ new Map();
+async function discoverPluginGenerators(cwd) {
+	const cached = cache.get(cwd);
+	if (cached) return cached;
+	const promise = doDiscover(cwd);
+	cache.set(cwd, promise);
+	return promise;
+}
+async function doDiscover(cwd) {
+	const projectPkgPath = resolve(cwd, "package.json");
+	if (!existsSync(projectPkgPath)) return {
+		generators: [],
+		loaded: [],
+		failed: []
+	};
+	const depNames = collectDepNames(JSON.parse(await readFile(projectPkgPath, "utf-8")));
+	const require = createRequire(resolve(cwd, "package.json"));
+	const generators = [];
+	const loaded = [];
+	const failed = [];
+	for (const depName of depNames) {
+		let depPkgPath;
+		try {
+			depPkgPath = require.resolve(`${depName}/package.json`);
+		} catch {
+			continue;
+		}
+		let depPkg;
+		try {
+			depPkg = JSON.parse(await readFile(depPkgPath, "utf-8"));
+		} catch (err) {
+			failed.push({
+				source: depName,
+				reason: `failed to parse package.json: ${err}`
+			});
+			continue;
+		}
+		if (!depPkg.kickjs?.generators) continue;
+		const entryRel = depPkg.kickjs.generators;
+		const entryAbs = resolve(dirname(depPkgPath), entryRel);
+		if (!existsSync(entryAbs)) {
+			failed.push({
+				source: depName,
+				reason: `kickjs.generators points to missing file: ${entryRel}`
+			});
+			continue;
+		}
+		let mod;
+		try {
+			mod = await importManifest(entryAbs);
+		} catch (err) {
+			failed.push({
+				source: depName,
+				reason: `failed to import manifest: ${err}`
+			});
+			continue;
+		}
+		const manifest = mod.default;
+		if (!Array.isArray(manifest)) {
+			failed.push({
+				source: depName,
+				reason: `manifest's default export is not an array of GeneratorSpec`
+			});
+			continue;
+		}
+		for (const entry of manifest) {
+			if (!isGeneratorSpec(entry)) {
+				failed.push({
+					source: depName,
+					reason: `manifest entry is not a valid GeneratorSpec (missing name/files)`
+				});
+				continue;
+			}
+			generators.push({
+				source: depName,
+				spec: entry
+			});
+		}
+		loaded.push(depName);
+	}
+	return {
+		generators,
+		loaded,
+		failed
+	};
+}
+function collectDepNames(pkg) {
+	const set = /* @__PURE__ */ new Set();
+	for (const block of [
+		pkg.dependencies,
+		pkg.devDependencies,
+		pkg.peerDependencies
+	]) {
+		if (!block) continue;
+		for (const name of Object.keys(block)) set.add(name);
+	}
+	return Array.from(set);
+}
+function isGeneratorSpec(entry) {
+	if (!entry || typeof entry !== "object") return false;
+	const e = entry;
+	return typeof e.name === "string" && typeof e.files === "function";
+}
+//#endregion
+//#region src/generator-extension/dispatch.ts
+/**
+* Look up a plugin generator by name and run it. Returns `null` when
+* no plugin generator matches — callers can then fall through to the
+* built-in dispatch (module / scaffold / etc.).
+*
+* Resolution order:
+*   1. `additional` — generators sourced from `KickCliPlugin.generators`
+*      via `kick.config.ts > plugins[]`. Authoritative; the canonical
+*      path going forward.
+*   2. `package.json > kickjs.generators` discovery — first-match-wins
+*      in dependency declaration order. Deprecated path retained for
+*      packages that haven't migrated yet.
+*
+* Adopters with conflicts should rename the generator on their side or
+* pin one of the plugins to a different version.
+*/
+async function tryDispatchPluginGenerator(input, additional = []) {
+	const cwd = input.cwd ?? process.cwd();
+	const fromConfig = additional.find((g) => g.spec.name === input.generatorName);
+	if (fromConfig) return runGenerator(fromConfig.spec, fromConfig.source, input, cwd);
+	const match = findGenerator(await discoverPluginGenerators(cwd), input.generatorName);
+	if (!match) return null;
+	return runGenerator(match.spec, match.source, input, cwd);
+}
+/**
+* Public helper for `kick g --list` — returns every plugin generator
+* the CLI knows about, merging config-supplied entries on top of the
+* package.json discovery result. Config entries always come first.
+*/
+async function listPluginGenerators(cwd, additional = []) {
+	const discovered = await discoverPluginGenerators(cwd);
+	const configNames = new Set(additional.map((g) => g.spec.name));
+	const filteredDiscovered = discovered.generators.filter((g) => !configNames.has(g.spec.name));
+	return {
+		generators: [...additional, ...filteredDiscovered],
+		loaded: discovered.loaded,
+		failed: discovered.failed
+	};
+}
+function findGenerator(discovery, name) {
+	return discovery.generators.find((g) => g.spec.name === name);
+}
+async function runGenerator(spec, source, input, cwd) {
+	const ctx = buildGeneratorContext({
+		name: input.itemName,
+		args: input.args,
+		flags: input.flags,
+		modulesDir: input.modulesDir,
+		pluralize: input.pluralize,
+		cwd
+	});
+	const files = await spec.files(ctx);
+	const written = [];
+	for (const file of files) {
+		const absPath = resolveGeneratorPath(ctx, file.path);
+		await writeFileSafe(absPath, file.content);
+		written.push(absPath);
+	}
+	return {
+		files: written,
+		source
+	};
+}
+//#endregion
+export { httpMethodColor as A, intro as C, select as D, outro as E, writeFileSafe as F, severityColor as M, fileExists as N, spinner as O, setDryRun as P, confirm as S, multiSelect as T, pluralize as _, initProject as a, toKebabCase as b, generateKickJsSkills as c, generateService as d, generateGuard as f, resolveRepoType as g, generateModule as h, defineGenerator as i, pc as j, text as k, generateDto as l, generateAdapter as m, tryDispatchPluginGenerator as n, generateAgents as o, generateMiddleware as p, buildGeneratorContext as r, generateClaude as s, listPluginGenerators as t, generateController as u, pluralizePascal as v, log as w, toPascalCase as x, toCamelCase as y };
+
+//# sourceMappingURL=generator-extension-DRNQpoZP.mjs.map