@forinda/kickjs-cli 2.2.1 → 2.2.3

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.2.1
+ * @forinda/kickjs-cli v2.2.3
  *
  * Copyright (c) Felix Orinda
  *
@@ -55,7 +55,7 @@ async function fileExists(filePath) {
 function generatePackageJson(name, template, kickjsVersion) {
 	const baseDeps = {
 		"@forinda/kickjs": kickjsVersion,
-		"@forinda/kickjs-config": kickjsVersion,
+		dotenv: "^17.3.1",
 		express: "^5.1.0",
 		"reflect-metadata": "^0.2.2",
 		zod: "^4.3.6",
@@ -122,13 +122,16 @@ function generateViteConfig() {
 	return `import { defineConfig } from 'vite'
 import { resolve } from 'node:path'
 import swc from 'unplugin-swc'
-import { kickjsVitePlugin } from '@forinda/kickjs-vite'
+import { kickjsVitePlugin, envWatchPlugin } from '@forinda/kickjs-vite'
 
 export default defineConfig({
   oxc: false,
   plugins: [
     swc.vite(),
     kickjsVitePlugin({ entry: 'src/index.ts' }),
+    // Watches .env files and triggers a full reload on change so the
+    // dev server picks up env tweaks without a manual restart.
+    envWatchPlugin(),
   ],
   resolve: {
     alias: {
@@ -278,6 +281,11 @@ export default defineConfig({
 function generateEntryFile(name, template, version) {
 	switch (template) {
 		case "graphql": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { DevToolsAdapter } from '@forinda/kickjs-devtools'
 import { GraphQLAdapter } from '@forinda/kickjs-graphql'
@@ -300,6 +308,11 @@ export const app = await bootstrap({
 })
 `;
 		case "cqrs": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { DevToolsAdapter } from '@forinda/kickjs-devtools'
 import { SwaggerAdapter } from '@forinda/kickjs-swagger'
@@ -327,6 +340,11 @@ export const app = await bootstrap({
 })
 `;
 		case "minimal": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { modules } from './modules'
 
@@ -334,6 +352,11 @@ import { modules } from './modules'
 export const app = await bootstrap({ modules })
 `;
 		default: return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import express from 'express'
 import {
   bootstrap,
@@ -376,10 +399,17 @@ export const modules: AppModuleClass[] = [HelloModule]
 `;
 }
 /**
-* Generate `src/env.ts` — the project's typed env schema.
+* Generate `src/config/index.ts` — the project's typed env schema.
 *
 * Default-exports a `defineEnv(...)` schema so `kick typegen` can
-* infer it into the global `KickEnv` registry. After typegen runs:
+* infer it into the global `KickEnv` registry, and *also* calls
+* `loadEnv(envSchema)` as a module-load side effect so `ConfigService`
+* and `@Value()` see the extended shape from the very first DI
+* resolution. The companion `src/index.ts` template adds
+* `import './config'` immediately after `reflect-metadata` so the
+* registration runs before `bootstrap()` constructs anything.
+*
+* After typegen runs:
 *
 *   @Value('DATABASE_URL') private url!: Env<'DATABASE_URL'>
 *   process.env.DATABASE_URL  // typed as string
@@ -387,7 +417,7 @@ export const modules: AppModuleClass[] = [HelloModule]
 * Both autocomplete and type-check at compile time.
 */
 function generateEnvFile() {
-	return `import { defineEnv } from '@forinda/kickjs-config'
+	return `import { defineEnv, loadEnv } from '@forinda/kickjs/config'
 import { z } from 'zod'
 
 /**
@@ -403,11 +433,25 @@ import { z } from 'zod'
  *   JWT_SECRET: z.string().min(32),
  *   REDIS_URL: z.string().url().optional(),
  */
-export default defineEnv((base) =>
+const envSchema = defineEnv((base) =>
   base.extend({
     // DATABASE_URL: z.string().url(),
   }),
 )
+
+/**
+ * IMPORTANT — side effect: register the schema with kickjs's env cache
+ * **at module-load time**. \`ConfigService\` and \`@Value()\` both consume
+ * this cache, and they will fall back to the base schema (or undefined)
+ * if no extended schema has been registered before they're resolved.
+ *
+ * As long as \`src/index.ts\` imports this file (\`import './env'\`) at the
+ * top — before \`bootstrap()\` runs — every controller and service in the
+ * app sees the typed extended values.
+ */
+export const env = loadEnv(envSchema)
+
+export default envSchema
 `;
 }
 /** Generate src/modules/hello/hello.service.ts */
@@ -535,11 +579,7 @@ function generateReadme(name, template, pm) {
 		cqrs: "CQRS + Event-Driven",
 		minimal: "Minimal"
 	};
-	const packages = [
-		"@forinda/kickjs",
-		"@forinda/kickjs-vite",
-		"@forinda/kickjs-config"
-	];
+	const packages = ["@forinda/kickjs", "@forinda/kickjs-vite"];
 	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
 	if (template === "graphql") packages.push("@forinda/kickjs-graphql");
 	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws", "@forinda/kickjs-otel");
@@ -775,10 +815,23 @@ kick add --list        # Show all available packages
 
 ## Environment Configuration
 
-Edit \`.env\` for environment variables. Access them with \`@Value()\` decorator:
+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-config'
+import { Value } from '@forinda/kickjs'
 
 @Service()
 export class ApiService {
@@ -793,7 +846,7 @@ export class ApiService {
 Or use \`ConfigService\`:
 
 \`\`\`ts
-import { ConfigService } from '@forinda/kickjs-config'
+import { Service, Autowired, ConfigService } from '@forinda/kickjs'
 
 @Service()
 export class AppService {
@@ -801,11 +854,16 @@ export class AppService {
   private config!: ConfigService
 
   getPort() {
-    return this.config.get('PORT', 3000)
+    // 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.
+
 ## Testing
 
 Tests live in \`src/**/*.test.ts\`:
@@ -867,6 +925,7 @@ ${template === "cqrs" ? `### CQRS/Event Decorators
 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
 
@@ -898,7 +957,8 @@ 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>/\` |
-${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Environment config | \`.env\` |
+${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Env values | \`.env\` |
+| Env schema (Zod) | \`src/config/index.ts\` |
 | TypeScript config | \`tsconfig.json\` |
 | Vite config (HMR) | \`vite.config.ts\` |
 | Vitest config | \`vitest.config.ts\` |
@@ -1108,26 +1168,37 @@ Run tests:
 
 ## Environment Variables
 
-Managed via \`.env\` file. Access with:
+Schema is declared in \`src/config/index.ts\` (extends the base
+\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` shape via \`defineEnv\`) and registered
+with kickjs at module load. \`src/index.ts\` imports it via
+\`import './config'\` **before** \`bootstrap()\` so the cache is populated
+in time for DI. Add new keys to the schema, drop their values into
+\`.env\`, and they're typed everywhere.
 
-1. **@Value() decorator** (recommended):
+Access patterns:
+
+1. **@Value() decorator** (recommended for known-at-construction keys):
 \`\`\`ts
 @Value('DATABASE_URL')
 private dbUrl!: string
 \`\`\`
 
-2. **ConfigService** (for dynamic access):
+2. **ConfigService** (recommended for dynamic / method-scoped access):
 \`\`\`ts
 @Autowired()
 private config!: ConfigService
 
-const port = this.config.get('PORT', 3000)
+const port = this.config.get('PORT')  // typed: number
 \`\`\`
 
-3. **Direct access** (avoid in app code):
-\`\`\`ts
-process.env.PORT
-\`\`\`
+3. **Direct \`process.env\`** — avoid in app code; bypasses Zod
+   coercion and the typed \`KickEnv\` registry.
+
+> **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
+> If the schema is not registered before DI runs, \`config.get()\`
+> returns \`undefined\` for user keys (the base shape only) and
+> \`@Value()\` only works because of its raw \`process.env\` fallback —
+> Zod coercion + schema defaults are silently skipped.
 
 ## Key Decorators
 
@@ -1174,6 +1245,7 @@ ${template === "graphql" ? `### GraphQL
 4. **Routes not found** — Check controller path and module registration
 5. **HMR not working** — Verify \`vite.config.ts\` has \`hmr: true\`
 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.
 
 ## CLI Commands Reference
 
@@ -1226,7 +1298,7 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, ".gitattributes"), generateGitAttributes());
 	await writeFileSafe(join(dir, ".env"), generateEnv());
 	await writeFileSafe(join(dir, ".env.example"), generateEnvExample());
-	await writeFileSafe(join(dir, "src/env.ts"), generateEnvFile());
+	await writeFileSafe(join(dir, "src/config/index.ts"), generateEnvFile());
 	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version));
 	await writeFileSafe(join(dir, "src/modules/index.ts"), generateModulesIndex());
 	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
@@ -4864,31 +4936,49 @@ function extractInjectsFromSource(source, filePath, cwd) {
 	return out;
 }
 /**
-* Look for an env schema file at `<cwd>/<envFile>`. Returns a
-* `DiscoveredEnv` if the file exists and contains both a
+* 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
+* here for back-compat). The first match wins.
+*/
+const DEFAULT_ENV_FILE_CANDIDATES = [
+	"src/config/index.ts",
+	"src/config/env.ts",
+	"src/config.ts",
+	"src/env.ts"
+];
+/**
+* Look for an env schema file. When `envFile` is the string default
+* (`'src/env.ts'`) or omitted, every entry in `DEFAULT_ENV_FILE_CANDIDATES`
+* is tried in order. When the caller passes an explicit path, only that
+* path is tried (so projects can opt out of the search by setting
+* `kick.config.ts → typegen.envFile`).
+*
+* Returns a `DiscoveredEnv` if the file exists and contains both a
 * `defineEnv(...)` call and a default export — the two markers we
 * need before it's safe to emit `import type schema from '...'` in
-* the generator.
-*
-* Returns `null` for any other state (file missing, no defineEnv, no
-* default export) so the generator skips env typing silently. Users
-* who want env typing must opt in by writing `src/env.ts` to the
-* documented shape.
+* the generator. Returns `null` for any other state (no candidate
+* found, no defineEnv, no default export) so the generator skips env
+* typing silently.
 */
 async function detectEnvFile(cwd, envFile) {
-	const abs = resolve(cwd, envFile);
-	let source;
-	try {
-		source = await readFile(abs, "utf-8");
-	} catch {
-		return null;
+	const candidates = envFile === "src/env.ts" ? DEFAULT_ENV_FILE_CANDIDATES : [envFile];
+	for (const candidate of candidates) {
+		const abs = resolve(cwd, candidate);
+		let source;
+		try {
+			source = await readFile(abs, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!/\bdefineEnv\s*\(/.test(source)) continue;
+		if (!/export\s+default\b/.test(source)) continue;
+		return {
+			filePath: abs,
+			relativePath: toRelative(abs, cwd)
+		};
 	}
-	if (!/\bdefineEnv\s*\(/.test(source)) return null;
-	if (!/export\s+default\b/.test(source)) return null;
-	return {
-		filePath: abs,
-		relativePath: toRelative(abs, cwd)
-	};
+	return null;
 }
 /** Detect duplicate class names across files */
 function findCollisions(classes) {
@@ -6111,9 +6201,9 @@ const PACKAGE_REGISTRY = {
 		dev: true
 	},
 	config: {
-		pkg: "@forinda/kickjs-config",
+		pkg: "dotenv",
 		peers: [],
-		description: "Zod-based env validation"
+		description: "Optional .env file loader (kickjs ConfigService now ships in @forinda/kickjs)"
 	},
 	cli: {
 		pkg: "@forinda/kickjs-cli",

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.2.1
+ * @forinda/kickjs-cli v2.2.3
  *
  * Copyright (c) Felix Orinda
  *
@@ -1528,6 +1528,11 @@ export class Prisma${pascal}Repository implements I${pascal}Repository {
 function generateEntryFile(name, template, version) {
 	switch (template) {
 		case "graphql": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { DevToolsAdapter } from '@forinda/kickjs-devtools'
 import { GraphQLAdapter } from '@forinda/kickjs-graphql'
@@ -1550,6 +1555,11 @@ export const app = await bootstrap({
 })
 `;
 		case "cqrs": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { DevToolsAdapter } from '@forinda/kickjs-devtools'
 import { SwaggerAdapter } from '@forinda/kickjs-swagger'
@@ -1577,6 +1587,11 @@ export const app = await bootstrap({
 })
 `;
 		case "minimal": return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import { bootstrap } from '@forinda/kickjs'
 import { modules } from './modules'
 
@@ -1584,6 +1599,11 @@ import { modules } from './modules'
 export const app = await bootstrap({ modules })
 `;
 		default: return `import 'reflect-metadata'
+// Side-effect import — registers the extended env schema with kickjs
+// **before** any controller / service / @Value gets resolved. Without
+// this line ConfigService.get('YOUR_KEY') returns undefined because the
+// cached schema would still be the base shape. See guide/configuration.
+import './config'
 import express from 'express'
 import {
   bootstrap,
@@ -1626,10 +1646,17 @@ export const modules: AppModuleClass[] = [HelloModule]
 `;
 }
 /**
-* Generate `src/env.ts` — the project's typed env schema.
+* Generate `src/config/index.ts` — the project's typed env schema.
 *
 * Default-exports a `defineEnv(...)` schema so `kick typegen` can
-* infer it into the global `KickEnv` registry. After typegen runs:
+* infer it into the global `KickEnv` registry, and *also* calls
+* `loadEnv(envSchema)` as a module-load side effect so `ConfigService`
+* and `@Value()` see the extended shape from the very first DI
+* resolution. The companion `src/index.ts` template adds
+* `import './config'` immediately after `reflect-metadata` so the
+* registration runs before `bootstrap()` constructs anything.
+*
+* After typegen runs:
 *
 *   @Value('DATABASE_URL') private url!: Env<'DATABASE_URL'>
 *   process.env.DATABASE_URL  // typed as string
@@ -1637,7 +1664,7 @@ export const modules: AppModuleClass[] = [HelloModule]
 * Both autocomplete and type-check at compile time.
 */
 function generateEnvFile() {
-	return `import { defineEnv } from '@forinda/kickjs-config'
+	return `import { defineEnv, loadEnv } from '@forinda/kickjs/config'
 import { z } from 'zod'
 
 /**
@@ -1653,11 +1680,25 @@ import { z } from 'zod'
  *   JWT_SECRET: z.string().min(32),
  *   REDIS_URL: z.string().url().optional(),
  */
-export default defineEnv((base) =>
+const envSchema = defineEnv((base) =>
   base.extend({
     // DATABASE_URL: z.string().url(),
   }),
 )
+
+/**
+ * IMPORTANT — side effect: register the schema with kickjs's env cache
+ * **at module-load time**. \`ConfigService\` and \`@Value()\` both consume
+ * this cache, and they will fall back to the base schema (or undefined)
+ * if no extended schema has been registered before they're resolved.
+ *
+ * As long as \`src/index.ts\` imports this file (\`import './env'\`) at the
+ * top — before \`bootstrap()\` runs — every controller and service in the
+ * app sees the typed extended values.
+ */
+export const env = loadEnv(envSchema)
+
+export default envSchema
 `;
 }
 /** Generate src/modules/hello/hello.service.ts */
@@ -2577,7 +2618,7 @@ export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
 function generatePackageJson(name, template, kickjsVersion) {
 	const baseDeps = {
 		"@forinda/kickjs": kickjsVersion,
-		"@forinda/kickjs-config": kickjsVersion,
+		dotenv: "^17.3.1",
 		express: "^5.1.0",
 		"reflect-metadata": "^0.2.2",
 		zod: "^4.3.6",
@@ -2644,13 +2685,16 @@ function generateViteConfig() {
 	return `import { defineConfig } from 'vite'
 import { resolve } from 'node:path'
 import swc from 'unplugin-swc'
-import { kickjsVitePlugin } from '@forinda/kickjs-vite'
+import { kickjsVitePlugin, envWatchPlugin } from '@forinda/kickjs-vite'
 
 export default defineConfig({
   oxc: false,
   plugins: [
     swc.vite(),
     kickjsVitePlugin({ entry: 'src/index.ts' }),
+    // Watches .env files and triggers a full reload on change so the
+    // dev server picks up env tweaks without a manual restart.
+    envWatchPlugin(),
   ],
   resolve: {
     alias: {
@@ -2799,11 +2843,7 @@ function generateReadme(name, template, pm) {
 		cqrs: "CQRS + Event-Driven",
 		minimal: "Minimal"
 	};
-	const packages = [
-		"@forinda/kickjs",
-		"@forinda/kickjs-vite",
-		"@forinda/kickjs-config"
-	];
+	const packages = ["@forinda/kickjs", "@forinda/kickjs-vite"];
 	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
 	if (template === "graphql") packages.push("@forinda/kickjs-graphql");
 	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws", "@forinda/kickjs-otel");
@@ -3039,10 +3079,23 @@ kick add --list        # Show all available packages
 
 ## Environment Configuration
 
-Edit \`.env\` for environment variables. Access them with \`@Value()\` decorator:
+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-config'
+import { Value } from '@forinda/kickjs'
 
 @Service()
 export class ApiService {
@@ -3057,7 +3110,7 @@ export class ApiService {
 Or use \`ConfigService\`:
 
 \`\`\`ts
-import { ConfigService } from '@forinda/kickjs-config'
+import { Service, Autowired, ConfigService } from '@forinda/kickjs'
 
 @Service()
 export class AppService {
@@ -3065,11 +3118,16 @@ export class AppService {
   private config!: ConfigService
 
   getPort() {
-    return this.config.get('PORT', 3000)
+    // 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.
+
 ## Testing
 
 Tests live in \`src/**/*.test.ts\`:
@@ -3131,6 +3189,7 @@ ${template === "cqrs" ? `### CQRS/Event Decorators
 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
 
@@ -3162,7 +3221,8 @@ 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>/\` |
-${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Environment config | \`.env\` |
+${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Env values | \`.env\` |
+| Env schema (Zod) | \`src/config/index.ts\` |
 | TypeScript config | \`tsconfig.json\` |
 | Vite config (HMR) | \`vite.config.ts\` |
 | Vitest config | \`vitest.config.ts\` |
@@ -3372,26 +3432,37 @@ Run tests:
 
 ## Environment Variables
 
-Managed via \`.env\` file. Access with:
+Schema is declared in \`src/config/index.ts\` (extends the base
+\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` shape via \`defineEnv\`) and registered
+with kickjs at module load. \`src/index.ts\` imports it via
+\`import './config'\` **before** \`bootstrap()\` so the cache is populated
+in time for DI. Add new keys to the schema, drop their values into
+\`.env\`, and they're typed everywhere.
+
+Access patterns:
 
-1. **@Value() decorator** (recommended):
+1. **@Value() decorator** (recommended for known-at-construction keys):
 \`\`\`ts
 @Value('DATABASE_URL')
 private dbUrl!: string
 \`\`\`
 
-2. **ConfigService** (for dynamic access):
+2. **ConfigService** (recommended for dynamic / method-scoped access):
 \`\`\`ts
 @Autowired()
 private config!: ConfigService
 
-const port = this.config.get('PORT', 3000)
+const port = this.config.get('PORT')  // typed: number
 \`\`\`
 
-3. **Direct access** (avoid in app code):
-\`\`\`ts
-process.env.PORT
-\`\`\`
+3. **Direct \`process.env\`** — avoid in app code; bypasses Zod
+   coercion and the typed \`KickEnv\` registry.
+
+> **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
+> If the schema is not registered before DI runs, \`config.get()\`
+> returns \`undefined\` for user keys (the base shape only) and
+> \`@Value()\` only works because of its raw \`process.env\` fallback —
+> Zod coercion + schema defaults are silently skipped.
 
 ## Key Decorators
 
@@ -3438,6 +3509,7 @@ ${template === "graphql" ? `### GraphQL
 4. **Routes not found** — Check controller path and module registration
 5. **HMR not working** — Verify \`vite.config.ts\` has \`hmr: true\`
 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.
 
 ## CLI Commands Reference
 
@@ -3490,7 +3562,7 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, ".gitattributes"), generateGitAttributes());
 	await writeFileSafe(join(dir, ".env"), generateEnv());
 	await writeFileSafe(join(dir, ".env.example"), generateEnvExample());
-	await writeFileSafe(join(dir, "src/env.ts"), generateEnvFile());
+	await writeFileSafe(join(dir, "src/config/index.ts"), generateEnvFile());
 	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version));
 	await writeFileSafe(join(dir, "src/modules/index.ts"), generateModulesIndex());
 	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
@@ -3536,7 +3608,7 @@ async function initProject(options) {
 		}
 	}
 	try {
-		const { runTypegen } = await import("./typegen-UejiKdXA.mjs");
+		const { runTypegen } = await import("./typegen-BncsvEr-.mjs");
 		await runTypegen({
 			cwd: dir,
 			allowDuplicates: true,