@forinda/kickjs-cli 3.2.0 → 4.1.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.2.0
+ * @forinda/kickjs-cli v4.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,15 +8,17 @@
  *
  * @license MIT
  */
+import { createRequire } from "node:module";
 import { Command } from "commander";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { execSync, fork, spawn, spawnSync } from "node:child_process";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import * as clack from "@clack/prompts";
 import pc from "picocolors";
 import pkg from "pluralize";
+import { glob, globSync } from "glob";
 import { arch, platform, release } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -36,11 +38,60 @@ let _dryRun = false;
 function setDryRun(enabled) {
 	_dryRun = enabled;
 }
-/** 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) {
 	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 _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) {
@@ -113,7 +164,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);
@@ -296,15 +347,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
@@ -337,15 +388,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'`);
@@ -364,7 +415,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  ],`}
 })
 `;
 		}
@@ -373,15 +424,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'`);
@@ -405,15 +456,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
@@ -707,404 +758,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
-}
+${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
 \`\`\`
 
-Or use \`ConfigService\`:
-
-\`\`\`ts
-import { Service, Autowired, ConfigService } from '@forinda/kickjs'
-
-@Service()
-export class AppService {
-  @Autowired()
-  private config!: ConfigService
+## v4 framework reminders
 
-  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)
+When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`AGENTS.md\`:
 
-These utilities work outside decorated classes:
+- **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\`.
 
-### 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)
-  })
-})
-\`\`\`
-
-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
-
-` : ""}## Common Pitfalls
-
-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).
-
-## 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
 
@@ -1115,6 +985,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\` |
@@ -1197,7 +1068,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)
@@ -1259,8 +1130,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! })],
     }),
   ],
 })
@@ -1290,7 +1161,7 @@ import { WsAdapter } from '@forinda/kickjs-ws'
 
 bootstrap({
   modules,
-  adapters: [new WsAdapter()],
+  adapters: [WsAdapter()],
 })
 \`\`\`
 
@@ -1310,14 +1181,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')
   })
@@ -1381,7 +1251,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))\` |
@@ -1394,7 +1264,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) |
@@ -1451,13 +1321,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
 
@@ -1490,6 +1362,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$1 = dirname(fileURLToPath(import.meta.url));
@@ -1522,6 +1649,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 {
@@ -1915,6 +2043,228 @@ function pluralizePascal(name) {
 	return pkg.plural(name);
 }
 //#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.).
+*
+* The lookup is FIRST-MATCH-WINS in dependency declaration order: if
+* two plugins claim the same generator name, the one whose package was
+* resolved first wins. Adopters with conflicts should rename the
+* generator on their side or pin one of the plugins to a different
+* version.
+*/
+async function tryDispatchPluginGenerator(input) {
+	const cwd = input.cwd ?? process.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 discovered plugin generator. */
+async function listPluginGenerators(cwd) {
+	return discoverPluginGenerators(cwd);
+}
+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
 //#region src/generators/templates/module-index.ts
 const repoLabelMap = {
 	inmemory: "in-memory",
@@ -2388,7 +2738,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) {
@@ -3806,97 +4156,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;
@@ -3904,80 +4271,84 @@ export class ${pascal}Adapter implements AppAdapter {
 //#endregion
 //#region src/generators/plugin.ts
 /**
-* Scaffold a `KickPlugin` under `src/plugins/<name>.plugin.ts`.
+* Scaffold a `definePlugin()` factory under `src/plugins/<name>.plugin.ts`.
 *
-* Plugins are the canonical place to wire DI bindings, load extra
-* modules, add middleware, or attach startup hooks without writing a
-* full adapter. The generated template implements every optional
-* `KickPlugin` hook with commented examples so users can uncomment
-* the ones they need and delete the rest.
+* v4 standardised on the `definePlugin()` factory pattern (architecture
+* §21.2.2) — same surface as `defineAdapter()`, so adopters learn one
+* mental model. The generated template uses the factory shape with a
+* typed config object, defaults block, and a build function returning
+* the underlying KickPlugin hooks.
 */
 async function generatePlugin(options) {
 	const { name, outDir } = options;
 	const kebab = toKebabCase(name);
 	const pascal = toPascalCase(name);
-	const factoryName = `${toCamelCase(name)}Plugin`;
 	const files = [];
 	const filePath = join(outDir, `${kebab}.plugin.ts`);
-	await writeFileSafe(filePath, `import type { KickPlugin, Container, AppAdapter, AppModuleClass } from '@forinda/kickjs'
+	await writeFileSafe(filePath, `import {
+  definePlugin,
+  type AppAdapter,
+  type AppModuleClass,
+  type Container,
+} from '@forinda/kickjs'
 
 /**
- * Options for the ${pascal} plugin.
+ * Configuration for the ${pascal} plugin.
  *
- * Plugins typically take a small options object in their factory so
- * callers can configure them inline at bootstrap time. Keep the
- * shape narrow — anything derived from the environment should be
- * read via \`getEnv\` inside the plugin itself, not forced onto the
- * caller.
+ * Plugins 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}PluginOptions {
-  // Add your plugin options here, for example:
+export interface ${pascal}PluginConfig {
+  // Add your plugin config here, e.g.:
   // enabled?: boolean
   // apiKey?: string
 }
 
 /**
- * ${pascal} plugin.
+ * ${pascal} plugin — built via \`definePlugin()\` so callers get the
+ * factory's call / \`.scoped()\` / \`.async()\` surfaces for free.
  *
- * A \`KickPlugin\` bundles DI bindings, modules, adapters, and
- * middleware into one object that can be added to \`bootstrap({ plugins })\`.
- * Every hook is optional — delete the ones you don't need and keep
- * only the surface your plugin actually uses.
+ * A plugin bundles DI bindings, modules, adapters, and middleware
+ * into one object that can be added to \`bootstrap({ plugins })\`.
  *
- * Lifecycle order:
+ * Lifecycle order (each hook is optional — delete the ones you don't
+ * need and keep only the surface your plugin actually uses):
  *
- *   1. \`register(container)\`   — runs before user modules load. Use
+ *   1. \`register(container)\` — runs before user modules load. Use
  *      it to bind services that modules depend on.
- *   2. \`modules()\`               — plugin modules load before user modules.
- *   3. \`adapters()\`              — plugin adapters are added before user adapters.
- *   4. \`middleware()\`            — plugin middleware runs before user middleware.
- *   5. \`onReady(container)\`     — runs after the app has fully bootstrapped.
- *   6. \`shutdown()\`              — runs on graceful shutdown.
+ *   2. \`modules()\`            — plugin modules load before user modules.
+ *   3. \`adapters()\`           — plugin adapters mount before user adapters.
+ *   4. \`middleware()\`         — plugin middleware runs before user middleware.
+ *   5. \`onReady(container)\`   — runs after the app has fully bootstrapped.
+ *   6. \`shutdown()\`           — runs on graceful shutdown.
  *
  * @example
  * \`\`\`ts
  * import { bootstrap } from '@forinda/kickjs'
- * import { ${factoryName} } from './plugins/${kebab}.plugin'
+ * import { ${pascal}Plugin } from './plugins/${kebab}.plugin'
  *
  * export const app = await bootstrap({
  *   modules,
- *   plugins: [${factoryName}({})],
+ *   plugins: [${pascal}Plugin({ /* config overrides *\\/ })],
  * })
  * \`\`\`
  */
-export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin {
-  return {
-    name: '${kebab}',
-
+export const ${pascal}Plugin = definePlugin<${pascal}PluginConfig>({
+  name: '${pascal}Plugin',
+  defaults: {
+    // Default config values go here
+  },
+  build: (_config, { name: _name }) => ({
     /**
      * Register DI bindings before modules load.
      * Use \`container.registerInstance(TOKEN, value)\` for singletons
      * and \`container.registerFactory(TOKEN, () => ...)\` for lazy
      * constructions.
      */
-    register(container: Container): void {
-      // Example: bind a configured service to a DI token
-      // container.registerInstance(MY_TOKEN, new MyService(options))
+    register(_container: Container): void {
+      // Example: _container.registerInstance(MY_TOKEN, new MyService(_config))
     },
 
     /**
@@ -3993,11 +4364,11 @@ export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin
 
     /**
      * Return adapter instances to be added to the application.
-     * Plugin adapters are added before user adapters.
+     * Plugin adapters mount before user adapters.
      */
     adapters(): AppAdapter[] {
       return [
-        // new MyAdapter({ ... }),
+        // MyAdapter({ ... }),
       ]
     },
 
@@ -4005,10 +4376,10 @@ export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin
      * Return Express middleware entries to be added to the global
      * pipeline. Plugin middleware runs before user-defined middleware.
      */
-    middleware(): any[] {
+    middleware(): unknown[] {
       return [
         // helmet(),
-        // myCustomMiddleware(options),
+        // myCustomMiddleware(_config),
       ]
     },
 
@@ -4017,9 +4388,9 @@ export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin
      * for post-startup work like logging, health checks, or warming
      * a cache. Runs once per process.
      */
-    async onReady(container: Container): Promise<void> {
-      // const logger = container.resolve(Logger)
-      // logger.info('${pascal} plugin ready')
+    async onReady(_container: Container): Promise<void> {
+      // const log = _container.resolve(Logger)
+      // log.info('${pascal} plugin ready')
     },
 
     /**
@@ -4027,10 +4398,10 @@ export function ${factoryName}(options: ${pascal}PluginOptions = {}): KickPlugin
      * resources this plugin owns (connections, timers, subscriptions).
      */
     async shutdown(): Promise<void> {
-      // await this.connection?.close()
+      // Example: await this.connection?.close()
     },
-  }
-}
+  }),
+})
 `);
 	files.push(filePath);
 	return files;
@@ -4353,6 +4724,188 @@ export default defineConfig({
 	return [filePath];
 }
 //#endregion
+//#region src/config.ts
+const PACKAGE_MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+const BUILTIN_REPO_TYPES = [
+	"drizzle",
+	"inmemory",
+	"prisma"
+];
+/** Resolve module config from `modules.*` block. */
+function resolveModuleConfig(config) {
+	if (!config) return {};
+	const mc = {
+		dir: config.modules?.dir,
+		repo: config.modules?.repo,
+		schemaDir: config.modules?.schemaDir,
+		pluralize: config.modules?.pluralize,
+		prismaClientPath: config.modules?.prismaClientPath
+	};
+	if (mc.repo && typeof mc.repo === "string" && !BUILTIN_REPO_TYPES.includes(mc.repo)) console.warn(`  Warning: modules.repo '${mc.repo}' is not a built-in type (${BUILTIN_REPO_TYPES.join(", ")}). It will generate a stub repository. Use { name: '${mc.repo}' } to silence this warning.`);
+	return mc;
+}
+const CONFIG_FILES = [
+	"kick.config.ts",
+	"kick.config.js",
+	"kick.config.mjs",
+	"kick.config.json"
+];
+/** Load kick.config.* from the project root */
+async function loadKickConfig(cwd) {
+	for (const filename of CONFIG_FILES) {
+		const filepath = join(cwd, filename);
+		try {
+			await access(filepath);
+		} catch {
+			continue;
+		}
+		if (filename.endsWith(".json")) {
+			const content = await readFile(filepath, "utf-8");
+			return JSON.parse(content);
+		}
+		try {
+			const { pathToFileURL } = await import("node:url");
+			const mod = await import(pathToFileURL(filepath).href);
+			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;
+		}
+	}
+	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$1(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$1(path, root) {
+	const rel = relative(root, path);
+	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
+}
+//#endregion
+//#region src/generators/agent-docs.ts
+const VALID_TEMPLATES = new Set([
+	"rest",
+	"graphql",
+	"ddd",
+	"cqrs",
+	"minimal"
+]);
+function detectName(outDir, override) {
+	if (override) return override;
+	try {
+		const pkg = JSON.parse(readFileSync(join(outDir, "package.json"), "utf-8"));
+		if (pkg.name) return pkg.name.replace(/^@[^/]+\//, "");
+	} catch {}
+	return outDir.split("/").filter(Boolean).pop() ?? "app";
+}
+function detectPm(outDir, override) {
+	if (override) return override;
+	try {
+		const pkg = JSON.parse(readFileSync(join(outDir, "package.json"), "utf-8"));
+		if (pkg.packageManager) return pkg.packageManager.split("@")[0];
+	} catch {}
+	return "pnpm";
+}
+async function detectTemplate(outDir, override) {
+	if (override) return override;
+	try {
+		const pattern = (await loadKickConfig(outDir))?.pattern;
+		if (pattern && VALID_TEMPLATES.has(pattern)) return pattern;
+	} catch {}
+	return "ddd";
+}
+async function generateAgentDocs(options) {
+	const only = options.only ?? "all";
+	const name = detectName(options.outDir, options.name);
+	const pm = detectPm(options.outDir, options.pm);
+	const template = await detectTemplate(options.outDir, options.template);
+	const wantsAgents = only === "agents" || only === "both" || only === "all";
+	const wantsClaude = only === "claude" || only === "both" || only === "all";
+	const wantsSkills = only === "skills" || only === "all";
+	const targets = [];
+	if (wantsAgents) targets.push({
+		file: join(options.outDir, "AGENTS.md"),
+		render: () => generateAgents(name, template, pm)
+	});
+	if (wantsClaude) targets.push({
+		file: join(options.outDir, "CLAUDE.md"),
+		render: () => generateClaude(name, template, pm)
+	});
+	if (wantsSkills) targets.push({
+		file: join(options.outDir, "kickjs-skills.md"),
+		render: () => generateKickJsSkills(name, template, pm)
+	});
+	const written = [];
+	for (const { file, render } of targets) {
+		if (existsSync(file) && !options.force) {
+			if (!await confirm({
+				message: `${file.replace(options.outDir + "/", "")} already exists. Overwrite?`,
+				initialValue: false
+			})) {
+				console.log(`  Skipped — existing ${file.replace(options.outDir + "/", "")} preserved.`);
+				continue;
+			}
+		}
+		await writeFileSafe(file, render());
+		written.push(file);
+	}
+	return written;
+}
+//#endregion
 //#region src/generators/auth-scaffold.ts
 /**
 * Generate a complete auth module with registration, login, logout,
@@ -4441,7 +4994,7 @@ import type { RequestContext } from '@forinda/kickjs'
 import { Autowired } from '@forinda/kickjs'
 import { AuthService } from './auth.service'
 
-@Controller('/auth')
+@Controller()
 @Authenticated()
 export class AuthController {
   @Autowired() private authService!: AuthService
@@ -4523,7 +5076,7 @@ import type { RequestContext } from '@forinda/kickjs'
 import { Autowired } from '@forinda/kickjs'
 import { AuthService } from './auth.service'
 
-@Controller('/auth')
+@Controller()
 @Authenticated()
 export class AuthController {
   @Autowired() private authService!: AuthService
@@ -5162,7 +5715,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 genDomainService(pascal, kebab) {
@@ -5318,62 +5871,6 @@ describe('${pascal}', () => {
 	return files;
 }
 //#endregion
-//#region src/config.ts
-const PACKAGE_MANAGERS = [
-	"pnpm",
-	"npm",
-	"yarn",
-	"bun"
-];
-const BUILTIN_REPO_TYPES = [
-	"drizzle",
-	"inmemory",
-	"prisma"
-];
-/** Resolve module config with backward-compatible fallbacks from top-level fields */
-function resolveModuleConfig(config) {
-	if (!config) return {};
-	const mc = {
-		dir: config.modules?.dir ?? config.modulesDir,
-		repo: config.modules?.repo ?? config.defaultRepo,
-		schemaDir: config.modules?.schemaDir ?? config.schemaDir,
-		pluralize: config.modules?.pluralize ?? config.pluralize,
-		prismaClientPath: config.modules?.prismaClientPath
-	};
-	if (mc.repo && typeof mc.repo === "string" && !BUILTIN_REPO_TYPES.includes(mc.repo)) console.warn(`  Warning: modules.repo '${mc.repo}' is not a built-in type (${BUILTIN_REPO_TYPES.join(", ")}). It will generate a stub repository. Use { name: '${mc.repo}' } to silence this warning.`);
-	return mc;
-}
-const CONFIG_FILES = [
-	"kick.config.ts",
-	"kick.config.js",
-	"kick.config.mjs",
-	"kick.config.json"
-];
-/** Load kick.config.* from the project root */
-async function loadKickConfig(cwd) {
-	for (const filename of CONFIG_FILES) {
-		const filepath = join(cwd, filename);
-		try {
-			await access(filepath);
-		} catch {
-			continue;
-		}
-		if (filename.endsWith(".json")) {
-			const content = await readFile(filepath, "utf-8");
-			return JSON.parse(content);
-		}
-		try {
-			const { pathToFileURL } = await import("node:url");
-			const mod = await import(pathToFileURL(filepath).href);
-			return mod.default ?? mod;
-		} 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;
-		}
-	}
-	return null;
-}
-//#endregion
 //#region src/typegen/scanner.ts
 /** Decorators that mark a class as DI-managed */
 const DECORATOR_NAMES = [
@@ -5428,6 +5925,28 @@ const BARE_CREATE_TOKEN_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+
 /** Match `@Inject('literal')` — only literals; computed args are skipped */
 const INJECT_LITERAL_REGEX = /@Inject\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
 /**
+* Match the start of a `defineAdapter(...)` or `definePlugin(...)` call,
+* tolerating optional `<TConfig, TExtra>` generics. Captures the helper
+* name. The callsite's first-arg object is parsed forward via
+* `findBalancedClose` so nested objects/parens don't confuse us.
+*/
+const DEFINE_HELPER_START = /\b(defineAdapter|definePlugin)\s*(?:<[^>]*>)?\s*\(/g;
+/**
+* Match a class declaration whose `implements` clause includes `AppAdapter`.
+* Captures the class name. Used to pick up the (rare, post-defineAdapter)
+* legacy class-style adapters so their literal `name = '...'` field can
+* still feed `KickJsPluginRegistry`.
+*/
+const APP_ADAPTER_CLASS_REGEX = new RegExp(String.raw`export\s+(?:default\s+)?(?:abstract\s+)?class\s+(\w+)` + String.raw`(?:\s+extends\s+\w+(?:<[^>]*>)?)?` + String.raw`\s+implements\s+[^{]*\bAppAdapter\b`, "g");
+/** Match a string-literal `name = '...'` field on a class body. */
+const CLASS_NAME_FIELD_REGEX = /\bname\s*(?::\s*[^=]+)?=\s*['"`]([^'"`]+)['"`]/;
+/**
+* Match the start of a `defineAugmentation('Name', ...)` call. Captures
+* the literal name. The optional second-arg object is parsed forward so
+* `description` / `example` can be pulled out.
+*/
+const DEFINE_AUGMENTATION_START = /\bdefineAugmentation\s*\(\s*['"`]([^'"`]+)['"`]\s*(,\s*\{)?/g;
+/**
 * Locate the start of a route decorator: `@Get(`, `@Post(`, etc.
 * Used by `extractRoutesFromSource`; the rest of the route declaration
 * (balanced parens, stacked decorators, method name) is parsed by walking
@@ -5774,6 +6293,120 @@ function extractInjectsFromSource(source, filePath, cwd) {
 	return out;
 }
 /**
+* Extract the bounds of an object literal that begins at `openBracePos`
+* (the index of the `{` character). Returns the index of the matching `}`
+* or -1 if no match is found. Counts balanced braces only — does not
+* understand string literals so a `{` or `}` inside a string inside the
+* object will skew the depth counter (matches `findBalancedClose`).
+*/
+function findBalancedBrace(text, openBracePos) {
+	let depth = 1;
+	for (let i = openBracePos + 1; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Extract plugins/adapters declared via `defineAdapter({ name: '...' })`
+* or `definePlugin({ name: '...' })` calls and via class-style adapters
+* (`class XxxAdapter implements AppAdapter` with a string-literal `name`
+* field).
+*
+* Only the literal `name:` field feeds the result — the symbol on the LHS
+* is irrelevant since `dependsOn` references the runtime name.
+*/
+function extractPluginsAndAdaptersFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	DEFINE_HELPER_START.lastIndex = 0;
+	let helperMatch;
+	while ((helperMatch = DEFINE_HELPER_START.exec(source)) !== null) {
+		const helper = helperMatch[1];
+		const openParen = DEFINE_HELPER_START.lastIndex - 1;
+		const closeParen = findBalancedClose(source, openParen);
+		if (closeParen < 0) continue;
+		const callArgs = source.slice(openParen + 1, closeParen);
+		const nameMatch = /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(callArgs);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `${helper}::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: helper === "definePlugin" ? "plugin" : "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	APP_ADAPTER_CLASS_REGEX.lastIndex = 0;
+	let classMatch;
+	while ((classMatch = APP_ADAPTER_CLASS_REGEX.exec(source)) !== null) {
+		const classStart = classMatch.index;
+		const bracePos = source.indexOf("{", classStart);
+		if (bracePos < 0) continue;
+		const closeBrace = findBalancedBrace(source, bracePos);
+		if (closeBrace < 0) continue;
+		const body = source.slice(bracePos + 1, closeBrace);
+		const nameMatch = CLASS_NAME_FIELD_REGEX.exec(body);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `class::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Extract `defineAugmentation('Name', { description, example })` calls
+* from a source file. The metadata object is optional — when absent both
+* `description` and `example` resolve to `null`.
+*/
+function extractAugmentationsFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	DEFINE_AUGMENTATION_START.lastIndex = 0;
+	let match;
+	while ((match = DEFINE_AUGMENTATION_START.exec(source)) !== null) {
+		const name = match[1];
+		let description = null;
+		let example = null;
+		if (match[2]) {
+			const bracePos = source.indexOf("{", match.index + match[0].length - 1);
+			if (bracePos >= 0) {
+				const closeBrace = findBalancedBrace(source, bracePos);
+				if (closeBrace >= 0) {
+					const body = source.slice(bracePos + 1, closeBrace);
+					const descMatch = /\bdescription\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					const exampleMatch = /\bexample\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					description = descMatch ? descMatch[1] : null;
+					example = exampleMatch ? exampleMatch[1] : null;
+				}
+			}
+		}
+		out.push({
+			name,
+			description,
+			example,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
 * Default search order for the env schema file. Newer projects keep
 * the schema under `src/config/` so the framework's "config" concept
 * has a single home; older scaffolds dropped it at `src/env.ts` (kept
@@ -5844,6 +6477,8 @@ async function scanProject(opts) {
 	const routes = [];
 	const tokens = [];
 	const injects = [];
+	const pluginsAndAdapters = [];
+	const augmentations = [];
 	const sources = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let source;
@@ -5856,6 +6491,8 @@ async function scanProject(opts) {
 		classes.push(...extractClassesFromSource(source, file, opts.cwd));
 		tokens.push(...extractTokensFromSource(source, file, opts.cwd));
 		injects.push(...extractInjectsFromSource(source, file, opts.cwd));
+		pluginsAndAdapters.push(...extractPluginsAndAdaptersFromSource(source, file, opts.cwd));
+		augmentations.push(...extractAugmentationsFromSource(source, file, opts.cwd));
 	}
 	for (const [file, source] of sources) {
 		const classesInFile = classes.filter((c) => c.filePath === file);
@@ -5868,15 +6505,148 @@ async function scanProject(opts) {
 	tokens.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	injects.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	routes.sort((a, b) => a.controller.localeCompare(b.controller) || a.method.localeCompare(b.method));
+	pluginsAndAdapters.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	augmentations.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	return {
 		classes,
 		routes,
 		tokens,
 		injects,
 		collisions: findCollisions(classes),
-		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts")
+		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts"),
+		pluginsAndAdapters,
+		augmentations
+	};
+}
+//#endregion
+//#region src/typegen/asset-types.ts
+/**
+* Walks every `assetMap` entry's source directory + emits a typed
+* `KickAssets` ambient augmentation (assets-plan.md PR 4). Generates
+* `.kickjs/types/assets.d.ts` so adopters get autocomplete on
+* `assets.<namespace>.<key>` and `@Asset('<namespace>/<key>')`.
+*
+* Pure module — no side effects beyond what the caller does with the
+* returned content. Mirrors the shape of `renderPlugins` /
+* `renderRegistry` in the generator so the typegen output stays
+* consistent across surfaces.
+*
+* @module @forinda/kickjs-cli/typegen/asset-types
+*/
+function discoverAssets(assetMap, cwd) {
+	if (!assetMap) return {
+		entries: [],
+		count: 0
+	};
+	const seen = /* @__PURE__ */ new Map();
+	for (const [namespace, entry] of Object.entries(assetMap)) {
+		if (!entry || typeof entry.src !== "string") continue;
+		const srcAbs = resolve(cwd, entry.src);
+		if (!isDir(srcAbs)) continue;
+		const matches = globSync(entry.glob ?? "**/*", {
+			cwd: srcAbs,
+			nodir: true,
+			dot: false,
+			posix: true
+		});
+		matches.sort();
+		for (const rel of matches) {
+			const key = stripExt$1(rel);
+			const logical = `${namespace}/${key}`;
+			seen.set(logical, {
+				namespace,
+				key
+			});
+		}
+	}
+	return {
+		entries: [...seen.values()],
+		count: seen.size
 	};
 }
+function renderAssetTypes(discovered) {
+	const HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+	if (discovered.entries.length === 0) return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * (No assetMap entries discovered yet — declare with
+   *  \`assetMap: { name: { src: 'src/...' } }\` in kick.config.ts.)
+   */
+  interface KickAssets {}
+}
+
+export {}
+`;
+	const tree = {};
+	for (const entry of discovered.entries) {
+		const path = `${entry.namespace}/${entry.key}`.split("/");
+		let node = tree;
+		for (let i = 0; i < path.length - 1; i++) {
+			const part = path[i];
+			const existing = node[part];
+			if (existing === LEAF) {
+				const promoted = {};
+				node[part] = promoted;
+				node = promoted;
+			} else {
+				if (!existing) node[part] = {};
+				node = node[part];
+			}
+		}
+		const leaf = path[path.length - 1];
+		if (typeof node[leaf] === "object") continue;
+		node[leaf] = LEAF;
+	}
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * Each leaf is a \`() => string\` thunk that returns the resolved
+   * absolute path for the file in the current run mode (dev → src,
+   * prod → dist).
+   */
+  interface KickAssets {
+${renderTree(tree, "    ")}
+  }
+}
+
+export {}
+`;
+}
+const LEAF = Symbol("asset-leaf");
+function renderTree(node, indent) {
+	const keys = Object.keys(node).sort();
+	const lines = [];
+	for (const key of keys) {
+		const child = node[key];
+		const safeKey = isIdentifier(key) ? key : JSON.stringify(key);
+		if (child === LEAF) lines.push(`${indent}${safeKey}: () => string`);
+		else {
+			lines.push(`${indent}${safeKey}: {`);
+			lines.push(renderTree(child, `${indent}  `));
+			lines.push(`${indent}}`);
+		}
+	}
+	return lines.join("\n");
+}
+function isIdentifier(str) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(str);
+}
+function isDir(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function stripExt$1(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
+}
 //#endregion
 //#region src/typegen/generator.ts
 /**
@@ -6013,12 +6783,17 @@ function renderIndex(includeEnv) {
 export type { ServiceToken } from './services'
 export type { ModuleToken } from './modules'
 
-// The registry, routes, and env augmentations are loaded as side-effects —
-// importing this file (or having it on tsconfig include) is enough for
-// \`container.resolve()\`, \`Ctx<KickRoutes.UserController['getUser']>\`,
-// and \`@Value('PORT')\` to resolve.
+// The registry, routes, plugins, assets, and env augmentations are
+// loaded as side-effects — importing this file (or having it on
+// tsconfig include) is enough for \`container.resolve()\`,
+// \`Ctx<KickRoutes.UserController['getUser']>\`,
+// \`dependsOn: ['TenantAdapter']\`, \`assets.mails.welcome()\`, and
+// \`@Value('PORT')\` to resolve.
 import './registry'
 import './routes'
+import './plugins'
+import './augmentations'
+import './assets'
 ${includeEnv ? "import './env'\n" : ""}`;
 }
 /**
@@ -6213,9 +6988,94 @@ ${interfaces.join("\n")}
 export {}
 `;
 }
+/**
+* Render the `KickJsPluginRegistry` augmentation. Each entry maps the
+* literal `name` field of a plugin/adapter to a marker type (the
+* registry value isn't load-bearing at runtime — `dependsOn` only cares
+* about `keyof`, so any non-`never` type works). We emit `'plugin'` /
+* `'adapter'` strings so DevTools can later read the registry to tell
+* the kinds apart without a second source of truth.
+*
+* When the project has no discoverable plugins/adapters, the augmentation
+* is intentionally empty rather than skipped so the `keyof` constraint
+* resolves to `never` (which is harmless — `dependsOn: []` still works).
+*/
+function renderPlugins(items) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const entries = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)).map((item) => `    '${item.name}': '${item.kind}'`).join("\n");
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every plugin/adapter \`name\` discovered in the project. The
+   * value type is the kind tag (\`'plugin'\` or \`'adapter'\`); the
+   * \`keyof\` of this interface narrows \`dependsOn\` so misspelled deps
+   * become compile errors instead of boot-time \`MissingMountDepError\`.
+   */
+  interface KickJsPluginRegistry {
+${entries ? entries : "    // (no plugins/adapters discovered yet — `defineAdapter`/`definePlugin` calls feed this)"}
+  }
+}
+
+export {}
+`;
+}
+/**
+* Render the augmentation manifest — one block per `defineAugmentation`
+* call discovered in the project. The output is a `.d.ts` file that
+* does nothing at runtime but acts as in-IDE documentation: adopters
+* jumping into it see every interface their plugins offer for
+* augmentation, alongside any `description` / `example` the plugin
+* authors provided.
+*/
+function renderAugmentations(items) {
+	if (items.length === 0) return `${HEADER}
+// No augmentations discovered.
+//
+// Plugins advertise augmentable interfaces via:
+//
+//   import { defineAugmentation } from '@forinda/kickjs'
+//   defineAugmentation('FeatureFlags', {
+//     description: 'Feature flag shape consumed by FlagsPlugin',
+//     example: '{ beta: boolean; rolloutPercentage: number }',
+//   })
+//
+// See \`docs/guide/typegen.md#augmentations\` for the full pattern.
+export {}
+`;
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const blocks = [];
+	for (const item of [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))) {
+		const docLines = [];
+		if (item.description) for (const line of item.description.split("\n")) docLines.push(` * ${line}`);
+		if (item.example) {
+			docLines.push(` * @example`, ` * \`\`\`ts`);
+			for (const line of item.example.split("\n")) docLines.push(` * ${line}`);
+			docLines.push(` * \`\`\``);
+		}
+		docLines.push(` * @see ${item.relativePath}`);
+		blocks.push([
+			"/**",
+			...docLines,
+			" */",
+			`export interface ${item.name}Augmentation {}`
+		].join("\n"));
+	}
+	return `${HEADER}
+// Catalogue of augmentable interfaces in this project. The interfaces
+// below are documentation only — augment the source-of-truth interfaces
+// in your own \`d.ts\` files (the framework declares the actual types).
+
+${blocks.join("\n\n")}
+`;
+}
 /** Write all generated `.d.ts` files to `outDir` */
 async function generateTypes(opts) {
-	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, outDir, allowDuplicates = false, schemaValidator = false } = opts;
+	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, pluginsAndAdapters = [], augmentations = [], assets = {
+		entries: [],
+		count: 0
+	}, outDir, allowDuplicates = false, schemaValidator = false } = opts;
 	if (collisions.length > 0 && !allowDuplicates) throw new TokenCollisionError(collisions);
 	await mkdir(outDir, { recursive: true });
 	const registryFile = join(outDir, "registry.d.ts");
@@ -6223,6 +7083,9 @@ async function generateTypes(opts) {
 	const modulesFile = join(outDir, "modules.d.ts");
 	const routesFile = join(outDir, "routes.ts");
 	const envFile = join(outDir, "env.ts");
+	const pluginsFile = join(outDir, "plugins.d.ts");
+	const augmentationsFile = join(outDir, "augmentations.d.ts");
+	const assetsFile = join(outDir, "assets.d.ts");
 	const indexFile = join(outDir, "index.d.ts");
 	const collidingNames = new Set(collisions.map((c) => c.className));
 	const registryContent = renderRegistry(classes, registryFile, collidingNames);
@@ -6239,17 +7102,26 @@ async function generateTypes(opts) {
 	const modulesContent = renderUnion("ModuleToken", modules, "(no @Module classes discovered — `kick g module <name>` to add one)");
 	const routesContent = renderRoutes(routes, routesFile, schemaValidator);
 	const envContent = renderEnv(env, envFile);
+	const pluginsContent = renderPlugins(pluginsAndAdapters);
+	const augmentationsContent = renderAugmentations(augmentations);
+	const assetsContent = renderAssetTypes(assets);
 	const indexContent = renderIndex(envContent !== null);
 	await writeFile(registryFile, registryContent, "utf-8");
 	await writeFile(servicesFile, servicesContent, "utf-8");
 	await writeFile(modulesFile, modulesContent, "utf-8");
 	await writeFile(routesFile, routesContent, "utf-8");
+	await writeFile(pluginsFile, pluginsContent, "utf-8");
+	await writeFile(augmentationsFile, augmentationsContent, "utf-8");
+	await writeFile(assetsFile, assetsContent, "utf-8");
 	await writeFile(indexFile, indexContent, "utf-8");
 	const written = [
 		registryFile,
 		servicesFile,
 		modulesFile,
 		routesFile,
+		pluginsFile,
+		augmentationsFile,
+		assetsFile,
 		indexFile
 	];
 	if (envContent) {
@@ -6257,17 +7129,62 @@ async function generateTypes(opts) {
 		written.push(envFile);
 	}
 	await writeFile(join(dirname(outDir), ".gitignore"), "# Auto-generated by kick typegen\n*\n", "utf-8");
+	const uniquePluginNames = new Set(pluginsAndAdapters.map((p) => p.name)).size;
+	const uniqueAugmentations = new Set(augmentations.map((a) => a.name)).size;
 	return {
 		registryEntries: classTokens.length,
 		serviceTokens: new Set(allServices).size,
 		moduleTokens: modules.length,
 		routeEntries: routes.length,
+		pluginEntries: uniquePluginNames,
+		augmentationEntries: uniqueAugmentations,
+		assetEntries: assets.count,
 		envWritten: envContent !== null,
 		written,
 		resolvedCollisions: collisions.length
 	};
 }
 //#endregion
+//#region src/typegen/token-conventions.ts
+/**
+* Regex for the §22.2 token shape. Breakdown:
+*
+* - `^(kick\/)?` — optional reserved framework prefix.
+* - `([a-z][\w-]*\/[A-Z]\w*)` — `<scope>/<PascalKey>`. Scope is
+*   lowercase, key is PascalCase.
+* - `(\/.+)?` — optional `/suffix` for sub-flavours
+*   (e.g. `mycorp/Cache/redis`).
+* - `(:[a-z][\w-]+(:[a-z][\w-]+)*)?` — optional `:instance` (and
+*   further `:extra` colon-sections) for `.scoped()` shards.
+*/
+const TOKEN_CONVENTION_REGEX = /^(kick\/)?([a-z][\w-]*\/[A-Z]\w*)(\/.+)?(:[a-z][\w-]+(:[a-z][\w-]+)*)?$/;
+const LEGACY_PREFIX = "kickjs.";
+function validateTokenConventions(tokens) {
+	const warnings = [];
+	for (const token of tokens) {
+		const name = token.name;
+		if (name.startsWith(LEGACY_PREFIX)) continue;
+		if (TOKEN_CONVENTION_REGEX.test(name)) continue;
+		warnings.push({
+			token: name,
+			variable: token.variable,
+			filePath: token.relativePath,
+			reason: "does not match `<scope>/<PascalKey>[/<suffix>][:<instance>]`",
+			suggestion: suggestRename(name)
+		});
+	}
+	return warnings;
+}
+function suggestRename(name) {
+	if (/^[A-Z]\w*$/.test(name)) return `'<scope>/${name}' (e.g. 'mycorp/${name}')`;
+	if (name.includes(".")) return `consider '<scope>/PascalKey' instead of dotted form`;
+	const slashLower = /^([a-z][\w-]*)\/([a-z]\w*)$/.exec(name);
+	if (slashLower) {
+		const [, scope, key] = slashLower;
+		return `'${scope}/${key.charAt(0).toUpperCase()}${key.slice(1)}'`;
+	}
+}
+//#endregion
 //#region src/typegen/index.ts
 /**
 * Public entry point for the KickJS typegen module.
@@ -6312,6 +7229,7 @@ async function runTypegen(opts = {}) {
 		cwd,
 		envFile: envFile === false ? void 0 : envFile
 	});
+	const assets = discoverAssets(opts.assetMap, cwd);
 	const result = await generateTypes({
 		classes: scan.classes,
 		routes: scan.routes,
@@ -6319,20 +7237,36 @@ async function runTypegen(opts = {}) {
 		injects: scan.injects,
 		collisions: scan.collisions,
 		env: envFile === false ? null : scan.env,
+		pluginsAndAdapters: scan.pluginsAndAdapters,
+		augmentations: scan.augmentations,
+		assets,
 		outDir,
 		allowDuplicates,
 		schemaValidator
 	});
+	const tokenWarnings = validateTokenConventions(scan.tokens);
 	const elapsed = Date.now() - start;
 	if (!silent) {
 		const where = outDir.replace(cwd + "/", "");
 		const collisionNote = result.resolvedCollisions > 0 ? `, ${result.resolvedCollisions} collisions namespaced` : "";
 		const envNote = result.envWritten ? ", env typed" : "";
-		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		const pluginNote = result.pluginEntries > 0 ? `, ${result.pluginEntries} plugins/adapters` : "";
+		const augNote = result.augmentationEntries > 0 ? `, ${result.augmentationEntries} augmentations` : "";
+		const assetNote = result.assetEntries > 0 ? `, ${result.assetEntries} assets` : "";
+		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${pluginNote}${augNote}${assetNote}${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		if (tokenWarnings.length > 0) {
+			console.warn(`  kick typegen: ${tokenWarnings.length} token(s) don't match the §22.2 convention:`);
+			for (const warning of tokenWarnings) {
+				const variableNote = warning.variable ? ` [${warning.variable}]` : "";
+				console.warn(`    '${warning.token}' (${warning.filePath})${variableNote} — ${warning.reason}`);
+				if (warning.suggestion) console.warn(`      → suggestion: ${warning.suggestion}`);
+			}
+		}
 	}
 	return {
 		scan,
-		result
+		result,
+		tokenWarnings
 	};
 }
 /**
@@ -6405,6 +7339,13 @@ async function safeRun(opts, silent) {
 }
 //#endregion
 //#region src/commands/generate.ts
+const AGENT_DOCS_ONLY_VALUES = [
+	"agents",
+	"claude",
+	"skills",
+	"both",
+	"all"
+];
 /** Check if --dry-run was passed on the parent generate command */
 function isDryRun(cmd) {
 	return (cmd.parent?.opts())?.dryRun ?? false;
@@ -6487,12 +7428,29 @@ const GENERATORS = [
 	{
 		name: "config",
 		description: "Generate kick.config.ts"
+	},
+	{
+		name: "agents",
+		description: "Regenerate AGENTS.md + CLAUDE.md + kickjs-skills.md from upstream templates"
 	}
 ];
-function printGeneratorList() {
-	console.log("\n  Available generators:\n");
+async function printGeneratorList() {
+	console.log("\n  Built-in generators:\n");
 	const maxName = Math.max(...GENERATORS.map((g) => g.name.length));
 	for (const g of GENERATORS) console.log(`    kick g ${g.name.padEnd(maxName + 2)} ${g.description}`);
+	const discovery = await listPluginGenerators(process.cwd());
+	if (discovery.generators.length > 0) {
+		console.log("\n  Plugin generators:\n");
+		const pluginMax = Math.max(...discovery.generators.map((g) => `${g.spec.name} <name>`.length));
+		for (const { source, spec } of discovery.generators) {
+			const usage = `${spec.name} <name>`;
+			console.log(`    kick g ${usage.padEnd(pluginMax + 2)} ${spec.description}  [${source}]`);
+		}
+	}
+	if (discovery.failed.length > 0) {
+		console.log("\n  Failed to load:\n");
+		for (const { source, reason } of discovery.failed) console.log(`    ${source} — ${reason}`);
+	}
 	console.log();
 }
 /**
@@ -6529,7 +7487,7 @@ async function runModuleGeneration(names, opts, dryRun) {
 function registerGenerateCommand(program) {
 	const gen = program.command("generate [names...]").alias("g").description("Generate code scaffolds — bare form `kick g <name>` is shorthand for `kick g module <name>`").option("--list", "List all available generators").option("--dry-run", "Preview files that would be generated without writing them").option("--no-entity", "Skip entity and value object generation (module shortcut)").option("--no-tests", "Skip test file generation (module shortcut)").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("-f, --force", "Overwrite existing files without prompting").action(async (names, opts, cmd) => {
 		if (opts.list) {
-			printGeneratorList();
+			await printGeneratorList();
 			return;
 		}
 		if (!names || names.length === 0) {
@@ -6538,6 +7496,20 @@ function registerGenerateCommand(program) {
 		}
 		const dryRun = isDryRun(cmd);
 		setDryRun(dryRun);
+		if (names.length >= 2) {
+			const [generatorName, itemName, ...rest] = names;
+			const result = await tryDispatchPluginGenerator({
+				generatorName,
+				itemName,
+				args: rest,
+				flags: opts,
+				cwd: process.cwd()
+			});
+			if (result) {
+				printGenerated(result.files, dryRun);
+				return;
+			}
+		}
 		await runModuleGeneration(names, opts, dryRun);
 	});
 	gen.command("module <names...>").description("Generate one or more modules (e.g. kick g module user task project)").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("--no-pluralize", "Use singular names (skip auto-pluralization)").option("-f, --force", "Overwrite existing files without prompting").action(async (names, opts, cmd) => {
@@ -6727,6 +7699,24 @@ function registerGenerateCommand(program) {
 			force: opts.force
 		}), dryRun);
 	});
+	gen.command("agents").alias("agent-docs").alias("ai-docs").description("Regenerate AGENTS.md + CLAUDE.md + kickjs-skills.md (sync after framework upgrades)").option("--only <which>", "Limit scope: agents | claude | skills | both (agents+claude) | all (default: all)", "all").option("--name <name>", "Project name (defaults to package.json name)").option("--pm <pm>", "Package manager (defaults to package.json packageManager)").option("--template <template>", "Template: rest | graphql | ddd | cqrs | minimal").option("-f, --force", "Overwrite existing files without prompting").action(async (opts, cmd) => {
+		const dryRun = isDryRun(cmd);
+		setDryRun(dryRun);
+		const only = opts.only ?? "all";
+		if (!AGENT_DOCS_ONLY_VALUES.includes(only)) {
+			console.error(`  Invalid --only value: ${only}. Expected: ${AGENT_DOCS_ONLY_VALUES.join(" | ")}`);
+			process.exitCode = 1;
+			return;
+		}
+		printGenerated(await generateAgentDocs({
+			outDir: resolve("."),
+			only,
+			name: opts.name,
+			pm: opts.pm,
+			template: opts.template,
+			force: opts.force
+		}), dryRun);
+	});
 }
 //#endregion
 //#region src/utils/shell.ts
@@ -6767,6 +7757,132 @@ function runNodeWithEnv(entry, env, cwd) {
 	});
 	if (result.status !== 0) process.exit(result.status ?? 1);
 }
+/**
+* Run the full asset build for a loaded config:
+*
+* 1. For each `assetMap` entry, glob → copy → manifest stub.
+* 2. Write `dist/.kickjs-assets.json`.
+*
+* Returns a summary including the manifest contents. No-op (and no
+* manifest written) when `assetMap` is empty / missing — the build
+* pipeline shouldn't litter `dist/` with empty manifests for
+* adopters who don't use the feature.
+*/
+async function buildAssets(config, opts) {
+	const { cwd, silent = false } = opts;
+	const distDir = opts.distDir ?? config?.build?.outDir ?? "dist";
+	const map = config?.assetMap;
+	if (!map || Object.keys(map).length === 0) return null;
+	const log = silent ? () => {} : console.log;
+	const distAbs = resolve(cwd, distDir);
+	mkdirSync(distAbs, { recursive: true });
+	const summary = [];
+	const manifestEntries = {};
+	for (const [namespace, entry] of Object.entries(map)) {
+		const result = await processEntry(namespace, entry, cwd, distAbs);
+		summary.push(result.entrySummary);
+		Object.assign(manifestEntries, result.manifestSlice);
+		log(`    ✓ ${namespace}: ${result.entrySummary.filesCopied} file(s) → ${result.entrySummary.dest}`);
+	}
+	const manifest = {
+		version: 1,
+		entries: manifestEntries
+	};
+	const manifestPath = join(distAbs, ".kickjs-assets.json");
+	writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+	log(`    ✓ wrote manifest → ${relative(cwd, manifestPath)} (${Object.keys(manifestEntries).length} entries)`);
+	return {
+		manifestPath,
+		entries: summary,
+		manifest
+	};
+}
+/** Per-entry inner pipeline — extracted for unit-test reuse. */
+async function processEntry(namespace, entry, cwd, distAbs) {
+	const srcAbs = resolve(cwd, entry.src);
+	const destAbs = entry.dest ? resolve(cwd, entry.dest) : join(distAbs, namespace);
+	if (escapesRoot(destAbs, cwd)) {
+		console.warn(`  ⚠ assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — skipping copy`);
+		return {
+			entrySummary: {
+				namespace,
+				src: entry.src,
+				dest: relative(cwd, destAbs),
+				filesCopied: 0
+			},
+			manifestSlice: {}
+		};
+	}
+	if (!existsSync(srcAbs) || !isDirectorySync(srcAbs)) return {
+		entrySummary: {
+			namespace,
+			src: entry.src,
+			dest: relative(cwd, destAbs),
+			filesCopied: 0
+		},
+		manifestSlice: {}
+	};
+	const matches = await glob(entry.glob ?? "**/*", {
+		cwd: srcAbs,
+		nodir: true,
+		dot: false,
+		posix: true
+	});
+	mkdirSync(destAbs, { recursive: true });
+	const manifestSlice = {};
+	const keyOwner = /* @__PURE__ */ new Map();
+	for (const relPath of matches.sort()) {
+		const srcFile = join(srcAbs, relPath);
+		const destFile = join(destAbs, relPath);
+		mkdirSync(dirname(destFile), { recursive: true });
+		cpSync(srcFile, destFile);
+		const logicalKey = `${namespace}/${stripExt(relPath)}`;
+		const previous = keyOwner.get(logicalKey);
+		if (previous) console.warn(`  ⚠ assetMap collision in '${namespace}': '${previous}' and '${relPath}' both flatten to key '${logicalKey}'. Last-alphabetical wins ('${relPath}'). Rename one of them or set assetMap.${namespace}.glob to filter by extension.`);
+		keyOwner.set(logicalKey, relPath);
+		manifestSlice[logicalKey] = toManifestRelative(distAbs, destFile);
+	}
+	return {
+		entrySummary: {
+			namespace,
+			src: entry.src,
+			dest: relative(cwd, destAbs),
+			filesCopied: matches.length
+		},
+		manifestSlice
+	};
+}
+/** Strip the final extension from a file path (`mails/welcome.ejs` → `mails/welcome`). */
+function stripExt(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
+}
+/**
+* Make `destFile` relative to the manifest's directory + force POSIX
+* separators so the manifest is byte-stable across platforms.
+*/
+function toManifestRelative(manifestDir, destFile) {
+	return relative(manifestDir, destFile).split(/[\\/]/).filter(Boolean).join("/");
+}
+/**
+* Project-root escape check that's safe across symlinks + drive letters.
+* `path.relative` returns `..` segments when the target sits above root,
+* and an absolute path when the two live on different roots (Windows).
+* `startsWith(root)` would miss both cases.
+*/
+function escapesRoot(path, root) {
+	const rel = relative(root, path);
+	if (rel === "") return false;
+	return rel.startsWith("..") || isAbsolute(rel);
+}
+/** Pure helper — `false` for missing, non-dir, or unreadable paths. */
+function isDirectorySync(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
 //#endregion
 //#region src/commands/run.ts
 /**
@@ -6795,7 +7911,8 @@ async function startDevServer(_entry, port) {
 			schemaValidator,
 			envFile,
 			srcDir: devConfig?.typegen?.srcDir,
-			outDir: devConfig?.typegen?.outDir
+			outDir: devConfig?.typegen?.outDir,
+			assetMap: devConfig?.assetMap
 		});
 	} catch (err) {
 		console.warn(`  kick typegen: skipped (${err?.message ?? err})`);
@@ -6806,11 +7923,15 @@ async function startDevServer(_entry, port) {
 		configFile: resolve("vite.config.ts"),
 		server: { port: port ? parseInt(port, 10) : void 0 }
 	});
+	const assetSrcRoots = devConfig?.assetMap ? Object.values(devConfig.assetMap).map((entry) => entry?.src).filter((src) => typeof src === "string" && src.length > 0).map((src) => resolve(cwd, src)) : [];
+	const isAssetFile = (file) => assetSrcRoots.some((root) => file === root || file.startsWith(`${root}/`));
 	let typegenTimer = null;
 	const scheduleTypegen = (file) => {
-		if (!/\.(ts|tsx|mts|cts)$/.test(file)) return;
 		if (file.includes(".kickjs")) return;
 		if (file.endsWith(".d.ts")) return;
+		const isTs = /\.(ts|tsx|mts|cts)$/.test(file);
+		const isAsset = isAssetFile(file);
+		if (!isTs && !isAsset) return;
 		if (typegenTimer) clearTimeout(typegenTimer);
 		typegenTimer = setTimeout(() => {
 			runTypegen({
@@ -6820,13 +7941,15 @@ async function startDevServer(_entry, port) {
 				schemaValidator,
 				envFile,
 				srcDir: devConfig?.typegen?.srcDir,
-				outDir: devConfig?.typegen?.outDir
+				outDir: devConfig?.typegen?.outDir,
+				assetMap: devConfig?.assetMap
 			}).catch(() => {});
 		}, 100);
 	};
 	server.watcher.on("add", scheduleTypegen);
 	server.watcher.on("unlink", scheduleTypegen);
 	server.watcher.on("change", scheduleTypegen);
+	if (assetSrcRoots.length > 0) server.watcher.add(assetSrcRoots);
 	await server.listen();
 	server.printUrls();
 	console.log(`\n  KickJS dev server running (Vite + @forinda/kickjs-vite)\n`);
@@ -6853,7 +7976,8 @@ function registerRunCommands(program) {
 		const { createRequire } = await import("node:module");
 		const { build } = await import(pathToFileURL(createRequire(resolve("package.json")).resolve("vite")).href);
 		await build({ configFile: resolve("vite.config.ts") });
-		const copyDirs = (await loadKickConfig(process.cwd()))?.copyDirs ?? [];
+		const config = await loadKickConfig(process.cwd());
+		const copyDirs = config?.copyDirs ?? [];
 		if (copyDirs.length > 0) {
 			console.log("\n  Copying directories to dist...");
 			for (const entry of copyDirs) {
@@ -6870,8 +7994,32 @@ function registerRunCommands(program) {
 				console.log(`    ✓ ${src} → ${dest}`);
 			}
 		}
+		if (config?.assetMap && Object.keys(config.assetMap).length > 0) {
+			console.log("\n  Building asset map...");
+			try {
+				await buildAssets(config, { cwd: process.cwd() });
+			} catch (err) {
+				console.error(`    ✗ asset build failed: ${err instanceof Error ? err.message : String(err)}`);
+				process.exit(1);
+			}
+		}
 		console.log("\n  Build complete.\n");
 	});
+	program.command("build:assets").description("Rebuild the .kickjs-assets.json manifest under the configured outDir (no JS rebuild)").action(async () => {
+		const config = await loadKickConfig(process.cwd());
+		if (!config?.assetMap || Object.keys(config.assetMap).length === 0) {
+			console.log("  No assetMap entries — nothing to build.");
+			return;
+		}
+		console.log("\n  Building asset map...");
+		try {
+			await buildAssets(config, { cwd: process.cwd() });
+			console.log("\n  Asset build complete.\n");
+		} catch (err) {
+			console.error(`  ✗ ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(1);
+		}
+	});
 	program.command("start").description("Start production server").option("-e, --entry <file>", "Entry file", "dist/index.js").option("-p, --port <port>", "Port number").action((opts) => {
 		const env = { NODE_ENV: "production" };
 		if (opts.port) env.PORT = String(opts.port);
@@ -6903,7 +8051,6 @@ function registerInfoCommand(program) {
   Packages:
     @forinda/kickjs          workspace
     @forinda/kickjs-vite     workspace
-    @forinda/kickjs-config   workspace
     @forinda/kickjs-cli      workspace
 `);
 	});
@@ -8141,7 +9288,8 @@ function registerTypegenCommand(program) {
 			silent: opts.silent,
 			allowDuplicates: opts.allowDuplicates,
 			schemaValidator,
-			envFile
+			envFile,
+			assetMap: config?.assetMap
 		};
 		try {
 			if (opts.watch) {