@forinda/kickjs-cli 3.2.0 → 4.1.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.2.0
+ * @forinda/kickjs-cli v4.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,18 +8,68 @@
  *
  * @license MIT
  */
-import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 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 { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-/** Write a file, creating parent directories if needed. Skips writing in dry run mode. */
+/** Extensions prettier 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 prettier against the file when:
+*   - format-on-write is enabled (default)
+*   - the extension is in {@link FORMATTABLE}
+*   - prettier resolves from the user's project (or our own cwd)
+*
+* Failures (missing prettier, unparseable source, prettier crash) are
+* swallowed silently — formatting is a polish step, not a correctness
+* gate. The pre-existing pre-commit hook still catches anything we
+* couldn't format.
+*
+* Skips writing entirely in dry run mode.
+*/
 async function writeFileSafe(filePath, content) {
 	await mkdir(dirname(filePath), { recursive: true });
 	await writeFile(filePath, content, "utf-8");
+	if (FORMATTABLE.has(extname(filePath))) await formatFile(filePath, content).catch(() => {});
+}
+let _prettier = void 0;
+/** Resolve prettier from the user's project; cache the result (or null) for the process. */
+function resolvePrettier(cwd) {
+	if (_prettier !== void 0) return _prettier;
+	try {
+		_prettier = createRequire(join(cwd, "package.json"))("prettier");
+	} catch {
+		_prettier = null;
+	}
+	return _prettier;
+}
+async function formatFile(filePath, content) {
+	const prettier = resolvePrettier(process.cwd());
+	if (!prettier) return;
+	if ((await prettier.getFileInfo(filePath, { resolveConfig: true })).ignored) return;
+	const config = await prettier.resolveConfig(filePath) ?? {};
+	const formatted = await prettier.format(content, {
+		...config,
+		filepath: filePath
+	});
+	if (formatted === content) return;
+	await writeFile(filePath, formatted, "utf-8");
 }
 /** Check if a file exists */
 async function fileExists(filePath) {
@@ -551,7 +601,7 @@ export interface I${pascal}Repository {
  * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
  * interface — no manual generic, no \`any\` cast.
  */
-export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${pascal}/Repository')
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('app/${kebab}/repository')
 `;
 }
 function generateInMemoryRepository(ctx) {
@@ -1543,15 +1593,15 @@ function generateEntryFile(name, template, version, packages = []) {
 			const gqlAdapters = [];
 			if (packages.includes("devtools")) {
 				gqlImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				gqlAdapters.push(`    new DevToolsAdapter(),`);
+				gqlAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				gqlImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				gqlAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				gqlAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("swagger")) {
 				gqlImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				gqlAdapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				gqlAdapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -1584,15 +1634,15 @@ ${gqlAdapters.length ? gqlAdapters.join("\n") + "\n" : ""}    new GraphQLAdapter
 			const cqrsAdapters = [];
 			if (packages.includes("otel")) {
 				cqrsImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				cqrsAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				cqrsAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("devtools")) {
 				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				cqrsAdapters.push(`    new DevToolsAdapter(),`);
+				cqrsAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				cqrsAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("graphql")) {
 				cqrsImports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -1611,7 +1661,7 @@ ${cqrsImports.length ? cqrsImports.join("\n") + "\n" : ""}import { modules } fro
 
 // 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    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // new WsAdapter(),\n    // Uncomment when Redis is available:\n    // new QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
+  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  ],`}
 })
 `;
 		}
@@ -1620,15 +1670,15 @@ export const app = await bootstrap({
 			const adapters = [];
 			if (packages.includes("swagger")) {
 				imports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				adapters.push(`    new SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
+				adapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
 			}
 			if (packages.includes("devtools")) {
 				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				adapters.push(`    new DevToolsAdapter(),`);
+				adapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("otel")) {
 				imports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				adapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				adapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			if (packages.includes("graphql")) {
 				imports.push(`import { GraphQLAdapter } from '@forinda/kickjs-graphql'`);
@@ -1652,15 +1702,15 @@ export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters:
 			const restAdapters = [];
 			if (packages.includes("devtools")) {
 				restImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				restAdapters.push(`    new DevToolsAdapter(),`);
+				restAdapters.push(`    DevToolsAdapter(),`);
 			}
 			if (packages.includes("swagger")) {
 				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				restAdapters.push(`    new SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
+				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
 			}
 			if (packages.includes("otel")) {
 				restImports.push(`import { OtelAdapter } from '@forinda/kickjs-otel'`);
-				restAdapters.push(`    new OtelAdapter({ serviceName: '${name}' }),`);
+				restAdapters.push(`    OtelAdapter({ serviceName: '${name}' }),`);
 			}
 			return `import 'reflect-metadata'
 // Side-effect import — registers the extended env schema with kickjs
@@ -2311,97 +2361,114 @@ export const modules: AppModuleClass[] = [${pascal}Module]
 }
 //#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 type { AppAdapter, AdapterContext, AdapterMiddleware } from '@forinda/kickjs'
+	await writeFileSafe(filePath, `import { defineAdapter, type AdapterContext, type AdapterMiddleware } from '@forinda/kickjs'
 
-export interface ${pascal}AdapterOptions {
-  // Add your adapter configuration here
+/**
+ * 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.
+ * ${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,
  * or external service connections.
  *
- * Usage:
- *   bootstrap({
- *     adapters: [new ${pascal}Adapter({ ... })],
- *   })
+ * @example
+ * \`\`\`ts
+ * import { bootstrap } from '@forinda/kickjs'
+ * import { ${pascal}Adapter } from './adapters/${kebab}.adapter'
+ *
+ * bootstrap({
+ *   modules,
+ *   adapters: [${pascal}Adapter({ /* config overrides *\\/ })],
+ * })
+ * \`\`\`
  */
-export class ${pascal}Adapter implements AppAdapter {
-  name = '${pascal}Adapter'
-
-  constructor(private options: ${pascal}AdapterOptions = {}) {}
-
-  /**
-   * Return middleware entries that the Application will mount.
-   * Use \`phase\` to control where in the pipeline they run:
-   *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'
-   */
-  middleware(): AdapterMiddleware[] {
-    return [
-      // Example: add a custom header to all responses
-      // {
-      //   phase: 'beforeGlobal',
-      //   handler: (_req: any, res: any, next: any) => {
-      //     res.setHeader('X-${pascal}', 'true')
-      //     next()
-      //   },
-      // },
-      // Example: scope middleware to a specific path
-      // {
-      //   phase: 'beforeRoutes',
-      //   path: '/api/v1/admin',
-      //   handler: myAdminMiddleware(),
-      // },
-    ]
-  }
+export const ${pascal}Adapter = defineAdapter<${pascal}AdapterConfig>({
+  name: '${pascal}Adapter',
+  defaults: {
+    // Default config values go here
+  },
+  build: (_config, { name: _name }) => ({
+    /**
+     * Return middleware entries that the Application will mount.
+     * \`phase\` controls where in the pipeline they run:
+     * 'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'.
+     */
+    middleware(): AdapterMiddleware[] {
+      return [
+        // Example: add a custom header to all responses
+        // {
+        //   phase: 'beforeGlobal',
+        //   handler: (_req, res, next) => {
+        //     res.setHeader('X-${pascal}', 'true')
+        //     next()
+        //   },
+        // },
+      ]
+    },
 
-  /**
-   * Called before global middleware.
-   * Use this to mount routes that bypass the middleware stack
-   * (health checks, docs UI, static assets).
-   */
-  beforeMount({ app }: AdapterContext): void {
-    // Example: mount a status route
-    // app.get('/${kebab}/status', (_req, res) => {
-    //   res.json({ status: 'ok' })
-    // })
-  }
+    /**
+     * Called before global middleware. Use this to mount routes that
+     * bypass the middleware stack (health checks, docs UI, static
+     * assets).
+     */
+    beforeMount(_ctx: AdapterContext): void {
+      // Example:
+      // _ctx.app.get('/${kebab}/status', (_req, res) => res.json({ status: 'ok' }))
+    },
 
-  /**
-   * Called after modules and routes are registered, before the server starts.
-   * Use this for late-stage DI registrations or config validation.
-   */
-  beforeStart({ container }: AdapterContext): void {
-    // Example: register a service in the DI container
-    // container.registerInstance(MY_TOKEN, new MyService(this.options))
-  }
+    /**
+     * Called after modules and routes are registered, before the
+     * server starts. Use this for late-stage DI registrations or
+     * config validation.
+     */
+    beforeStart(_ctx: AdapterContext): void {
+      // Example: _ctx.container.bindToken(MY_TOKEN, new MyService(_config))
+    },
 
-  /**
-   * Called after the HTTP server is listening.
-   * Use this to attach to the raw http.Server (Socket.IO, gRPC, etc).
-   */
-  afterStart({ server, container }: AdapterContext): void {
-    // Example: attach Socket.IO
-    // const io = new Server(server)
-    // container.registerInstance(SOCKET_IO, io)
-  }
+    /**
+     * Called after the HTTP server is listening. Use this to attach
+     * to the raw http.Server (Socket.IO, gRPC, etc).
+     */
+    afterStart(_ctx: AdapterContext): void {
+      // Example: const io = new Server(_ctx.server)
+    },
 
-  /**
-   * Called on graceful shutdown. Clean up connections.
-   */
-  async shutdown(): Promise<void> {
-    // Example: close a connection pool
-    // await this.pool.end()
-  }
-}
+    /** Called on graceful shutdown. Clean up connections. */
+    async shutdown(): Promise<void> {
+      // Example: await this.pool.end()
+    },
+  }),
+})
 `);
 	files.push(filePath);
 	return files;
@@ -2730,7 +2797,7 @@ function generatePackageJson(name, template, kickjsVersion, packages = []) {
 			"unplugin-swc": "^1.5.9",
 			vite: "^8.0.3",
 			vitest: "^4.1.2",
-			typescript: "^5.9.2",
+			typescript: "^6.0.3",
 			prettier: "^3.8.1"
 		}
 	}, null, 2);
@@ -2976,404 +3043,223 @@ Copy \`.env.example\` to \`.env\` and configure:
 - [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
 `;
 }
-/** Generate CLAUDE.md with AI development guide */
-function generateClaude(name, template, pm) {
-	return `# CLAUDE.md — ${name} Development Guide
-
-> **Read \`AGENTS.md\` first.** It is the canonical, multi-agent reference for this project (Claude, Copilot, Codex, Gemini, etc.). This file contains the same project context distilled for Claude, plus Claude-specific notes. When the two disagree on anything substantive, treat \`AGENTS.md\` as authoritative and flag the discrepancy.
-
-## Project Overview
-
-This is a **${{
-		rest: "REST API",
-		graphql: "GraphQL API",
-		ddd: "Domain-Driven Design",
-		cqrs: "CQRS + Event-Driven",
-		minimal: "Minimal Express"
-	}[template] ?? "REST API"}** application built with [KickJS](https://forinda.github.io/kick-js/) — a decorator-driven Node.js framework on Express 5 and TypeScript.
-
-## Quick Commands
-
-\`\`\`bash
-${pm} install           # Install dependencies
-kick dev                # Start dev server with HMR
-kick build              # Production build via Vite
-kick start              # Run production build
-${pm} run test          # Run tests with Vitest
-${pm} run typecheck     # TypeScript type checking
-${pm} run format        # Format code with Prettier
-\`\`\`
-
-## Project Structure
-
-\`\`\`
-src/
-├── index.ts           # Application bootstrap
-├── modules/           # Feature modules (DDD/CQRS pattern)
-│   └── index.ts       # Module registry
-${template === "graphql" ? "├── resolvers/         # GraphQL resolvers\n" : ""}└── ...
-\`\`\`
-
-## Package Manager
-
-- Always use **${pm}** for this project
-- Run \`${pm} install\` to sync dependencies
-- Never mix package managers (npm/yarn/pnpm)
-
-## Code Style
-
-- **Prettier** — no semicolons, single quotes, trailing commas, 100 char width
-- **TypeScript strict mode** — all types required
-- Format before committing: \`${pm} run format\`
-- Type check with: \`${pm} run typecheck\`
-
-## Key Patterns
-
-### Controllers
-
-Use decorators to define routes. Annotate \`ctx\` with \`Ctx<KickRoutes.X['method']>\`
-to get fully-typed \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` from the
-generated \`KickRoutes\` namespace (refreshed on \`kick dev\` and \`kick typegen\`).
-
-\`\`\`ts
-import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
-
-@Controller('/users')
-export class UserController {
-  @Get('/')
-  async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
-    return ctx.json({ users: [] })
-  }
-
-  @Post('/')
-  async create(ctx: Ctx<KickRoutes.UserController['create']>) {
-    const data = ctx.body
-    return ctx.created({ user: data })
-  }
-}
-\`\`\`
-
-### Services
-
-Inject dependencies with \`@Service()\` and \`@Autowired()\`:
-
-\`\`\`ts
-import { Service, Autowired } from '@forinda/kickjs'
-
-@Service()
-export class UserService {
-  @Autowired()
-  private userRepository!: UserRepository
-
-  async findAll() {
-    return this.userRepository.findAll()
-  }
-}
-\`\`\`
-
-### Modules
-
-Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`.
-
-> **Naming matters.** Module files **must** be named \`<name>.module.ts\` and live under \`src/modules/\`. The Vite plugin auto-discovers files matching \`*.module.[tj]sx?\` for HMR — a misnamed file (e.g., \`projects.ts\`) won't trigger a graceful module rebuild on save and will require a full server restart. The CLI generator (\`kick g module <name>\`) follows this convention automatically.
-
-\`\`\`ts
-// src/modules/users/users.module.ts   (named <feature>.module.ts)
-import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
-import { UserController } from './user.controller'
-
-export class UserModule implements AppModule {
-  routes(): ModuleRoutes {
-    return {
-      path: '/users',
-      router: buildRoutes(UserController),
-      controller: UserController,
-    }
-  }
-}
-\`\`\`
-
-Register all modules in \`src/modules/index.ts\`:
-
-\`\`\`ts
-import type { AppModuleClass } from '@forinda/kickjs'
-import { UserModule } from './user/user.module'
-
-export const modules: AppModuleClass[] = [UserModule]
-\`\`\`
-
-### RequestContext
-
-Every controller method receives a \`ctx\` (alias \`Ctx<TRoute>\` or the
-loose \`RequestContext\`):
-
-\`\`\`ts
-ctx.body           // Request body (parsed JSON)
-ctx.params         // Route params
-ctx.query          // Query string
-ctx.headers        // Request headers
-ctx.requestId      // Auto-generated request ID
-ctx.session        // Session data (if session middleware enabled)
-ctx.file           // Uploaded file (single)
-ctx.files          // Uploaded files (multiple)
-
-// Pagination helpers
-ctx.qs(config)           // Parse query with filters/sort/pagination
-ctx.paginate(handler)     // Auto-paginated response
-
-// Response helpers
-ctx.json(data)            // 200 OK with JSON
-ctx.created(data)         // 201 Created
-ctx.noContent()           // 204 No Content
-ctx.notFound()            // 404 Not Found
-ctx.badRequest(msg)       // 400 Bad Request
-\`\`\`
-
-> **Context decorators** — when a middleware's only job is to populate \`ctx.set/get\` for the handler to read, prefer \`defineContextDecorator()\` over \`@Middleware()\`. Typed via \`ContextMeta\`, supports \`dependsOn\` ordering, validates the pipeline at boot. Full pattern reference in \`AGENTS.md\` and at <https://forinda.github.io/kick-js/guide/context-decorators>.
-
-## CLI Generators
-
-Generate code with the \`kick\` CLI:
-
-\`\`\`bash
-kick g module <name>              # Full module (controller, service, DTOs, repo)
-kick g scaffold <name> <fields>   # CRUD module from field definitions
-kick g controller <name>          # Standalone controller
-kick g service <name>             # Service class
-kick g middleware <name>          # Express middleware
-kick g guard <name>               # Route guard (auth, roles)
-kick g adapter <name>             # AppAdapter with lifecycle hooks
-kick g dto <name>                 # Zod DTO schema
-${template === "graphql" ? "kick g resolver <name>           # GraphQL resolver\n" : ""}${template === "cqrs" ? "kick g job <name>                # Queue job processor\n" : ""}\`\`\`
-
-## Adding Packages
+/**
+* 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
-kick add auth          # JWT, API key, OAuth strategies
-kick add swagger       # OpenAPI docs from decorators
-kick add ws            # WebSocket support
-kick add queue         # Background jobs (BullMQ/RabbitMQ/Kafka)
-kick add mailer        # Email (SMTP, Resend, SES)
-kick add cron          # Scheduled tasks
-kick add prisma        # Prisma ORM adapter
-kick add drizzle       # Drizzle ORM adapter
-kick add otel          # OpenTelemetry tracing
-kick add --list        # Show all available packages
-\`\`\`
-
-## Environment Configuration
-
-The project's typed env schema lives in **\`src/config/index.ts\`** —
-extend the base schema there with your application-specific keys, and
-the schema is auto-registered with kickjs at module load. The companion
-\`src/index.ts\` imports it as a side effect (\`import './config'\`) **before**
-\`bootstrap()\` runs, so every \`@Service\`, \`@Controller\`, \`@Value\`, and
-\`ConfigService\` resolution sees the validated extended values.
-
-> **Do not delete \`import './config'\` from \`src/index.ts\`.** It is the
-> registration step that wires \`ConfigService\` to your env schema.
-> Without it, \`config.get('YOUR_KEY')\` returns \`undefined\` for every
-> user-defined key and \`@Value('YOUR_KEY')\` only works because of a
-> raw \`process.env\` fallback (Zod coercion + defaults are skipped).
-
-Edit \`.env\` for variable values. Access them with \`@Value()\`:
-
-\`\`\`ts
-import { Value } from '@forinda/kickjs'
-
-@Service()
-export class ApiService {
-  @Value('API_KEY')
-  private apiKey!: string
-
-  @Value('PORT', 3000)  // With default
-  private port!: number
-}
-\`\`\`
-
-Or use \`ConfigService\`:
-
-\`\`\`ts
-import { Service, Autowired, ConfigService } from '@forinda/kickjs'
-
-@Service()
-export class AppService {
-  @Autowired()
-  private config!: ConfigService
-
-  getPort() {
-    // typed: number, Zod-coerced from baseEnvSchema
-    return this.config.get('PORT')
-  }
-}
-\`\`\`
-
-Hot-reload of \`.env\` changes during dev is wired up automatically via
-\`envWatchPlugin()\` in \`vite.config.ts\` — edit \`.env\`, the dev server
-reloads, and the next \`config.get()\` re-parses with the new values.
-
-### Standalone Env Utilities (No DI Required)
-
-These functions work anywhere — scripts, CLI tools, plain files, outside \`@Service\`/\`@Controller\`:
-
-\`\`\`ts
-import { defineEnv, loadEnv, getEnv, reloadEnv, resetEnvCache, baseEnvSchema } from '@forinda/kickjs/config'
-import { z } from 'zod'
-
-// Define and parse schema
-const schema = defineEnv((base) =>
-  base.extend({ DATABASE_URL: z.string().url() })
-)
-const env = loadEnv(schema)      // Parse + validate process.env
-console.log(env.PORT)            // 3000 (coerced to number)
-console.log(env.DATABASE_URL)    // validated URL string
-
-// Get single value
-const port = getEnv('PORT')      // typed after kick typegen
-
-// Reload after .env changes (HMR calls this automatically)
-reloadEnv()
-
-// Reset cache in tests that swap schemas
-resetEnvCache()
-\`\`\`
-
-| Function | Purpose |
-|----------|---------|
-| \`defineEnv(fn)\` | Extend base schema with custom Zod keys |
-| \`loadEnv(schema?)\` | Parse \`process.env\`, validate, cache, return typed object |
-| \`getEnv(key, schema?)\` | Get single validated env value |
-| \`reloadEnv()\` | Re-read \`.env\` from disk, re-parse with same schema |
-| \`resetEnvCache()\` | Clear parsed cache AND registered schema (for tests) |
-| \`baseEnvSchema\` | Base Zod schema: \`PORT\`, \`NODE_ENV\`, \`LOG_LEVEL\` |
-
-## Standalone Utilities (No DI Required)
-
-These utilities work outside decorated classes:
-
-### Logger
-
-\`\`\`ts
-import { Logger, createLogger } from '@forinda/kickjs'
-
-const log = Logger.for('MyScript')    // Static factory
-log.info('Processing started')
-log.error('Something failed')
-
-const log2 = createLogger('Worker')   // Function form
-\`\`\`
-
-### Injection Tokens
-
-\`\`\`ts
-import { createToken } from '@forinda/kickjs'
-
-// Type-safe DI tokens for factory/interface binding
-const DB_URL = createToken<string>('config.database.url')
-const FEATURE_FLAGS = createToken<FeatureFlags>('app.features')
-\`\`\`
-
-### Reactivity
-
-\`\`\`ts
-import { ref, computed, watch, reactive } from '@forinda/kickjs'
-
-const count = ref(0)
-const doubled = computed(() => count.value * 2)
-const stop = watch(() => count.value, (val) => console.log(val))
-count.value++  // logs 1
-\`\`\`
-
-### HTTP Errors
-
-\`\`\`ts
-import { HttpException, HttpStatus } from '@forinda/kickjs'
-
-throw new HttpException(HttpStatus.NOT_FOUND, 'User not found')
-\`\`\`
-
-## Testing
-
-Tests live in \`src/**/*.test.ts\`:
-
-\`\`\`ts
-import { describe, it, expect, beforeEach } from 'vitest'
-import { Container } from '@forinda/kickjs'
-import { createTestApp } from '@forinda/kickjs-testing'
-
-describe('UserController', () => {
-  beforeEach(() => Container.reset())
-
-  it('should return users', async () => {
-    const app = await createTestApp([UserModule])
-    const res = await app.get('/users')
-    expect(res.status).toBe(200)
-  })
-})
+${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
 \`\`\`
 
-Run tests:
-- \`${pm} run test\` — run all tests
-- \`${pm} run test:watch\` — watch mode
-
-## Decorators Reference
-
-### Route Decorators
-- \`@Controller('/path')\` — define controller prefix
-- \`@Get('/'), @Post('/'), @Put('/'), @Delete('/'), @Patch('/')\` — HTTP methods
-- \`@Middleware(fn)\` — attach middleware
-- \`@Public()\` — skip authentication (requires @forinda/kickjs-auth)
-- \`@Roles('admin', 'user')\` — role-based access control
-
-### DI Decorators
-- \`@Service()\` — singleton service (DI-registered)
-- \`@Repository()\` — repository (semantic alias for @Service)
-- \`@Autowired()\` — property injection
-- \`@Inject('token')\` — token-based injection
-- \`@Value('ENV_VAR')\` — inject config value
-
-${template === "cqrs" ? `### CQRS/Event Decorators
-- \`@Job('job-name')\` — queue job handler
-- \`@Process('queue-name')\` — queue processor
-- \`@Cron('0 * * * *')\` — cron schedule
-- \`@WsController('/path')\` — WebSocket controller
-- \`@Subscribe('event')\` — WebSocket event handler
-
-` : ""}${template === "graphql" ? `### GraphQL Decorators
-- \`@Resolver()\` — GraphQL resolver
-- \`@Query()\` — GraphQL query
-- \`@Mutation()\` — GraphQL mutation
-- \`@Arg('name')\` — resolver argument
+## v4 framework reminders
 
-` : ""}## Common Pitfalls
+When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`AGENTS.md\`:
 
-1. **Decorators fire at import time** — make sure to import module classes in \`src/modules/index.ts\`
-2. **Tests need \`Container.reset()\`** — call in \`beforeEach\` to isolate DI state
-3. **Always use \`ctx.body\`** — never \`req.body\` directly
-4. **DI requires \`reflect-metadata\`** — already imported in \`src/index.ts\`
-5. **Vite HMR requires proper cleanup** — adapters should implement \`shutdown()\`
-6. **Never delete \`import './config'\` from \`src/index.ts\`** — that side-effect import registers the env schema with kickjs. Without it \`ConfigService.get('YOUR_KEY')\` returns \`undefined\` for every user-defined key. \`@Value('YOUR_KEY')\` *appears* to keep working but only via a raw \`process.env\` fallback (Zod coercion + schema defaults are silently skipped).
+- **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\`.
 
-## Learn More
-
-- [KickJS Documentation](https://forinda.github.io/kick-js/)
-- [API Reference](https://forinda.github.io/kick-js/api/)
-- [CLI Commands](https://forinda.github.io/kick-js/guide/cli-commands.html)
-- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
+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 helps AI agents (Claude, Copilot, etc.) work effectively on this KickJS application.
+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. Read \`CLAUDE.md\` for project conventions and commands
-2. Run \`${pm} install\` to install dependencies
-3. Run \`kick dev\` to verify the app starts
-4. Read the [KickJS documentation](https://forinda.github.io/kick-js/) for framework details
+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
+    \`requestStore.getStore()?.values.get('key')\` from a service that
+    has no \`ctx\` reference). \`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
 
@@ -3384,6 +3270,7 @@ This guide helps AI agents (Claude, Copilot, etc.) work effectively on this Kick
 | 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) |
 ${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Env values | \`.env\` |
 | Env schema (Zod) | \`src/config/index.ts\` |
 | TypeScript config | \`tsconfig.json\` |
@@ -3466,7 +3353,7 @@ Then:
 If not using generators:
 
 - [ ] Create \`src/modules/<name>/<name>.controller.ts\`
-- [ ] Add \`@Controller('/path')\` decorator
+- [ ] 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)
@@ -3528,8 +3415,8 @@ import { AuthAdapter, JwtStrategy } from '@forinda/kickjs-auth'
 bootstrap({
   modules,
   adapters: [
-    new AuthAdapter({
-      strategies: [new JwtStrategy({ secret: process.env.JWT_SECRET! })],
+    AuthAdapter({
+      strategies: [JwtStrategy({ secret: process.env.JWT_SECRET! })],
     }),
   ],
 })
@@ -3559,7 +3446,7 @@ import { WsAdapter } from '@forinda/kickjs-ws'
 
 bootstrap({
   modules,
-  adapters: [new WsAdapter()],
+  adapters: [WsAdapter()],
 })
 \`\`\`
 
@@ -3579,14 +3466,13 @@ import { Container } from '@forinda/kickjs'
 import { createTestApp } from '@forinda/kickjs-testing'
 
 describe('UserController', () => {
-  beforeEach(() => {
-    Container.reset()  // Important: isolate DI state
-  })
-
   it('should return users', async () => {
-    const app = await createTestApp([UserModule])
+    // 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')
   })
@@ -3650,7 +3536,7 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 |---------|--------|---------|
 | \`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>('db.url')\` |
+| \`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))\` |
@@ -3663,7 +3549,7 @@ These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller
 ### HTTP Routes
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Controller('/path')\` | Define route prefix |
+| \`@Controller()\` | Define route prefix |
 | \`@Get('/'), @Post('/')\` | HTTP method handlers |
 | \`@Middleware(fn)\` | Attach middleware |
 | \`@Public()\` | Skip auth (requires auth adapter) |
@@ -3720,13 +3606,15 @@ ${template === "graphql" ? `### GraphQL
 
 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** — Missing \`Container.reset()\` in \`beforeEach\`
+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
 
@@ -3759,6 +3647,261 @@ ${template === "graphql" ? `### GraphQL
 - [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 Map (\`requestStore.getStore().values\`).
+- **\`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 can read contributor output without a \`ctx\` reference via \`requestStore.getStore()?.values.get('tenant')\` — same Map, no DI plumbing needed.
+
+**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));
@@ -3791,6 +3934,7 @@ async function initProject(options) {
 	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 {
@@ -3804,7 +3948,7 @@ async function initProject(options) {
 		}
 	}
 	try {
-		const { runTypegen } = await import("./typegen-C30frihW.mjs");
+		const { runTypegen } = await import("./typegen-C-H8pg-y.mjs");
 		await runTypegen({
 			cwd: dir,
 			allowDuplicates: true,
@@ -3902,7 +4046,10 @@ async function loadKickConfig(cwd) {
 		try {
 			const { pathToFileURL } = await import("node:url");
 			const mod = await import(pathToFileURL(filepath).href);
-			return mod.default ?? mod;
+			const config = mod.default ?? mod;
+			const warnings = validateAssetMap(config, cwd);
+			for (const warning of warnings) console.warn(`  Warning: ${warning}`);
+			return config;
 		} catch (err) {
 			if (filename.endsWith(".ts")) console.warn(`Warning: Failed to load ${filename}. TypeScript config files require a runtime loader (e.g. tsx, ts-node) or use kick.config.js/.mjs instead.`);
 			continue;
@@ -3910,7 +4057,126 @@ async function loadKickConfig(cwd) {
 	}
 	return null;
 }
+/**
+* Validate `assetMap` entries on a loaded config. Returns a list of
+* human-readable warnings; the caller decides how to surface them
+* (typically `console.warn`). Never throws — `kick g` and other
+* unrelated commands should keep working even when the assetMap is
+* misconfigured.
+*
+* Checks:
+*
+* - Each entry's `src` is a non-empty string.
+* - The `src` directory exists on disk (otherwise the typegen + build
+*   steps will fail later with cryptic errors).
+* - `dest` doesn't escape the project root (defensive — a `dest:
+*   '../../etc'` typo could write files outside the workspace).
+* - The namespace key is a non-empty string and doesn't include a
+*   `/` (would conflict with the `<namespace>/<key>` manifest format).
+*/
+function validateAssetMap(config, cwd) {
+	const warnings = [];
+	if (!config?.assetMap) return warnings;
+	const root = resolve(cwd);
+	for (const [namespace, entry] of Object.entries(config.assetMap)) {
+		if (!namespace || namespace.includes("/")) {
+			warnings.push(`assetMap key '${namespace}' is invalid — must be a non-empty string without '/'`);
+			continue;
+		}
+		if (typeof entry?.src !== "string" || entry.src.length === 0) {
+			warnings.push(`assetMap.${namespace} is missing a non-empty 'src' field`);
+			continue;
+		}
+		if (!existsSync(resolve(cwd, entry.src))) warnings.push(`assetMap.${namespace}.src ('${entry.src}') does not exist — typegen + build will fail`);
+		if (entry.dest) {
+			if (escapesRoot(resolve(cwd, entry.dest), root)) warnings.push(`assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — refusing to copy`);
+		}
+	}
+	return warnings;
+}
+/**
+* Returns true when `path` (absolute) resolves outside of `root`
+* (also absolute). Uses `path.relative` for accuracy:
+*
+* - The result is empty when paths are identical (inside).
+* - It starts with `..` when the path traverses outside the root.
+* - It's absolute (Windows: cross-drive) when there's no relative
+*   path between them.
+*
+* Avoids the prefix-match pitfalls of `startsWith` (e.g. `/app`
+* matching `/app2/...`, or case-mismatches on macOS / Windows).
+*/
+function escapesRoot(path, root) {
+	const rel = relative(root, path);
+	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
+}
+//#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;
+}
 //#endregion
-export { defineConfig, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
+export { buildGeneratorContext, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
 
 //# sourceMappingURL=index.mjs.map