@gaonjs/cli 0.36.0 → 0.37.1

package/dist/commands/check.d.ts

@@ -49,15 +49,6 @@ export interface CheckReport {
     readonly regen: CheckRegen;
     readonly steps: readonly CheckStepResult[];
 }
-/**
- * 결정 170: 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는
- * package.json 의 `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을
- * 기록하므로, `gaon check` 가 사용자 스크립트(예 build)를 돌릴 때 그 pm 으로
- * 실행해야 한다 — pnpm 하드코딩은 npm/yarn 로 스캐폴드한 프로젝트에서 pnpm 이
- * "This project is configured to use npm" 로 실행을 거부해 build 단계가 깨진다.
- * 우선순위: packageManager 필드 → 락파일 → pnpm(기본).
- */
-export declare function detectPackageManager(cwd: string): 'pnpm' | 'npm' | 'yarn';
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만

package/dist/commands/check.js

@@ -35,6 +35,8 @@ import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 import { listFrontendApps, verifyAppDist } from '../dev/build.js';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
+import { detectPackageManager, scriptRunArgs } from '../pm.js';
 /**
  * 프로젝트 스크립트 존재 여부. pnpm/npm 어느 쪽이든 `scripts.<name>` 을
  * 정의해 두면 우선 사용한다.
@@ -54,35 +56,6 @@ function hasScript(cwd, name) {
 function binExists(cwd, name) {
     return existsSync(join(cwd, 'node_modules', '.bin', name));
 }
-/**
- * 결정 170: 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는
- * package.json 의 `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을
- * 기록하므로, `gaon check` 가 사용자 스크립트(예 build)를 돌릴 때 그 pm 으로
- * 실행해야 한다 — pnpm 하드코딩은 npm/yarn 로 스캐폴드한 프로젝트에서 pnpm 이
- * "This project is configured to use npm" 로 실행을 거부해 build 단계가 깨진다.
- * 우선순위: packageManager 필드 → 락파일 → pnpm(기본).
- */
-export function detectPackageManager(cwd) {
-    const pkgPath = join(cwd, 'package.json');
-    if (existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-            const pm = pkg.packageManager?.split('@')[0];
-            if (pm === 'pnpm' || pm === 'npm' || pm === 'yarn')
-                return pm;
-        }
-        catch {
-            // 파싱 실패는 락파일/기본으로 폴백
-        }
-    }
-    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
-        return 'pnpm';
-    if (existsSync(join(cwd, 'yarn.lock')))
-        return 'yarn';
-    if (existsSync(join(cwd, 'package-lock.json')))
-        return 'npm';
-    return 'pnpm';
-}
 /**
  * 단일 서브 프로세스를 spawn 해서 stdout+stderr 를 모으고 exit 코드를
  * 돌려준다. 실행 실패(파일 없음)는 exit 127 로 매핑.
@@ -107,9 +80,10 @@ async function runStep(step, cwd) {
     const scriptName = step;
     if (hasScript(cwd, scriptName)) {
         // 결정 170: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 실행(npm/yarn 스캐폴드
-        // 대응). `<pm> run <name>` 는 pnpm·npm·yarn(classic) 셋 다 동일하게 동작한다.
+        // 대응 · pm 해상은 공유 `pm.ts` 단일 소스). build/typecheck/vue-tsc 는 잔여
+        // 인자가 없어 `<pm> run <name>` 만 — pnpm·npm·yarn(classic) 동일 동작.
         const cmd = detectPackageManager(cwd);
-        const args = ['run', scriptName];
+        const args = scriptRunArgs(cmd, scriptName);
         const { exitCode, output } = await runSubprocess(cwd, cmd, args);
         // 결정 146(12차 W2): build 가 성공했으면 **등록된 앱마다** dist/<앱>/index.html 과
         // 그 문서가 참조하는 에셋이 실제로 존재하는지 검증한다. build 스크립트가 통과해도
@@ -277,6 +251,7 @@ async function regenerateGaon(cwd) {
             regenerateTables: generateTablesDts,
             regenerateRoutes: generateRoutesDts,
             regenerateMessages: generateMessagesDts,
+            regenerateEnv: generateEnvDts,
         });
         return { status: 'done', tables: result.tables, apps: result.apps };
     }

package/dist/commands/dev.js

@@ -27,6 +27,7 @@ import { startDev, resolveDevLayout } from '../dev.js';
 import { generateTablesDts, watchDir } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
 import { createDevConsole } from '../dev/console.js';
 import { ensureInfra, composeDown } from '../dev/docker.js';
 import { startTscWatchers, killChild } from '../dev/tsc.js';
@@ -88,6 +89,7 @@ async function startGaonRegen(args) {
         regenerateTables: generateTablesDts,
         regenerateRoutes: generateRoutesDts,
         regenerateMessages: generateMessagesDts,
+        regenerateEnv: generateEnvDts,
         watch: watchDir,
         log: (e) => {
             if (e.kind === 'ready') {
@@ -101,7 +103,14 @@ async function startGaonRegen(args) {
                     : `.gaon 재생성 대상 없음 (domain/schema · apps/* 확인)`);
             }
             else if (e.kind === 'regen') {
-                args.console.log('watcher', e.target === 'tables' ? '↻ tables.d.ts 재생성' : `↻ ${e.app}/.gaon/routes.d.ts 재생성`);
+                const label = e.target === 'tables'
+                    ? '↻ tables.d.ts 재생성'
+                    : e.target === 'messages'
+                        ? '↻ messages.d.ts 재생성'
+                        : e.target === 'env'
+                            ? '↻ env.d.ts 재생성'
+                            : `↻ ${e.app}/.gaon/routes.d.ts 재생성`;
+                args.console.log('watcher', label);
             }
             else {
                 args.console.log('watcher', '.gaon 워처 종료');

package/dist/commands/gen.d.ts

@@ -11,6 +11,8 @@ export interface GenResult {
     readonly tables: boolean;
     /** routes.d.ts·routes.manifest.ts 를 재생성한 앱 이름. */
     readonly apps: readonly string[];
+    /** env.d.ts 를 재생성했는가(프론트 앱 존재 · 결정 198). */
+    readonly env?: boolean;
     /** 실패 시 에러 + 수리 안내. */
     readonly error?: string;
 }

package/dist/commands/gen.js

@@ -16,6 +16,7 @@
 import { generateTablesDts } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
 import { generateMessagesDts } from '../messages-gen.js';
+import { generateEnvDts } from '../env-gen.js';
 import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 /**
@@ -26,13 +27,14 @@ import { registerTsResolve } from '../tsResolve.js';
 export async function regenerateProjectGaon(cwd) {
     const layout = resolveDevLayout(cwd);
     if (!layout.schemaDir && layout.apps.length === 0 && !layout.localesDir) {
-        return { tables: false, apps: [], messages: false, skipped: true };
+        return { tables: false, apps: [], messages: false, env: false, skipped: true };
     }
     registerTsResolve();
     const result = await regenerateGaonOnce(layout, {
         regenerateTables: generateTablesDts,
         regenerateRoutes: generateRoutesDts,
         regenerateMessages: generateMessagesDts,
+        regenerateEnv: generateEnvDts,
     });
     return { ...result, skipped: false };
 }
@@ -46,7 +48,7 @@ export async function runGenCommand(opts = {}) {
     let result;
     try {
         const r = await regenerateProjectGaon(cwd);
-        result = { ok: true, skipped: r.skipped, tables: r.tables, apps: r.apps };
+        result = { ok: true, skipped: r.skipped, tables: r.tables, apps: r.apps, env: r.env };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -75,6 +77,8 @@ export async function runGenCommand(opts = {}) {
         for (const app of result.apps) {
             parts.push(`apps/${app}/.gaon/routes.d.ts`, `apps/${app}/.gaon/routes.manifest.ts`);
         }
+        if (result.env)
+            parts.push('.gaon/env.d.ts');
         process.stdout.write(`  ✓ gaon gen — ${parts.join(', ')}\n`);
     }
     return result.ok ? 0 : 1;

package/dist/commands/new.js

@@ -179,6 +179,13 @@ export async function runNewCommand(name, opts = {}) {
         gaonjsVersion,
         packageManager: PACKAGE_MANAGER_PINS[pm],
     });
+    // 결정 198(F-9 ②): env.d.ts 축은 `.env` 를 타입 출처로 요구한다(프론트 앱 전제). 스캐폴드가
+    // `.env.example` 만 남기면 `gaon new` 직후 `gaon check` 가 `.env` 부재로 실패한다 — 첫 실행이
+    // 바로 green 이도록 `.env.example` 내용 그대로 `.env` 도 함께 심는다(.gitignore 로 커밋 제외).
+    const envExample = files.find((f) => f.path === '.env.example');
+    if (envExample && !files.some((f) => f.path === '.env')) {
+        files.push({ path: '.env', contents: envExample.contents });
+    }
     let filesCreated = 0;
     try {
         mkdirSync(root, { recursive: true });

package/dist/commands/test.d.ts

@@ -6,6 +6,7 @@ export interface TestCommandOptions {
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
- * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ * user script 경로는 프로젝트 선언 pm 으로 실행하며(결정 170), 인자 전달 관례는
+ * pm 별로 갈린다(pnpm·npm = `--` 분리 · yarn classic = 직접) — `scriptRunArgs`.
  */
 export declare function runTestCommand(args?: readonly string[], opts?: TestCommandOptions): Promise<number>;

package/dist/commands/test.js

@@ -12,7 +12,8 @@
  *   (기본)         둘 다 실행
  *
  * 실행 경로 우선순위:
- *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `pnpm test -- <args>`
+ *   1) 사용자 package.json 의 `test` 스크립트가 있으면 `<pm> run test`(결정 170 ·
+ *      프로젝트 선언 pm · 인자 전달은 pnpm/npm `--` · yarn classic 직접)
  *   2) 로컬 node_modules/.bin/vitest 가 있으면 직접 spawn(`run` 모드)
  *   3) 둘 다 없으면 exit 127 + 설치 안내
  *
@@ -26,6 +27,7 @@ import { loadGaonConfig } from '@gaonjs/config';
 import { deriveTestDatabaseConfig, ensureTestDatabaseExists, destroyAllConnections, } from '@gaonjs/data';
 import { registerTsResolve } from '../tsResolve.js';
 import { runDbMigrate } from '../db/migrate.js';
+import { detectPackageManager, scriptRunArgs } from '../pm.js';
 /** 사용자 프로젝트에 `test` 스크립트가 있는지. */
 function hasTestScript(cwd) {
     const pkgPath = join(cwd, 'package.json');
@@ -118,7 +120,8 @@ async function provisionTestDatabases(cwd, json) {
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).
- * pnpm test 는 pnpm 관례상 `pnpm test -- <args>` 로 넘겨야 vitest 까지 도달.
+ * user script 경로는 프로젝트 선언 pm 으로 실행하며(결정 170), 인자 전달 관례는
+ * pm 별로 갈린다(pnpm·npm = `--` 분리 · yarn classic = 직접) — `scriptRunArgs`.
  */
 export async function runTestCommand(args = [], opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -135,9 +138,12 @@ export async function runTestCommand(args = [], opts = {}) {
     let cmd;
     let spawnArgs;
     if (hasTestScript(cwd)) {
-        cmd = 'pnpm';
-        // pnpm test -- <extras> — `--` 로 뒤 인자를 스크립트에 전달.
-        spawnArgs = ['test', ...(passthrough.length ? ['--', ...passthrough] : [])];
+        // 결정 170 W1: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 test 스크립트 실행
+        // (npm/yarn 스캐폴드 대응 · 공유 `pm.ts` 단일 소스). passthrough(필터 등)는
+        // pnpm·npm 은 `--` 로, yarn(classic)은 `--` 없이 전달 — scriptRunArgs 가 처리.
+        const pm = detectPackageManager(cwd);
+        cmd = pm;
+        spawnArgs = scriptRunArgs(pm, 'test', passthrough);
     }
     else {
         const vitestBin = join(cwd, 'node_modules', '.bin', 'vitest');

package/dist/dev.d.ts

@@ -15,6 +15,12 @@ export interface DevLayout {
     readonly localesDir?: string;
     /** .gaon/messages.d.ts */
     readonly messagesOut: string;
+    /** 프론트 진입(index.html)이 있는 앱이 하나라도 있는가 — env 축 적용 조건(결정 198). */
+    readonly hasFrontendApps: boolean;
+    /** 프로젝트 루트 `.env`(env 축 타입 출처 · 결정 198 · C). */
+    readonly envFile: string;
+    /** .gaon/env.d.ts */
+    readonly envOut: string;
 }
 export interface DevDeps {
     readonly layout: DevLayout;
@@ -22,6 +28,8 @@ export interface DevDeps {
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
     /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
     regenerateMessages?(localesDir: string, out: string): unknown;
+    /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
+    regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
     log(event: DevEvent): void;
     onError(err: Error): void;
@@ -32,7 +40,7 @@ export type DevEvent = {
     readonly apps: string[];
 } | {
     readonly kind: 'regen';
-    readonly target: 'tables' | 'routes' | 'messages';
+    readonly target: 'tables' | 'routes' | 'messages' | 'env';
     readonly app?: string;
 } | {
     readonly kind: 'stopped';
@@ -52,6 +60,8 @@ export interface RegenDeps {
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
     /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
     regenerateMessages?(localesDir: string, out: string): unknown;
+    /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
+    regenerateEnv?(envFile: string, out: string): unknown;
 }
 export interface RegenResult {
     /** tables.d.ts 를 재생성했는가(domain/schema 존재 시에만). */
@@ -60,6 +70,8 @@ export interface RegenResult {
     readonly apps: readonly string[];
     /** messages.d.ts 를 재생성했는가(locales/ 존재 · 결정 158 · W2). */
     readonly messages: boolean;
+    /** env.d.ts 를 재생성했는가(프론트 앱 존재 · 결정 198 · F-9 ②). */
+    readonly env: boolean;
 }
 /**
  * 워처 없이 .gaon 타입 브리지를 1회 전체 재생성한다. `gaon check` 처럼

package/dist/dev.js

@@ -42,6 +42,13 @@ export async function startDev(deps) {
         await deps.regenerateMessages(layout.localesDir, layout.messagesOut);
         deps.log({ kind: 'regen', target: 'messages' });
     }
+    // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
+    // regenerateEnv 가 throw(수리 안내) → dev 부팅 실패로 노출한다. `.env` 변경은 build-time
+    // 이라(Vite 가 서버 재시작으로 반영) 연속 워치는 두지 않는다 — 초기 1회 재생성으로 충분.
+    if (layout.hasFrontendApps && deps.regenerateEnv) {
+        await deps.regenerateEnv(layout.envFile, layout.envOut);
+        deps.log({ kind: 'regen', target: 'env' });
+    }
     // 2) 스키마 워치 → tables.d.ts 재생성.
     if (layout.schemaDir) {
         const schemaDir = layout.schemaDir;
@@ -105,7 +112,12 @@ export async function regenerateGaonOnce(layout, deps) {
     if (layout.localesDir && deps.regenerateMessages) {
         messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut)) === true;
     }
-    return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages };
+    // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
+    let env = false;
+    if (layout.hasFrontendApps && deps.regenerateEnv) {
+        env = (await deps.regenerateEnv(layout.envFile, layout.envOut)) === true;
+    }
+    return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages, env };
 }
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export function resolveDevLayout(cwd) {
@@ -113,11 +125,16 @@ export function resolveDevLayout(cwd) {
     const schemaDirPath = join(root, 'domain', 'schema');
     const appsDir = join(root, 'apps');
     const apps = [];
+    // env 축 적용 조건(결정 198) — 프론트 진입(index.html)을 가진 앱이 하나라도 있는가.
+    // API-only(index.html 없음)·스키마 전용 프로젝트는 클라 env 접근자를 안 쓰므로 제외한다.
+    let hasFrontendApps = false;
     if (existsSync(appsDir)) {
         for (const entry of readdirSync(appsDir, { withFileTypes: true })) {
             if (!entry.isDirectory())
                 continue;
             const appDir = join(appsDir, entry.name);
+            if (existsSync(join(appDir, 'index.html')))
+                hasFrontendApps = true;
             if (!existsSync(join(appDir, 'routes.ts')))
                 continue;
             apps.push({
@@ -134,6 +151,9 @@ export function resolveDevLayout(cwd) {
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
         localesDir: existsSync(localesDirPath) ? localesDirPath : undefined,
         messagesOut: join(root, '.gaon', 'messages.d.ts'),
+        hasFrontendApps,
+        envFile: join(root, '.env'),
+        envOut: join(root, '.gaon', 'env.d.ts'),
     };
 }
 // runDevCommand · DevCommandOptions 는 M9-C 에서 commands/dev.ts 로 이동.

package/dist/doctor/no-import-meta-env.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 소스(.vue)에 import.meta.env 코드 사용이 있는지(단위 테스트 진입점 · 스크립트만·주석 제외). */
+export declare function usesImportMetaEnv(source: string): boolean;
+/** apps/·shared/ 의 .vue 를 훑어 import.meta.env 직접 사용을 error 로 낸다(결정 198). */
+export declare function checkNoImportMetaEnv(cwd: string): Promise<RuleReport>;

package/dist/doctor/no-import-meta-env.js

@@ -0,0 +1,98 @@
+// @gaonjs/cli · doctor · `.vue` 의 import.meta.env 직접 사용 검출 (결정 198 · F-9 옵션 ② · error)
+//
+// `.vue`(SFC)에서 `import.meta.env.*` 를 직접 쓰면 vue-tsc 가 SFC 가상 모듈을 nodenext
+// CommonJS 출력으로 분류해 **TS1470**(`import.meta` 는 CommonJS 출력 파일에서 불가)로
+// 거부한다 — `gaon check` 가 red 지만 에러 문구가 원인·수리를 안 알려준다(F-9). 이 검사가
+// 그 지점을 먼저 잡아 수리 안내(`env` 접근자)를 준다. 값은 소스 텍스트 기반(주석 제외).
+//
+// 정답 경로(결정 198 · A/B): 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로
+// 읽는다 — `VITE_API_URL` → `env.API_URL`(접두 제거·타입드) · 내장은 `env.dev/prod/mode/
+// baseUrl`. `.env` 의 VITE_* 키가 `.gaon/env.d.ts` 로 물성화돼 없는 키는 컴파일 에러.
+// `.ts`(main.ts 의 import.meta.glob 등)는 ESM 출력이라 문제없어 검사 대상이 아니다 — .vue 만.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const blankKeepLines = (m) => m.replace(/[^\n]/g, ' ');
+// import.meta 는 `<script>` 에서만 유효하다(템플릿 보간·프로즈에는 못 쓴다). SFC 의 `<template>`
+// 텍스트가 "import.meta.env 미사용" 같은 프로즈로 언급하면 오탐이 되므로, 스캔 전 `<script>`
+// 블록 외 영역을 공백으로 지운다(줄바꿈 보존 → 라인 번호 유지). .ts 는 전체가 스크립트다.
+function scriptOnlyKeepLines(source, isVue) {
+    if (!isVue)
+        return source;
+    const kept = blankKeepLines(source); // 전체를 공백으로 시작 → script 블록만 복원.
+    const chars = kept.split('');
+    for (const m of source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)) {
+        const inner = m[1];
+        const start = (m.index ?? 0) + m[0].indexOf(inner);
+        for (let i = 0; i < inner.length; i++)
+            chars[start + i] = inner[i];
+    }
+    return chars.join('');
+}
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — "쓰지 말라" 설명 주석 오탐 방지.
+function stripCommentsKeepLines(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blankKeepLines)
+        .replace(/<!--[\s\S]*?-->/g, blankKeepLines)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
+}
+// import.meta.env 사용(공백 허용 · .env·[·글자 접근 모두). 문자열/식별자 오탐 최소화 위해
+// `import.meta` 뒤 `.env` 또는 `['env']`/`["env"]` 만 잡는다.
+const IMPORT_META_ENV = /import\s*\.\s*meta\s*(?:\.\s*env\b|\[\s*['"]env['"]\s*\])/;
+/** 소스(.vue)에 import.meta.env 코드 사용이 있는지(단위 테스트 진입점 · 스크립트만·주석 제외). */
+export function usesImportMetaEnv(source) {
+    return IMPORT_META_ENV.test(stripCommentsKeepLines(scriptOnlyKeepLines(source, true)));
+}
+/** apps/·shared/ 의 .vue 를 훑어 import.meta.env 직접 사용을 error 로 낸다(결정 198). */
+export async function checkNoImportMetaEnv(cwd) {
+    const issues = [];
+    for (const base of ['apps', 'shared']) {
+        for (const abs of await walkVue(join(cwd, base))) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const stripped = stripCommentsKeepLines(scriptOnlyKeepLines(source, true));
+            const rel = relative(cwd, abs);
+            for (const line of stripped.split('\n').map((l, i) => ({ l, i }))) {
+                if (!IMPORT_META_ENV.test(line.l))
+                    continue;
+                issues.push({
+                    rule: 'no-import-meta-env',
+                    level: 'error',
+                    file: rel,
+                    line: line.i + 1,
+                    message: `\`.vue\` 에서 import.meta.env 직접 사용: ${rel}:${line.i + 1}. SFC 는 nodenext 아래 ` +
+                        `CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부합니다(gaon check red · F-9).\n` +
+                        `→ 클라 공개 환경변수는 \`env\` 접근자로 읽으세요: \`import { env } from 'gaonjs/vue'\` 후 ` +
+                        `\`env.API_URL\`(= .env 의 VITE_API_URL · 접두 제거) · 내장은 \`env.dev/prod/mode/baseUrl\`. ` +
+                        `없는 키는 \`.gaon/env.d.ts\`(.env 스캔 생성)로 컴파일 타임에 잡힙니다(결정 198).`,
+                    detail: { file: rel, line: line.i + 1 },
+                });
+            }
+        }
+    }
+    return { rule: 'no-import-meta-env', issues };
+}
+/** dir 하위 .vue(node_modules·.gaon 제외) 절대경로. */
+async function walkVue(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -25,10 +25,10 @@ export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-bu
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 23개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
  */
 /**
- * doctor 정적 검사 25종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 25 검사를 조립한다:
+ * 26 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -27,6 +27,7 @@
  * 23) link-button-nesting (결정 113 · Link 로 Button 감싸기 = <a><button> 중첩 경고)
  * 24) seal-security (결정 121 · seal 클라 배선 · 보안 역전)
  * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
+ * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -64,6 +65,7 @@ import { checkAsyncOffload } from './doctor/async-offload.js';
 import { checkSealSecurity } from './doctor/seal-security.js';
 import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
+import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -92,10 +94,10 @@ export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-bu
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 23개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 26개 모두.
  */
 /**
- * doctor 정적 검사 25종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 26종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -125,6 +127,7 @@ export const ALL_RULES = [
     'link-button-nesting',
     'seal-security',
     'schema-relations',
+    'no-import-meta-env',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -152,6 +155,7 @@ const CHECKERS = {
     'link-button-nesting': checkLinkButtonNesting,
     'seal-security': checkSealSecurity,
     'schema-relations': checkSchemaRelations,
+    'no-import-meta-env': checkNoImportMetaEnv,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/env-gen.d.ts

@@ -0,0 +1,12 @@
+/** `.env` 본문에서 `VITE_*` 키를 접두 제거해 뽑는다(중복 제거·정렬). */
+export declare function parseViteEnvKeys(content: string): string[];
+/** VITE_ 키 유니온을 gaonjs/vue augment d.ts 로 렌더한다. 값 타입은 Vite 관례상 string. */
+export declare function renderEnvDts(keys: readonly string[]): string;
+/** `.env` 가 없을 때의 수리 안내 오류 메시지(결정 198 · C). */
+export declare function missingEnvError(envFile: string): string;
+/**
+ * `.env` 에서 .gaon/env.d.ts 를 생성한다. `.env` 가 없으면 **throw**(결정 198 · C ·
+ * 프론트 앱 전제). 이 함수를 부르는 쪽(orchestrator)이 프론트 앱 유무로 호출을
+ * 게이트하므로, API-only·스키마 전용 프로젝트는 여기 도달하지 않는다. 생성했으면 true.
+ */
+export declare function generateEnvDts(envFile: string, out: string): boolean;

package/dist/env-gen.js

@@ -0,0 +1,63 @@
+// @gaonjs/cli · .gaon/env.d.ts 생성기 (결정 198 · F-9 옵션 ②)
+//
+// tables·routes·messages 에 이은 .gaon 파이프라인의 클라이언트 환경변수 축. `.env`
+// 의 `VITE_*` 키(Vite 표준 공개 접두)를 스캔해 `gaonjs/vue` 의 GaonClientEnv 를
+// augment 한다 — `.vue`·클라 `.ts` 에서 `env.<없는키>` 를 컴파일 타임에 잡는다.
+// 생성 파일은 타입만 담는다(규칙 3). 지정자는 파사드 서브패스 `gaonjs/vue`(결정 56·
+// 158 동형 · 사용자는 gaonjs 하나만 의존하므로 @gaonjs/vue 는 루트에서 미해석).
+//
+// 결정 198 · C(회원님): 타입 출처는 `.env`(.env.example 아님). 프론트 앱이 있는데
+// `.env` 가 없으면 gen/dev/build/check 가 **명확 오류**를 낸다 — `.env` 는 앱 실행
+// 전제라, 없으면 설정 부재를 조용히 넘기지 않고 노출한다(우회 X · §7.5.3).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const VITE_PREFIX = 'VITE_';
+// KEY=value 라인에서 키만 뽑는다(export 접두 · 앞 공백 허용). 값·따옴표는 안 본다.
+const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** `.env` 본문에서 `VITE_*` 키를 접두 제거해 뽑는다(중복 제거·정렬). */
+export function parseViteEnvKeys(content) {
+    const keys = new Set();
+    for (const line of content.split(/\r?\n/)) {
+        const m = ENV_LINE.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (key.startsWith(VITE_PREFIX) && key.length > VITE_PREFIX.length) {
+            keys.add(key.slice(VITE_PREFIX.length));
+        }
+    }
+    return [...keys].sort();
+}
+/** VITE_ 키 유니온을 gaonjs/vue augment d.ts 로 렌더한다. 값 타입은 Vite 관례상 string. */
+export function renderEnvDts(keys) {
+    const body = keys.length > 0
+        ? keys.map((k) => `    readonly ${k}: string`).join('\n')
+        : `    // (.env 에 VITE_* 공개 변수 없음 — 내장 필드 env.dev/mode/... 만 사용 가능)`;
+    return (`// 이 파일은 gaon 이 .env 의 VITE_* 키에서 생성한다 — 직접 수정하지 마세요.\n` +
+        `// 결정 198 · F-9 옵션 ②: 클라이언트 공개 환경변수 타입 브리지(gaonjs/vue env).\n` +
+        // gaonjs/vue 서브패스로 augment 해야 사용자 프로젝트에서 병합된다(결정 56·158 동형).
+        `declare module 'gaonjs/vue' {\n` +
+        `  interface GaonClientEnv {\n${body}\n  }\n` +
+        `}\n` +
+        `export {}\n`);
+}
+/** `.env` 가 없을 때의 수리 안내 오류 메시지(결정 198 · C). */
+export function missingEnvError(envFile) {
+    return (`클라이언트 환경변수 타입을 생성할 수 없습니다 — ${envFile} 가 없습니다.\n` +
+        `→ 프로젝트 루트에 .env 를 만드세요:  cp .env.example .env\n` +
+        `   (\`VITE_*\` 접두 변수만 클라 번들·env 접근자에 노출됩니다 · 그 외는 서버-only)`);
+}
+/**
+ * `.env` 에서 .gaon/env.d.ts 를 생성한다. `.env` 가 없으면 **throw**(결정 198 · C ·
+ * 프론트 앱 전제). 이 함수를 부르는 쪽(orchestrator)이 프론트 앱 유무로 호출을
+ * 게이트하므로, API-only·스키마 전용 프로젝트는 여기 도달하지 않는다. 생성했으면 true.
+ */
+export function generateEnvDts(envFile, out) {
+    if (!existsSync(envFile)) {
+        throw new Error(missingEnvError(envFile));
+    }
+    const keys = parseViteEnvKeys(readFileSync(envFile, 'utf8'));
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, renderEnvDts(keys), 'utf8');
+    return true;
+}

package/dist/index.js

@@ -146,7 +146,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 25종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 26종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);

package/dist/pm.d.ts

@@ -0,0 +1,13 @@
+export type PackageManager = 'pnpm' | 'npm' | 'yarn';
+/**
+ * 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는 package.json 의
+ * `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을 기록하므로 그것을
+ * 최우선으로 삼고, 없으면 락파일, 그래도 없으면 pnpm(골든 경로 기본).
+ */
+export declare function detectPackageManager(cwd: string): PackageManager;
+/**
+ * `<pm> run <script>` 실행 인자를 pm 별 passthrough 관례에 맞춰 만든다. 잔여
+ * 인자가 있을 때 pnpm·npm 은 `--` 로 스크립트에 분리 전달해야 하고(그래야 vitest
+ * 필터 등이 도달), yarn(classic)은 `--` 없이 직접 전달한다(결정 170 W1).
+ */
+export declare function scriptRunArgs(pm: PackageManager, script: string, extras?: readonly string[]): string[];

package/dist/pm.js

@@ -0,0 +1,59 @@
+/**
+ * @gaonjs/cli · 패키지 매니저 해상 — pm-awareness 단일 소스 (결정 170)
+ *
+ * CLI 는 대부분 도구를 직접 spawn 한다(vitest·vite·tsc·vue-tsc·node·docker =
+ * pm 무관). pm 이 관여하는 접점은 **딱 셋** 뿐이다:
+ *   1) `gaon new`  초기 install (`new.ts` · `--package-manager` 선택)
+ *   2) `gaon check` build 등 user script (`commands/check.ts`)
+ *   3) `gaon test`  test user script (`commands/test.ts`)
+ *
+ * (2)·(3) 은 사용자 스크립트를 **프로젝트가 선언한 pm** 으로 돌려야 한다 —
+ * pnpm 하드코딩은 npm/yarn 로 스캐폴드한 프로젝트에서 pnpm 이 "This project is
+ * configured to use npm" 으로 실행을 거부해 깨진다. 이 해상 로직을 한 모듈에
+ * 모아 check·test 가 **같은 함수**를 쓴다(중복 하드코딩 재발 차단 · 결정 170 W2).
+ *
+ * anti-creep(결정 170 W3): 새 CLI 명령은 도구를 직접 부른다(pm 무관). 부득이
+ * pm 이 필요하면 4번째 하드코딩을 만들지 말고 **반드시 이 모듈을 경유**한다.
+ * pnpm = 골든/보장 경로 · npm/yarn = best-effort 탈출구(§6 · CLAUDE.md).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 프로젝트가 선언한 패키지 매니저를 감지한다. `gaon new` 는 package.json 의
+ * `packageManager` 필드(corepack 핀 · 결정 169)에 선택 pm 을 기록하므로 그것을
+ * 최우선으로 삼고, 없으면 락파일, 그래도 없으면 pnpm(골든 경로 기본).
+ */
+export function detectPackageManager(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const pm = pkg.packageManager?.split('@')[0];
+            if (pm === 'pnpm' || pm === 'npm' || pm === 'yarn')
+                return pm;
+        }
+        catch {
+            // 파싱 실패는 락파일/기본으로 폴백
+        }
+    }
+    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(cwd, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(cwd, 'package-lock.json')))
+        return 'npm';
+    return 'pnpm';
+}
+/**
+ * `<pm> run <script>` 실행 인자를 pm 별 passthrough 관례에 맞춰 만든다. 잔여
+ * 인자가 있을 때 pnpm·npm 은 `--` 로 스크립트에 분리 전달해야 하고(그래야 vitest
+ * 필터 등이 도달), yarn(classic)은 `--` 없이 직접 전달한다(결정 170 W1).
+ */
+export function scriptRunArgs(pm, script, extras = []) {
+    const base = ['run', script];
+    if (extras.length === 0)
+        return base;
+    if (pm === 'yarn')
+        return [...base, ...extras];
+    return [...base, '--', ...extras];
+}

package/dist/templates/project/.env.example.tpl

@@ -30,3 +30,9 @@ COOKIE_SECRET=change-me-too-32-char-random-secret!!
 
 # 리슨 포트 (gaon serve --port 로 덮음).
 PORT=3000
+
+# 클라이언트 공개 환경변수(결정 198) — `VITE_` 접두 변수만 브라우저 번들에 노출된다(그 외는
+# 서버-only). `.vue`·클라 `.ts` 에서 `import { env } from 'gaonjs/vue'` 로 읽는다(import.meta.env
+# 직접 사용은 vue-tsc TS1470 · doctor no-import-meta-env 가 잡음). 접두는 제거된다: 아래를 켜면
+# `env.API_URL` 로 접근. `.env` 의 VITE_* 키가 `.gaon/env.d.ts` 로 물성화돼 없는 키는 컴파일 에러.
+# VITE_API_URL=https://api.example.com

package/dist/templates/project/AGENTS.md.tpl

@@ -108,7 +108,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 25종
+### 2.2 `gaon doctor` 검사 26종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -135,6 +135,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 23. `link-button-nesting` — `<Link><Button>…</Button></Link>` 이중 감싸기(`<a><button>` 중첩 · HTML 비준수·접근성 결함 · 버튼 모양 링크는 `<Button href="…">` 한 표면을 쓰라 · Link 직계 자식 Button 만 검출) (결정 113 · 경고)
 24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon check --fix` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
 25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134 · `agents/data.md`)
+26. `no-import-meta-env` — `.vue`(SFC) `<script>` 에서 `import.meta.env` 직접 사용 = **에러**. SFC 는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부한다(`gaon check` red). 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로 읽으라(VITE_* 접두 제거·타입드 · `.gaon/env.d.ts` 는 `.env` 스캔 생성) — 템플릿 프로즈·주석의 언급은 오탐 제외 (결정 198 · `agents/frontend.md` §9)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -195,7 +196,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 25종 (§2.2)
+gaon doctor       # 정적 검사 26종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

package/dist/templates/project/agents/async.md.tpl

@@ -247,21 +247,51 @@ export default schedule((s) => {
   (`.later()`), 처리·스케줄은 워커가 한다. 스케줄이 안 도는 흔한 원인은
   `gaon work` 를 안 띄운 것이다.
 
+#### 시간대 (결정 202)
+
+`s.daily.at('04:00', Job)`·`s.cron('0 9 * * 1', Job)` 는 **서버 로컬 타임존**의
+wall-clock 으로 매치한다(`new Date()` 로컬 시·분·요일). v1 은 **잡별 타임존
+옵션이 없다** — 특정 TZ 로 돌려야 하면 워커 프로세스의 `TZ` 환경변수를 그
+타임존으로 띄운다(예: `TZ=Asia/Seoul gaon work`). 여러 인스턴스는 같은 TZ 로
+맞춘다(리더가 어느 인스턴스든 같은 wall-clock 을 봐야 한다).
+
+#### 중첩 방지 (결정 202)
+
+스케줄러는 매 주기 **발행만** 한다(§7 리더). 한 주기보다 오래 걸리는 잡이
+**자기 자신과 겹쳐** 실행되면 안 되면, 잡 핸들러가 `lock(key, fn, { onBusy:
+'skip' })` 으로 임계구역을 지킨다 — 이미 도는 인스턴스가 있으면 이번 틱은
+스킵된다(중복 실행 방지). 락은 `gaon work` 워커에서도 배선된다(결정 202).
+
 ### 6. 워커 프로세스 (`gaon work`)
 
 잡·리스너·스케줄러·아웃박스 릴레이를 한 프로세스로 조립한다. 운영
 프로세스 3종(serve·work·hub) 중 하나. SIGTERM/SIGINT 에 graceful
 drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤 종료한다.
 
+#### graceful drain 계약 (결정 201)
+
+배포·재시작(k8s 롤링 등)에서 **SIGTERM 이 진행 중 작업을 자르지 않는다**:
+
+- **`gaon serve`** — 인플라이트 HTTP 요청을 **완료까지 기다린 뒤** 종료한다(리셋
+  안 함 · 롤링 배포 중 502 방지). 새 연결은 안 받고, 진행 요청이 끝나면 idle
+  keep-alive 를 닫아 종료가 즉시 완결된다(결정 201 · `forceCloseConnections:false`
+  + close idle 스윕).
+- **`gaon work`** — 신규 잡 pull 을 멈추고 **진행 중 잡을 완료**한 뒤 종료한다
+  (`drainTimeoutMs` 상한 · 기본 30s). 스케줄러 리더는 즉시 반납해 다른 인스턴스가
+  승계한다. drain 상한을 넘긴 잡은 ack 되지 않아 재전달(크래시 복구)된다.
+- **컨테이너 기본 워커 1** — `gaon serve` 클러스터(`--workers`)도 SIGTERM 에
+  워커들을 graceful drain 후 종료한다(결정 84).
+
 ### 7. 분산 락 (`lock()`) (결정 147)
 
 **동시 실행을 막아야 하면 `lock(key, fn)`** — 같은 `key` 에 대해 전
 인스턴스를 통틀어 동시 1개의 `fn` 만 임계구역에 들인다. **로컬 뮤텍스는
 반정본이다** — 멀티 인스턴스(워커 여러 대·serve 여러 대)에서는 프로세스마다
 따로 놀아 무의미하다(결정 88 ①). 그래서 백엔드는 Redis 다: 설정에 `redis`
-가 있으면 `gaon serve` 가 분산 락을 자동 배선한다. **`redis` 미설정 상태로
-`lock()` 을 부르면 로컬 뮤텍스로 조용히 떨어지지 않고 수리 안내와 함께
-throw** 한다.
+가 있으면 **`gaon serve` 와 `gaon work` 둘 다** 분산 락을 자동 배선한다(결정
+202 · wireDomain 공통 경로) — 그래서 **잡·서비스 안에서도 `lock()` 을 쓸 수
+있다**(예: 중첩 방지 · §5). **`redis` 미설정 상태로 `lock()` 을 부르면 로컬
+뮤텍스로 조용히 떨어지지 않고 수리 안내와 함께 throw** 한다.
 
 ```ts
 import { lock } from 'gaonjs/async'
@@ -344,4 +374,7 @@ async create() {
 | 결정 103 | doctor `async-offload` 검사 (컨트롤러 인라인 메일·이미지·외부 HTTP 경고) |
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |
 | 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`agents/testing.md`) |
+| 결정 200 | DLQ 재처리 `retryDlq(nats, id)` (이미 설정된 잡 전송 보존 · DLQ 재적재 후 원본 삭제) |
+| 결정 201 | graceful drain 계약 (serve 인플라이트 요청 완결 · work 진행 잡 완결 · §6) |
+| 결정 202 | 락·캐시 백엔드 serve·work 공통 배선(wireDomain) · 잡/서비스 lock() 가능 · 스케줄러 시간대(서버 로컬 TZ)·중첩 방지(§5·§7) |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |

package/dist/templates/project/agents/frontend.md.tpl

@@ -251,6 +251,24 @@ import PageShell from '@shared/components/ui/PageShell.vue'
 | 원자 (18) | Button · Input · Label · Badge · Card · CardHeader · CardTitle · CardDescription · CardContent · CardFooter · Alert · AlertTitle · AlertDescription · Form · FormField · FormMessage · Dialog · Sheet |
 | 블록 (4 · 결정 106) | PageShell · PageHeader · EmptyState · Pagination |
 
+**슬롯·props 요약 (첫 시도용 · 소스 안 읽어도 되게 · O-2):** 카탈로그는 이름만이라 슬롯/prop 을
+소스에서 찾아야 했다 — 자주 쓰는 표면을 여기 못박는다(전체·정확한 타입은 컴포넌트 소스가 정본).
+**주의: named slot 이름이 비대칭이다** — `PageHeader` 는 `#actions`(**복수**), `EmptyState` 는
+`#action`(**단수**). 기본 슬롯을 잘못 쓰면 조용히 안 그려진다.
+
+| 컴포넌트 | props | slots | emits |
+|---|---|---|---|
+| **PageShell** | `size?: 'default'\|'narrow'\|'wide'\|'full'` | 기본 | — |
+| **PageHeader** | `title?` · `description?` | `#title` · `#description` · **`#actions`**(복수) | — |
+| **EmptyState** | `title?` · **`description?`(prop)** | `#icon` · `#title` · `#description` · **`#action`**(단수) | — |
+| **Pagination** | `page`(필수) · `pageCount`(필수) · `siblings?=1` | — | `update:page` (= `v-model:page`) |
+| Button | `variant?='default'` · `size?='default'` · `type?='button'` · `href?` · `external?` · `target?` | 기본 | 네이티브(예 `@click`) |
+| FormField | `label?` · `error?` | 기본(컨트롤) | — |
+| FormMessage | `message?` | — | — |
+| Alert | `variant?: 'default'\|'destructive'` | 기본 | — |
+| Badge | `variant?: 'default'\|'secondary'\|'destructive'\|'outline'` | 기본 | — |
+| Card / CardHeader / CardTitle / CardDescription / CardContent / CardFooter | — | 기본(조합) | — |
+
 - **블록은 성격 중립(결정 106)** — 관리자/프론트를 나누지 않고 전 앱에서 쓴다.
   `PageShell`(최대폭·여백·세로 리듬) · `PageHeader`(제목+설명+액션) · `EmptyState`
   (빈 목록) · `Pagination`(페이지 이동 · `v-model:page`). 이외 블록(DataTable·StatCard·
@@ -287,7 +305,7 @@ import PageShell from '@shared/components/ui/PageShell.vue'
   통째로 넘기면, 블록의 `:page`·`:pageCount` 가 필드명 그대로 붙는다(매핑 보일러플레이트 0).
   ```vue
   <script setup lang="ts">
-  import { Pagination } from '@shared/components/ui'
+  import Pagination from '@shared/components/ui/Pagination.vue'
   import { router } from 'gaonjs/vue'
   const props = pageProps<'web:posts#index'>()  // props.page = paginate 결과
   function goto(p: number) { router.get('/posts', { page: p }, { preserveState: true }) }
@@ -311,6 +329,37 @@ import PageShell from '@shared/components/ui/PageShell.vue'
 `tailwind.config.ts` 의 `content` 에 `./shared/**/*.{vue,ts}` 가 있는지도 확인한다
 (스캐폴드 기본값엔 이미 포함).
 
+### 9. 클라이언트 환경변수 — `env` (결정 198 · F-9 옵션 ②)
+
+`.vue`·클라 `.ts` 에서 공개 환경변수는 **`env` 접근자**로 읽는다 — `import.meta.env`
+를 직접 쓰지 않는다. `.vue`(SFC)는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가
+`import.meta` 를 **TS1470** 로 거부하기 때문이다(`gaon check` red). 프레임웍이
+`import.meta.env` 를 대신 읽어 재노출하므로 페이지는 `import.meta` 를 안 쓴다.
+
+```vue
+<script setup lang="ts">
+import { env } from 'gaonjs/vue'
+
+const api = env.API_URL      // .env 의 VITE_API_URL — VITE_ 접두 제거 · 타입드
+if (env.dev) console.log(env.mode)   // 내장: dev·prod·mode·baseUrl(camelCase 정규화)
+</script>
+```
+
+- **노출 정책 = Vite 표준 `VITE_*`** — `.env` 의 `VITE_` 접두 변수만 클라 번들에
+  노출된다(그 외 `SECRET_KEY`·`DATABASE_URL` 등은 **자동 서버-only**, 번들에 절대 안 감).
+  접근자에서 접두는 제거된다: `VITE_API_URL` → `env.API_URL`.
+- **타입 안전** — `.env` 의 VITE_* 키가 `.gaon/env.d.ts`(gen/dev/build/check 재생성)로
+  물성화돼 `gaonjs/vue` 의 `GaonClientEnv` 를 augment 한다. `env.<없는키>` 는 컴파일
+  에러(messages.d.ts 동형 · 결정 158). 키를 추가하면 `.env` 에 `VITE_...` 를 넣는다.
+- **`.env` 필수** — 프론트 앱이 있으면 `.env` 가 없을 때 gen/dev/build/check 가 명확히
+  실패한다(수리 안내: `cp .env.example .env`). `.env` 는 앱 실행 전제다.
+- **내장 필드**: `env.mode`(빌드 모드)·`env.dev`/`env.prod`(불리언)·`env.baseUrl`
+  (앱 base · web='/'·admin='/admin/'). `import.meta.env.MODE/DEV/PROD/BASE_URL` 대체.
+- **doctor**: `.vue` 에서 `import.meta.env` 직접 사용은 **no-import-meta-env** 가
+  error 로 잡아 `env` 접근자로 안내한다(TS1470 을 읽기 전에).
+- 서버 코드(컨트롤러·domain)의 환경변수는 이 접근자가 아니라 서버 env(`gaon.config.ts`
+  의 `env('KEY')`·`process.env`)로 읽는다 — `env`(gaonjs/vue)는 **클라 전용**이다.
+
 ## 정본 예시
 
 ```vue
@@ -406,6 +455,8 @@ async function runSearch(q: string) {
 | 결정 116 | 공유 prop(currentUser·csrf·flash) 자동 주입 · `useShared()` 로 읽기(라우트 키 불요 · `agents/web.md`) |
 | 결정 150 | 앱 전역 공유 키 확장 — `app.config` sharedProps 등록 → useShared 로 읽기(코어 3종 고정 · 선언 병합 타입 · hidden 미유출 · `agents/web.md` §4.2) |
 | 결정 119 | `Pagination` 블록이 `chain.paginate()` 결과에 정합(`:page`·`:pageCount` 필드 그대로 · 매핑 0 · `agents/data.md`) |
+| 결정 198 | 클라 환경변수 접근자 `env`(gaonjs/vue · `.vue` 의 import.meta.env TS1470 회피) · VITE_* 접두만 노출·접두 제거 · `.gaon/env.d.ts`(.env 스캔) 타입 브리지 · doctor no-import-meta-env(§9) |
+| 결정 206 | UI 킷 §8 슬롯·props 요약표(카탈로그가 이름만이라 소스 열람 유발 · O-2 해소) · named slot 비대칭 명시(PageHeader `#actions` 복수 vs EmptyState `#action` 단수) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |
 
 ## `@gaonjs/seal` 켠 앱의 프론트

package/dist/templates/project/agents/i18n.md.tpl

@@ -32,6 +32,29 @@ t('nav.home')                     // 중첩은 점 표기
 | 지원 언어 | `languages(): string[]` | 설정된 supportedLngs |
 | 고정 번역 | `runWithLanguage(lng, fn)` | fn 안의 t() 가 그 언어(메일·비요청 경로 · §mail) |
 
+### 1.5 복수형 — `count` 로 자동 선택 (i18next 규약 · 결정 181)
+
+복수형은 카탈로그에 **접미사 키**(`<키>_one`·`<키>_other`)를 두고 `t('<키>', { count })`
+로 부른다 — i18next 가 `count` 와 로케일의 CLDR 규칙으로 알맞은 접미사를 고른다. 타입은
+**base 키**(`<키>`)로 검사한다(생성기가 접미사 키에서 base 키를 함께 노출 · 결정 181).
+
+```json
+// locales/en.json — 영어는 단수/복수 구분(_one·_other)
+{ "cart": { "items_one": "{{count}} item", "items_other": "{{count}} items" } }
+// locales/ko.json — 한국어는 복수 구분 없음(_other 만)
+{ "cart": { "items_other": "상품 {{count}}개" } }
+```
+
+```ts
+t('cart.items', { count: 1 })   // en → "1 item" · ko → "상품 1개"
+t('cart.items', { count: 5 })   // en → "5 items" · ko → "상품 5개"
+```
+
+- **base 키로 부른다** — `t('cart.items', { count })`. `t('cart.items_one')` 처럼 접미사를
+  직접 부르면 복수 선택이 안 된다(안티패턴).
+- 로케일마다 필요한 접미사만 둔다(영어 `_one`·`_other` / 한국어·일본어 `_other`). 기준
+  로케일(§4)에 있는 키가 타입 유니온이 되므로 **기준 로케일 카탈로그에 복수형 키를 둔다**.
+
 ### 2. 요청별 로케일 자동 협상 (결정 159)
 
 `gaon.config.ts` 에 `i18n` 설정이 있으면 `gaon serve`/`gaon dev` 가 **매 요청**
@@ -97,6 +120,9 @@ export function greetLine(name: string): string {
   전환은 `this.setLocale`, 특정 로케일 강제는 `runWithLanguage`.
 - **메일은 요청 로케일이 아니라 수신자 로케일** — `deliver(data, { locale })` 로
   명시한다(`agents/mail.md` · 결정 160).
+- **검증 실패 문안도 로케일화된다** — 예약 namespace `validation.<code>`(예 `validation.required`)
+  를 `locales/` 에 넣으면 필드별 사유가 요청 로케일로 번역된다(`agents/web.md` §4.1 · 결정 183).
+  프레임웍은 코드만 노출하고 번역은 앱 몫이다(미제공 시 내장 fallback).
 
 ## 관련 결정 번호
 

package/dist/templates/project/agents/mail.md.tpl

@@ -57,6 +57,37 @@ await WelcomeMail.deliver(data, { locale: 'ja', to: 'ops@example.com' })
 ·`.env.example` 에 mail 블록이 이미 있어(결정 160) `cp .env.example .env` 후 바로 돈다.
 운영은 `SMTP_HOST`·자격증명·`SMTP_SECURE=true` 로 교체(같은 코드).
 
+### 5. `gaon.config.ts` 의 `mail` 블록 (env-gated)
+
+메일러는 루트 `gaon.config.ts` 의 `mail` 블록으로 배선된다 — `db`·`redis`·`nats`
+동형으로 **env-gated**(SMTP_HOST 없으면 미배선). 스캐폴드(`gaon new`)가 아래 블록을
+이미 넣어 둔다(결정 160). 발신자 기본값은 **`defaultFrom`**(메시지 `from` 아님 · `from`
+은 개별 메시지 override).
+
+```ts
+// gaon.config.ts
+export default defineConfig({
+  mail: process.env.SMTP_HOST
+    ? {
+        host: process.env.SMTP_HOST,
+        port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : 1025,
+        secure: process.env.SMTP_SECURE === 'true', // 운영 TLS
+        user: process.env.SMTP_USER,                 // 선택(인증 SMTP)
+        pass: process.env.SMTP_PASS,                 // 선택
+        defaultFrom: process.env.MAIL_FROM,          // 발신자 기본값(from 없는 메시지)
+      }
+    : undefined,
+})
+```
+
+| 필드 | 타입 | 비고 |
+|---|---|---|
+| `host` | `string` | SMTP 호스트(dev = MailPit `127.0.0.1`) |
+| `port` | `number` | SMTP 포트(dev MailPit = 1025) |
+| `secure?` | `boolean` | TLS(운영). 생략 = false |
+| `user?`·`pass?` | `string` | 인증 SMTP 자격증명(생략 가능) |
+| `defaultFrom` | `string` | 발신자 기본값 — 메시지에 `from` 이 없을 때. `configureMailer({ defaultFrom })` 와 동치 |
+
 ## 정본 예시
 
 ```ts

package/dist/templates/project/agents/realtime.md.tpl

@@ -186,6 +186,15 @@ export function useRoom(roomId: number) {
 - 허브가 죽었다 재시작하면 같은 포트로 재bind 하고 KV 에서 상태를
   복원한다.
 - ping 무활동 타임아웃은 네트워크 파티션 백스톱이다.
+- **fail-fast — 리더가 됐는데 포트를 못 잡으면 즉시 종료한다(결정 207).**
+  리스는 얻었으나 TCP 포트 bind 에 실패하면(포트를 다른 허브·orphan·
+  오설정이 점유) 허브는 **좀비 리더**(리스 보유·프레즌스 서빙 불가)가 되지
+  않도록 리스를 사임하고 `process.exit(1)` 한다. 조용히 프레즌스가 죽는
+  대신 명확히 종료해 systemd/pm2 가 재시작하게 하고, 대기 인스턴스가 즉시
+  승계한다. **운영 함정**: 한 호스트에 허브를 여러 개 띄우면 포트가
+  겹친다 — 인스턴스마다 다른 `GAON_HUB_PORT` 를 주거나 호스트를 분리한다.
+  `gaon dev` 는 내장 허브를 기본 포트로 띄우므로, 같은 호스트에서 별도
+  `gaon hub` 를 돌릴 땐 포트를 바꾼다.
 
 ## 정본 예시
 
@@ -255,6 +264,7 @@ export default channel({
 | §7 (v0.15) | 실시간 v1 포함 — 채널·프레즌스·허브 · KV 영속 · 리스 리더 선출 HA |
 | 결정 126 | 서버 개시 `broadcast(name, data)`(`gaonjs/async`) — 컨트롤러·서비스·잡에서 클라 메시지 없이 채널 발화 · authorize 재실행 없음 · seal 재봉인 자동 |
 | 결정 154 | `useChannel` 앱 프리픽스 자동 주입 — `import.meta.env.BASE_URL`(vite base·에셋 base 단일 소스) 로 `<프리픽스>/gaon/ws/<name>` · `opts.path` 는 탈출구 · 프리픽스 앱 실시간 무한 재연결 제거(§4) |
+| 결정 207 | 허브 fail-fast(§5) — 리스는 얻고 TCP 포트 bind 실패 시 좀비 리더 대신 리스 사임 + `process.exit(1)`(F-13 fix · `onFatal` 훅으로 주입 가능) |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

package/dist/templates/project/agents/testing.md.tpl

@@ -24,10 +24,13 @@
   매 테스트 뒤 전 테이블을 비운다(`truncateAll`). 아래 §5 참고.
 - `gaon test` 가 잡·이벤트 NATS 스트림도 **자동 격리**한다(결정 130) —
   테스트 프로세스에 `GAON_STREAM_PREFIX` 를 주입해 스트림·subject 가
-  `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로 갈린다. 그래서 개발용 `gaon work` 가
-  떠 있어도 테스트 잡을 훔치지 않고, 테스트가 남긴 잡을 개발 워커가 처리하지도
-  않는다 — **테스트 전에 워커를 내릴 필요가 없다.** (직접 `vitest` 로 돌리면 이
-  격리가 없어 개발 스택과 섞이니 `gaon test` 를 쓴다.)
+  `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로 갈린다. 같은 접두가 **NATS KV 버킷**
+  (스케줄러 리스 `gaon_lease`·프레즌스·허브)에도 적용돼(결정 203) `test_gaon_lease`
+  처럼 격리된다 — 스트림뿐 아니라 KV 도 개발·운영 스택과 안 겹친다. 그래서
+  개발용 `gaon work` 가 떠 있어도 테스트 잡을 훔치지 않고 스케줄러 리더 경합도
+  안 생기며, 테스트가 남긴 잡을 개발 워커가 처리하지도 않는다 — **테스트 전에
+  워커를 내릴 필요가 없다.** (직접 `vitest` 로 돌리면 이 격리가 없어 개발 스택과
+  섞이니 `gaon test` 를 쓴다.)
 - SQLite 는 Docker 가 불가능한 환경의 폴백으로만 남고 공식 경로가
   아니다.
 
@@ -256,5 +259,6 @@ hidden 값은 **서버 코드에서는 여전히 읽힌다**(직렬화 경계에
 | 결정 122 | 직렬화 경계 테스트는 관계 경유 hidden 을 반드시 포함(재귀 no-leak 단언) |
 | 결정 111 | `gaon test` 테스트 DB 자동 준비 + `connectTestDatabase`·`truncateAll` 격리(truncate · service COMMIT 실측) |
 | 결정 130 | `gaon test` 가 NATS 스트림도 자동 격리(`GAON_STREAM_PREFIX` → `GAON_TEST_JOBS`·`test.gaon.jobs.>`) — 개발 워커 병행 시 잡 누출 방지(규칙 10 이행) |
+| 결정 203 | 같은 접두를 **NATS KV 버킷**에도 적용(`gaon_lease`·프레즌스·허브 → `test_gaon_lease` 등) — 스트림만 격리하던 결정 130 의 빈틈(KV 미격리)을 메움. 스케줄러 리스 경합·크로스-프리픽스 KV 누출 방지 |
 | §9 (v0.15) | 실 인프라 필수 · 목업/인메모리 금지 |
 | 결정 32 | 잡 발행 위치 자유 — publish 함수가 서비스 경유여도 검증 대상 |

package/dist/templates/project/agents/web.md.tpl

@@ -239,6 +239,35 @@ async create() {
 
 순수 JSON/API 앱(X-Inertia 아님·세션 없음)은 기존대로 **422 JSON** 을 받는다.
 
+#### 검증 사유 로케일화 — 예약 namespace `validation.*` (결정 183)
+
+검증 실패의 **필드별 사유**(`form.errors.<필드>` 로 엔드유저에 노출되는 부분)는 요청
+로케일로 번역된다 — `i18n` 이 설정돼 있고 앱이 `locales/<lng>.json` 의 **예약 namespace
+`validation.<code>`** 로 번역을 제공하면. 프레임웍은 **안정적 코드만** 노출하고 번역은
+앱 몫이다(The One Way: 코드는 프레임웍, 문안은 앱). 키가 없으면 내장 fallback(한국어)로
+떨어져 거동이 보존된다. i18n 미설정이면 항상 fallback.
+
+| code | 파라미터 | 언제 |
+|---|---|---|
+| `required` | — | 필수 컬럼 누락 |
+| `too_long` | `{ max, len }` | `.max(n)` 초과 |
+| `not_allowed` | `{ value, allowed }` | enum 밖 값 |
+| `not_integer` | `{ value }` | bigint 변환 실패 |
+| `not_boolean` | `{ value }` | boolean 변환 실패 |
+| `not_date` | `{ value }` | 날짜 변환 실패 |
+
+```json
+// locales/en.json — 앱이 검증 문안을 로케일별로 준다(i18next {{max}} 보간).
+{ "validation": {
+    "required": "This field is required.",
+    "too_long": "At most {{max}} characters (got {{len}})."
+} }
+```
+
+주의: 상단 개발자용 422 `message`(스키마 어느 파일을 고치라는 §7.5.3 **수리 안내**)는
+로케일화하지 않는다 — AI/개발자용 고정 안내다. 로케일화 대상은 **엔드유저에 닿는 필드별
+사유**뿐이다.
+
 #### 세션/CSRF 실패·415 도 코어가 Inertia-네이티브로 마감한다 (결정 165)
 
 폼 검증(결정 109)과 **대칭**으로, 컨트롤러 액션 밖(디스패처 try-catch 밖)에서 나는
@@ -423,6 +452,13 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
 
   API 앱(JWT)은 세션 대신 `this.jwt.issue(user)` / `this.jwt.refresh(token)` 를 쓴다.
 
+- **API 앱은 프론트엔드가 없다(JSON 전용).** `apps/<app>/app.config.ts`(`auth: { strategy:'jwt', … }`)
+  + `routes.ts` + `controllers/` 만 두면 된다 — `index.html`·`main.ts`·`pages/` 는 만들지 않는다.
+  앱 발견은 `routes.ts` 기준이라 `gaon serve` 가 이 앱을 `/<app>` 프리픽스로 정상 마운트하고,
+  `gaon build`·`gaon check` 는 프론트 앱(=`index.html` 보유)만 검사하므로 API 앱을 프론트로
+  오검사하지 않는다. JWT 앱의 표준 형태다("프론트엔드는 프로젝트당 하나" 규칙은 Vue 앱 한정 ·
+  API 앱은 그 규칙 밖).
+
 - **`this.auth.user`/`requireAuth()` 사용자 타입은 앱이 증강한다** (결정 58).
   `GaonCurrentUser` 는 빈 인터페이스라 증강 없이는 `user.id` 접근이 타입에러다.
   `gaon g auth` 가 `apps/<app>/auth.ts` 에 심는다:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.36.0",
-  "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
+  "version": "0.37.1",
+  "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
   "homepage": "https://gaonjs.dev",
@@ -27,13 +27,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.11.0",
-    "@gaonjs/mail": "0.2.0",
-    "@gaonjs/core": "0.2.1",
-    "@gaonjs/config": "0.14.1",
-    "@gaonjs/i18n": "0.2.0",
-    "@gaonjs/web": "0.17.0",
-    "@gaonjs/data": "0.16.0"
+    "@gaonjs/async": "0.12.0",
+    "@gaonjs/config": "0.15.2",
+    "@gaonjs/core": "0.2.2",
+    "@gaonjs/mail": "0.2.1",
+    "@gaonjs/i18n": "0.2.1",
+    "@gaonjs/data": "0.16.1",
+    "@gaonjs/web": "0.18.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""