@gaonjs/cli 0.18.0 → 0.21.2

package/dist/doctor/method-override.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** 소스에 _method 오버라이드 hack 이 있는지(단위 테스트 진입점 · 주석은 제외). */
+export declare function usesMethodOverride(source: string): boolean;
+/** apps/ 의 .vue·.ts 를 훑어 _method 오버라이드 hack 을 경고로 낸다. */
+export declare function checkMethodOverride(cwd: string): Promise<RuleReport>;

package/dist/doctor/method-override.js

@@ -0,0 +1,75 @@
+// @gaonjs/cli · doctor · _method 오버라이드 hack 검출 (결정 89 · 경고)
+//
+// Gaon 은 `_method`(Rails/Laravel 식 HTTP 메서드 스푸핑)를 지원하지 않는다 —
+// Inertia 는 실 DELETE/PUT/PATCH 를 보낸다. `?_method=DELETE` 쿼리·`<input
+// name="_method">` 폼 필드·`{ _method: 'DELETE' }` 를 쓰면 컴파일은 통과하지만
+// 런타임이 조용히 파손된다(서버가 무시). 이 검사가 그 패턴을 경고로 잡는다.
+// (auth-flow 벤치 (d) 실측 근거 · AGENTS 절대 규칙 6). 판정은 소스 텍스트 기반.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+// 메서드 오버라이드 hack 패턴: 쿼리(?_method=DELETE)·폼 필드(name="_method")·
+// 객체 키(_method: 'DELETE' · 따옴표 유무 무관 · 값이 HTTP 메서드일 때만 — 오탐 방지).
+const METHOD_OVERRIDE = /[?&]_method=|name\s*=\s*['"]_method['"]|['"]?\b_method\b['"]?\s*:\s*['"]?(?:DELETE|PUT|PATCH)/i;
+// 주석을 제거한다(줄 주석·블록 주석·HTML/Vue 주석) — 안티패턴을 "쓰지 말라"고
+// 설명하는 주석이 오탐을 내지 않도록. 실제 실행 코드만 남긴다.
+function stripComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/<!--[\s\S]*?-->/g, ' ')
+        .replace(/(^|[^:])\/\/[^\n]*/g, '$1'); // // 줄 주석(http:// 는 보존)
+}
+/** 소스에 _method 오버라이드 hack 이 있는지(단위 테스트 진입점 · 주석은 제외). */
+export function usesMethodOverride(source) {
+    return METHOD_OVERRIDE.test(stripComments(source));
+}
+/** apps/ 의 .vue·.ts 를 훑어 _method 오버라이드 hack 을 경고로 낸다. */
+export async function checkMethodOverride(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const abs of await walkSources(appsDir)) {
+        const source = await readFile(abs, 'utf8').catch(() => '');
+        if (!usesMethodOverride(source))
+            continue;
+        issues.push({
+            rule: 'method-override',
+            level: 'warning',
+            file: relative(cwd, abs),
+            message: `_method 오버라이드 hack 발견: ${relative(cwd, abs)} 이 \`_method\`(Rails/Laravel 식 HTTP ` +
+                `메서드 스푸핑)를 씁니다. Gaon 은 이를 지원하지 않아 컴파일은 통과해도 런타임이 조용히 ` +
+                `파손됩니다(서버가 무시 · 결정 89).\n` +
+                `→ Gaon 은 \`_method\` 를 지원하지 않습니다. HTML 폼이 못 보내는 메서드는 ` +
+                `\`router.delete(...)\` / \`useForm(...).delete(...)\` 를 쓰세요 (AGENTS 절대 규칙 6).`,
+            detail: { file: relative(cwd, abs) },
+        });
+    }
+    return { rule: 'method-override', issues };
+}
+/** apps/ 하위 .vue·.ts(선언·테스트 제외) 절대경로. */
+async function walkSources(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()) {
+                if (e.name.endsWith('.d.ts') || e.name.endsWith('.test.ts'))
+                    continue;
+                if (e.name.endsWith('.vue') || e.name.endsWith('.ts'))
+                    out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/route-registration.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점). */
+export declare function referencedControllers(routesSource: string): Set<string>;
+/** apps/ 를 훑어 라우트에 등록되지 않은(고아) 컨트롤러를 경고로 낸다. */
+export declare function checkRouteRegistration(cwd: string): Promise<RuleReport>;

package/dist/doctor/route-registration.js

@@ -0,0 +1,77 @@
+// @gaonjs/cli · doctor · 라우트 미등록(고아 컨트롤러) 검사 (결정 79)
+//
+// apps/<앱>/controllers/<name>.ts 가 있는데 그 앱 routes.ts 어디에서도 참조되지
+// 않으면(= `<name>#action` 대상도, `resource(s)('<name>')` 도 없음) 그 컨트롤러는
+// 어떤 URL 로도 도달할 수 없다 — "라우트 미등록" 상태다. 컴파일은 통과하므로
+// check 로는 안 잡히는 조용한 누락이라, 이 검사가 경고로 낸다(라우트가 없는
+// 컨트롤러 파일은 배선을 깜빡한 흔한 실수 · §7.5.3 수리 안내).
+//
+// routes.ts 가 참조하는데 파일이 없는 반대 경우는 이미 generator 가 하드 에러로
+// 잡으므로(gaon check 중 throw) 여기서는 고아 컨트롤러만 본다. 판정은 소스 텍스트
+// 기반(가벼운 정적 검사) — routes.ts 를 실행하지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점). */
+export function referencedControllers(routesSource) {
+    const names = new Set();
+    // 메서드 대상: r.get('/', 'posts#index') → 'posts'
+    for (const m of routesSource.matchAll(/['"]([A-Za-z_]\w*)#\w+['"]/g))
+        names.add(m[1]);
+    // 리소스: r.resource('posts') · r.resources('posts')
+    for (const m of routesSource.matchAll(/\bresources?\s*\(\s*['"]([A-Za-z_]\w*)['"]/g))
+        names.add(m[1]);
+    return names;
+}
+/** apps/ 를 훑어 라우트에 등록되지 않은(고아) 컨트롤러를 경고로 낸다. */
+export async function checkRouteRegistration(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const routesPath = join(appsDir, app, 'routes.ts');
+        const routesSource = await readFile(routesPath, 'utf8').catch(() => undefined);
+        // routes.ts 가 없으면 참조 집합을 알 수 없어 diff 불가 — 건너뛴다
+        // (routes.ts 자체 부재는 다른 층의 관심사).
+        if (routesSource === undefined)
+            continue;
+        const referenced = referencedControllers(routesSource);
+        const controllersDir = join(appsDir, app, 'controllers');
+        for (const stem of await controllerStems(controllersDir)) {
+            if (referenced.has(stem))
+                continue;
+            issues.push({
+                rule: 'route-registration',
+                level: 'warning',
+                file: `apps/${app}/controllers/${stem}.ts`,
+                message: `라우트 미등록: apps/${app}/controllers/${stem}.ts 가 있는데 ` +
+                    `apps/${app}/routes.ts 어디에서도 참조되지 않습니다 — 이 컨트롤러는 어떤 URL 로도 ` +
+                    `도달할 수 없습니다(결정 79).\n` +
+                    `→ apps/${app}/routes.ts 에 \`r.get('/${stem}', '${stem}#index')\`(또는 \`r.resources('${stem}')\`)를 ` +
+                    `추가하거나, 쓰지 않는 컨트롤러라면 파일을 지우세요.`,
+                detail: { app, controller: stem },
+            });
+        }
+    }
+    return { rule: 'route-registration', issues };
+}
+/** apps/<앱>/controllers/*.ts 의 stem 목록(선언·테스트 제외). */
+async function controllerStems(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts') && !e.name.endsWith('.test.ts'))
+            .map((e) => e.name.slice(0, -'.ts'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/static-collision.d.ts

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** routes.ts 소스에서 리터럴 라우트 경로 집합을 뽑는다(단위 테스트 진입점). */
+export declare function routePaths(routesSource: string): Set<string>;
+/** apps/ 를 훑어 라우트/에셋에 가려지는 정적 파일을 경고로 낸다. */
+export declare function checkStaticCollision(cwd: string): Promise<RuleReport>;

package/dist/doctor/static-collision.js

@@ -0,0 +1,84 @@
+// @gaonjs/cli · doctor · 정적 파일 ↔ 예약 경로 충돌 검사 (결정 85 · 경고)
+//
+// apps/<앱>/static/ 의 파일은 앱 prefix 아래로 서빙되지만, **명시 라우트와
+// /assets/ 는 항상 우선**한다(결정 85 · appStatic 은 폴백). 따라서 라우트가
+// 이미 쓰는 경로(또는 /assets/*)에 같은 이름의 정적 파일을 두면 그 파일은
+// **영원히 도달 불가**(조용히 라우트에 가려짐)다. 이 검사가 그 상태를 경고한다.
+// 판정은 소스 텍스트 기반(정적 · routes.ts 를 실행하지 않는다).
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** routes.ts 소스에서 리터럴 라우트 경로 집합을 뽑는다(단위 테스트 진입점). */
+export function routePaths(routesSource) {
+    const paths = new Set();
+    // r.get('/path', ...) · r.post("/x/:id", ...) 등 — 첫 문자열 인자가 경로.
+    for (const m of routesSource.matchAll(/\br\.(?:get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/g)) {
+        paths.add(m[1]);
+    }
+    // resource(s)('name') → REST 표준 경로의 콜리전 후보(/name).
+    for (const m of routesSource.matchAll(/\bresources?\s*\(\s*['"]([A-Za-z_]\w*)['"]/g)) {
+        paths.add(`/${m[1]}`);
+    }
+    return paths;
+}
+/** apps/ 를 훑어 라우트/에셋에 가려지는 정적 파일을 경고로 낸다. */
+export async function checkStaticCollision(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const staticDir = join(appsDir, app, 'static');
+        const files = await listFiles(staticDir, staticDir);
+        if (files.length === 0)
+            continue;
+        const routesSource = await readFile(join(appsDir, app, 'routes.ts'), 'utf8').catch(() => '');
+        const routes = routePaths(routesSource);
+        for (const rel of files) {
+            const urlPath = `/${rel}`;
+            const shadowedByRoute = routes.has(urlPath);
+            const shadowedByAssets = rel === 'assets' || rel.startsWith('assets/');
+            if (!shadowedByRoute && !shadowedByAssets)
+                continue;
+            const by = shadowedByAssets ? '프론트 에셋(/assets/*)' : `라우트 ${urlPath}`;
+            issues.push({
+                rule: 'static-collision',
+                level: 'warning',
+                file: `apps/${app}/static/${rel}`,
+                message: `정적 파일 가려짐: apps/${app}/static/${rel} 은 ${by} 에 가려져 서빙되지 않습니다 ` +
+                    `(결정 85 · 라우트·에셋이 정적 폴더보다 우선).\n` +
+                    `→ 정적 파일 이름을 바꾸거나, 그 경로를 라우트로 직접 응답하세요.`,
+                detail: { app, path: urlPath },
+            });
+        }
+    }
+    return { rule: 'static-collision', issues };
+}
+/** staticDir 하위 파일을 상대 경로(posix)로 나열. */
+async function listFiles(dir, base) {
+    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())
+                await walk(abs);
+            else if (e.isFile())
+                out.push(abs.slice(base.length + 1).split('\\').join('/'));
+        }
+    };
+    await walk(dir);
+    return out;
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

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';
+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';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/types.js

@@ -1,6 +1,6 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 14 검사(response-mixing · n-plus-one · dependency-direction · connections
+// 17 검사(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)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는 level 로 passed/

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 14 검사를 조립한다:
+ * 17 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -16,6 +16,9 @@
  * 12) page-filename (§3.4 · 결정 32·46 · Vue 페이지 파일명 PascalCase)
  * 13) auth-wiring (§7 · 결정 59 · requireAuth ↔ app.config.ts auth 배선)
  * 14) ui-kit-wiring (§6.4 · 결정 76 · UI 킷 import ↔ apps/<앱>/style.css Tailwind 배선)
+ * 15) route-registration (결정 79 · 고아 컨트롤러 = routes.ts 미참조 경고)
+ * 16) static-collision (결정 85 · 정적 파일이 라우트/에셋에 가려짐 경고)
+ * 17) method-override (결정 89 · _method HTTP 스푸핑 hack 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -42,6 +45,9 @@ import { checkModelFilename } from './doctor/model-filename.js';
 import { checkPageFilename } from './doctor/page-filename.js';
 import { checkAuthWiring } from './doctor/auth-wiring.js';
 import { checkUiKitWiring } from './doctor/ui-kit-wiring.js';
+import { checkRouteRegistration } from './doctor/route-registration.js';
+import { checkStaticCollision } from './doctor/static-collision.js';
+import { checkMethodOverride } from './doctor/method-override.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -63,7 +69,7 @@ export { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 14개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 17개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -80,6 +86,9 @@ const ALL_RULES = [
     'page-filename',
     'auth-wiring',
     'ui-kit-wiring',
+    'route-registration',
+    'static-collision',
+    'method-override',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -96,6 +105,9 @@ const CHECKERS = {
     'page-filename': checkPageFilename,
     'auth-wiring': checkAuthWiring,
     'ui-kit-wiring': checkUiKitWiring,
+    'route-registration': checkRouteRegistration,
+    'static-collision': checkStaticCollision,
+    'method-override': checkMethodOverride,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -100,10 +100,11 @@ function renderHelp(version = VERSION) {
         "    gaon dev --json    통합 콘솔을 JSON 라인으로 출력(자동화)",
         "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
         "    gaon serve --port <n> --host <h>   리슨 포트·호스트 (config 값을 덮음)",
+        "    gaon serve --workers <n|auto>      node:cluster 워커 다중화 (env WEB_CONCURRENCY · 기본 1)",
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (14 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선)",
+        "    gaon doctor        정적 검사 (17 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -194,11 +195,15 @@ export function runCli(argv, opts = {}) {
     if (argv[0] === "serve") {
         const portIdx = argv.indexOf("--port");
         const hostIdx = argv.indexOf("--host");
+        const workersIdx = argv.indexOf("--workers");
         const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
         const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+        // --workers <n|auto>: node:cluster 다중화(결정 84). env WEB_CONCURRENCY 도 가능.
+        const workersRaw = workersIdx >= 0 ? argv[workersIdx + 1] : undefined;
+        const workers = workersRaw === "auto" ? "auto" : workersRaw !== undefined ? Number(workersRaw) : undefined;
         // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식
         // serve 에 넘긴다(결정 69 · dev-only by construction).
-        void runServeCommand({ json: argv.includes("--json"), port, host, dev: argv.includes("--dev") }).catch((err) => {
+        void runServeCommand({ json: argv.includes("--json"), port, host, workers, dev: argv.includes("--dev") }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
             process.exitCode = 1;
@@ -230,7 +235,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 14 검사). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 17 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {

package/dist/serve.d.ts

@@ -1,3 +1,8 @@
+/**
+ * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
+ * (availableParallelism). 0·음수·비수치는 1 로 떨어진다(안전 기본). 결정 84.
+ */
+export declare function resolveWorkerCount(workers: number | 'auto' | undefined, env?: NodeJS.ProcessEnv): number;
 export interface ServeCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
@@ -5,6 +10,11 @@ export interface ServeCommandOptions {
     readonly port?: number;
     /** 리슨 호스트. 우선순위: 옵션 > config.web.host > '0.0.0.0'. */
     readonly host?: string;
+    /**
+     * 워커 수(node:cluster). 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수.
+     * 2 이상이면 프라이머리가 fork 해 다중화한다(결정 84).
+     */
+    readonly workers?: number | 'auto';
     /**
      * dev 모드(gaon dev 자식). true 면 dev 전용 진단 라우트(/_gaon/health)를
      * 등록한다. 운영 serve 는 이 플래그 없이 실행되어 진단 라우트가 노출되지

package/dist/serve.js

@@ -8,13 +8,32 @@
  * env 를 먼저 로드한다 — .env 의 값이 gaon.config.ts 안의 env('KEY') 에
  * 들어갈 수 있어야 하기 때문.
  *
- * 워커 수(--workers, WEB_CONCURRENCY)는 v0.8 정본이지만 컨테이너 안 기본
- * 1워커라 M9-A 는 단일 프로세스만 다룬다. node:cluster 통합은 후속(M9-C).
+ * 워커 다중화(--workers · WEB_CONCURRENCY)는 node:cluster 로 처리한다(결정 84):
+ * 기본 1(컨테이너 기본). 2 이상이면 프라이머리가 N 워커를 fork 하고 OS 가
+ * 연결을 분산(cluster 라운드로빈)한다. 워커가 예기치 않게 죽으면 교체 fork,
+ * SIGTERM/SIGINT 에 워커들을 graceful drain 후 종료한다.
  */
+import cluster from 'node:cluster';
+import { availableParallelism } from 'node:os';
 import { loadDotEnv } from '@gaonjs/core';
 import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
 import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
+/**
+ * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
+ * (availableParallelism). 0·음수·비수치는 1 로 떨어진다(안전 기본). 결정 84.
+ */
+export function resolveWorkerCount(workers, env = process.env) {
+    const raw = workers ?? env.WEB_CONCURRENCY;
+    if (raw === undefined || raw === '')
+        return 1;
+    if (raw === 'auto')
+        return Math.max(1, availableParallelism());
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return 1;
+    return Math.floor(n);
+}
 function humanEvent(e) {
     switch (e.kind) {
         case 'starting': {
@@ -24,17 +43,81 @@ function humanEvent(e) {
         }
         case 'listening':
             return `  ▶ 리슨 중 — ${e.url}  (Ctrl+C 로 종료)`;
+        case 'cluster':
+            return `  gaon serve · 클러스터 — 워커 ${e.workers}개 fork (node:cluster)`;
+        case 'worker-exit':
+            return `  ⚠ 워커 종료(pid ${e.pid ?? '?'} · code ${e.code}${e.signal ? ` · ${e.signal}` : ''})${e.restarted ? ' — 교체 fork' : ''}`;
         case 'stopping':
             return '  gaon serve · 종료 중 (graceful) ...';
         case 'stopped':
             return '  gaon serve · 종료';
     }
 }
+/**
+ * 클러스터 프라이머리 — N 워커를 fork 하고 감독한다. 워커가 예기치 않게 죽으면
+ * 교체 fork(복원력), SIGTERM/SIGINT 에 워커들을 SIGTERM 으로 graceful drain 한 뒤
+ * (상한 `GAON_WORKER_DRAIN_MS`, 기본 30s) SIGKILL 로 강제 종료한다. 결정 84.
+ */
+async function runClusterPrimary(workerCount, opts) {
+    const json = opts.json ?? false;
+    const signals = opts.signals ?? process;
+    const drainMs = process.env.GAON_WORKER_DRAIN_MS ? Number(process.env.GAON_WORKER_DRAIN_MS) : 30_000;
+    const emit = (e) => {
+        if (json)
+            process.stdout.write(JSON.stringify(e) + '\n');
+        else
+            process.stdout.write(humanEvent(e) + '\n');
+    };
+    emit({ kind: 'cluster', workers: workerCount });
+    let shuttingDown = false;
+    for (let i = 0; i < workerCount; i++)
+        cluster.fork();
+    cluster.on('exit', (worker, code, signal) => {
+        if (shuttingDown)
+            return;
+        // 예기치 않은 종료 → 교체 fork 로 워커 수를 유지한다.
+        emit({ kind: 'worker-exit', pid: worker.process.pid, code, signal, restarted: true });
+        cluster.fork();
+    });
+    await new Promise((resolvePromise) => {
+        const stop = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            signals.off('SIGINT', stop);
+            signals.off('SIGTERM', stop);
+            emit({ kind: 'stopping' });
+            for (const w of Object.values(cluster.workers ?? {}))
+                w?.kill('SIGTERM');
+            const killTimer = setTimeout(() => {
+                for (const w of Object.values(cluster.workers ?? {}))
+                    w?.kill('SIGKILL');
+            }, drainMs);
+            const check = () => {
+                if (Object.keys(cluster.workers ?? {}).length === 0) {
+                    clearTimeout(killTimer);
+                    emit({ kind: 'stopped' });
+                    resolvePromise();
+                }
+            };
+            cluster.on('exit', check);
+            check();
+        };
+        signals.on('SIGINT', stop);
+        signals.on('SIGTERM', stop);
+    });
+}
 /**
  * `gaon serve` 진입점. loadDotEnv → loadGaonConfig → wireGaon → listen →
  * SIGINT 대기 → graceful close. 예외는 stderr + exit 1.
  */
 export async function runServeCommand(opts = {}) {
+    // 워커 다중화(결정 84): 2 이상이고 이 프로세스가 프라이머리면 감독만 한다.
+    // 워커(cluster.isWorker)와 단일 프로세스(count=1)는 아래 서버 본문을 실행한다.
+    const workerCount = resolveWorkerCount(opts.workers);
+    if (workerCount > 1 && cluster.isPrimary) {
+        return runClusterPrimary(workerCount, opts);
+    }
     const cwd = opts.cwd ?? process.cwd();
     const json = opts.json ?? false;
     const signals = opts.signals ?? process;
@@ -85,4 +168,9 @@ export async function runServeCommand(opts = {}) {
         signals.on('SIGINT', stop);
         signals.on('SIGTERM', stop);
     });
+    // 클러스터 워커는 graceful close 후에도 cluster IPC 채널이 이벤트 루프를 잡아
+    // 프로세스가 안 죽는다 → 프라이머리가 워커 소멸을 감지 못 해 매달린다. close 가
+    // 끝난 뒤 명시적으로 종료한다(안전). 단일 프로세스는 자연 종료(호출 안 함). 결정 84.
+    if (cluster.isWorker)
+        process.exit(0);
 }

package/dist/templates/project/.dockerignore.tpl

@@ -0,0 +1,12 @@
+# 컨테이너 빌드에서 제외 — 호스트 산출물이 이미지로 새지 않게 한다.
+# node_modules 는 반드시 제외: 호스트(예: darwin/arm64) 네이티브 바이너리가
+# 리눅스 컨테이너로 복사되면 esbuild 등이 깨진다(이미지 안에서 재설치).
+node_modules
+**/node_modules
+.gaon
+dist
+.git
+.env
+.env.*
+npm-debug.log*
+*.log

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

@@ -2,8 +2,8 @@
 
 이 문서는 **AI 코딩 에이전트**(Claude · Codex · Cursor · Copilot 등)와
 사람 개발자가 Gaon 프로젝트에서 작업할 때 참조하는 관례의 진입점이다.
-정본은 설계 문서(v0.15 동결 + errata E-1~E-5, v0.16 편입)이며, 관례
-문서는 **2층 구조**다 (결정 40):
+정본은 설계 문서(`docs/gaondesignv0.17.md` · v1.0 출시 기준 스냅샷 ·
+v0.15+errata→v0.16→v0.17 · 결정 31~89)이며, 관례 문서는 **2층 구조**다 (결정 40):
 
 - **이 파일 (코어)** — 절대 규칙 · 로직 배치 판단표 · 검증 루프 ·
   카테고리 색인. 여기엔 요약만 있다.
@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 14종
+### 2.2 `gaon doctor` 검사 17종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -120,6 +120,9 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 12. `page-filename` — Vue 페이지 파일명 PascalCase 관례 (결정 32·46)
 13. `auth-wiring` — requireAuth/this.auth 사용 ↔ `app.config.ts` 인증 배선 (결정 59)
 14. `ui-kit-wiring` — UI 킷 컴포넌트 import ↔ `apps/<앱>/style.css` Tailwind 배선 (결정 76 · 경고)
+15. `route-registration` — 고아 컨트롤러(파일은 있는데 `routes.ts` 미참조 · 도달 불가) (결정 79 · 경고)
+16. `static-collision` — 정적 파일(`apps/<앱>/static/`)이 라우트/에셋에 가려져 도달 불가 (결정 85 · 경고)
+17. `method-override` — `_method` HTTP 메서드 스푸핑 hack(Gaon 미지원 · router.delete 를 쓰라) (결정 89 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -160,7 +163,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 14종 (§2.2)
+gaon doctor       # 정적 검사 17종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -210,7 +213,8 @@ gaon doctor       # 정적 검사 14종 (§2.2)
 
 ## 7. 참고 문서
 
-- 설계 정본: `docs/gaondesignv0.15.md` (동결) + errata E-1~E-5
+- 설계 정본: `docs/gaondesignv0.17.md` (v1.0 출시 기준 스냅샷 · 결정 31~89) ·
+  이력 동결 = `gaondesignv0.16.md`·`v0.15.md` + errata E-1~E-5
   (E-1 파사드명 · E-2 실시간 TCP · E-3 JSON 액션/params · E-4 컬럼·
   체이닝 · E-5 컴포저블·레이아웃).
 - 가이드: `docs/guides/*.md` (getting-started · data · data-flow ·

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

@@ -85,7 +85,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
-gaon doctor                       # 정적 검사 5종 (응답·N+1·의존·커넥션·마이그)
+gaon doctor                       # 정적 검사 17종 (응답·N+1·의존·커넥션·마이그·순수·자동import·파일명/컬럼·인증·UI킷·라우트 · 상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

package/dist/templates/project/Dockerfile.tpl

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} 운영 이미지 — Node 22 · pnpm · TS 네이티브(gaon serve)
+#
+# gaonjs 는 TS 네이티브(Node 타입 스트리핑)라 별도 tsc 빌드가 없다. `vite build`
+# 로 프론트 번들만 만들고, 런타임은 소스 + 번들을 `gaon serve` 로 그대로 돌린다.
+# 웹·워커·허브 프로세스는 compose.prod.yaml 이 같은 이미지로 command 만 바꿔 띄운다.
+
+FROM node:22-slim AS base
+ENV PNPM_HOME=/pnpm PATH=/pnpm:$PATH
+RUN corepack enable
+WORKDIR /app
+
+# 1) 의존 설치 — lockfile 로 재현 가능하게(빌드에 dev 의존 필요).
+FROM base AS deps
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# 2) 프론트 번들 빌드(vite build).
+FROM base AS build
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN pnpm build
+
+# 3) 런타임 — 소스 + 번들 + 의존을 그대로 실행.
+FROM base AS runtime
+ENV NODE_ENV=production
+COPY --from=build /app ./
+# 웹 서버 포트(gaon.config.ts 의 web.port · 기본 3000). 프록시 뒤에 둔다.
+EXPOSE 3000
+# 웹 프로세스. 워커(gaon work)·허브(gaon hub)는 compose.prod.yaml 의 별도 서비스.
+CMD ["pnpm", "serve"]

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

@@ -143,6 +143,10 @@ export const PlaceOrder = service(async (input: { name: string }) => {
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이
   흡수한다.
 - 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 워커 기동 시 보장된다.
+- 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
+  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격은 `gaon work` 의
+  `outboxRetentionMs`·`outboxPurgeIntervalMs` 로 조정한다(운영 상세는
+  `docs/guides/operations.md`). 미발행 행은 절대 삭제되지 않는다.
 
 ### 5. 스케줄러
 

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

@@ -193,8 +193,8 @@ export const posts = table('posts', {
 | `pluck` | `(col)` | `Promise<Row[col][]>` | 단일 컬럼 배열 · 정렬·limit·offset 반영 |
 | `select` | `(['a', 'b'])` | `SelectChain<Row, K>` | 부분 컬럼 — `first`/`all` 이 `Pick<Row, K>` **plain 행** 반환 (메서드·관계·update 없음) |
 | `include` | `(...rels)` | `IncludedChain` | 관계 eager 로드 — **4종 전부**(belongsTo·hasMany·hasOne·belongsToMany, §1.1). **N+1 방지**: 관계당 쿼리 1회 (belongsToMany 는 피벗 `inner join` 1회) · 행 수와 무관. doctor 의 **n-plus-one** 검사가 include 미사용 · loop 안 관계 호출을 감지한다 |
-| `updateAll` | `(patch)` | `Promise<bigint>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수 반환. limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
-| `deleteAll` | `()` | `Promise<bigint>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
+| `updateAll` | `(patch)` | `Promise<number>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수(number · 결정 90). limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
+| `deleteAll` | `()` | `Promise<number>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
 
 **집계·조인 그룹** (`Chain` · M2E · 결정 34):
 
@@ -218,18 +218,35 @@ export const posts = table('posts', {
 | 메서드 | 시그니처 | 반환 | 비고 |
 |---|---|---|---|
 | `create` | `(data)` | `Promise<Rec>` | `t.id()`·`t.timestamps()`·`.default()` 컬럼은 입력에서 선택적 (`InsertOf`) |
-| `batchInsert` | `(rows)` | `Promise<Rec[]>` | **벌크 삽입** (M2F · 결정 35) — 여러 row 를 **단일 INSERT 문**(원자적)으로 · 넣은 순서대로 Rec 반환. 빈 배열은 DB 무접촉 `[]`. beforeCreate 훅은 각 row 에 적용 |
-| `insertOrIgnore` | `(row \| rows)` | `Promise<Rec[]>` | **멱등 삽입** (M2F) — `ON CONFLICT DO NOTHING` · UNIQUE/PK 충돌 행은 건너뛰고 **실제로 삽입된 Rec 만** 반환. 충돌 대상 인자 없음(어떤 UNIQUE/PK 든 충돌 시 건너뜀) |
-| `upsert` | `(row \| rows, { onConflict?, update? })` | `Promise<Rec[]>` | **있으면 갱신 없으면 삽입** (M2F) — `ON CONFLICT DO UPDATE`. `onConflict` 생략 = 기본 키(`id`) 자동(없으면 throw) · `update` 생략(`'exclude'`) = 입력 컬럼에서 충돌 기준·`id` 뺀 나머지를 `excluded` 로 덮음 · 갱신 대상 없으면 DO NOTHING |
+| `batchInsert` | `(rows)` | `Promise<BulkResult>` | **벌크 삽입** (M2F · 결정 35 → BulkResult 결정 90) — 여러 row 를 **단일 INSERT 문**(원자적)으로 · `{ count }`(삽입 행 수) 반환. 빈 배열은 DB 무접촉 `{ count: 0 }`. beforeCreate 훅은 각 row 에 적용 |
+| `insertOrIgnore` | `(row \| rows)` | `Promise<BulkResult>` | **멱등 삽입** (M2F) — 충돌 행은 건너뛰고 `count` = **실제로 삽입된 행 수**(PG=`ON CONFLICT DO NOTHING` · MySQL=`INSERT IGNORE`). 충돌 대상 인자 없음(어떤 UNIQUE/PK 든 충돌 시 건너뜀) |
+| `upsert` | `(row \| rows, { onConflict?, update? })` | `Promise<BulkResult>` | **있으면 갱신 없으면 삽입** (M2F) — PG=`ON CONFLICT DO UPDATE` · MySQL=`ON DUPLICATE KEY UPDATE`. `count` = 처리된 입력 행 수(삽입+갱신 · 갱신 대상 없으면 실 삽입 수). `onConflict` 생략 = 기본 키(`id`) 자동(없으면 throw) · `update` 생략(`'exclude'`) = 입력 컬럼에서 충돌 기준·`id` 뺀 나머지를 덮음 |
 | `find` | `(id)` | `Promise<Rec>` | 없으면 **throw** — undefined 를 허용하려면 `where('id', '=', id).first()` |
 | `query` | `()` | Kysely `SelectQueryBuilder` | §5 탈출구 |
 
-> 벌크 삽입 3종(`batchInsert`·`insertOrIgnore`·`upsert`)은 **RETURNING 을
-> 지원하는 커넥션(Postgres)** 에서만 된다 — 삽입/무시/갱신된 행 집합을
-> 정확히 복원할 수 있는 방언이 RETURNING 뿐이라, 비 RETURNING 커넥션에서는
-> 어림하지 않고 수리 안내와 함께 **throw** 한다(결정 35 · §7.5.3). 삽입 계열은
+> 벌크 3종은 **전 방언 통일 `BulkResult`**(`{ count, meta? }`)를 돌려준다(결정 90 ·
+> 원안의 "비 RETURNING 방언 throw" 폐기). `count` 는 **처리된 입력 행 수**로 방언
+> 무관 같은 의미다 — MySQL upsert 의 원시 `affectedRows`(삽입 1·갱신 2·무변경 0/1)를
+> 그대로 노출하지 않고 정규화한다. 방언 원시값이 필요하면 `meta`(PG `returnedIds` ·
+> MySQL `firstInsertId`·`affectedRows`)를 쓴다. **행 자체가 필요하면**: 소량은
+> `create()`(단건 · 전 방언 Rec 반환), 대량은 유니크 키로 재조회 — **id 범위 추정
+> 재조회는 금지**(MySQL auto-increment 는 동시 삽입에서 연속 보장이 없다). 삽입 계열은
 > `create` 처럼 루트 전용 — `where` 필터와 무관하므로 체인 종단이 아니다.
 
+**개수·집계 반환 타입 — 영역별로 다르다** (결정 90·91 · 헷갈리지 말 것):
+
+| 영역 | 반환 타입 | 근거 |
+|---|---|---|
+| 쓰기 개수 (`BulkResult.count` · `updateAll` · `deleteAll`) | `number` | 처리 행 수 — 2^53 초과 실무 없음 · JSON 직렬화 |
+| 읽기 집계 `count()` | `bigint` | E-4 정본 |
+| 읽기 집계 `sum()` · `avg()` | `string` | 무손실(정밀도 보존) |
+| 읽기 집계 `min()` · `max()` | 컬럼 타입 따름 | E-4 정본 |
+
+> **왜 sum/avg 가 `number` 가 아닌가**: 양 방언 실측 결과 집계 체인은 이미 방언
+> 일관이라(silent split 없음) 고칠 문제가 없고, `string→number` 강제는 2^53 초과
+> 합계에서 **정밀도를 잃는**(lossy) breaking 이라 "어림 금지" 원칙에 어긋나 기각했다
+> (결정 91). 쓰기 개수(number)와 읽기 집계(string/bigint)는 축이 다르다.
+
 **레코드(`Rec`) 내장** (`model.ts:47-52`):
 
 - `rec.update(patch)` — `Partial<Row>` 부분 갱신, 갱신된 Rec 반환.
@@ -546,14 +563,15 @@ const slim = await Post.select(['id', 'title']).all()  // Pick<Row, 'id' | 'titl
 // 삭제 — 단건은 레코드, 벌크는 deleteAll (M2C)
 const post = await Post.find(id)
 await post.delete()
-const removed = await Post.where('published', '=', false).deleteAll()   // bigint
+const removed = await Post.where('published', '=', false).deleteAll()   // number
 const touched = await Post.where('authorId', '=', me.id).updateAll({ published: true })
 
-// 벌크 삽입·UPSERT — 루트 전용 (M2F · 결정 35)
-const seeded = await Post.batchInsert(rows)          // 단일 INSERT 문 · Rec[] (순서 보존)
-const fresh = await Post.insertOrIgnore(rows)         // 충돌 건너뜀 · 실 삽입만
-await Post.upsert(rows, { onConflict: 'slug', update: ['title', 'body'] })
+// 벌크 삽입·UPSERT — 루트 전용 (M2F · 결정 35 → BulkResult 결정 90 · 전 방언 통일)
+const seeded = await Post.batchInsert(rows)          // { count } (삽입 행 수)
+const fresh = await Post.insertOrIgnore(rows)         // { count } (실 삽입만 · 충돌 건너뜀)
+const { count } = await Post.upsert(rows, { onConflict: 'slug', update: ['title', 'body'] })
 await Post.upsert({ id, title, body })                // onConflict 생략 = 기본 키(id)
+// 삽입된 행이 필요하면: 소량은 create(), 대량은 유니크 키로 재조회 (id 범위 추정 금지)
 ```
 
 ## 알려진 함정
@@ -568,6 +586,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   `foreignKey`/`otherKey` 를 명시한다.
 - **`updateAll`/`deleteAll` 에 limit·offset·orderBy 가 걸려 있으면 throw** —
   행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`.
+- **벌크 3종은 행이 아니라 `{ count }` 를 준다** (결정 90) — 반환을 `Rec[]` 처럼
+  다루지 말 것. 삽입된 행이 필요하면 소량은 `create()`, 대량은 유니크 키 재조회.
+  `throw` 하던 옛 계약(비 RETURNING 방언)은 폐기 — MySQL 도 그냥 `count` 를 준다.
 - **loop 안 관계 lazy 호출 = N+1** — doctor **n-plus-one** 검사가 잡는다.
   목록은 `include()` 로.
 - **스키마 파일명은 camelCase** — 테이블 `posts_tags` → 파일 `postsTags.ts`
@@ -588,8 +609,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 31 | `rec.delete()` 명명(destroy 아님) · 파라미터 스코프 (M2C) |
 | 결정 33 | 관계 선언 위치(컬럼 + relations) · 문자열 테이블명 (M2D) |
 | 결정 34 | 집계·조인 그룹(groupBy·having·distinct·withCount·join) (M2E) |
-| 결정 35 | 벌크 삽입 3종(batchInsert·insertOrIgnore·upsert) (M2F) |
+| 결정 35 | 벌크 삽입 3종(batchInsert·insertOrIgnore·upsert) (M2F) → **결정 90 으로 개정** |
 | 결정 39 | 마이그레이션 합성형(파일 replay → 스키마 diff · no-auto-drop) |
+| 결정 90 | 벌크 3종 `BulkResult`(count+meta) 전 방언 통일 · updateAll/deleteAll bigint→number (W14) |
 | 결정 43 | 네이밍 정본화 · DB 네이밍 SSOT(§1.2 · 테이블 snake · 컬럼 camel) |
 | 결정 46 | doctor 컬럼(column-casing)·모델/페이지 파일명 검사 3종 |
 | 결정 47 | `gaon g model` 다단어 테이블명 snake_case(마지막 단어 복수) |

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

@@ -36,6 +36,12 @@ const props = pageProps<'web:posts#index'>()
   액션 → `'web:posts#index'`.
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
   로 import 하지 않는다.
+- **Gaon 은 `vue-router` 를 쓰지 않는다** — 라우팅은 **Inertia = SPA + 서버
+  라우팅**이라 클라이언트 라우터 라이브러리가 없다. `vue-router`·`react-router`
+  를 install/import 하지 말 것(`createRouter`·`useRoute`·`useRouter`·`<RouterLink>`
+  전부 없음 · CLAUDE.md 규칙 12). 페이지 전환은 `gaonjs/vue` 의 `router`
+  (`router.visit(url)`·`router.get/post/delete`), 폼은 `useForm(...)` (결정 64).
+  라우트 정의는 서버의 `apps/<앱>/routes.ts` 뿐이다.
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 
@@ -259,6 +265,19 @@ async function runSearch(q: string) {
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
   `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
+- **`vue-router` import 금지** — Gaon 은 클라이언트 라우터가 없다(Inertia =
+  SPA + 서버 라우팅). `import { useRouter } from 'vue-router'` 는 존재하지 않는
+  의존을 끌어와 컴파일 실패한다 — 전환은 `gaonjs/vue` 의 `router`, 라우트 정의는
+  `apps/<앱>/routes.ts`(§1).
+- **로그아웃은 `router.delete('/session')`** — `?_method=DELETE` 폼 override(Rails/
+  Laravel 관례)는 Gaon 에서 안 통한다(Inertia 는 실 DELETE 를 보낸다 · 컴파일은
+  통과해도 런타임 조용히 파손). 로그아웃 링크/버튼은 `router.delete(...)` 또는
+  `useForm(...).delete(...)` 로 한다(결정 64 · 절대 규칙 6). `_method` 사용은 doctor
+  **method-override** 가 잡는다(결정 89).
+- **채널 구독은 `useChannel()`** — 실시간 클라이언트는 `gaonjs/vue` 의
+  `useChannel(name, opts)` 가 정본(결정 87). `new WebSocket` 을 손으로 짜면
+  URL(`/gaon/ws/<채널>`)·봉투(`{ t:'msg', data }`)·라이프사이클을 재구현하다
+  틀린다(`agents/realtime.md` §4). 구독 래핑은 컴포저블에.
 - **레이아웃을 shared 에 두지 않는다** — 앱별이 정상.
 - **페이지 파일명은 PascalCase** — `pages/Posts/Index.vue`(폴더 세그먼트도
   Route 이름). 소문자(`posts/index.vue`)는 doctor **page-filename** 이 잡는다

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

@@ -89,29 +89,36 @@ const members = await ctx.presence()
 - leave 는 best-effort 이고, 서버가 죽으면 허브가 그 서버의 멤버 전원을
   **즉시** 정리한다 (TCP `close`).
 
-### 4. 클라이언트 (WebSocket)
+### 4. 클라이언트 (`useChannel` · 결정 87)
 
-브라우저는 표준 WebSocket 으로 채널에 접속한다. 세션 앱은 세션 쿠키로,
-JWT 앱은 쿼리(`access_token`)로 인증한다.
-
-**경로는 `<앱 프리픽스>/gaon/ws/<채널명>`** 이고, 보내는 프레임은 `{ t: 'msg',
-data }` **봉투** 다 — 날 페이로드를 그대로 보내면 서버가 `onMessage` 로
-흘리지 않는다. 받는 프레임도 같은 모양(`t` 로 종류를 가른다).
+**정본 = `gaonjs/vue` 의 `useChannel(name, opts)`.** 채널 구독의 One Way 다 —
+URL 조립(`<앱 프리픽스>/gaon/ws/<채널명>` · ws/wss 자동)·봉투(`{ t:'msg', data }`)
+감싸기/풀기·마운트 접속·언마운트 정리·반응형 상태를 한 번에 준다. `new WebSocket`
+을 손으로 짜지 말 것(라이프사이클·봉투를 재구현하다 실수한다). 세션 앱은 쿠키로
+자동 인증, JWT 앱은 `params: { access_token }`.
 
 ```ts
-// 브라우저측 — 채널 구독 래핑은 컴포저블에 (agents/frontend.md)
-// web 앱(프리픽스 /)의 room 채널 = /gaon/ws/room. admin 앱이면 /admin/gaon/ws/room.
-const ws = new WebSocket(`wss://example.com/gaon/ws/room?room=42`)
-ws.onmessage = (ev) => {
-  const frame = JSON.parse(ev.data)      // { t: 'msg' | 'presence' | ... , data }
-  if (frame.t === 'msg') {
-    // 서버가 broadcast/send 한 데이터
-  }
+// apps/web/composables/useRoom.ts — 컴포저블에 래핑(agents/frontend.md §3.2)
+import { useChannel } from 'gaonjs/vue'
+
+export function useRoom(roomId: number) {
+  // messages(반응형)·status·send·connect·close 를 돌려준다. 마운트에 접속.
+  const { messages, status, send } = useChannel('room', {
+    params: { room: roomId },
+    onMessage: (data) => { /* 서버가 broadcast/send 한 데이터 */ },
+    onPresence: (delta) => { /* 접속자 join/leave */ },
+  })
+  return { messages, status, send }
 }
-// 보낼 때도 봉투로 감싼다 — 이래야 채널의 onMessage 가 호출된다.
-ws.send(JSON.stringify({ t: 'msg', data: { text: '안녕하세요' } }))
 ```
 
+- **보내기** — `send(data)` 가 `{ t:'msg', data }` 봉투로 감싸 보낸다(서버 `onMessage`
+  정답 경로). 날 페이로드를 직접 보내면 서버가 안 흘린다.
+- **받기** — `msg` 프레임은 `messages` 에 축적 + `onMessage` 호출, `presence` 는
+  `onPresence`. 그 외는 `onFrame`.
+- **탈출구** — 표준 WebSocket 이 필요하면 `new WebSocket('<프리픽스>/gaon/ws/<채널명>')`
+  을 직접 쓸 수 있다(봉투·라이프사이클을 스스로 책임진다). 기본 경로는 `useChannel`.
+
 ### 5. 허브 프로세스 (`gaon hub`)
 
 허브는 접속자 목록의 단일 권위이자 서버 간 중계다.

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

@@ -7,12 +7,21 @@
 
 ### 1. 보안 기본값 = fail-closed (v0.15 §2.5.1)
 
-**CORS · rate limit · CSRF 는 코어에서 기본 켬.** 끄는 것은 명시적
-설정으로만 (v0.15 §2.5.1 원문 근거).
+**CORS · rate limit · CSRF · 보안 응답 헤더는 코어에서 기본 켬.** 끄는 것은
+명시적 설정으로만 (v0.15 §2.5.1 원문 근거).
 
 보안 결함 = 보안이 선택 설치면 설치 안 한 앱의 기본값이 무방비가
 된다. Rails/Laravel 이 증명한 원칙이다 (§2.5.1).
 
+- **보안 응답 헤더 (결정 86)** — 코어가 모든 응답에 CSP·HSTS(HTTPS 한정)·
+  `X-Content-Type-Options: nosniff`·`X-Frame-Options: SAMEORIGIN`·
+  `Referrer-Policy: strict-origin-when-cross-origin`·`Cross-Origin-Opener-Policy`
+  를 자동으로 붙인다. 기본 CSP 는 Inertia SPA + vite 스택에서 안 깨지게 튜닝돼
+  있다(`script-src 'self'`·인라인 스타일 허용·`connect-src ... ws: wss:` 로
+  realtime 허용). 끄거나 조정은 `createApp({ security: { securityHeaders: … } })`
+  — `false` 로 전부 끔, `{ contentSecurityPolicy: '…' | false, hsts: false }` 로 조정.
+  `helmet` 등 라이브러리를 따로 깔지 말 것(코어 내장 · 라이브러리 미의존).
+
 ### 2. 세션·CSRF·JWT
 
 - 세션은 앱별 완전 분리 (v0.15 §7 · Fastify 캡슐화 스코프): 쿠키

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

@@ -275,6 +275,11 @@ export default controller({
 - **`@gaonjs/*` 스코프 직접 import 금지** — 파사드 `gaonjs/*` 만.
 - **bigint PK 를 render props 로 흘릴 때는 `String(p.id)` 정규화**
   (결정 37 · 상세는 `agents/frontend.md`).
+- **정적 파일(robots.txt·favicon.ico·이미지 등)은 `apps/<앱>/static/`** 에 둔다
+  (결정 85) — 앱 prefix 아래로 서빙된다(web→`/robots.txt`, admin→`/admin/robots.txt`).
+  라우트·`/assets/*` 가 항상 우선하므로 라우트와 같은 경로에 두면 가려진다
+  (doctor **static-collision** 가 경고). 정적 서빙에 `@fastify/static` 을 따로
+  깔지 말 것(코어 내장).
 
 ## 관련 결정 번호
 

package/dist/templates/project/apps/web/static/robots.txt.tpl

@@ -0,0 +1,4 @@
+# {{PROJECT_NAME}} · 정적 파일 폴더 (결정 85) — 이 폴더의 파일은 앱 루트로 서빙된다.
+# 예: 이 robots.txt 는 /robots.txt 로, static/img/logo.png 은 /img/logo.png 으로.
+User-agent: *
+Disallow:

package/dist/templates/project/compose.prod.yaml.tpl

@@ -0,0 +1,98 @@
+# {{PROJECT_NAME}} 운영 스택 — 웹·워커·허브 3종 프로세스 + 실 인프라.
+#
+# 개발 스택(docker-compose.yaml)과 달리 앱 이미지(Dockerfile)를 빌드해 serve·work·
+# hub 를 별도 서비스로 띄운다(운영 프로세스 3종 · CLAUDE.md §2 · 결정 60). 인프라는
+# 실 pg·redis·nats(목업 금지 §9). 시크릿은 env 로 주입한다 — 이 파일에 값을 박지 말 것.
+#
+# 기동:  docker compose -f compose.prod.yaml up -d --build
+# 정지:  docker compose -f compose.prod.yaml down
+name: {{PROJECT_NAME}}-prod
+
+x-app-env: &app-env
+  DATABASE_URL: postgres://{{PROJECT_NAME}}:${DB_PASSWORD:?set DB_PASSWORD}@postgres:5432/{{PROJECT_NAME}}
+  REDIS_URL: redis://redis:6379
+  NATS_URL: nats://nats:4222
+  COOKIE_SECRET: ${COOKIE_SECRET:?set COOKIE_SECRET (32+ chars)}
+  NODE_ENV: production
+
+services:
+  # 웹 프로세스(gaon serve). node:cluster 워커 수는 WEB_CONCURRENCY 로(기본 1).
+  web:
+    build: .
+    command: ["pnpm", "serve"]
+    environment:
+      <<: *app-env
+      PORT: "3000"
+      WEB_CONCURRENCY: "${WEB_CONCURRENCY:-1}"
+    ports:
+      - "3000:3000"
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  # 워커 프로세스(gaon work) — 잡·리스너·스케줄러·아웃박스 릴레이.
+  worker:
+    build: .
+    command: ["pnpm", "work"]
+    environment: *app-env
+    depends_on:
+      postgres: { condition: service_healthy }
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  # 허브 프로세스(gaon hub) — 리더만 bind, 프레즌스 단일 권위(결정 60 · §7).
+  hub:
+    build: .
+    command: ["pnpm", "hub"]
+    environment:
+      <<: *app-env
+      GAON_HUB_PORT: "4001"
+      GAON_HUB_ADVERTISE: "hub:4001"
+    depends_on:
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: {{PROJECT_NAME}}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      POSTGRES_DB: {{PROJECT_NAME}}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{PROJECT_NAME}} -d {{PROJECT_NAME}}"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redisdata:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+  nats:
+    image: nats:2.10-alpine
+    command: ["-js", "-sd", "/data", "-m", "8222"]
+    volumes:
+      - natsdata:/data
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8222/healthz"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+volumes:
+  pgdata:
+  redisdata:
+  natsdata:

package/dist/templates/project/package.json.tpl

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "packageManager": "pnpm@10.27.0",
   "engines": {
     "node": ">=22"
   },

package/dist/work.js

@@ -44,6 +44,8 @@ function emitHuman(e) {
             return undefined;
         case 'relay':
             return `  ↪ 아웃박스 릴레이 — ${e.count}건 발행`;
+        case 'purge':
+            return `  🧹 아웃박스 정리 — ${e.count}건 삭제(보존 기간 초과)`;
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.18.0",
+  "version": "0.21.2",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.5.0",
+    "@gaonjs/async": "0.6.0",
+    "@gaonjs/config": "0.5.1",
+    "@gaonjs/data": "0.9.0",
     "@gaonjs/core": "0.2.0",
-    "@gaonjs/config": "0.4.1",
-    "@gaonjs/web": "0.6.1",
-    "@gaonjs/mail": "0.1.1",
-    "@gaonjs/data": "0.8.4"
+    "@gaonjs/mail": "0.1.2",
+    "@gaonjs/web": "0.7.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""