@gaonjs/cli 0.21.2 → 0.23.0

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

@@ -0,0 +1,5 @@
+import type { RuleReport } from './types.js';
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+export declare function hasStateChangingRoutes(routesSource: string): boolean;
+/** apps/ 를 훑어 CSRF/세션 미배선(비-GET 라우트 + session 없음)을 경고로 낸다. */
+export declare function checkCsrfWiring(cwd: string): Promise<RuleReport>;

package/dist/doctor/csrf-wiring.js

@@ -0,0 +1,72 @@
+// @gaonjs/cli · doctor · CSRF/세션 배선 검사 (결정 93)
+//
+// 규칙 8(§2.5.1): 보안 기본값(CORS·rate limit·CSRF)은 코어에서 기본 켬이다.
+// CSRF 는 세션 위에 얹힌다(session.ts) — 세션이 없으면 CSRF 토큰을 저장·검증할
+// 곳이 없어 상태 변경 요청(POST/PUT/PATCH/DELETE)이 **무방비**로 통과한다.
+//
+// 이 검사는 앱 routes.ts 에 비-GET 라우트가 있는데 그 앱 app.config.ts 에
+// session 배선이 없으면 경고한다 — 컴파일은 통과하지만 CSRF 가 실질적으로 꺼진
+// 상태다. JWT/API 앱(strategy:'jwt')은 토큰 인증이라 CSRF 대상이 아니므로 제외한다.
+//
+// 판정은 소스 텍스트 기반(가벼운 정적 검사) — routes.ts·app.config.ts 를 실행하지
+// 않는다. gaon new 스캐폴드는 web 앱에 세션을 기본 배선하므로(결정 93) 관례를
+// 따르면 이 경고는 나오지 않는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { hasSessionWiring } from './auth-wiring.js';
+/** routes.ts 소스에 상태 변경(비-GET) 라우트가 있는지 판정한다(단위 테스트 진입점). */
+export function hasStateChangingRoutes(routesSource) {
+    // r.post('/x', ...) · r.put/patch/delete — 메서드 + 경로 문자열.
+    if (/\.\s*(post|put|patch|delete)\s*\(\s*['"]/.test(routesSource))
+        return true;
+    // resource(s)('posts') — 리소스 라우트는 create/update/destroy(POST/PUT/DELETE)를 만든다.
+    if (/\.\s*resources?\s*\(\s*['"]/.test(routesSource))
+        return true;
+    return false;
+}
+/** apps/ 를 훑어 CSRF/세션 미배선(비-GET 라우트 + session 없음)을 경고로 낸다. */
+export async function checkCsrfWiring(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);
+        if (routesSource === undefined)
+            continue;
+        if (!hasStateChangingRoutes(routesSource))
+            continue;
+        const acPath = join(appsDir, app, 'app.config.ts');
+        const acRel = relative(cwd, acPath);
+        const acSource = existsSync(acPath) ? await readFile(acPath, 'utf8') : undefined;
+        // JWT/API 앱은 토큰 인증 — CSRF 대상 아님(제외).
+        const jwt = acSource != null && /strategy\s*:\s*['"]jwt['"]/.test(acSource);
+        if (jwt)
+            continue;
+        if (acSource != null && hasSessionWiring(acSource))
+            continue;
+        issues.push({
+            rule: 'csrf-wiring',
+            level: 'warning',
+            file: `apps/${app}/routes.ts`,
+            message: `CSRF 미배선: apps/${app} 에 비-GET 라우트(POST/PUT/PATCH/DELETE)가 있는데 ` +
+                `${acRel} 에 session 배선이 없습니다 — CSRF 는 세션 위에 얹히므로(규칙 8 · §2.5.1) ` +
+                `이대로면 상태 변경 요청이 CSRF 검증 없이 통과합니다(결정 93).\n` +
+                `→ apps/${app}/app.config.ts 의 defineAppConfig({...}) 에 다음을 추가하세요:\n` +
+                `   session: { secret: process.env.SESSION_SECRET ?? '32자 이상 비밀' }\n` +
+                `→ 루트 gaon.config.ts 에 redis: { url: process.env.REDIS_URL } 이 켜져 있는지 확인하세요(세션 스토어).\n` +
+                `→ 토큰 인증 API 앱이라면 app.config 에 auth: { strategy: 'jwt', ... } 를 선언하세요(CSRF 대상 제외).`,
+            detail: { app },
+        });
+    }
+    return { rule: 'csrf-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 [];
+    }
+}

package/dist/doctor/internal-anchor.d.ts

@@ -0,0 +1,6 @@
+import type { RuleReport } from './types.js';
+export declare function internalAnchorHref(openTag: string): string | null;
+/** 소스에 내부 이동 일반 앵커가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export declare function usesInternalAnchor(source: string): boolean;
+/** apps/ 의 .vue 를 훑어 내부 이동 일반 앵커를 경고로 낸다. */
+export declare function checkInternalAnchor(cwd: string): Promise<RuleReport>;

package/dist/doctor/internal-anchor.js

@@ -0,0 +1,122 @@
+// @gaonjs/cli · doctor · 앱 내부 이동 일반 <a> 앵커 검출 (결정 96 · 경고)
+//
+// 앱 내부 경로로 이동하는 일반 `<a href="/...">` 는 클릭마다 전체 문서를
+// 다시 로드한다 — Inertia SPA 상태(스크롤·폼·구독)가 초기화되고, "메인
+// 경로" 로 이동할 때마다 풀 리로드가 난다(첫 실사용 블로그에서 관측된 결함).
+// 앱 내부 이동은 `gaonjs/vue` 의 `Link`(선언적) 또는 `router.visit`(프로그램적)
+// 를 쓴다. 이 검사가 내부 경로 일반 앵커를 경고로 잡는다. 판정은 소스 텍스트 기반.
+//
+// 오탐 방지(결정 96): 외부 URL(http/https·//·mailto·tel)·프래그먼트(#)·
+// `target="_blank"`·정적 판별 불가한 바인딩(`:href="expr"` 중 템플릿 리터럴이
+// 아닌 것)은 건드리지 않는다. 내부로 확정 가능한 경우만 — 정적 `href="/..."`
+// 와 `/` 로 시작하는 템플릿 리터럴 `:href="`/...`"` — 잡는다.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+// 주석을 공백으로 치환하되 줄바꿈은 보존한다(라인 번호 유지) — 안티패턴을
+// "쓰지 말라"고 설명하는 주석(줄/블록/HTML-Vue)이 오탐을 내지 않도록.
+function stripCommentsKeepLines(source) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1 + ' '.repeat(_m.length - p1.length));
+}
+// 값이 앱 내부 경로(루트-상대)인지. 외부·프래그먼트·스킴은 제외.
+function isInternalStaticHref(value) {
+    const v = value.trim();
+    if (v === '')
+        return false;
+    if (v.startsWith('//'))
+        return false; // 프로토콜-상대 → 외부
+    if (/^[a-z][a-z0-9+.-]*:/i.test(v))
+        return false; // http:·mailto:·tel:·data: 등 스킴
+    if (v.startsWith('#'))
+        return false; // 페이지 내 프래그먼트
+    return v.startsWith('/'); // 루트-상대만 내부로 확정
+}
+// 여는 `<a ...>` 태그 하나가 "내부 이동 일반 앵커" 인지 판정해, 그렇다면
+// 문제의 href 문자열을 돌려준다(아니면 null). 정적 판별 불가는 null(오탐 방지).
+export function internalAnchorHref(openTag) {
+    // target="_blank" = 외부 의도 → 건드리지 않는다.
+    if (/\btarget\s*=\s*['"]_blank['"]/i.test(openTag))
+        return null;
+    // 정적 href="..."
+    const staticM = openTag.match(/\shref\s*=\s*(['"])([^'"]*)\1/i);
+    if (staticM)
+        return isInternalStaticHref(staticM[2]) ? staticM[2].trim() : null;
+    // 바인딩 :href / v-bind:href — 템플릿 리터럴 `/...` 만 내부로 확정.
+    const boundM = openTag.match(/(?::|v-bind:)href\s*=\s*(['"])([^'"]*)\1/i);
+    if (boundM) {
+        const expr = boundM[2].trim();
+        const tl = expr.match(/^`([^`]*)`$/); // `...` 전체가 템플릿 리터럴
+        if (tl && tl[1].startsWith('/') && !tl[1].startsWith('//'))
+            return expr;
+        return null; // 바인딩된 식(prop·식별자)은 정적 판별 불가 → 건드리지 않는다
+    }
+    return null;
+}
+/** 소스에 내부 이동 일반 앵커가 있는지(단위 테스트 진입점 · 주석은 제외). */
+export function usesInternalAnchor(source) {
+    const stripped = stripCommentsKeepLines(source);
+    for (const m of stripped.matchAll(/<a\b[^>]*>/gi)) {
+        if (internalAnchorHref(m[0]) !== null)
+            return true;
+    }
+    return false;
+}
+/** apps/ 의 .vue 를 훑어 내부 이동 일반 앵커를 경고로 낸다. */
+export async function checkInternalAnchor(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const abs of await walkVue(appsDir)) {
+        const source = await readFile(abs, 'utf8').catch(() => '');
+        const stripped = stripCommentsKeepLines(source);
+        const rel = relative(cwd, abs);
+        for (const m of stripped.matchAll(/<a\b[^>]*>/gi)) {
+            const href = internalAnchorHref(m[0]);
+            if (href === null)
+                continue;
+            const line = stripped.slice(0, m.index ?? 0).split('\n').length;
+            issues.push({
+                rule: 'internal-anchor',
+                level: 'warning',
+                file: rel,
+                line,
+                message: `내부 이동 일반 앵커 발견: ${rel}:${line} 이 \`<a href="${href}">\` 로 앱 내부 경로를 ` +
+                    `가리킵니다. 일반 \`<a>\` 는 클릭마다 전체 문서를 다시 로드해 Inertia SPA 상태가 ` +
+                    `초기화됩니다(첫 실사용에서 관측된 결함 · 결정 96).\n` +
+                    `→ \`gaonjs/vue\` 의 \`Link\` 를 쓰세요: \`import { Link } from 'gaonjs/vue'\` 후 ` +
+                    `\`<Link href="${href}">…</Link>\`. 프로그램적 이동은 \`router.visit(...)\`. ` +
+                    `외부 URL·\`target="_blank"\` 만 \`<a>\` 를 유지합니다.`,
+                detail: { file: rel, line, href },
+            });
+        }
+    }
+    return { rule: 'internal-anchor', issues };
+}
+/** apps/ 하위 .vue(선언·테스트 제외) 절대경로. */
+async function walkVue(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}

package/dist/doctor/types.d.ts

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

package/dist/doctor/types.js

@@ -1,9 +1,7 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 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/
+// 19 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
+// 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
 // warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
 // errors.length > 0 이면 fail 로 판단한다.
 //

package/dist/doctor.d.ts

@@ -15,6 +15,8 @@ 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 { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
+export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js';
+export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.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 확장)
  *
- * 17 검사를 조립한다:
+ * 19 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -19,6 +19,8 @@
  * 15) route-registration (결정 79 · 고아 컨트롤러 = routes.ts 미참조 경고)
  * 16) static-collision (결정 85 · 정적 파일이 라우트/에셋에 가려짐 경고)
  * 17) method-override (결정 89 · _method HTTP 스푸핑 hack 경고)
+ * 18) csrf-wiring (결정 93 · 비-GET 라우트 + session 미배선 = CSRF 무방비 경고)
+ * 19) internal-anchor (결정 96 · 앱 내부 이동 일반 <a> = 풀 리로드 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -48,6 +50,8 @@ 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 { checkCsrfWiring } from './doctor/csrf-wiring.js';
+import { checkInternalAnchor } from './doctor/internal-anchor.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -66,10 +70,12 @@ 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 { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
+export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js';
+export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 17개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 19개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -89,6 +95,8 @@ const ALL_RULES = [
     'route-registration',
     'static-collision',
     'method-override',
+    'csrf-wiring',
+    'internal-anchor',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -108,6 +116,8 @@ const CHECKERS = {
     'route-registration': checkRouteRegistration,
     'static-collision': checkStaticCollision,
     'method-override': checkMethodOverride,
+    'csrf-wiring': checkCsrfWiring,
+    'internal-anchor': checkInternalAnchor,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/generate.d.ts

@@ -21,6 +21,14 @@ export declare function authScaffoldFiles(opts?: AuthScaffoldOptions): ScaffoldF
  * `routes((r) => {` 콜백 여는 지점 뒤에 두 줄을 삽입한다.
  */
 export declare function patchRoutes(existing: string): string | null;
+/**
+ * 기존 app.config.ts 에 auth 배선을 끼워 넣는다 (결정 93 · gaon new 기본 web 앱은
+ * 세션만 배선돼 있어 g auth 는 auth 만 추가하면 완성된다). 반환:
+ *  · auth 가 이미 있으면 null (그대로 둔다),
+ *  · defineAppConfig 객체 리터럴을 못 찾으면 null (안전 · 상위에서 경고 폴백).
+ * 성공 시 loadUser import 도 함께 보장한다.
+ */
+export declare function patchAppConfigAddAuth(existing: string): string | null;
 /** 스캐폴드를 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip 한다. routes.ts 는 패치. */
 export declare function writeAuthScaffold(cwd: string, opts?: AuthScaffoldOptions): ScaffoldResult;
 export interface GenerateAuthOptions {

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               로드맵과 개발 상태를 출력",
@@ -104,7 +101,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        정적 검사 (17 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method)",
+        "    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)",
@@ -149,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 = [];
@@ -165,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 시]).

package/dist/serve.js

@@ -149,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);

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/AGENTS.md.tpl

@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 17종
+### 2.2 `gaon doctor` 검사 19종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -123,6 +123,8 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 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 판단표
 
@@ -163,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       # 정적 검사 17종 (§2.2)
+gaon doctor       # 정적 검사 19종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)
@@ -171,8 +173,8 @@ gaon doctor       # 정적 검사 17종 (§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` | 검증 루프 |
@@ -184,6 +186,11 @@ gaon doctor       # 정적 검사 17종 (§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`)
 
 | 패키지 | 버전 | 역할 |

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

@@ -42,6 +42,13 @@ const props = pageProps<'web:posts#index'>()
   전부 없음 · CLAUDE.md 규칙 12). 페이지 전환은 `gaonjs/vue` 의 `router`
   (`router.visit(url)`·`router.get/post/delete`), 폼은 `useForm(...)` (결정 64).
   라우트 정의는 서버의 `apps/<앱>/routes.ts` 뿐이다.
+- **앱 내부 이동 = `Link`(선언적) 또는 `router.visit`(프로그램적) — 내부 경로
+  일반 `<a>` 금지** (결정 96). 내부 경로로 가는 `<a href="/...">` 는 클릭마다
+  전체 문서를 다시 로드해 Inertia SPA 상태(스크롤·폼 입력·채널 구독)가 초기화된다
+  (첫 실사용 블로그에서 "메인 경로" 풀 리로드로 관측). 선언적 링크는 `gaonjs/vue`
+  의 `Link`(`<Link href="/posts">글 목록</Link>`), 코드에서의 이동은
+  `router.visit(url)`. **외부 URL(`https://…`)·`target="_blank"` 만 `<a>`** 를
+  유지한다. 내부 경로 일반 앵커는 doctor **internal-anchor** 가 잡는다(결정 96).
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 
@@ -175,7 +182,8 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
   scoped-CSS 미편입 방침은 결정 74 로 뒤집혔다).
 - **auth 링크는 수동(결정 70)** — `gaon g auth` 는 auth 페이지·라우트만 신설하고
   랜딩·레이아웃 nav 를 편집하지 않는다. 헤더에 로그인 링크를 두려면 `Default.vue`
-  의 nav 에 `<a href="/session/new">로그인</a>` 을 직접 추가한다(Rails 관례).
+  의 nav 에 `<Link href="/session/new">로그인</Link>` 을 직접 추가한다(내부 이동은
+  `Link` · 일반 `<a>` 는 풀 리로드 · 결정 96).
 - **auth 페이지 경로 = `pages/Auth/`(PascalCase)** — `gaon g auth` 는 `Auth/Login.vue`
   ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
   소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
@@ -265,6 +273,10 @@ async function runSearch(q: string) {
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
   `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
+- **내부 경로 일반 `<a href="/...">` 금지** — 클릭마다 전체 문서를 다시
+  로드해 SPA 상태가 초기화된다. 앱 내부 이동은 `gaonjs/vue` 의 `Link`
+  (`<Link href="/...">`) 또는 `router.visit(...)`, 외부 URL·`target="_blank"`
+  만 `<a>` (결정 96 · doctor **internal-anchor**).
 - **`vue-router` import 금지** — Gaon 은 클라이언트 라우터가 없다(Inertia =
   SPA + 서버 라우팅). `import { useRouter } from 'vue-router'` 는 존재하지 않는
   의존을 끌어와 컴파일 실패한다 — 전환은 `gaonjs/vue` 의 `router`, 라우트 정의는
@@ -300,4 +312,5 @@ async function runSearch(q: string) {
 | 결정 74 | Tailwind 스캐폴드 편입(tailwind.config.ts·postcss.config.js·style.css · 결정 69 scoped-CSS 방침 뒤집기) |
 | 결정 75 | shadcn 식 UI 킷(`gaon g ui-kit` · 복사-소유 · Vue 3 신작 · 외부 런타임 의존 0) |
 | 결정 76 | 멀티앱 UI 킷 배선 자동화(`g app`·`g ui-kit --app` 이 앱별 Tailwind 배선 동봉·멱등 보정 · doctor ui-kit-wiring) |
+| 결정 96 | 앱 내부 이동 = `Link`(선언적)/`router.visit`(프로그램적) · 내부 경로 일반 `<a>` 금지(풀 리로드) · `Link` 재수출 · doctor internal-anchor |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |

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

@@ -30,6 +30,12 @@
 - CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF
   강제. `api()` 클라이언트는 `<meta name="csrf-token">` 을 자동으로
   읽어 `X-CSRF-Token` 헤더에 붙인다 (`packages/vue/src/api.ts:184`).
+- **CSRF 는 세션 위에 얹힌다 — 세션이 없으면 CSRF 도 없다 (결정 93).**
+  세션이 있어야 토큰을 저장·검증할 곳이 생긴다. `gaon new` 기본 web 앱은
+  `app.config.ts` 에 세션을 **기본 배선**해 규칙 8(기본 켬)이 실태가 되게
+  한다 — 폼(POST)을 추가하는 순간 CSRF 가 이미 켜져 있다. 앱에 비-GET
+  라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
+  `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
 - JWT 는 API 앱 전용 옵션. 세션 쿠키가 기본 (v0.15 §7 · v0.11 확정).
 
 ### 3. 시크릿
@@ -99,3 +105,4 @@ const rows = await Post.query()
 | §2.5.1 (v0.15) | 보안 기본값 fail-closed (CORS·rate limit·CSRF 기본 켬) |
 | 결정 24 (E-3 §5) | `this.params` 고정 우선순위 — 파라미터 오염 차단 |
 | §7 (v0.15) | 세션 앱별 분리 · JWT 는 API 앱 전용 |
+| 결정 93 (W2) | 기본 web 앱 세션 기본 배선 = CSRF 기본 켬 실태 · doctor `csrf-wiring` 경고 |

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

@@ -100,6 +100,47 @@ export default controller({
 - 기본 경로는 여전히 `this.params` 하나(The One Way) — 스캐폴드·문서·
   기본 예시는 `this.params` 만 쓴다 (E-3 §5.3 원문).
 
+**폼 모양 두 가지 — 스키마 파생 vs 애드혹 (라우트 파라미터는 둘 다 자동 병합 · 결정 95):**
+
+라우트 파라미터·body·query 병합은 폼 모양과 무관하게 항상 일어난다 —
+`this.params(...)` 에 넘기는 폼은 **결과 타입**만 정한다. 그래서 `/posts/:id`
+같은 라우트 파라미터와 폼 필드를 **한 번의 `this.params` 로 함께** 받는다.
+
+- **① 스키마 파생 폼 `this.params(Model.form)`** — 정본. 모델 컬럼 타입으로
+  런타임 강제 변환·검증(대량 할당 차단)까지 한다. 라우트 파라미터는 **키 이름이
+  컬럼과 같으면** 자동으로 그 자리에 들어간다. 그래서 라우트를 컬럼명에 맞춰
+  짓는 게 관례다:
+
+  ```ts
+  // routes: r.post('/posts/:postId/comments', 'comments#create')
+  // 스키마 comments 에 postId·author·body 컬럼이 있으면:
+  async create() {
+    // :postId 는 라우트에서, author·body 는 body 에서 — 한 번에 검증까지.
+    const data = this.params(Comment.form)   // { postId, author, body, ... } (검증됨)
+    const comment = await Comment.create(data)
+    return this.redirect(`/posts/${String(data.postId)}`)
+  }
+  ```
+
+- **② 애드혹 폼 `this.params({ _row: {} as { ... } })`** — 전용 모델이 없거나
+  받을 필드를 **정확히** 고를 때. 라우트 파라미터·폼 필드를 자유롭게 섞어 타입을
+  못박는다. 단 **런타임 스키마 검증은 없다**(타입만 · 컬럼 정의가 없어 coerce
+  스킵) — 필요하면 값 검사를 직접 하거나 ①로 간다:
+
+  ```ts
+  // routes: r.post('/posts/:id/comments', 'comments#create')
+  async create() {
+    // :id(라우트) + author·body(폼) 를 한 폼 모양으로.
+    const { id, author, body } = this.params({
+      _row: {} as { id: string; author: string; body: string },
+    })
+    // ...
+  }
+  ```
+
+  ①이 검증까지 주므로 **모델이 있으면 ①을 먼저 고른다**. ②는 로그인 폼처럼
+  전용 테이블이 없는 입력의 탈출구다.
+
 ### 4. 데이터 경로 판단 — 루트 판단표가 정본
 
 데이터가 필요할 때는 루트 `AGENTS.md` 의 데이터 경로 4종 판단표를 따른다
@@ -290,4 +331,5 @@ export default controller({
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 — `agents/async.md`) |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 (`agents/frontend.md`) |
 | 결정 59 | 인증 배선 = `app.config.ts` 의 `session`+`auth(loadUser)` — 없으면 currentUser 영구 null |
+| 결정 95 (W4) | 폼 모양 2종 — 스키마 파생 `Model.form`(검증) vs 애드혹 `{ _row }`(타입만) · 라우트 파라미터는 둘 다 자동 병합 |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/project/apps/web/app.config.ts.tpl

@@ -0,0 +1,14 @@
+// 앱 설정 — apps/web/app.config.ts. 보안 기본값(세션 + CSRF)을 표준 부팅
+// (gaon dev / gaon serve)에 배선한다. 잘 지은 app.config 는 거의 비어 있어야
+// 하지만(§1.1), 세션은 CSRF 토큰 저장소의 토대라 기본으로 켠다.
+//
+// 규칙 8(§2.5.1): CORS·rate limit·CSRF 는 코어에서 **기본 켬** — 끄는 것은
+// 명시적 설정으로만. 세션이 있어야 상태 변경 요청(POST/PUT/PATCH/DELETE)에
+// CSRF 토큰 검증이 걸린다. 세션 스토어는 루트 gaon.config.ts 의 redis(REDIS_URL)
+// 를 wireGaon 이 주입한다(결정 93).
+import { defineAppConfig } from 'gaonjs/config'
+
+export default defineAppConfig({
+  // secret 은 32자 이상 — .env 의 SESSION_SECRET 로 주입한다(운영은 반드시 교체).
+  session: { secret: process.env.SESSION_SECRET ?? 'dev-only-session-secret-change-me-now!!' },
+})

package/dist/templates/project/apps/web/layouts/Default.vue.tpl

@@ -9,6 +9,10 @@
 // 다크 헤더 + 라이트 본문(결정 69). 스타일은 Tailwind 유틸(결정 74) — 다크
 // 헤더는 본문 테마와 무관하게 항상 어둡게 두려고 브랜드 색을 명시값으로 박는다.
 // 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
+//
+// 결정 96: 앱 내부 이동은 `Link`(선언적) — `<a href="/">` 는 전체 문서
+// 리로드라 SPA 가 깨진다. 외부 URL 만 `<a>`(문서·GitHub).
+import { Link } from 'gaonjs/vue'
 
 // package.json 의 gaonjs 의존 범위(예: ^0.9.2)에서 캐럿·틸드를 벗겨 표기.
 const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
@@ -19,13 +23,13 @@ const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
     <header
       class="flex items-center justify-between gap-4 border-b border-[#21262d] bg-[#0d1117] px-6 py-3.5 text-[#e6edf3]"
     >
-      <a href="/" class="inline-flex items-baseline gap-2.5 text-inherit no-underline">
+      <Link href="/" class="inline-flex items-baseline gap-2.5 text-inherit no-underline">
         <span
           class="inline-block rounded-md bg-gradient-to-br from-[#4f8cff] to-[#7c5cff] px-1.5 py-0.5 text-xs font-bold tracking-wide text-white"
         >가온</span>
         <span class="text-[0.95rem] font-bold tracking-[0.08em]">GAONJS</span>
         <span class="text-xs tabular-nums text-[#8b949e]">v{{ version }}</span>
-      </a>
+      </Link>
       <nav class="flex gap-[1.1rem] text-sm">
         <a href="https://gaonjs.dev" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">문서</a>
         <a href="https://github.com/gaonjs" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">GitHub</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.21.2",
+  "version": "0.23.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.6.0",
-    "@gaonjs/config": "0.5.1",
-    "@gaonjs/data": "0.9.0",
-    "@gaonjs/core": "0.2.0",
-    "@gaonjs/mail": "0.1.2",
-    "@gaonjs/web": "0.7.0"
+    "@gaonjs/async": "0.6.1",
+    "@gaonjs/data": "0.9.1",
+    "@gaonjs/web": "0.7.1",
+    "@gaonjs/core": "0.2.1",
+    "@gaonjs/config": "0.5.2",
+    "@gaonjs/mail": "0.1.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""