@forinda/kickjs-cli 4.0.0 → 4.1.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v4.0.0
+ * @forinda/kickjs-cli v4.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -38,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) {
@@ -115,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);
@@ -709,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()
-export class UserController {
-  @Get('/')
-  async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
-    return ctx.json({ users: [] })
-  }
-
-  @Post('/')
-  async create(ctx: Ctx<KickRoutes.UserController['create']>) {
-    const data = ctx.body
-    return ctx.created({ user: data })
-  }
-}
-\`\`\`
-
-### Services
-
-Inject dependencies with \`@Service()\` and \`@Autowired()\`:
-
-\`\`\`ts
-import { Service, Autowired } from '@forinda/kickjs'
-
-@Service()
-export class UserService {
-  @Autowired()
-  private userRepository!: UserRepository
-
-  async findAll() {
-    return this.userRepository.findAll()
-  }
-}
-\`\`\`
-
-### Modules
-
-Modules implement \`AppModule\` and wire controllers via \`buildRoutes()\`.
-
-> **Naming matters.** Module files **must** be named \`<name>.module.ts\` and live under \`src/modules/\`. The Vite plugin auto-discovers files matching \`*.module.[tj]sx?\` for HMR — a misnamed file (e.g., \`projects.ts\`) won't trigger a graceful module rebuild on save and will require a full server restart. The CLI generator (\`kick g module <name>\`) follows this convention automatically.
-
-\`\`\`ts
-// src/modules/users/users.module.ts   (named <feature>.module.ts)
-import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
-import { UserController } from './user.controller'
-
-export class UserModule implements AppModule {
-  routes(): ModuleRoutes {
-    return {
-      path: '/users',
-      router: buildRoutes(UserController),
-      controller: UserController,
-    }
-  }
-}
-\`\`\`
-
-Register all modules in \`src/modules/index.ts\`:
-
-\`\`\`ts
-import type { AppModuleClass } from '@forinda/kickjs'
-import { UserModule } from './user/user.module'
-
-export const modules: AppModuleClass[] = [UserModule]
-\`\`\`
-
-### RequestContext
-
-Every controller method receives a \`ctx\` (alias \`Ctx<TRoute>\` or the
-loose \`RequestContext\`):
-
-\`\`\`ts
-ctx.body           // Request body (parsed JSON)
-ctx.params         // Route params
-ctx.query          // Query string
-ctx.headers        // Request headers
-ctx.requestId      // Auto-generated request ID
-ctx.session        // Session data (if session middleware enabled)
-ctx.file           // Uploaded file (single)
-ctx.files          // Uploaded files (multiple)
-
-// Pagination helpers
-ctx.qs(config)           // Parse query with filters/sort/pagination
-ctx.paginate(handler)     // Auto-paginated response
-
-// Response helpers
-ctx.json(data)            // 200 OK with JSON
-ctx.created(data)         // 201 Created
-ctx.noContent()           // 204 No Content
-ctx.notFound()            // 404 Not Found
-ctx.badRequest(msg)       // 400 Bad Request
-\`\`\`
-
-> **Context decorators** — when a middleware's only job is to populate \`ctx.set/get\` for the handler to read, prefer \`defineContextDecorator()\` over \`@Middleware()\`. Typed via \`ContextMeta\`, supports \`dependsOn\` ordering, validates the pipeline at boot. Full pattern reference in \`AGENTS.md\` and at <https://forinda.github.io/kick-js/guide/context-decorators>.
-
-## CLI Generators
-
-Generate code with the \`kick\` CLI:
-
-\`\`\`bash
-kick g module <name>              # Full module (controller, service, DTOs, repo)
-kick g scaffold <name> <fields>   # CRUD module from field definitions
-kick g controller <name>          # Standalone controller
-kick g service <name>             # Service class
-kick g middleware <name>          # Express middleware
-kick g guard <name>               # Route guard (auth, roles)
-kick g adapter <name>             # AppAdapter with lifecycle hooks
-kick g dto <name>                 # Zod DTO schema
-${template === "graphql" ? "kick g resolver <name>           # GraphQL resolver\n" : ""}${template === "cqrs" ? "kick g job <name>                # Queue job processor\n" : ""}\`\`\`
-
-## Adding Packages
+/**
+* Generate CLAUDE.md.
+*
+* v4 update: this file is intentionally thin. AGENTS.md is the
+* canonical, multi-agent project reference (Claude / Copilot /
+* Codex / Gemini / etc.) — duplicating it here meant two files
+* drifting out of sync after every framework change. The generated
+* CLAUDE.md now redirects there + adds Claude-specific affordances
+* only.
+*/
+function generateClaude(name, _template, pm) {
+	return `# CLAUDE.md — ${name}
+
+**Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
+reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
+project conventions, structure, decorator patterns, env wiring, CLI
+generators, every gotcha.
+
+**Then read \`./kickjs-skills.md\`.** That file is the task-oriented
+skill index — short, rigid recipes keyed to triggers ("add-module",
+"write-controller-test", "bootstrap-export", "deny-list", …). Use it
+as the playbook when executing common KickJS workflows.
+
+This file is a thin Claude-specific layer on top of those two; when
+they disagree on anything substantive, treat \`AGENTS.md\` as
+authoritative and flag the discrepancy.
+
+## Why two files
+
+\`AGENTS.md\` is what every agent reads. \`CLAUDE.md\` is what
+Claude Code automatically loads as project context on each
+conversation. Keeping CLAUDE.md slim avoids two files drifting; the
+redirect above ensures Claude pulls the canonical content without
+us copy-pasting.
+
+## Claude-specific notes
+
+- **Slash commands** — \`/help\` for Claude Code commands; \`/init\`
+  to refresh project memory if AGENTS.md changes substantially.
+- **Feedback** — file issues at <https://github.com/anthropics/claude-code/issues>.
+- **Persistent memory** — Claude maintains user/feedback/project/
+  reference memories under \`.claude/memory/\`. If you ask for
+  something that contradicts a remembered preference, Claude flags
+  it before acting; corrections update memory automatically.
+- **Long-running tasks** — \`/loop\` and \`/schedule\` for recurring
+  or background work. Useful for "wait for the deploy then open a
+  cleanup PR" or "every Monday triage the issue board" patterns.
+
+## Quick reference (full version in AGENTS.md)
 
 \`\`\`bash
-kick add auth          # JWT, API key, OAuth strategies
-kick add swagger       # OpenAPI docs from decorators
-kick add ws            # WebSocket support
-kick add queue         # Background jobs (BullMQ/RabbitMQ/Kafka)
-kick add mailer        # Email (SMTP, Resend, SES)
-kick add cron          # Scheduled tasks
-kick add prisma        # Prisma ORM adapter
-kick add drizzle       # Drizzle ORM adapter
-kick add otel          # OpenTelemetry tracing
-kick add --list        # Show all available packages
-\`\`\`
-
-## Environment Configuration
-
-The project's typed env schema lives in **\`src/config/index.ts\`** —
-extend the base schema there with your application-specific keys, and
-the schema is auto-registered with kickjs at module load. The companion
-\`src/index.ts\` imports it as a side effect (\`import './config'\`) **before**
-\`bootstrap()\` runs, so every \`@Service\`, \`@Controller\`, \`@Value\`, and
-\`ConfigService\` resolution sees the validated extended values.
-
-> **Do not delete \`import './config'\` from \`src/index.ts\`.** It is the
-> registration step that wires \`ConfigService\` to your env schema.
-> Without it, \`config.get('YOUR_KEY')\` returns \`undefined\` for every
-> user-defined key and \`@Value('YOUR_KEY')\` only works because of a
-> raw \`process.env\` fallback (Zod coercion + defaults are skipped).
-
-Edit \`.env\` for variable values. Access them with \`@Value()\`:
-
-\`\`\`ts
-import { Value } from '@forinda/kickjs'
-
-@Service()
-export class ApiService {
-  @Value('API_KEY')
-  private apiKey!: string
-
-  @Value('PORT', 3000)  // With default
-  private port!: number
-}
-\`\`\`
-
-Or use \`ConfigService\`:
-
-\`\`\`ts
-import { Service, Autowired, ConfigService } from '@forinda/kickjs'
-
-@Service()
-export class AppService {
-  @Autowired()
-  private config!: ConfigService
-
-  getPort() {
-    // typed: number, Zod-coerced from baseEnvSchema
-    return this.config.get('PORT')
-  }
-}
-\`\`\`
-
-Hot-reload of \`.env\` changes during dev is wired up automatically via
-\`envWatchPlugin()\` in \`vite.config.ts\` — edit \`.env\`, the dev server
-reloads, and the next \`config.get()\` re-parses with the new values.
-
-### Standalone Env Utilities (No DI Required)
-
-These functions work anywhere — scripts, CLI tools, plain files, outside \`@Service\`/\`@Controller\`:
-
-\`\`\`ts
-import { defineEnv, loadEnv, getEnv, reloadEnv, resetEnvCache, baseEnvSchema } from '@forinda/kickjs/config'
-import { z } from 'zod'
-
-// Define and parse schema
-const schema = defineEnv((base) =>
-  base.extend({ DATABASE_URL: z.string().url() })
-)
-const env = loadEnv(schema)      // Parse + validate process.env
-console.log(env.PORT)            // 3000 (coerced to number)
-console.log(env.DATABASE_URL)    // validated URL string
-
-// Get single value
-const port = getEnv('PORT')      // typed after kick typegen
-
-// Reload after .env changes (HMR calls this automatically)
-reloadEnv()
-
-// Reset cache in tests that swap schemas
-resetEnvCache()
-\`\`\`
-
-| Function | Purpose |
-|----------|---------|
-| \`defineEnv(fn)\` | Extend base schema with custom Zod keys |
-| \`loadEnv(schema?)\` | Parse \`process.env\`, validate, cache, return typed object |
-| \`getEnv(key, schema?)\` | Get single validated env value |
-| \`reloadEnv()\` | Re-read \`.env\` from disk, re-parse with same schema |
-| \`resetEnvCache()\` | Clear parsed cache AND registered schema (for tests) |
-| \`baseEnvSchema\` | Base Zod schema: \`PORT\`, \`NODE_ENV\`, \`LOG_LEVEL\` |
-
-## Standalone Utilities (No DI Required)
-
-These utilities work outside decorated classes:
-
-### Logger
-
-\`\`\`ts
-import { Logger, createLogger } from '@forinda/kickjs'
-
-const log = Logger.for('MyScript')    // Static factory
-log.info('Processing started')
-log.error('Something failed')
-
-const log2 = createLogger('Worker')   // Function form
-\`\`\`
-
-### Injection Tokens
-
-\`\`\`ts
-import { createToken } from '@forinda/kickjs'
-
-// Type-safe DI tokens for factory/interface binding
-const DB_URL = createToken<string>('config.database.url')
-const FEATURE_FLAGS = createToken<FeatureFlags>('app.features')
+${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
 \`\`\`
 
-### Reactivity
+## v4 framework reminders
 
-\`\`\`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
-\`\`\`
+When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`AGENTS.md\`:
 
-### HTTP Errors
+- **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\`.
 
-\`\`\`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()\` — mark a class as an HTTP controller (path comes from \`routes().path\`)
-- \`@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
 
@@ -1117,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\` |
@@ -1312,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')
   })
@@ -1383,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))\` |
@@ -1453,42 +1321,299 @@ ${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
+
+| Command | Description |
+|---------|-------------|
+| \`kick dev\` | Dev server with HMR |
+| \`kick dev:debug\` | Dev server with debugger |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`kick g module <names...>\` | Generate one or more modules |
+| \`kick g scaffold <name> <fields>\` | Generate CRUD |
+| \`kick g controller <name>\` | Generate controller |
+| \`kick g service <name>\` | Generate service |
+| \`kick g middleware <name>\` | Generate middleware |
+| \`kick add <package>\` | Add KickJS package |
+| \`kick add --list\` | List available packages |
+| \`kick rm module <names...>\` | Remove one or more modules |
+
+> **Note:** When using \`kick new\` in scripts or CI, pass \`-t\` (or \`--template\`) and \`-r\` (or \`--repo\`) flags to bypass interactive prompts:
+> \`\`\`bash
+> kick new my-api -t ddd -r prisma --pm ${pm} --no-git --no-install -f
+> \`\`\`
+
+## Learn More
+
+- [KickJS Docs](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
+- [DI System](https://forinda.github.io/kick-js/guide/dependency-injection.html)
+- [Testing](https://forinda.github.io/kick-js/api/testing.html)
+`;
+}
+/**
+* Generate `kickjs-skills.md` — task-oriented "skill" recipes for AI
+* agents (Claude superpowers, Copilot, etc.). Where AGENTS.md is the
+* narrative reference, this file lists short, rigid workflows the agent
+* should follow when it sees the corresponding trigger.
+*/
+function generateKickJsSkills(name, _template, pm) {
+	return `# kickjs-skills.md — Task Skills for AI Agents (${name})
+
+This file is the agent-facing **skills index** for KickJS work in this
+repo. Each block below is a short, rigid workflow keyed to a specific
+trigger ("user wants to add a module", "tests are leaking state", etc.).
+
+- Reference docs (narrative, exhaustive) → \`AGENTS.md\`.
+- Tool-specific notes → \`CLAUDE.md\`, \`GEMINI.md\`, etc.
+- **This file** → step-by-step recipes the agent should *execute*.
+
+Re-run \`kick g agents -f --only skills\` after framework upgrades to refresh.
+
+---
+
+## Skill: add-module
+
+\`\`\`yaml
+name: kickjs-add-module
+description: Use when the user asks to add a new feature module (controller + service + repo + DTOs).
+\`\`\`
+
+**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
+
+**Steps**:
+1. Run \`kick g module <name>\` (use plural form if the project pluralizes — check \`kick.config.ts\`).
+2. Verify the new folder under \`src/modules/<name>/\` contains \`<name>.module.ts\` (filename suffix is mandatory for HMR).
+3. Confirm the module appears in \`src/modules/index.ts\` exports — generator does this automatically; verify if you bypassed it.
+4. Open \`<name>.dto.ts\` and tighten the Zod schemas to real fields (the generator emits placeholders).
+5. Run \`${pm} run typecheck\` and \`${pm} run test\` before claiming done.
+
+**Red flags** (stop and ask):
+- File created as \`<name>.ts\` instead of \`<name>.module.ts\` — Vite won't HMR it.
+- Module not registered in \`src/modules/index.ts\`.
+- \`@Controller('/path')\` with a path argument — that's a v3 pattern; remove it (mount comes from \`routes().path\`).
+
+---
+
+## Skill: add-adapter
+
+\`\`\`yaml
+name: kickjs-add-adapter
+description: Use when wiring a new lifecycle integration (Swagger, DevTools, Auth, custom).
+\`\`\`
+
+**Steps**:
+1. \`kick g adapter <name>\` to scaffold the boilerplate, OR install via \`kick add <package>\` for first-party adapters.
+2. The generated file uses \`defineAdapter()\` — never \`class implements AppAdapter\`.
+3. Add the adapter instance to \`src/adapters/index.ts\` (don't inline in \`src/index.ts\`).
+4. If the adapter contributes to \`ctx.set/get\`, prefer \`AppAdapter.contributors?()\` over a wrapping middleware.
+5. Verify with \`kick dev\` that the adapter's lifecycle logs fire.
+
+**Red flags**:
+- Inlining the adapter list directly in \`src/index.ts\` (entry file should stay thin).
+- Returning a plain object instead of going through \`defineAdapter()\` — type inference for \`config\` will be wrong.
+
+---
+
+## Skill: write-controller-test
+
+\`\`\`yaml
+name: kickjs-write-controller-test
+description: Use when adding a Vitest test that exercises an HTTP route or DI graph.
+\`\`\`
+
+**Template** (copy/paste, adjust):
+
+\`\`\`ts
+import { describe, it, expect } from 'vitest'
+import { Container } from '@forinda/kickjs'
+import { createTestApp } from '@forinda/kickjs-testing'
+
+describe('UserController', () => {
+  it('returns users', async () => {
+    const container = Container.create()           // isolated DI per test
+    const app = await createTestApp([UserModule], { container })
+    const res = await app.get('/users')
+    expect(res.status).toBe(200)
+  })
+})
+\`\`\`
+
+**Red flags**:
+- \`new Container()\` — wrong; use \`Container.create()\`.
+- \`Container.getInstance().reset()\` — wrong; same fix.
+- Sharing a container across \`it()\` blocks — leaks registrations.
+
+---
+
+## Skill: env-wiring-check
+
+\`\`\`yaml
+name: kickjs-env-wiring-check
+description: Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.
+\`\`\`
+
+**Diagnosis**:
+1. Open \`src/index.ts\`. The **first non-\`reflect-metadata\`** import MUST be \`import './config'\`.
+2. Open \`src/config/index.ts\`. It MUST call \`loadEnv(envSchema)\` as a top-level side effect.
+3. The new key MUST be declared in the Zod schema there. \`@Value('NEW_KEY')\` won't work without a schema entry (it'll fall back to raw \`process.env\` and skip Zod coercion silently).
+
+**Fix**: add the key to the schema; ensure both side-effect imports above are present.
+
+---
+
+## Skill: bootstrap-export
+
+\`\`\`yaml
+name: kickjs-bootstrap-export
+description: Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.
+\`\`\`
+
+**Check** \`src/index.ts\`'s last line:
+
+\`\`\`ts
+// CORRECT
+export const app = await bootstrap({ ... })
+
+// WRONG (HMR degrades to full restart, createTestApp loses the handle)
+await bootstrap({ ... })
+\`\`\`
+
+The Vite plugin imports the named \`app\` symbol; testing helpers do too.
+
+---
+
+## Skill: thin-entry-file
+
+\`\`\`yaml
+name: kickjs-thin-entry-file
+description: Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.
+\`\`\`
+
+**Refactor target**:
+
+\`\`\`ts
+// src/modules/index.ts
+export const modules: AppModuleClass[] = [HelloModule, UsersModule, ...]
+
+// src/middleware/index.ts
+export const middleware = [helmet(), cors(), requestId(), ...]
+
+// src/plugins/index.ts
+export const plugins = [MetricsPlugin(), ...]
+
+// src/adapters/index.ts
+export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
+
+// src/index.ts — stays small
+import 'reflect-metadata'
+import './config'
+import { bootstrap } from '@forinda/kickjs'
+import { modules } from './modules'
+import { middleware } from './middleware'
+import { plugins } from './plugins'
+import { adapters } from './adapters'
+export const app = await bootstrap({ modules, middleware, plugins, adapters })
+\`\`\`
+
+**Red flags**: any \`new SomeAdapter()\` or \`SomePlugin()\` literal inside \`bootstrap({ ... })\` instead of imported from a category folder.
+
+---
+
+## Skill: context-contributor
+
+\`\`\`yaml
+name: kickjs-context-contributor
+description: Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).
+\`\`\`
+
+**Pattern** (HTTP — most common):
+
+\`\`\`ts
+import { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'
+
+const LoadTenant = defineHttpContextDecorator({
+  key: 'tenant',
+  deps: { repo: TENANT_REPO },
+  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),
+})
+
+const LoadProject = defineHttpContextDecorator({
+  key: 'project',
+  dependsOn: ['tenant'],
+  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),
+})
+
+@LoadTenant
+@LoadProject
+@Get('/projects/:id')
+getProject(ctx: RequestContext) { ctx.json(ctx.get('project')) }
+\`\`\`
+
+Use \`defineContextDecorator\` (no Http prefix) when authoring a contributor that must run across HTTP, WebSocket, queue, and cron transports — \`Ctx\` defaults to the smaller \`ExecutionContext\` surface (\`get\` / \`set\` / \`requestId\` only, no \`req\`).
+
+Precedence high → low: **method > class > module > adapter > global**.
+Cycles or unmet \`dependsOn\` keys throw \`MissingContributorError\` at boot.
+
+**Critical rules — all stem from the same shared-via-ALS instance model**:
+- Every per-request stage (middleware → contributors → handler) gets its OWN \`RequestContext\` instance, but they all read/write the SAME \`AsyncLocalStorage\`-backed 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
 
-## CLI Commands Reference
+\`\`\`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.
+\`\`\`
 
-| Command | Description |
-|---------|-------------|
-| \`kick dev\` | Dev server with HMR |
-| \`kick dev:debug\` | Dev server with debugger |
-| \`kick build\` | Production build |
-| \`kick start\` | Run production build |
-| \`kick g module <names...>\` | Generate one or more modules |
-| \`kick g scaffold <name> <fields>\` | Generate CRUD |
-| \`kick g controller <name>\` | Generate controller |
-| \`kick g service <name>\` | Generate service |
-| \`kick g middleware <name>\` | Generate middleware |
-| \`kick add <package>\` | Add KickJS package |
-| \`kick add --list\` | List available packages |
-| \`kick rm module <names...>\` | Remove one or more modules |
+**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\`.
 
-> **Note:** When using \`kick new\` in scripts or CI, pass \`-t\` (or \`--template\`) and \`-r\` (or \`--repo\`) flags to bypass interactive prompts:
-> \`\`\`bash
-> kick new my-api -t ddd -r prisma --pm ${pm} --no-git --no-install -f
-> \`\`\`
+---
+
+## 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/)
-- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
-- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
-- [DI System](https://forinda.github.io/kick-js/guide/dependency-injection.html)
+- [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)
 `;
 }
@@ -1524,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 {
@@ -2612,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) {
@@ -4030,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;
@@ -4128,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))
     },
 
     /**
@@ -4217,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({ ... }),
       ]
     },
 
@@ -4229,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),
       ]
     },
 
@@ -4241,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')
     },
 
     /**
@@ -4251,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;
@@ -4487,94 +4634,276 @@ export class ${pascal}Controller {
     ctx.created({ message: '${pascal} created', data: ctx.body })
   }
 }
-`);
-	files.push(filePath);
-	return files;
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/dto.ts
+async function generateDto(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "dto",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/dtos",
+		pattern,
+		shouldPluralize: options.pluralize ?? true
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const camel = toCamelCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.dto.ts`);
+	await writeFileSafe(filePath, `import { z } from 'zod'
+
+export const ${camel}Schema = z.object({
+  // Define your schema fields here
+  name: z.string().min(1).max(200),
+})
+
+export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/config.ts
+async function generateConfig(options) {
+	const filePath = join(options.outDir, "kick.config.ts");
+	const modulesDir = options.modulesDir ?? "src/modules";
+	const defaultRepo = options.defaultRepo ?? "inmemory";
+	if (existsSync(filePath) && !options.force) {
+		if (!await confirm({
+			message: "kick.config.ts already exists. Overwrite?",
+			initialValue: false
+		})) {
+			console.log("\n  Skipped — existing kick.config.ts preserved.");
+			return [];
+		}
+	}
+	await writeFileSafe(filePath, `import { defineConfig } from '@forinda/kickjs-cli'
+
+export default defineConfig({
+  modules: {
+    dir: '${modulesDir}',
+    repo: '${defaultRepo}',
+    pluralize: true,
+  },
+
+  typegen: {
+    schemaValidator: 'zod',
+  },
+
+  commands: [
+    {
+      name: 'test',
+      description: 'Run tests with Vitest',
+      steps: 'npx vitest run',
+    },
+    {
+      name: 'format',
+      description: 'Format code with Prettier',
+      steps: 'npx prettier --write src/',
+    },
+    {
+      name: 'format:check',
+      description: 'Check formatting without writing',
+      steps: 'npx prettier --check src/',
+    },
+    {
+      name: 'ci:check',
+      description: 'Run typecheck + format check',
+      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
+      aliases: ['verify'],
+    },
+  ],
+})
+`);
+	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/dto.ts
-async function generateDto(options) {
-	const { name, moduleName, modulesDir, pattern } = options;
-	const outDir = resolveOutDir({
-		type: "dto",
-		outDir: options.outDir,
-		moduleName,
-		modulesDir,
-		defaultDir: "src/dtos",
-		pattern,
-		shouldPluralize: options.pluralize ?? true
-	});
-	const kebab = toKebabCase(name);
-	const pascal = toPascalCase(name);
-	const camel = toCamelCase(name);
-	const files = [];
-	const filePath = join(outDir, `${kebab}.dto.ts`);
-	await writeFileSafe(filePath, `import { z } from 'zod'
-
-export const ${camel}Schema = z.object({
-  // Define your schema fields here
-  name: z.string().min(1).max(200),
-})
-
-export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
-`);
-	files.push(filePath);
-	return files;
+//#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";
 }
-//#endregion
-//#region src/generators/config.ts
-async function generateConfig(options) {
-	const filePath = join(options.outDir, "kick.config.ts");
-	const modulesDir = options.modulesDir ?? "src/modules";
-	const defaultRepo = options.defaultRepo ?? "inmemory";
-	if (existsSync(filePath) && !options.force) {
-		if (!await confirm({
-			message: "kick.config.ts already exists. Overwrite?",
-			initialValue: false
-		})) {
-			console.log("\n  Skipped — existing kick.config.ts preserved.");
-			return [];
+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);
 	}
-	await writeFileSafe(filePath, `import { defineConfig } from '@forinda/kickjs-cli'
-
-export default defineConfig({
-  modules: {
-    dir: '${modulesDir}',
-    repo: '${defaultRepo}',
-    pluralize: true,
-  },
-
-  typegen: {
-    schemaValidator: 'zod',
-  },
-
-  commands: [
-    {
-      name: 'test',
-      description: 'Run tests with Vitest',
-      steps: 'npx vitest run',
-    },
-    {
-      name: 'format',
-      description: 'Format code with Prettier',
-      steps: 'npx prettier --write src/',
-    },
-    {
-      name: 'format:check',
-      description: 'Check formatting without writing',
-      steps: 'npx prettier --check src/',
-    },
-    {
-      name: 'ci:check',
-      description: 'Run typecheck + format check',
-      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
-      aliases: ['verify'],
-    },
-  ],
-})
-`);
-	return [filePath];
+	return written;
 }
 //#endregion
 //#region src/generators/auth-scaffold.ts
@@ -5386,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) {
@@ -5542,118 +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 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/typegen/scanner.ts
 /** Decorators that mark a class as DI-managed */
 const DECORATOR_NAMES = [
@@ -6831,8 +7048,12 @@ export {}
 	const blocks = [];
 	for (const item of [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))) {
 		const docLines = [];
-		if (item.description) docLines.push(` * ${item.description}`);
-		if (item.example) docLines.push(` * @example`, ` * \`\`\`ts`, ` * ${item.example}`, ` * \`\`\``);
+		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([
 			"/**",
@@ -7118,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;
@@ -7200,6 +7428,10 @@ const GENERATORS = [
 	{
 		name: "config",
 		description: "Generate kick.config.ts"
+	},
+	{
+		name: "agents",
+		description: "Regenerate AGENTS.md + CLAUDE.md + kickjs-skills.md from upstream templates"
 	}
 ];
 async function printGeneratorList() {
@@ -7467,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
@@ -7673,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({
@@ -7695,6 +7949,7 @@ async function startDevServer(_entry, port) {
 	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`);