@gaonjs/cli 0.10.2 → 0.13.0

package/dist/commands/check.js

@@ -145,16 +145,18 @@ async function runStep(step, cwd) {
             output,
         };
     }
-    // build — 사용자 스크립트가 없으면 pnpm -r build 를 최선의 폴백으로 시도.
-    const cmd = 'pnpm';
-    const args = ['-r', 'run', 'build'];
-    const { exitCode, output } = await runSubprocess(cwd, cmd, args);
+    // build — 사용자 `build` 스크립트가 있으면 위 hasScript 분기가 이미 처리한다.
+    // 여기에 도달했다는 건 build 스크립트가 없다는 뜻 — typecheck·vue-tsc 와
+    // 같은 관례로 스킵한다. 과거엔 폴백으로 `pnpm -r run build` 를 돌렸지만,
+    // gaon new 프로젝트는 build 스크립트가 없고 packages/ 도 비어 있어 항상
+    // ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT 로 실패했다(= 갓 만든 프로젝트에서
+    // gaon check 가 무조건 exit 1). 타입 정합은 typecheck·vue-tsc 가 이미
+    // 담보하므로, 빌드는 사용자가 명시적으로 정의했을 때만 검사한다.
     return {
         step,
-        status: exitCode === 0 ? 'passed' : 'failed',
-        command: `${cmd} ${args.join(' ')}`,
-        exitCode,
-        output,
+        status: 'skipped',
+        output: 'build 스크립트가 없어 건너뜁니다(.vue/타입 정합은 typecheck·vue-tsc 가 담보).\n' +
+            '→ 프론트 프로덕션 빌드를 검사에 포함하려면 package.json 에 "build": "vite build" 를 정의하세요.',
     };
 }
 /** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */

package/dist/doctor/auth-wiring.d.ts

@@ -0,0 +1,9 @@
+import type { RuleReport } from './types.js';
+/** 컨트롤러 소스가 인증 표면을 쓰는지 판정한다(단위 테스트 진입점). */
+export declare function usesAuthSurface(source: string): boolean;
+/** app.config.ts 소스에 auth 배선이 있는지(얕은 텍스트 판정). */
+export declare function hasAuthWiring(source: string): boolean;
+/** app.config.ts 소스에 session 배선이 있는지(얕은 텍스트 판정). */
+export declare function hasSessionWiring(source: string): boolean;
+/** apps/ 를 훑어 인증 배선 누락을 낸다. */
+export declare function checkAuthWiring(cwd: string): Promise<RuleReport>;

package/dist/doctor/auth-wiring.js

@@ -0,0 +1,93 @@
+// @gaonjs/cli · doctor · 인증 배선 검사 (결정 59)
+//
+// 컨트롤러가 인증 표면(this.requireAuth() · this.auth.login() · this.currentUser)
+// 을 쓰는데 app.config.ts 에 auth(loadUser) 배선이 없으면, 컴파일은 통과하지만
+// 표준 부팅(gaon serve = wireGaon)에서 currentUser 가 **영구 null** 이 된다 —
+// 로그인 직후에도 requireAuth 가 계속 리다이렉트하는 런타임 파손이다. 이 검사가
+// 그 상태를 check 시점에 잡는다.
+//
+// 판정은 소스 텍스트 기반(가벼운 정적 검사) — app.config.ts 를 실행하지 않는다.
+// auth 앱이 JWT(strategy:'jwt')여도 auth: 키가 있으면 배선으로 인정한다.
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/** 컨트롤러 소스가 인증 표면을 쓰는지 판정한다(단위 테스트 진입점). */
+export function usesAuthSurface(source) {
+    return /this\.requireAuth\s*\(|this\.auth\.login\s*\(|this\.currentUser\b/.test(source);
+}
+/** app.config.ts 소스에 auth 배선이 있는지(얕은 텍스트 판정). */
+export function hasAuthWiring(source) {
+    return /\bauth\s*:/.test(source);
+}
+/** app.config.ts 소스에 session 배선이 있는지(얕은 텍스트 판정). */
+export function hasSessionWiring(source) {
+    return /\bsession\s*:/.test(source);
+}
+/** apps/ 를 훑어 인증 배선 누락을 낸다. */
+export async function checkAuthWiring(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const ctrlDir = join(appsDir, app, 'controllers');
+        const authFiles = [];
+        for (const file of await safeListFiles(ctrlDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const source = await readFile(join(ctrlDir, file), 'utf8');
+            if (usesAuthSurface(source))
+                authFiles.push(relative(cwd, join(ctrlDir, file)));
+        }
+        if (authFiles.length === 0)
+            continue;
+        const acPath = join(appsDir, app, 'app.config.ts');
+        const acRel = relative(cwd, acPath);
+        const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : undefined;
+        const jwt = acSource != null && /strategy\s*:\s*['"]jwt['"]/.test(acSource);
+        if (acSource == null || !hasAuthWiring(acSource)) {
+            issues.push({
+                rule: 'auth-wiring',
+                level: 'error',
+                file: authFiles[0],
+                message: `인증 배선 누락: apps/${app} 컨트롤러(${authFiles.join(', ')})가 requireAuth/this.auth 를 쓰는데 ` +
+                    `${acRel} 에 auth 배선이 없습니다. 이대로면 로그인해도 currentUser 가 항상 null 입니다(결정 59).\n` +
+                    `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
+                    `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' },\n` +
+                    `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
+                    `→ loadUser 가 없으면 \`gaon g auth --app ${app}\` 스캐폴드가 apps/${app}/auth.ts 에 만들어 줍니다.`,
+                detail: { app, controllers: authFiles },
+            });
+        }
+        else if (!jwt && !hasSessionWiring(acSource)) {
+            // auth 는 있는데 세션이 없다 — 세션 전략에서는 로그인 자체가 저장될 곳이 없다.
+            issues.push({
+                rule: 'auth-wiring',
+                level: 'error',
+                file: acRel,
+                message: `세션 배선 누락: ${acRel} 에 auth 는 있는데 session 이 없습니다 — 세션 전략에서는 ` +
+                    `this.auth.login() 이 저장될 세션이 없어 로그인이 유지되지 않습니다(결정 59).\n` +
+                    `→ defineAppConfig({...}) 에 session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' } 을 추가하고,\n` +
+                    `→ 루트 gaon.config.ts 에 redis: { url: process.env.REDIS_URL } 이 켜져 있는지 확인하세요.`,
+                detail: { app },
+            });
+        }
+    }
+    return { rule: 'auth-wiring', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/response-mixing.d.ts

@@ -1,5 +1,5 @@
 import type { RuleReport } from './types.js';
-export type ResponseKind = 'render' | 'redirect' | 'json' | 'plain';
+export type ResponseKind = 'render' | 'redirect' | 'json' | 'guard' | 'plain';
 export interface ActionUsage {
     readonly file: string;
     readonly action: string;

package/dist/doctor/response-mixing.js

@@ -6,10 +6,13 @@
 //
 // 정적 분석: apps/<app>/controllers/*.ts 를 TS AST 로 파싱, 액션마다
 // return 노드에서 최종 응답 형태를 분류(render | redirect | json | plain).
-// 서로 다른 형태가 두 종류 이상이면 위반(error 등급).
+// 서로 다른 형태가 두 종류 이상이면 위반(error 등급). 단 {render, redirect}
+// 조합만은 폼 액션 정본(실패 render + 성공 redirect · 결정 57 보완)이라 허용.
 import { readdir, readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import ts from 'typescript';
+/** never 반환/throw 가드 헬퍼 — 응답 형태로 세지 않는다(결정 57). */
+const GUARD_METHODS = new Set(['notFound', 'requireAuth']);
 /** 소스 문자열 하나에서 액션별 응답 종류를 수집한다(단위 테스트 진입점). */
 export function inspectControllerSource(file, source) {
     const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
@@ -79,6 +82,8 @@ function classifyReturns(body) {
                     return 'redirect';
                 if (c.name.text === 'json')
                     return 'json';
+                if (GUARD_METHODS.has(c.name.text))
+                    return 'guard';
             }
             return 'plain';
         }
@@ -120,7 +125,17 @@ export async function checkResponseMixing(cwd) {
             const source = await readFile(full, 'utf8');
             const usages = inspectControllerSource(full, source);
             for (const u of usages) {
-                if (u.kinds.length < 2)
+                // 'guard'(notFound·requireAuth)는 응답 형태가 아니라 조기 종료라 카운트
+                // 제외(결정 57). 실제 응답 형태가 2종 이상일 때만 혼용 위반.
+                const responseKinds = u.kinds.filter((k) => k !== 'guard');
+                if (responseKinds.length < 2)
+                    continue;
+                // 결정 57 보완(2026-07-26): {render, redirect} 조합은 혼용이 아니라 **폼
+                // 액션 정본**이다 — 실패 시 이전 페이지 render + 성공 시 redirect (공식
+                // gaon g auth 스캐폴드 session#create 동형 · Inertia SPA §6). 이 조합을
+                // 위반으로 잡으면 공식 스캐폴드가 doctor 를 통과하지 못하는 오탐이 된다.
+                const kindSet = new Set(responseKinds);
+                if (kindSet.size === 2 && kindSet.has('render') && kindSet.has('redirect'))
                     continue;
                 const rel = relative(cwd, full);
                 issues.push({
@@ -128,10 +143,11 @@ export async function checkResponseMixing(cwd) {
                     level: 'error',
                     file: rel,
                     line: u.line,
-                    message: `응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${u.kinds.join(', ')}).\n` +
+                    message: `응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${responseKinds.join(', ')}).\n` +
                         `→ 한 액션은 한 응답 형태만 유지하세요 (render | JSON | redirect · errata E-3 §C).\n` +
+                        `→ 예외: 폼 액션의 "실패 render + 성공 redirect" 조합만 정본으로 허용됩니다 (결정 57 보완).\n` +
                         `→ 조건 분기가 필요하면 액션을 둘로 나누거나, JSON 반환에는 예외를 던져 상태 코드를 표현하세요.`,
-                    detail: { action: u.action, kinds: [...u.kinds] },
+                    detail: { action: u.action, kinds: [...responseKinds] },
                 });
             }
         }

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

package/dist/doctor.d.ts

@@ -13,6 +13,7 @@ export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-in
 export { expectedColumnName, extractSnakeColumns, checkColumnCasing, } from './doctor/column-casing.js';
 export { isPascalCase, checkModelFilename } from './doctor/model-filename.js';
 export { checkPageFilename } from './doctor/page-filename.js';
+export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } from './doctor/auth-wiring.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 12 검사를 조립한다:
+ * 13 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -14,6 +14,7 @@
  * 10) column-casing (§네이밍 · 결정 43·46 · 컬럼 camelCase)
  * 11) model-filename (§3.4 · 결정 32·46 · 모델 파일명 PascalCase)
  * 12) page-filename (§3.4 · 결정 32·46 · Vue 페이지 파일명 PascalCase)
+ * 13) auth-wiring (§7 · 결정 59 · requireAuth ↔ app.config.ts auth 배선)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -38,6 +39,7 @@ import { checkAgentsDocIndex } from './doctor/agents-doc-index.js';
 import { checkColumnCasing } from './doctor/column-casing.js';
 import { checkModelFilename } from './doctor/model-filename.js';
 import { checkPageFilename } from './doctor/page-filename.js';
+import { checkAuthWiring } from './doctor/auth-wiring.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -54,10 +56,11 @@ export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-in
 export { expectedColumnName, extractSnakeColumns, checkColumnCasing, } from './doctor/column-casing.js';
 export { isPascalCase, checkModelFilename } from './doctor/model-filename.js';
 export { checkPageFilename } from './doctor/page-filename.js';
+export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } from './doctor/auth-wiring.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 12개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 13개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -72,6 +75,7 @@ const ALL_RULES = [
     'column-casing',
     'model-filename',
     'page-filename',
+    'auth-wiring',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -86,6 +90,7 @@ const CHECKERS = {
     'column-casing': checkColumnCasing,
     'model-filename': checkModelFilename,
     'page-filename': checkPageFilename,
+    'auth-wiring': checkAuthWiring,
 };
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).

package/dist/generate.d.ts

@@ -11,6 +11,8 @@ export interface ScaffoldResult {
     readonly created: string[];
     readonly skipped: string[];
     readonly patched: string[];
+    /** 손 수리가 필요한 지점 — 수리 안내 문장(§7.5.3)을 그대로 담는다. */
+    readonly warnings: string[];
 }
 /** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다. */
 export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldFile[];

package/dist/generate.js

@@ -35,8 +35,11 @@ const TEMPLATES = [
     { tpl: 'Login.vue.tpl', out: (a) => `apps/${a}/pages/auth/Login.vue` },
     { tpl: 'Signup.vue.tpl', out: (a) => `apps/${a}/pages/auth/Signup.vue` },
     { tpl: 'Dashboard.vue.tpl', out: (a) => `apps/${a}/pages/Dashboard.vue` },
-    { tpl: 'app.ts.tpl', out: (a) => `apps/${a}/app.ts` },
-    { tpl: 'server.ts.tpl', out: () => 'server.ts' },
+    // 결정 59: 세션·인증 배선은 app.config.ts — 표준 부팅(gaon dev/serve = wireGaon)이
+    // 소비한다. 과거의 수동 부팅 스캐폴드(app.ts·server.ts)는 두 번째 부팅 경로를
+    // 만들어 One Way 를 깨고, 표준 경로에는 auth 배선이 빠져 currentUser 가 영구
+    // null 이 되는 파손을 남겼다 — 제거했다.
+    { tpl: 'app.config.ts.tpl', out: (a) => `apps/${a}/app.config.ts` },
 ];
 /** 인증 스캐폴드가 생성하는 파일 목록(라우트 제외). 템플릿을 읽어 렌더링한다. */
 export function authScaffoldFiles(opts = {}) {
@@ -54,7 +57,11 @@ export function patchRoutes(existing) {
     if (!m || m.index === undefined)
         return null;
     const insertAt = m.index + m[0].length;
-    const inject = "\n  r.resource('session') // 로그인/로그아웃 (gaon g auth)" +
+    // dashboard 라우트도 함께 배선한다 — 없으면 스캐폴드 Dashboard.vue 의
+    // pageProps<'…:dashboard#show'> 가 라우트 맵에서 해상되지 않아 vue-tsc 가
+    // 깨진다(결정 60 클린룸 실측 — gaon new 프로젝트에 g auth 를 얹는 경로).
+    const inject = "\n  r.get('/dashboard', 'dashboard#show') // 보호 페이지 (gaon g auth)" +
+        "\n  r.resource('session') // 로그인/로그아웃 (gaon g auth)" +
         "\n  r.resource('registration') // 회원가입 (gaon g auth)";
     return existing.slice(0, insertAt) + inject + existing.slice(insertAt);
 }
@@ -65,10 +72,23 @@ export function writeAuthScaffold(cwd, opts = {}) {
     const created = [];
     const skipped = [];
     const patched = [];
+    const warnings = [];
     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 으로 끝내지 않고 수리 안내를 남긴다.
+            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` +
+                        `   auth: { loadUser, loginRedirect: '/session/new' }  // import { loadUser } from './auth.js'\n` +
+                        `→ 이 배선이 없으면 로그인해도 this.currentUser/requireAuth() 가 사용자를 받지 못합니다.`);
+                }
+            }
             continue;
         }
         mkdirSync(dirname(abs), { recursive: true });
@@ -93,7 +113,7 @@ export function writeAuthScaffold(cwd, opts = {}) {
         writeFileSync(routesPath, renderTemplate('routes.ts.tpl', app), 'utf8');
         created.push(routesRel);
     }
-    return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort() };
+    return { created: created.sort(), skipped: skipped.sort(), patched: patched.sort(), warnings };
 }
 /** `gaon g auth` 진입점. 스캐폴드를 쓰고 결과를 사람/JSON 으로 출력한다. */
 export function runGenerateAuthCommand(opts = {}) {
@@ -113,12 +133,14 @@ export function runGenerateAuthCommand(opts = {}) {
         lines.push(`   ~ ${f} (라우트 추가)`);
     for (const f of result.skipped)
         lines.push(`   · ${f} (이미 있음 — 건너뜀)`);
+    for (const w of result.warnings)
+        lines.push('', `  ⚠ ${w.split('\n').join('\n  ')}`);
     lines.push('');
     lines.push('  다음 단계:');
-    lines.push('   1) gaon dev 로 .gaon 타입 브리지를 생성한다 (tables·routes).');
+    lines.push('   1) .env 에 REDIS_URL·SESSION_SECRET(32자 이상)·COOKIE_SECRET 을 설정한다.');
     lines.push('   2) gaon db diff && gaon db migrate 로 users 테이블을 만든다.');
-    lines.push('   3) REDIS_URL·SESSION_SECRET·COOKIE_SECRET 을 설정하고 server.ts 를 실행한다.');
-    lines.push('   → /registration/new 회원가입 · /session/new 로그인 · 보호 라우트는 this.requireAuth().');
+    lines.push('   3) gaon dev 로 실행한다 (.gaon 타입 브리지 생성 + 세션·인증 자동 배선).');
+    lines.push('   → /registration/new 회원가입 · /session/new 로그인 · /dashboard 보호 페이지 (this.requireAuth()).');
     lines.push('');
     process.stdout.write(lines.join('\n') + '\n');
     return 0;

package/dist/index.js

@@ -98,7 +98,7 @@ function renderHelp(version = VERSION) {
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (12 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례)",
+        "    gaon doctor        정적 검사 (13 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -110,7 +110,7 @@ function renderHelp(version = VERSION) {
         "    gaon g job <Name>          비동기 잡 (domain/jobs · later/in/at)",
         "    gaon g app <name>          앱 스캐폴드 (apps/<name>/ · routes·controllers·pages·layouts)",
         "    gaon g <type> --overwrite  기존 파일 덮어쓰기 · --app <이름> · --json",
-        "    gaon mcp           내장 MCP 서버 · AI 도구 4종 (list_routes·get_schema·run_migration·run_tests · --http)",
+        "    gaon mcp           내장 MCP 서버 · AI 도구 7종 (list_routes·get_schema·run_migration·run_tests·read_agent_doc·run_check·run_doctor · --http)",
         "    gaon hub           실시간 허브 프로세스 (프레즌스 권위·중계 · 리더 선출 HA)",
         "    gaon work          워커 프로세스 (잡·리스너·스케줄·아웃박스 · graceful drain)",
         "    gaon jobs list --failed   DLQ(실패 잡) 목록",
@@ -223,7 +223,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 12 검사). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 13 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -249,9 +249,10 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon mcp` — 내장 MCP 서버(M10-B · 정본 §12 질문 8). AI 에이전트에게 4종
-    // 도구(list_routes·get_schema·run_migration·run_tests)를 노출한다. stdio(기본)
-    // 또는 --http 전송. 표시 버전은 파사드 버전을 주입한다.
+    // `gaon mcp` — 내장 MCP 서버(M10-B · 정본 §12 질문 8). AI 에이전트에게 7종
+    // 도구를 노출한다: 원문 4종(list_routes·get_schema·run_migration·run_tests)
+    // + read_agent_doc(결정 40) + run_check·run_doctor(결정 63 검증 루프).
+    // stdio(기본) 또는 --http 전송. 표시 버전은 파사드 버전을 주입한다.
     if (argv[0] === "mcp") {
         void runMcpCommand({
             json: argv.includes("--json"),

package/dist/mcp/tools.d.ts

@@ -82,6 +82,27 @@ export declare function runTestsTool(args: ToolArgs, cwd: string): Promise<ToolR
  *                            생략 시 사용 가능한 카테고리 목록을 반환.
  */
 export declare function readAgentDocTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `run_check` — `gaon check` 를 실 실행한다(규칙 3 · 검사 전 `.gaon` 재생성 포함).
+ *
+ * 컴파일 정답률(v3)의 정의 그 자체이자 CLAUDE.md §3 검증 루프의 본체다.
+ * AI 에이전트가 자기 산출물을 스스로 확증하는 표준 경로.
+ *
+ * 인자:
+ *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', includeDoctor?: boolean }
+ */
+export declare function runCheckTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
+/**
+ * `run_doctor` — `gaon doctor` 를 실 실행한다(관례 강제 검사).
+ *
+ * 기계적으로 검사 가능한 관례는 doctor 가 정본이다(§7.5.3 — 에러가 곧 수리
+ * 안내서). `fix` 는 기본이 dry-run(계획만)이고, 실제 파일 편집은 `yes` 를
+ * 함께 줘야 일어난다 — CLI 규약(`--fix` + `--yes`)을 그대로 따른다.
+ *
+ * 인자:
+ *   { checks?: string, fix?: boolean, yes?: boolean }
+ */
+export declare function runDoctorTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /** MCP 도구 스펙 — MCP 클라이언트에게 노출할 이름·설명·입력 스키마. */
 export interface McpToolSpec {
     readonly name: string;
@@ -90,8 +111,9 @@ export interface McpToolSpec {
     readonly run: (args: ToolArgs, cwd: string) => Promise<ToolResult>;
 }
 /**
- * 정본 §12 질문 8 확정 명세 4종을 카탈로그로 제공한다. 순서 = 원문 순서
- * (라우트 · 스키마 · 마이그레이션 · 테스트).
+ * 도구 카탈로그. 앞 4종은 정본 §12 질문 8 확정 명세이며 순서도 원문 그대로
+ * (라우트 · 스키마 · 마이그레이션 · 테스트), 뒤이어 `read_agent_doc`(결정 40
+ * 2층 문서 조회) · `run_check`·`run_doctor`(결정 63 검증 루프 노출)가 붙는다.
  */
 export declare const TOOLS: readonly McpToolSpec[];
 /**

package/dist/mcp/tools.js

@@ -382,9 +382,136 @@ export async function readAgentDocTool(args, cwd) {
         isError: false,
     };
 }
+// ── 도구 6·7: run_check · run_doctor ────────────────────────
 /**
- * 정본 §12 질문 8 확정 명세 4종을 카탈로그로 제공한다. 순서 = 원문 순서
- * (라우트 · 스키마 · 마이그레이션 · 테스트).
+ * `gaon` 실행 파일을 자식 프로세스로 돌려 stdout/stderr 를 캡처한다.
+ *
+ * 결정 63: `runCheckCommand`·`runDoctorCommand` 를 in-process 로 부르면 안 된다 —
+ * 둘 다 `process.stdout.write` 로 결과를 찍는데, MCP 서버의 전송이
+ * StdioServerTransport(stdout = JSON-RPC 채널)라 프로토콜 스트림이 깨진다.
+ * `run_tests` 와 같은 spawn 경로를 쓰면 자식 stdout 이 파이프로 격리되고,
+ * 덤으로 사용자가 실제로 밟는 CLI 경로 그대로를 검증하게 된다.
+ */
+async function spawnGaon(cwd, cliArgs) {
+    const bin = join(resolvePath(cwd), 'node_modules', '.bin', 'gaon');
+    if (!existsSync(bin)) {
+        return {
+            error: `gaon 실행 파일이 없습니다: ${bin}\n` +
+                `→ 프로젝트에서 \`npm i gaonjs\` (또는 pnpm add gaonjs) 로 설치한 뒤 다시 시도하세요.`,
+        };
+    }
+    const child = spawn(bin, [...cliArgs], { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+        stdout += d.toString('utf8');
+    });
+    child.stderr.on('data', (d) => {
+        stderr += d.toString('utf8');
+    });
+    const exitCode = await new Promise((resolveExit) => {
+        child.on('close', (code) => resolveExit(code ?? 1));
+    });
+    return { exitCode, output: stdout + (stderr ? `\n[stderr]\n${stderr}` : '') };
+}
+/** stdout 에서 `--json` 산출을 건져낸다. 사람용 줄이 섞여 있어도 마지막 JSON 객체를 취한다. */
+function parseJsonTail(output) {
+    const lines = output.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const s = (lines[i] ?? '').trim();
+        if (!s.startsWith('{'))
+            continue;
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            // 사람용 출력에 섞인 중괄호 줄 — 계속 위로 훑는다.
+        }
+    }
+    return undefined;
+}
+/**
+ * `run_check` — `gaon check` 를 실 실행한다(규칙 3 · 검사 전 `.gaon` 재생성 포함).
+ *
+ * 컴파일 정답률(v3)의 정의 그 자체이자 CLAUDE.md §3 검증 루프의 본체다.
+ * AI 에이전트가 자기 산출물을 스스로 확증하는 표준 경로.
+ *
+ * 인자:
+ *   { only?: 'typecheck'|'vue-tsc'|'build'|'doctor', includeDoctor?: boolean }
+ */
+export async function runCheckTool(args, cwd) {
+    const only = stringOpt(args, 'only');
+    const includeDoctor = boolOpt(args, 'includeDoctor');
+    const known = ['typecheck', 'vue-tsc', 'build', 'doctor'];
+    if (only && !known.includes(only)) {
+        return errorResult(`only 는 ${known.map((k) => `'${k}'`).join(' | ')} 중 하나여야 합니다. 입력값: '${only}'\n` +
+            `→ 인자를 고치거나 생략해 전체 검사를 실행하세요.`);
+    }
+    const cliArgs = ['check', '--json', ...(only ? ['--only', only] : []), ...(includeDoctor ? ['--include-doctor'] : [])];
+    const r = await spawnGaon(cwd, cliArgs);
+    if ('error' in r)
+        return errorResult(r.error);
+    return {
+        text: r.output || `(gaon check 출력 없음 · exit ${r.exitCode})`,
+        data: {
+            ok: r.exitCode === 0,
+            exitCode: r.exitCode,
+            only: only ?? null,
+            includeDoctor,
+            report: parseJsonTail(r.output) ?? null,
+            output: r.output,
+        },
+        isError: r.exitCode !== 0,
+    };
+}
+/**
+ * `run_doctor` — `gaon doctor` 를 실 실행한다(관례 강제 검사).
+ *
+ * 기계적으로 검사 가능한 관례는 doctor 가 정본이다(§7.5.3 — 에러가 곧 수리
+ * 안내서). `fix` 는 기본이 dry-run(계획만)이고, 실제 파일 편집은 `yes` 를
+ * 함께 줘야 일어난다 — CLI 규약(`--fix` + `--yes`)을 그대로 따른다.
+ *
+ * 인자:
+ *   { checks?: string, fix?: boolean, yes?: boolean }
+ */
+export async function runDoctorTool(args, cwd) {
+    const checks = stringOpt(args, 'checks');
+    const fix = boolOpt(args, 'fix');
+    const yes = boolOpt(args, 'yes');
+    if (yes && !fix) {
+        return errorResult('yes=true 는 fix=true 와 함께여야 합니다 — 단독으로는 아무것도 하지 않습니다.\n' +
+            '→ 자동 정정을 적용하려면 { fix: true, yes: true }, 계획만 보려면 { fix: true } 로 호출하세요.');
+    }
+    const cliArgs = [
+        'doctor',
+        '--json',
+        ...(checks ? [`--check=${checks}`] : []),
+        ...(fix ? ['--fix'] : []),
+        ...(fix && yes ? ['--yes'] : []),
+    ];
+    const r = await spawnGaon(cwd, cliArgs);
+    if ('error' in r)
+        return errorResult(r.error);
+    // exit 2 = fatal(사용자 오류 · 크래시 아님) · 1 = 위반 있음 · 0 = 통과.
+    return {
+        text: r.output || `(gaon doctor 출력 없음 · exit ${r.exitCode})`,
+        data: {
+            ok: r.exitCode === 0,
+            exitCode: r.exitCode,
+            fatal: r.exitCode === 2,
+            checks: checks ?? null,
+            fix,
+            applied: fix && yes,
+            report: parseJsonTail(r.output) ?? null,
+            output: r.output,
+        },
+        isError: r.exitCode !== 0,
+    };
+}
+/**
+ * 도구 카탈로그. 앞 4종은 정본 §12 질문 8 확정 명세이며 순서도 원문 그대로
+ * (라우트 · 스키마 · 마이그레이션 · 테스트), 뒤이어 `read_agent_doc`(결정 40
+ * 2층 문서 조회) · `run_check`·`run_doctor`(결정 63 검증 루프 노출)가 붙는다.
  */
 export const TOOLS = [
     {
@@ -462,6 +589,43 @@ export const TOOLS = [
         },
         run: readAgentDocTool,
     },
+    {
+        name: 'run_check',
+        description: '`gaon check` 를 실 실행한다 — 검사 전에 .gaon 타입 브리지를 재생성(규칙 3)한 뒤 ' +
+            'typecheck·vue-tsc·build 를 순서대로 돌린다. 산출물을 고친 뒤 스스로 확증하는 표준 경로 ' +
+            '(CLAUDE.md §3 검증 루프). only 로 한 단계만, includeDoctor 로 doctor 까지 포함.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                only: {
+                    type: 'string',
+                    enum: ['typecheck', 'vue-tsc', 'build', 'doctor'],
+                    description: '지정 시 그 검사 하나만 실행. 생략 시 전체.',
+                },
+                includeDoctor: { type: 'boolean', description: 'true 면 doctor 도 함께 실행. 기본 false.' },
+            },
+            additionalProperties: false,
+        },
+        run: runCheckTool,
+    },
+    {
+        name: 'run_doctor',
+        description: '`gaon doctor` 를 실 실행한다 — 기계적으로 검사 가능한 관례 위반을 찾고 수리 안내까지 낸다(§7.5.3). ' +
+            'checks 로 일부 규칙만 선택, fix=true 는 dry-run(계획만), 실제 파일 편집은 fix+yes 를 함께 줘야 한다.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                checks: {
+                    type: 'string',
+                    description: "쉼표로 구분한 규칙 이름(예: 'schema-filename,model-filename'). 생략 시 전 규칙.",
+                },
+                fix: { type: 'boolean', description: 'true 면 자동 정정 계획(dry-run). 편집하려면 yes 도 필요.' },
+                yes: { type: 'boolean', description: 'fix 와 함께 줘야 실제 파일이 편집된다(원본은 .bak 백업).' },
+            },
+            additionalProperties: false,
+        },
+        run: runDoctorTool,
+    },
 ];
 /**
  * 이름으로 도구를 찾는다. 없으면 undefined.

package/dist/scaffold/app.js

@@ -112,8 +112,8 @@ export function appScaffoldFiles(name) {
             `<script setup lang="ts">`,
             `import { pageProps } from 'gaonjs/vue'`,
             ``,
-            `// home#index 의 render props — Serialized<> 로 넘어온다(§6.2).`,
-            `const props = pageProps<'home#index'>()`,
+            `// ${name}:home#index 의 render props — Serialized<> 로 넘어온다(§6.2).`,
+            `const props = pageProps<'${name}:home#index'>()`,
             `</script>`,
             ``,
             `<template>`,

package/dist/scaffold/page.js

@@ -22,8 +22,10 @@ export function pageScaffold(pagePath, app) {
     const segments = trimmed.split('/').filter(Boolean);
     const last = segments[segments.length - 1];
     const parent = segments[segments.length - 2] ?? last;
-    // 라우트 키 기본값 — 폴더는 리소스명(복수·소문자), 파일은 액션명(소문자).
-    const routeKey = `${toCamel(parent).toLowerCase()}#${toCamel(last).toLowerCase()}`;
+    // 라우트 키 기본값 — 앱 접두(결정 55) + 폴더=리소스명(복수·소문자) +
+    // 파일=액션명(소문자). 앱 네임스페이스가 있어야 멀티앱에서 전역 GaonRouteMap
+    // 충돌이 없다.
+    const routeKey = `${app}:${toCamel(parent).toLowerCase()}#${toCamel(last).toLowerCase()}`;
     const filePath = `apps/${app}/pages/${trimmed}.vue`;
     const lines = [
         `<script setup lang="ts">`,

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

@@ -2,7 +2,7 @@
 import { pageProps } from 'gaonjs/vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
-const { user } = pageProps<'dashboard#show'>()
+const { user } = pageProps<'{{APP_NAME}}:dashboard#show'>()
 </script>
 
 <template>

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

@@ -2,7 +2,7 @@
 import { pageProps } from 'gaonjs/vue'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2).
-const { error, csrf } = pageProps<'session#new'>()
+const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
 </script>
 
 <template>

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

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { pageProps } from 'gaonjs/vue'
 
-const { error, csrf } = pageProps<'registration#new'>()
+const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
 </script>
 
 <template>

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

@@ -0,0 +1,11 @@
+// 앱 설정 — gaon g auth 스캐폴드. 세션·인증을 표준 부팅(gaon dev / gaon serve)에 배선한다.
+import { defineAppConfig } from 'gaonjs/config'
+import { loadUser } from './auth.js'
+
+export default defineAppConfig({
+  // 세션 secret 은 32자 이상 — .env 의 SESSION_SECRET 로 주입한다.
+  session: { secret: process.env.SESSION_SECRET ?? 'dev-only-session-secret-change-me-now!!' },
+  // 결정 59: 세션 userId → 사용자 로드 배선. 이게 있어야 로그인 후
+  // this.currentUser / this.requireAuth() 가 실제 사용자를 받는다.
+  auth: { loadUser, loginRedirect: '/session/new' },
+})

package/dist/templates/auth/dashboard.controller.ts.tpl

@@ -2,7 +2,7 @@
 import { controller } from 'gaonjs/web'
 
 export default controller({
-  // GET / — 로그인해야 볼 수 있는 홈. 비로그인은 로그인 페이지로 보내진다.
+  // GET /dashboard — 로그인해야 볼 수 있는 보호 페이지. 비로그인은 로그인으로 보내진다.
   async show() {
     const user = this.requireAuth()
     return this.render('Dashboard', { user })

package/dist/templates/auth/registration.controller.ts.tpl

@@ -15,6 +15,6 @@ export default controller({
     const passwordDigest = await hashPassword(password)
     const user = await User.create({ name, email, passwordDigest })
     this.auth.login(user)
-    return this.redirect('/')
+    return this.redirect('/dashboard')
   },
 })

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

@@ -1,7 +1,7 @@
 import { routes } from 'gaonjs/web'
 
 export default routes((r) => {
-  r.get('/', 'dashboard#show') // 보호 홈 (gaon g auth)
+  r.get('/dashboard', 'dashboard#show') // 보호 페이지 (gaon g auth)
   r.resource('session') // 로그인/로그아웃 (gaon g auth)
   r.resource('registration') // 회원가입 (gaon g auth)
 })

package/dist/templates/auth/session.controller.ts.tpl

@@ -14,7 +14,7 @@ export default controller({
     // passwordDigest 는 hidden 이지만 서버 코드에서는 투명하게 읽힌다(§4.2).
     if (user && (await verifyPassword(password, user.passwordDigest))) {
       this.auth.login(user)
-      return this.redirect('/')
+      return this.redirect('/dashboard')
     }
     return this.render('auth/Login', {
       error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,

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

@@ -103,7 +103,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 12종
+### 2.2 `gaon doctor` 검사 13종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -117,6 +117,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 10. `column-casing` — 스키마 컬럼명 camelCase 관례 (결정 43·46 · 스네이크 컬럼 검출)
 11. `model-filename` — 모델 파일명 PascalCase 관례 (결정 32·46 · `--fix` 지원)
 12. `page-filename` — Vue 페이지 파일명 PascalCase 관례 (결정 32·46)
+13. `auth-wiring` — requireAuth/this.auth 사용 ↔ `app.config.ts` 인증 배선 (결정 59)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -157,7 +158,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 12종 (§2.2)
+gaon doctor       # 정적 검사 13종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -172,7 +173,7 @@ gaon doctor       # 정적 검사 12종 (§2.2)
 | `gaon check` / `test` / `doctor` | 검증 루프 |
 | `gaon console` | 프로젝트 컨텍스트 REPL |
 | `gaon jobs` | DLQ 조회·재적재 |
-| `gaon mcp` | 내장 MCP 서버 — 도구: `list_routes`·`get_schema`·`run_migration`·`run_tests`·`read_agent_doc` |
+| `gaon mcp` | 내장 MCP 서버 — 도구 7종: `list_routes`·`get_schema`·`run_migration`·`run_tests`·`read_agent_doc`·`run_check`·`run_doctor` |
 
 `gaon mcp` 는 프레임웍이 자신을 AI 도구로 노출한다 (§7.5.3) — grep
 으로 더듬는 대신 프레임웍에게 직접 묻는다. `read_agent_doc` 은 §0

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

@@ -285,7 +285,7 @@ const rows = await Post.query()
 
 - `packages/vue/src/serialize.ts:28` — **`Serialized<T>`**: 임의 값의
   JSON-safe 매핑 (Date → string, bigint → string, Hidden 브랜드 제외).
-  `api()` 반환 타입 · `pageProps<'ctrl#action'>()` 결과 타입이 이것.
+  `api()` 반환 타입 · `pageProps<'app:ctrl#action'>()` 결과 타입이 이것.
 - `packages/data/src/schema.ts:544` — **`SerializedOf<Defs>`**: 테이블
   스키마 defs 의 SerializedOf — hidden 컬럼 키 제외한 Row.
 
@@ -342,6 +342,10 @@ const post = await Post.create({ title: '제목', body: '...', authorId: user.id
 await post.publish()                                    // 인스턴스 메서드
 ```
 
+- **두 번째 인자는 생략할 수 없다** (결정 62). 스코프·메서드·훅이 하나도
+  없어도 빈 객체를 넘긴다 — 최소형은 `model(posts, {})` 다. `model(posts)`
+  는 타입 에러이며, `gaon check` 는 검사 전에 `.gaon` 을 재생성하느라
+  타입 진단보다 먼저 런타임 에러로 멈춘다.
 - **두 번째 인자** = `{ scopes?, methods?, hooks? }`. `scopes` 값은
   `(q) => q.where(...)` 형태로 쿼리를 좁히는 함수, `methods` 는 인스턴스
   메서드(`this` 로 레코드 필드·관계에 접근), `hooks` 는 `beforeCreate`

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

@@ -6,7 +6,7 @@
 
 ## 정본 규칙
 
-### 1. 페이지(Vue) — `pageProps<'ctrl#action'>()` 로 컨트롤러 props 수신
+### 1. 페이지(Vue) — `pageProps<'app:ctrl#action'>()` 로 컨트롤러 props 수신
 
 컨트롤러의 `this.render('Posts/Index', {...})` 가 넘긴 render props 를 페이지가 받는
 방식은 **하나뿐** — `gaonjs/vue` 의 `pageProps<K>()` 헬퍼. 라우트 키 `K` 로부터
@@ -19,8 +19,8 @@
 <script setup lang="ts">
 import { pageProps } from 'gaonjs/vue'                 // 파사드 · 서브패스 X
 
-// 라우트 posts#index 의 컨트롤러 render props 가 Serialized 로 흘러들어온다.
-const props = pageProps<'posts#index'>()
+// 라우트 web:posts#index 의 컨트롤러 render props 가 Serialized 로 흘러들어온다.
+const props = pageProps<'web:posts#index'>()
 </script>
 
 <template>
@@ -31,8 +31,9 @@ const props = pageProps<'posts#index'>()
 </template>
 ```
 
-- **라우트 키** = `<controller>#<action>` (컨트롤러 파일명 stem · 소문자 복수).
-  `apps/web/controllers/posts.ts` 의 `index` 액션 → `'posts#index'`.
+- **라우트 키** = `<app>:<controller>#<action>` (앱 폴더명 · 컨트롤러 파일명
+  stem · 소문자 복수 · 결정 55). `apps/web/controllers/posts.ts` 의 `index`
+  액션 → `'web:posts#index'`.
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
   로 import 하지 않는다.
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
@@ -52,7 +53,7 @@ import { api } from 'gaonjs/vue'                       // 파사드 · 서브패
 
 async function search(q: string) {
   // 첫 인자 = 'controller#action' 라우트 키, 두 번째 = 라우트 파라미터 + 쿼리/바디
-  const { results } = await api('posts#search', { q })
+  const { results } = await api('web:posts#search', { q })
   return results
 }
 </script>
@@ -159,11 +160,11 @@ import { ref } from 'vue'
 import { pageProps, api } from 'gaonjs/vue'
 import PostCard from '../../components/PostCard.vue'
 
-const props = pageProps<'posts#index'>()
+const props = pageProps<'web:posts#index'>()
 const results = ref<Awaited<ReturnType<typeof runSearch>>>([])
 
 async function runSearch(q: string) {
-  const res = await api('posts#search', { q })
+  const res = await api('web:posts#search', { q })
   return res.results
 }
 </script>

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

@@ -35,7 +35,9 @@
 ```ts
 import { connectNats } from 'gaonjs/async'
 
-const nats = await connectNats(process.env.NATS_URL ?? 'nats://localhost:4222')
+// 인자 없이 부르면 env NATS_URL(없으면 nats://127.0.0.1:4222)에 붙는다.
+// 명시하려면 옵션 객체: connectNats({ servers: 'nats://...', name: '...' }).
+const nats = await connectNats()
 // ... 검증 ...
 await nats.close()
 ```
@@ -58,7 +60,7 @@ import { SendWelcomeMail } from '../../domain/jobs/sendWelcomeMail.js'
 
 describe('SendWelcomeMail (실 NATS JetStream)', () => {
   it('발행한 잡이 워커에서 처리된다', async () => {
-    const nats = await connectNats(process.env.NATS_URL ?? 'nats://localhost:4222')
+    const nats = await connectNats()   // env NATS_URL → 기본 nats://127.0.0.1:4222
     try {
       await expectJobProcessed(SendWelcomeMail, () => SendWelcomeMail.later(1n), { nats })
     } finally {

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

@@ -24,12 +24,16 @@ export default controller({
 
   // JSON 액션 — 객체를 반환하면 JSON 응답
   async search() {
-    const { q } = this.params(Post.searchForm)          // 검증 실패 시 자동 422 JSON
+    const { q } = this.params({ _row: {} as { q: string } })  // 검증 실패 시 자동 422 JSON
     return { results: await Post.published().search(q).limit(10).all() }
   },
 })
 ```
 
+- **액션 이름 = 메서드 관례(camelCase · §2.1)** — JSON 액션도 컨트롤러
+  메서드이므로 `tagAdd`(○) `tag_add`(✗). 라우트 참조·`api()` 키도 같은
+  이름을 쓴다: `r.post('/posts/:id/tagAdd', 'posts#tagAdd')` ·
+  `api('web:posts#tagAdd', ...)`.
 - **import 관례** — 프레임웍 심볼은 파사드 `gaonjs/*` 에서 (`gaonjs/web`·
   `gaonjs/data`·`gaonjs/vue`·`gaonjs/async` 등), 도메인 모델은 상대경로
   `../../../domain/models/<Pascal>.js` 로 참조한다. `@gaonjs/*` (스코프
@@ -40,11 +44,14 @@ export default controller({
 - **리소스 부재 = `this.notFound()`** — 조회 결과가 없으면 404 를 손으로 만들지
   말고 `this.notFound()` 로 마감한다(`requireAuth()` 와 동형). `never` 를 반환해
   이 뒤로 값이 존재하는 것으로 좁혀지므로, `render` 반환 타입(타입 브리지)도 그대로
-  유지된다. 메시지는 선택: `this.notFound('post 없음')`.
+  유지된다. 메시지는 선택: `this.notFound('post 없음')`. 부재 가능 조회는
+  `.where(...).first()`(없으면 undefined)로 받는다 — **`Post.find(id)` 는 없으면
+  throw** 라(부재를 허용하지 않는 조회) `if (!post)` 가드가 죽은 코드가 된다.
 
   ```ts
   async show() {
-    const post = await Post.find(this.params(Post.showForm).id)
+    const { id } = this.params({ _row: {} as { id: string } })
+    const post = await Post.where('id', '=', BigInt(id)).first()
     if (!post) return this.notFound()   // 404 · 이 뒤로 post 는 non-null
     return this.render('Posts/Show', { post })
   }
@@ -55,6 +62,11 @@ export default controller({
 - **한 액션은 한 종류 응답만 낸다** (render 또는 JSON 또는 redirect —
   조건 분기 혼용 금지). `gaon doctor` 의 **response-mixing** 검사가
   혼용을 잡는다.
+- **단 하나의 예외 — 폼 액션 정본** (결정 57 보완): 폼을 받는 액션은
+  **실패 시 이전 페이지 render + 성공 시 redirect** 조합이 정본이다
+  (`gaon g auth` 의 session#create 동형 · Inertia SPA §6). 이
+  {render, redirect} 조합만은 doctor 가 허용한다 — render+JSON,
+  redirect+JSON 등 나머지 조합은 여전히 위반.
 - 검증은 페이지 액션과 동일하게 `this.params(스키마)` — 실패 시
   422 JSON.
 - 인증·세션은 같은 앱의 세션 쿠키를 그대로 쓴다. CSRF·rate limit 등
@@ -129,7 +141,56 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
 - 세션은 앱별 완전 분리 (Fastify 캡슐화 스코프): 쿠키 이름(`<app>_sid`) ·
   서명 secret · Redis 키 prefix · 쿠키 path 가 앱 단위로 갇힌다.
 - 스캐폴드는 `gaon g auth` — 로그인/회원가입 컨트롤러·페이지·라우트 일습.
-- 로그인 필요 액션은 `this.requireAuth()` 관례 (notFound 와 동형 — never 좁힘).
+- **로그인 필요 액션의 정답 = `this.requireAuth()`** (결정 57). notFound 처럼
+  예외로 마감하지만, **`if` 가드 자체가 없다**는 게 핵심:
+
+  ```ts
+  async new() {
+    this.requireAuth()                          // 미인증이면 로그인으로 리다이렉트
+    return this.render('Posts/New', { csrf: this.csrfToken() })
+  }
+  async create() {
+    const user = this.requireAuth()             // 반환값을 바로 쓴다
+    const post = await Post.create({ ...this.params(form), authorId: user.id })
+    return this.redirect(`/posts/${String(post.id)}`)
+  }
+  ```
+
+- **`this.auth.user`/`requireAuth()` 사용자 타입은 앱이 증강한다** (결정 58).
+  `GaonCurrentUser` 는 빈 인터페이스라 증강 없이는 `user.id` 접근이 타입에러다.
+  `gaon g auth` 가 `apps/<app>/auth.ts` 에 심는다:
+
+  ```ts
+  declare module 'gaonjs/web' {
+    interface GaonCurrentUser { id: bigint; name: string; email: string }
+  }
+  ```
+
+- **인증 배선 = `apps/<app>/app.config.ts` — 로그인 기능의 필수 구성 요소다**
+  (결정 59). 컨트롤러·페이지만 만들면 컴파일은 통과하지만, 이 배선이 없으면
+  세션에 로그인해도 요청마다 사용자를 로드할 길이 없어 `this.currentUser`/
+  `requireAuth()` 가 **영구 null** 이다(`gaon doctor` 의 `auth-wiring` 검사가
+  잡는다). 로그인 기능을 추가할 때는 반드시 함께 배선한다:
+
+  ```ts
+  // apps/web/app.config.ts — 세션 + 인증 배선 (gaon serve 가 자동 소비)
+  import { defineAppConfig } from 'gaonjs/config'
+  import { loadUser } from './auth.js'
+
+  export default defineAppConfig({
+    session: { secret: process.env.SESSION_SECRET ?? 'dev-only-session-secret-change-me-now!!' },
+    auth: { loadUser, loginRedirect: '/session/new' },
+  })
+  ```
+
+  ```ts
+  // apps/web/auth.ts — 세션 userId → 사용자 로드 이음새 (gaon g auth 가 생성)
+  import type { AuthOptions } from 'gaonjs/web'
+  import { User } from '../../domain/models/User.js'
+
+  export const loadUser: AuthOptions['loadUser'] = async (id) =>
+    await User.where('id', '=', BigInt(String(id))).first()
+  ```
 
 ## 정본 예시
 
@@ -144,7 +205,10 @@ export default controller({
     return this.render('Auth/Register', {})
   },
   async create() {
-    const user = await RegisterUser.call(this.params(RegisterUser.form))
+    const { name, email, password } = this.params({
+      _row: {} as { name: string; email: string; password: string },
+    })
+    const user = await RegisterUser.call({ name, email, password })
     await SendWelcomeMail.later(user.id)      // 잡 발행 위치는 결정 32 — 서비스 afterCommit 도 정합
     return this.redirect('/dashboard')
   },
@@ -154,7 +218,8 @@ export default controller({
 ## 알려진 함정
 
 - **render/JSON/redirect 를 한 액션에서 조건 혼용하면 doctor
-  response-mixing 위반** — 액션을 나눈다.
+  response-mixing 위반** — 액션을 나눈다. 예외는 폼 액션의
+  "실패 render + 성공 redirect" 조합 하나뿐(결정 57 보완).
 - **`fetch()` 로 로그인 폼 구현 금지** — 세션 앱 폼은 `Inertia.post()`.
   REST + fetch 는 API 앱(JWT) 전용.
 - **컨트롤러에 비즈니스 로직 인라인 금지** (§5.3 One Way) — 여러 모델·
@@ -174,4 +239,5 @@ export default controller({
 | 결정 24 (E-3 §5) | `this.params` 안전 규칙 (라우트 > body > query · 중복 키 · body/query 탈출구) |
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 — `agents/async.md`) |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 (`agents/frontend.md`) |
+| 결정 59 | 인증 배선 = `app.config.ts` 의 `session`+`auth(loadUser)` — 없으면 currentUser 영구 null |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/project/apps/web/pages/Home/Index.vue.tpl

@@ -3,7 +3,7 @@ import { pageProps } from 'gaonjs/vue'
 
 // home#index 의 render props — Serialized<> 로 넘어온다(§6.2).
 // 라우트 키는 .gaon/routes.d.ts 가 유효한 값을 알려준다.
-const props = pageProps<'home#index'>()
+const props = pageProps<'web:home#index'>()
 </script>
 
 <template>

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

@@ -21,6 +21,7 @@
     "vue": "^3.5.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "@vitejs/plugin-vue": "^6.0.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",

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

@@ -11,7 +11,7 @@
     "resolveJsonModule": true,
     "noEmit": true,
     "jsx": "preserve",
-    "types": ["node"]
+    "types": ["node", "vite/client"]
   },
   "include": [
     "apps/**/*.ts",
@@ -19,7 +19,9 @@
     "domain/**/*.ts",
     "shared/**/*.ts",
     "shared/**/*.vue",
-    "gaon.config.ts"
+    "gaon.config.ts",
+    ".gaon/**/*.d.ts",
+    "apps/*/.gaon/**/*.d.ts"
   ],
-  "exclude": ["node_modules", "dist", ".gaon"]
+  "exclude": ["node_modules", "dist"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.10.2",
+  "version": "0.13.0",
   "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.3.0",
-    "@gaonjs/core": "0.1.4",
-    "@gaonjs/data": "0.8.0",
-    "@gaonjs/mail": "0.1.0",
-    "@gaonjs/web": "0.5.0",
-    "@gaonjs/config": "0.2.0"
+    "@gaonjs/async": "0.3.1",
+    "@gaonjs/config": "0.3.0",
+    "@gaonjs/web": "0.5.3",
+    "@gaonjs/mail": "0.1.1",
+    "@gaonjs/data": "0.8.4",
+    "@gaonjs/core": "0.1.4"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""