@gaonjs/cli 0.18.0 → 0.23.0

package/dist/generate.js

@@ -69,6 +69,38 @@ export function patchRoutes(existing) {
         "\n  r.resource('registration') // 회원가입 (gaon g auth)";
     return existing.slice(0, insertAt) + inject + existing.slice(insertAt);
 }
+/**
+ * 기존 app.config.ts 에 auth 배선을 끼워 넣는다 (결정 93 · gaon new 기본 web 앱은
+ * 세션만 배선돼 있어 g auth 는 auth 만 추가하면 완성된다). 반환:
+ *  · auth 가 이미 있으면 null (그대로 둔다),
+ *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
+ * 성공 시 loadUser import 도 함께 보장한다.
+ */
+export function patchAppConfigAddAuth(existing) {
+    if (/\bauth\s*:/.test(existing))
+        return null;
+    const m = existing.match(/defineAppConfig\(\s*\{/);
+    if (!m || m.index === undefined)
+        return null;
+    const insertAt = m.index + m[0].length;
+    let out = existing.slice(0, insertAt) +
+        "\n  // 결정 59: 세션 userId → 사용자 로드 배선(g auth). 이게 있어야 로그인 후" +
+        "\n  // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다." +
+        "\n  auth: { loadUser, loginRedirect: '/session/new' }," +
+        existing.slice(insertAt);
+    // loadUser import 보장 — gaonjs/config import 바로 뒤에 넣는다.
+    if (!/from\s+['"]\.\/auth\.js['"]/.test(out)) {
+        const im = out.match(/import\s+\{[^}]*\}\s+from\s+['"]gaonjs\/config['"][^\n]*\n/);
+        if (im && im.index !== undefined) {
+            const at = im.index + im[0].length;
+            out = out.slice(0, at) + "import { loadUser } from './auth.js'\n" + out.slice(at);
+        }
+        else {
+            out = "import { loadUser } from './auth.js'\n" + out;
+        }
+    }
+    return out;
+}
 /** 스캐폴드를 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip 한다. routes.ts 는 패치. */
 export function writeAuthScaffold(cwd, opts = {}) {
     const root = resolve(cwd);
@@ -87,19 +119,31 @@ export function writeAuthScaffold(cwd, opts = {}) {
     for (const file of authScaffoldFiles(opts)) {
         const abs = join(root, file.path);
         if (existsSync(abs)) {
-            skipped.push(file.path);
-            // 결정 59: app.config.ts 가 이미 있는데 auth 배선이 없으면 로그인 후에도
-            // currentUser 가 영구 null 이다 — skip 으로 끝내지 않고 수리 안내를 남긴다.
+            // 결정 93: gaon new 기본 web 앱은 app.config.ts 에 세션만 배선돼 있다.
+            // g auth 는 이를 skip 하지 않고 **auth 배선을 패치로 추가**해 완성한다 —
+            // 결정 59: auth 배선이 없으면 로그인 후에도 currentUser 가 영구 null 이다.
             if (file.path === `apps/${app}/app.config.ts`) {
                 const existing = readFileSync(abs, 'utf8');
-                if (!/\bauth\s*:/.test(existing)) {
-                    warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 건너뛰었습니다.\n` +
-                        `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음 두 항목을 추가하세요:\n` +
-                        `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' },\n` +
+                const patchedConfig = patchAppConfigAddAuth(existing);
+                if (patchedConfig) {
+                    writeFileSync(abs, patchedConfig, 'utf8');
+                    patched.push(file.path);
+                }
+                else if (!/\bauth\s*:/.test(existing)) {
+                    // 패치 불가(비관례 config) — skip + 수리 안내로 폴백.
+                    skipped.push(file.path);
+                    warnings.push(`apps/${app}/app.config.ts 가 이미 있어 인증 배선을 자동 추가하지 못했습니다.\n` +
+                        `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
                         `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
                         `→ 이 배선이 없으면 로그인해도 this.currentUser/requireAuth() 가 사용자를 받지 못합니다.`);
                 }
+                else {
+                    // 이미 auth 배선됨 — 그대로 둔다.
+                    skipped.push(file.path);
+                }
+                continue;
             }
+            skipped.push(file.path);
             continue;
         }
         mkdirSync(dirname(abs), { recursive: true });

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";
     readonly version: string;
-    readonly stage: "stub";
+    readonly stage: "stable";
     readonly homepage: string;
     readonly docs: string;
     readonly milestones: readonly {
@@ -34,7 +34,11 @@ export interface RoadmapReport {
 }
 /** `--json` 출력용 구조화 리포트. */
 export declare function roadmapReport(version?: string): RoadmapReport;
-/** 사람이 읽는 로드맵 텍스트. */
+/**
+ * 인자 없이 실행했을 때의 사람용 배너 — 정식 배포(v1.0) 자기 소개 + 사용법 안내.
+ * 결정 94(W3): M1 스텁 시절 "개발 초기·런타임 없음" 오정보를 제거한다 — AI 가
+ * 사용 불가로 오판하거나 소형 모델이 멈추는 것을 막는다.
+ */
 export declare function renderRoadmap(version?: string): string;
 /** runCli 옵션. version 은 파사드가 주입하는 표시 버전(설치 패키지 버전). */
 export interface RunOptions {

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * @gaonjs/cli — Gaon CLI 구현.
  *
- * 인자 없이 실행하면 로드맵·개발 상태를 출력하는 스텁이다. M9-C 부터
- * `gaon dev` 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
+ * 인자 없이 실행하면 정식 배포(v1.0) 배너와 사용법을 출력한다. `gaon dev`
+ * 가 통합 개발 오케스트레이션을 담당한다 — Docker Compose
  * 자동 기동 + .gaon 타입 브리지 재생성 + serve 자식 프로세스 + tsc/vue-tsc
  * --watch + 소스 변경 시 서버 재시작(commands/dev.ts). 모든 명령은 `--json`
  * 출력을 함께 제공한다 (CLAUDE.md §4).
@@ -10,7 +10,7 @@
  * 표시 버전은 호출자(파사드)가 주입한다 — 사용자가 설치한 패키지
  * (`gaonjs`) 버전을 그대로 보여주기 위함. 미주입 시 core 버전을 쓴다.
  */
-import { MILESTONES, VERSION, HOMEPAGE } from "@gaonjs/core";
+import { MILESTONES, VERSION, HOMEPAGE, loadDotEnv } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
 import { runCheckCommand } from "./commands/check.js";
 import { runNewCommand } from "./commands/new.js";
@@ -54,41 +54,38 @@ export function roadmapReport(version = VERSION) {
     return {
         name: "gaon",
         version,
-        stage: "stub",
+        stage: "stable",
         homepage: HOMEPAGE,
         docs: HOMEPAGE,
         milestones: MILESTONES.map((m) => ({ id: m.id, title: m.title, status: m.status })),
     };
 }
-/** 사람이 읽는 로드맵 텍스트. */
+/**
+ * 인자 없이 실행했을 때의 사람용 배너 — 정식 배포(v1.0) 자기 소개 + 사용법 안내.
+ * 결정 94(W3): M1 스텁 시절 "개발 초기·런타임 없음" 오정보를 제거한다 — AI 가
+ * 사용 불가로 오판하거나 소형 모델이 멈추는 것을 막는다.
+ */
 export function renderRoadmap(version = VERSION) {
     const lines = [];
     lines.push("");
     lines.push(`  Gaon (가온) — AI가 개발을 가장 잘하는 Node.js 풀스택 웹 프레임웍`);
-    lines.push(`  v${version} · 개발 중 (스텁) · ${HOMEPAGE}`);
+    lines.push(`  v${version} · 정식 배포 · ${HOMEPAGE}`);
     lines.push("");
-    lines.push("  이 패키지는 아직 개발 초기 단계입니다. 런타임 기능은 아직 없고,");
-    lines.push("  자리(스코프·이름)를 잡아 두기 위한 동작하는 스텁입니다.");
+    lines.push("  데이터·인증·실시간·비동기·메일/스토리지·CLI 배터리가 모두 동작합니다.");
+    lines.push("  새 프로젝트를 만들고 개발 스택을 통합 기동하려면:");
     lines.push("");
-    lines.push("  로드맵");
-    lines.push("  ──────");
-    for (const m of MILESTONES) {
-        const mark = m.status === "in-progress" ? "▶" : "·";
-        const tag = m.status === "in-progress" ? " (진행 중)" : "";
-        lines.push(`   ${mark} ${m.id}  ${m.title}${tag}`);
-    }
+    lines.push("    gaon new <name>    새 프로젝트 스캐폴드");
+    lines.push("    gaon dev           개발 스택 통합 기동 (Docker · .gaon · serve · watch)");
+    lines.push("    gaon --help        전체 명령 목록");
     lines.push("");
-    lines.push("  참여 · 소식");
-    lines.push("  ──────────");
-    lines.push(`   문서 / 진행 상황:  ${HOMEPAGE}`);
-    lines.push(`   JSON 출력:         gaon --json`);
+    lines.push(`  문서: ${HOMEPAGE}   ·   JSON 출력: gaon --json`);
     lines.push("");
     return lines.join("\n");
 }
 function renderHelp(version = VERSION) {
     return [
         "",
-        "  gaon — Gaon 프레임웍 CLI (v" + version + ", 스텁)",
+        "  gaon — Gaon 프레임웍 CLI (v" + version + " · 정식 배포)",
         "",
         "  사용법:",
         "    gaon               로드맵과 개발 상태를 출력",
@@ -100,10 +97,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        정적 검사 (19 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -148,6 +146,7 @@ export function parseDoctorChecks(argv) {
         "migration-diff",
         "shared-composable-purity",
         "no-auto-import",
+        "csrf-wiring",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];
@@ -164,6 +163,13 @@ export function parseDoctorChecks(argv) {
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
+    // 결정 92(W1): `.env` 를 **진입점에서 한 번** 로드해 모든 명령이 동일하게
+    // 받는다. 이전엔 serve·dev·console 만 개별 호출해 db·work·hub·jobs·doctor·
+    // check 가 `.env` 없이 실행됐고(특히 work·hub 는 조용히 안 뜨는 부류),
+    // 실사용에서 `set -a; . ./.env` 수동 우회가 필요했다. 명령별 나열은 새
+    // 명령이 추가될 때마다 또 빠지므로 여기서 공통화한다. loadDotEnv 는 이미
+    // 설정된 env 를 덮지 않고 파일이 없으면 조용히 지나가 멱등하다(재호출 안전).
+    loadDotEnv();
     // `gaon dev` — 통합 개발 오케스트레이션(M9-C · v0.15 §13.5). Docker Compose
     // 자동 기동 + .gaon 재생성 + serve 자식 + tsc/vue-tsc watch + 서버 재시작 워처.
     // SIGINT/SIGTERM 시 순서대로 정리(serve → tsc → 워처 → Docker[--stop-docker 시]).
@@ -194,11 +200,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 +240,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;
@@ -66,6 +149,13 @@ export async function runServeCommand(opts = {}) {
     await wired.app.listen({ host, port });
     const displayHost = host === '0.0.0.0' ? 'localhost' : host;
     emit({ kind: 'listening', host, port, url: `http://${displayHost}:${port}` });
+    // 결정 98: serve 는 빌드된 번들을 서빙하며 코드 변경을 감시하지 않는다 —
+    // 수정이 조용히 반영 안 되는 혼란(첫 실사용 관측)을 막으려 한 줄 안내한다.
+    // dev 자식(gaon dev · opts.dev)은 이미 감시하므로 그때는 안내하지 않고,
+    // production 은 운영 로그 소음을 막으려 출력하지 않는다. json 은 파싱 안전상 제외.
+    if (!json && !opts.dev && process.env.NODE_ENV !== 'production') {
+        process.stdout.write('  ℹ serve 는 빌드된 번들을 서빙하며 코드 변경을 감시하지 않습니다 → 개발 중이면 `gaon dev` 를 쓰세요.\n');
+    }
     await new Promise((resolvePromise) => {
         const stop = () => {
             signals.off('SIGINT', stop);
@@ -85,4 +175,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/auth/Login.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/vue'
 import Card from '../../components/ui/Card.vue'
 import CardHeader from '../../components/ui/CardHeader.vue'
 import CardTitle from '../../components/ui/CardTitle.vue'
@@ -42,7 +42,7 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
         </Form>
         <p class="mt-4 text-center text-sm text-muted-foreground">
           계정이 없으신가요?
-          <a href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</a>
+          <Link href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>
         </p>
       </CardContent>
     </Card>

package/dist/templates/auth/Signup.vue.tpl

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { pageProps, useForm } from 'gaonjs/vue'
+import { pageProps, useForm, Link } from 'gaonjs/vue'
 import Card from '../../components/ui/Card.vue'
 import CardHeader from '../../components/ui/CardHeader.vue'
 import CardTitle from '../../components/ui/CardTitle.vue'
@@ -43,7 +43,7 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
         </Form>
         <p class="mt-4 text-center text-sm text-muted-foreground">
           이미 계정이 있으신가요?
-          <a href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</a>
+          <Link href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</Link>
         </p>
       </CardContent>
     </Card>

package/dist/templates/auth/app.ts.tpl

@@ -0,0 +1,29 @@
+// 웹 앱 팩토리 — gaon g auth 스캐폴드. createWebApp 으로 세션·인증을 배선한다.
+import { createApp, type AppSessionOptions } from 'gaonjs/web'
+import appRoutes from './routes.js'
+import session from './controllers/session.js'
+import registration from './controllers/registration.js'
+import dashboard from './controllers/dashboard.js'
+import { loadUser } from './auth.js'
+
+export interface WebAppDeps {
+  /** 세션 설정 — { redisUrl, secret } (또는 redis 인스턴스). */
+  readonly session: AppSessionOptions
+  /** 서명 쿠키/CSRF 용 비밀. */
+  readonly cookieSecret?: string
+}
+
+export function createWebApp(deps: WebAppDeps) {
+  return createApp({
+    apps: [
+      {
+        name: '{{APP_NAME}}',
+        routes: appRoutes,
+        controllers: { session, registration, dashboard },
+        session: deps.session,
+        auth: { loadUser, loginRedirect: '/session/new' },
+      },
+    ],
+    cookieSecret: deps.cookieSecret,
+  })
+}

package/dist/templates/auth/server.ts.tpl

@@ -0,0 +1,14 @@
+// 서버 진입점 — gaon g auth 스캐폴드. `node dist/server.js` 로 실행.
+import { createWebApp } from './apps/{{APP_NAME}}/app.js'
+
+const app = await createWebApp({
+  session: {
+    redisUrl: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
+    secret: process.env.SESSION_SECRET ?? 'change-me-to-a-32+char-random-secret!!',
+  },
+  cookieSecret: process.env.COOKIE_SECRET,
+})
+
+const port = Number(process.env.PORT ?? 3000)
+await app.listen({ port, host: '0.0.0.0' })
+console.log(`web 앱이 http://localhost:${port} 에서 실행 중입니다.`)

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` 검사 19종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -120,6 +120,11 @@ 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 · 경고)
+18. `csrf-wiring` — 비-GET 라우트(POST/PUT/PATCH/DELETE)가 있는데 `app.config.ts` 에 session 미배선 = CSRF 무방비 (결정 93 · 경고)
+19. `internal-anchor` — 앱 내부 경로 일반 `<a href="/...">`(풀 리로드로 SPA 파손 · `Link`/`router.visit` 를 쓰라 · 외부 URL·`target="_blank"` 는 제외) (결정 96 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -160,7 +165,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       # 정적 검사 19종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -168,8 +173,8 @@ gaon doctor       # 정적 검사 14종 (§2.2)
 | 명령 | 역할 |
 |---|---|
 | `gaon new <name>` | 프로젝트 스캐폴드 |
-| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·워처) |
-| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) |
+| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·**코드 변경 감시·재시작**) |
+| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** |
 | `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
 | `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
 | `gaon check` / `test` / `doctor` | 검증 루프 |
@@ -181,6 +186,11 @@ gaon doctor       # 정적 검사 14종 (§2.2)
 으로 더듬는 대신 프레임웍에게 직접 묻는다. `read_agent_doc` 은 §0
 카테고리 문서를 조회한다 (결정 40).
 
+**개발 중엔 `gaon dev`, 배포 실행은 `gaon serve`** (결정 98) — `gaon serve` 는
+빌드된 번들을 서빙하며 **코드 변경을 감시하지 않는다**(수정해도 반영 안 됨).
+개발 중이면 `gaon dev`(감시·재시작·`.gaon` 재생성 통합)를 쓴다. `serve` 는
+비-production 부팅 시 이 안내를 한 줄 출력한다.
+
 ## 5. npm 배포본 (2026-07-23 실측 · `npm view <pkg> version`)
 
 | 패키지 | 버전 | 역할 |
@@ -210,7 +220,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. 스케줄러